Performing common tasks

Each object in the AR System has an ARGetList object function that returns a list of records that match the specified criteria. Depending on the object, this list contains zero or more names or IDs (or both) that uniquely identify the record. The following table shows the unique identifier for each AR System object:

AR System object	Return parameter	Parameter type	Unique identifier
Active link	nameList	ARNameList *	Name
Character menu	nameList	ARNameList *	Name
Container	conList	ARContainerInfoList *	Name
Entry	entryList	AREntryListList *	ID
Escalation	nameList	ARNameList *	Name
Field	idList	ARInternalIdList *	ID
Filter	nameList	ARNameList *	Name
Group	groupList	ARGroupInfoList *	ID
Image	imageList	ARNameList *	Name
Schema	nameList	ARNameList *	Name
Server	serverList	ARServerNameList *	Name
User	userList	ARUserInfoList *	Name
View (VUI)	idList	ARInternalIdList *	ID

These names or IDs can then be passed as input arguments to the ARGet object, ARSet object, or ARDelete object functions to perform the corresponding operation on those records.

Unqualified ARGetList Object calls generate a complete list of records (for a particular object). You can select a subset of these records by using a qualification. When retrieving a list of entries, you can specify any set of selection conditions by using ARQualifierStruct (see Representing-qualifications-with-structures). For other objects, you can retrieve lists limited to records modified after a specified date and time value. For fields, views, filters, escalations, and active links, you can also limit it to items associated with a specified schema.

The following examples use common tasks to illustrate these concepts. The first two examples include a brief task description, an outline of the conceptual steps involved, a diagram of the C API functions and parameters used to accomplish the task. These examples also demonstrate the general problem-solving approach of breaking tasks into conceptual steps. This approach might help you identify the sequence of C API functions needed to solve your programming problem. The third example consists of a small sample program that retrieves and prints a list of available AR System server.

Example 1: Retrieving field properties

The goal in this example is to retrieve selected properties for a particular schema field. In this case, the field is a data or control field, and the properties shown are the field name, data type, access control information, and display properties. The high-level steps are illustrated in the figure.

To retrieve selected properties for a field

Retrieve a list of available schemas (ARGetListSchema), and select the desired schema name (schema) from the list (nameList).
Retrieve a list of data, trim, and control fields (fieldType) associated with the schema (ARGetListField).
Select the desired field (fieldId) from the list (idList), and retrieve the specified properties for that field (ARGetField).

Retrieving selected properties from a field

Example 2: Retrieving selected entries

The goal in this example is to retrieve the set of schema entries that match specified query conditions. The selection criteria are those entries that are either New or Open and were created more than two weeks ago. The high-level steps are illustrated in the figure.

To retrieve selected entries from a schema

Retrieve a list of available schemas (ARGetListSchema), and select the desired schema name (schema) from the list (nameList).
Create a string with the desired query conditions (qualString), and place it into the proper structure (ARLoadARQualifierStruct).
Retrieve a list of entries (ARGetListEntry) from the schema that match the query conditions (qualifier).
If desired, select a particular entry (entryId) from the list (entryList), and retrieve the field data (fieldList) for that entry (ARGetEntry).

Retrieving the field data

Example 3: Retrieving a schema list

#include "ar.h"
#include "arextern.h"
#include "arfree.h"

void printStatusList(ARStatusList *theList)
{
unsigned int i;
for (i = 0; i < theList->numItems; i++)

{
if (theList->statusList[i].appendedText == NULL ||
theList->statusList[i].appendedText[0] == '\0')
printf("%s", theList->statusList[i].messageText);
else
printf("%s : %s", theList->statusList[i].messageText,
theList->statusList[i].appendedText);
printf(" (ARERR %d)\n", theList->statusList[i].messageNum);
}
}

int main(void)
{
ARControlStruct control = {0,0,"Demo", "", "", 0, "",
"yourservername"};
ARNameList formNameList;
unsigned int i;
ARStatusList status = {0, NULL};
if (ARInitialization(&control, &status) >= AR_RETURN_ERROR)
{
printStatusList(&status);
FreeARStatusList(&status, FALSE);
return 1;
}

FreeARStatusList(&status, FALSE);

if (ARGetListSchema(&control, 0,
AR_LIST_SCHEMA_ALL |AR_HIDDEN_INCREMENT,
NULL, NULL, NULL,
&formNameList, &status) >= AR_RETURN_ERROR)
printStatusList(&status);
else
{
for (i = 0; i < formNameList.numItems; i++)
printf("%s\n", formNameList.nameList[i]);
}

FreeARStatusList(&status, FALSE);
FreeARNameList(&formNameList, FALSE);
if ((&control, &status) >= AR_RETURN_ERROR)
printStatusList(&status);
FreeARStatusList(&status, FALSE);
return 0;
}