Entries and structures

The AR System C API uses the term entry, but the AR System clients refer to entries as requests.

The most common operations in AR System involve creating, retrieving, or updating entries. The following section describes some of the structures used to perform these tasks.

Entries returned as concatenated strings

The ARGetListEntry function returns an entryList output parameter that is a pointer to an AREntryListList structure.

Structures used to represent a list of entries as concatenated strings

AREntryListList has zero or more AREntryListStruct items, each representing a matching entry. The AREntryListStruct structure has the following elements:

Entries returned as Field/Value pairs

The ARGetListEntryWithFields function returns an entryList output parameter that is a pointer to an AREntryListFieldValueList structure.

Structures used to represent a list of entries as Field/Value pairs

AREntryListFieldValueList has zero or more AREntryListFieldValueStruct items, each representing a matching entry. The AREntryListFieldValueStruct structure has an entry ID and a list of ARFieldValueStruct structures, each representing a field in the entry. An ARFieldValueStruct structure has the following elements:

Specifying fields to retrieve

The getListFields parameter of both ARGetListEntry and ARGetListEntryWithFields identifies the fields to return with each entry. It also defines the column width and column separator for each field, which are used by ARGetListEntry but ignored by ARGetListEntryWithFields. This parameter is a pointer to an AREntryListFieldList structure (see the following figure).

Structures used to define column fields in an entry list

Each AREntryListFieldStruct item specifies a particular field and associated display information:

For ARGetListEntry, the combined length of all specified fields, including separator characters, can be up to 128 bytes (limited by AR_MAX_SDESC_SIZE).

Sorting a list of entries

The sortList parameter of both ARGetListEntry and ARGetListEntryWithFields specifies the sort order for a list of entries. This parameter is a pointer to an ARSortList structure.

Structures used to define sort fields in an entry list

As this figure shows, ARSortList contains zero or more ARSortStruct items. Each ARSortStruct has the following elements:

The overall order of entries in the list is determined by the value specified for each field and the order of ARSortStruct items in the ARSortList structure.

Manipulating individual entries

The ARGetListEntry and ARGetListEntryWithFields functions (see AR-System-C-API-functions) return a list of entries that match specified criteria. This list contains the entry IDs for the matching entries but does not contain all field values. To retrieve or modify individual entries, you must pass the entry ID as an input argument to the ARGetEntry or ARSetEntry functions (see AR-System-C-API-functions).

Both of these functions, the ARCreateEntry and the ARGetListEntryWithFields functions use the ARFieldValueList structure to pass field values for individual entries. The ARFieldValueList structure in the following figure has zero or more ARFieldValueStruct items. Each of these structures contains a field and its value (a field/value pair):

All entry data, whether submitted, retrieved, or modified, is represented by this structure.

Here is a code fragment that loads data into this structure:

#include "arstruct.h"    /* symbolic constants for core field IDs */

int main( int argc, char *argv[] )
{
ARFieldValueList     fieldList;     /* structure to populate */
ARFieldValueStruct *fldStrcp;      /* working pointer       */
...
...
/**********************************************************/
/*Populate fieldList with data */
/**********************************************************/
fieldList.numItems = 3;
fieldList.fieldValueList=malloc(3*sizeof(ARFieldValueStruct));
fldStrcp = fieldList.fieldValueList;
if( fldStrcp == NULL){
fprintf(stderr,"Out of memory, malloc failure\n");
exit(1);
}
fldStrcp[0].fieldId = AR_CORE_SUBMITTER;
fldStrcp[0].value.dataType = AR_DATA_TYPE_CHAR;
fldStrcp[0].value.u.charVal = "Bob";

fldStrcp[1].fieldId = AR_CORE_STATUS;
fldStrcp[1].value.dataType = AR_DATA_TYPE_ENUM;
fldStrcp[1].value.u.enumVal = STATUS_NEW;

fldStrcp[2].fieldId = AR_CORE_SHORT_DESCRIPTION;
fldStrcp[2].value.dataType = AR_DATA_TYPE_CHAR;
fldStrcp[2].value.u.charVal = "Broken computer";
...
...
}

In this example, the charVal members for the Submitter and Short Description fields are on the stack. As a result, you cannot use the FreeARFieldValueList function to free this structure because the FreeAR routines assume that all structure components are in allocated memory (on the heap). For more information, see Freeing-allocated-memory.

Retrieving multiple entries

The ARGetMultipleEntries function returns a list of entries with the specified entry IDs. You can retrieve data for specific fields or all accessible fields. ARGetMultipleEntries performs the same action as ARGetEntry but is easier and more efficient than retrieving multiple entries one by one.

This function uses the ARFieldValueListList structure to return field values for the specified entries. This structure has zero or more ARFieldValueList structures.

ARGetMultipleEntries uses the AREntryIdListList structure to pass entry IDs for the specified entries. This structure has zero or more AREntryIdList structures. ARGetMultipleEntries can request a maximum of 100 entries but can be used multiple times.

You can also use the ARGetMultipleEntries function to check whether the entries in the AREntryIdListList exist without transferring any field data, conserving network traffic. The function has an existList parameter that returns a pointer to an ARBooleanList structure. Each ARBoolean flag in that list specifies whether a given entry ID exists in the database.