This documentation supports the 9.1 version of Remedy Action Request System.

To view the latest version, select the version from the Product version menu.

ARGetListEntry

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 a list of form entries from the specified server. The BMC Remedy AR System Server returns data from each entry as a string containing the concatenated values of selected fields. In the returned data, the combined length of all specified fields, including separator characters, can be up to 128 bytes (limited by AR_MAX_SDESC_SIZE). You can limit the list to entries that match particular conditions by specifying the qualifier parameter. ARGetListEntryWithFields can be used to return a qualified list of entries formatted as field/value pairs, without the 128 byte limitation.

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 ARGetListEntry(
   ARControlStruct *control,
   ARNameType schema,
   ARQualifierStruct *qualifier,
   AREntryListFieldList *getListFields,
   ARSortList *sortList,
   unsigned int firstRetrieve,
   unsigned int maxRetrieve,
   ARBoolean useLocale,
   AREntryListList *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 name of the form to retrieve entries for.

qualifier

A query that determines the set of entries to retrieve. The qualification can include one or more fields and any combination of conditional, relational, and arithmetic (numeric data types only) operations. The system generates an error if the user does not have read permission for a field or a field does not exist. Specify NULL or assign an operation value of 0 (AR_COND_OP_NONE) to match all form entries.

getListFields

A list of zero or more fields that identifies the data to display in the query list. The list can include any data fields except diary fields and long character fields. The system checks the permissions for each specified field and returns only those fields for which you have read access. The combined length of all specified fields, including separator characters, can be as many as 128 bytes (limited by AR_MAX_SDESC_SIZE). Specify NULL for this parameter (or zero fields) to return the default query list data for the form (see ARCreateSchema). The system returns the Short-Description core field if the form has no default query list data.

sortList

A list of zero or more fields that identifies the entry sort order. The system generates an error if you do not have read access on all specified fields. Specify NULL for this parameter (or zero fields) to use the default sort order for the form (see ARCreateSchema). The system sorts the entries in ascending order by entryId if the form has no default sort order.

firstRetrieve

The first entry to retrieve. A value of 0 (AR_START_WITH_FIRST_ENTRY) represents the first entry.  A value of 1 will skip the first entry.
 

maxRetrieve

The maximum number of entries to retrieve. Use this parameter to limit the amount of data returned if the qualification does not sufficiently narrow the list. Specify 0 (AR_NO_MAX_LIST_RETRIEVE) to assign no maximum.

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. 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 more information, see Setting the Localize Server option.

Return values

entryList

A list of zero or more (accessible) entries that match the criteria defined by the qualifier parameter. The system returns a list with zero items if no entries match the specified criteria.

numMatches

The total number of (accessible) entries that match the qualification criteria. This value does not represent the number of entries returned unless the number of matching entries is less than or equal to the maxRetrieve value. Specify NULL for this parameter if you do not want to retrieve this value.

Note

Performing this count requires additional search time if the number of matching entries is more than the maxRetrieve value. In this case, the cost of completing the search diminishes the performance benefits of retrieving fewer entries.

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.

See also

ARGetListEntryWithFields, ARGetOneEntryWithFields, ARCreateEntry, ARDeleteEntry, ARGetEntry, ARGetEntryStatistics, ARLoadARQualifierStruct, ARMergeEntry, ARSetEntry. See FreeAR for: FreeAREntryListFieldList, FreeAREntryListList, FreeARQualifierStruct, FreeARSortList, FreeARStatusList.

Was this page helpful? Yes No Submitting... Thank you

Comments