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.

Entries and structures

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

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

Retrieving entry lists

You can retrieve a list of entries in either of these ways:

In both cases, the function performs the query specified by the qualifier parameter (of type ARQualifierStruct) and returns the list of entries that match the search criteria.

Note

The system identifies entries in join schemas by concatenating the entry IDs from the member schemas. As a result, an entry ID can have one or more values of type AREntryIdType and, therefore, is represented by AREntryIdList.

Entries returned as concatenated strings

The ARGetListEntry function returns an entryList output parameter that is a pointer to an AREntryListList structure (see the following figure).

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:

Short Description

128-character string containing data concatenated from the fields specified by the getListFields parameter.

Entry ID

ID associated with the entry.

Entries returned as Field/Value pairs

The ARGetListEntryWithFields function returns an entryList output parameter that is a pointer to an AREntryListFieldValueList structure (see the following figure).

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:

Field ID

Internal ID associated with the field.

Value

Value for the field represented by ARValueStruct (see  Group information).

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:

Field ID

Internal ID associated with the field.

Column Width

Integer that specifies the number of characters to display for the field ( ARGetListEntry only). For ARGetListEntryWithFields , set this value to a number greater than 0 .

Separator

Characters to display after the field data (ARGetListEntry only). The separator can contain from zero to 10 characters. For ARGetListEntryWithFields , set this value to one blank space.

Note

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:

Field ID

Internal ID associated with the field.

Sort Order

Integer that specifies the sort order for the field (see the following table).

1

AR_SORT_ASCENDING

Sort values in field in ascending order.

2

AR_SORT_DESCENDING

Sort values in field in descending order.

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 BMC Remedy 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 BMC Remedy AR System C API functions).

Both of these functions and the ARCreateEntry and 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):

Field ID

Internal ID associated with the field.

Value

Value for the field represented by ARValueStruct (see Group information ). This value must be of the same data type as the field or have the data type set to zero (AR_DATA_TYPE_NULL).

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

The following 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";
	...
	...
}

Note

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 (see the following figure).

ARGetMultipleEntries uses the AREntryIdListList structure to pass entry IDs for the specified entries. This structure has zero or more AREntryIdList structures (see the following figure). 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.

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

Comments