ARGetOneEntryWithFields

Note

You can continue to use C APIs to customize your application, but C APIs are not enhanced to support new capabilities provided by Java APIs and REST APIs.

Description

Retrieves one entry from AR System matching a given qualification. Similar to ARGetListEntryWithFields, with the following behavioral changes:

If the qualifier in the API call matches multiple records, only the first is returned.
Get filters on the form being queried are fired for that one record.

This function is equivalent to issuing an ARGetListEntry call followed by ARGetEntry with one of the entry IDs.

The keyword $LASTCOUNT$ is set to the number of entries matched, even though only one is returned.

Privileges

The system returns information based on the access privileges of the user that you specify for the control parameter. All lists, therefore, are limited to entries the user can access (users must have permission for the entryId field to access and retrieve entries).

Synopsis

#include "ar.h"
#include "arerrno.h"
#include "arextern.h"
#include "arstruct.h"

int ARGetOneEntryWithFields(
  ARControlStruct *control,
  ARNameType schema,
  ARQualifierStruct *qualifier,
  AREntryListFieldList *getListFields,
  ARSortList *sortList,
  ARBoolean useLocale,
  AREntryListFieldValueList *entryList,
  unsigned int *numMatches,
  ARStatusList *status)

Input arguments

control

The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user and server fields are required.

schema

The schema of which the entry is a member.

qualifier

Qualification to limit entries retrieved.

getListFields

Fields returned for matching entries.

sortList

The sort order for returned data.

useLocale

A flag that indicates whether to search for entries based on the locale. If you specify 1 (TRUE) and the Localize Server option is selected, entries are searched using the locale specified in AR_RESERV_LOCALE_LOCALIZED_SCHEMA (field ID 160). If no matches are found for the specified locale, the search becomes less restrictive until a match is found. If you specify 0 (FALSE) or the Localize Server option is cleared, all entries are searched. For information, see Localizing-the-server.

Return values

entryList

A list of zero or more matching entries.

numMatches

The number of matches for qualifier, greater than or equal to the number returned in entryList.

status

A list of zero or more notes, warnings, or errors generated from a call to this function. For a description of all possible values, see Error-checking.