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

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

Performing common tasks

Each object in the BMC Remedy 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 BMC Remedy AR System object.

BMC Remedy 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. Each of the first two examples include a brief task description, an outline of the conceptual steps involved, and 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 BMC Remedy AR System servers.

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 following high-level steps are illustrated in the following figure.

To retrieve selected properties for a field

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

    Retrieving selected properties from a field
    (Click the image to expand it.)

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 following high-level steps are illustrated in the following figure.

To retrieve selected entries from a schema

  1. Retrieve a list of available schemas (ARGetListSchema), and select the desired schema name (schema) from the list (nameList).
  2. Create a string with the desired query conditions (qualString), and place it into the proper structure (ARLoadARQualifierStruct).
  3. Retrieve a list of entries (ARGetListEntry) from the schema that match the query conditions (qualifier).
  4. 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
(Click the image to expand it.)

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;
}
Was this page helpful? Yes No Submitting... Thank you

Comments