ARGetListSchemaWithAlias

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 definitions and their corresponding aliases from the specified server. You can retrieve all (accessible) forms or limit the list to forms of a particular type or forms modified after a specified time.

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 forms the user can access.

Synopsis

#include "ar.h"
#include "arerrno.h"
#include "arextern.h"
#include "arstruct.h"

int ARGetListSchemaWithAlias(
  ARControlStruct *control,
  ARTimestamp changedSince,
  unsigned int schemaType,
  ARNameType name,
  ARInternalIdList *fieldIdList,
  ARNameType vuiLabel,
  ARPropList *objPropList,
  ARNameList *nameList,
  ARNameList *aliasList,
  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.

To specify whether to search for an object's real or resolved name, use the AR_SESS_CONTROL_PROP_API_OVERLAYGROUP variable of the ARSetSessionConfiguration function (see ARSetSessionConfiguration). For calls that use field or view IDs, the search is performed on the real or resolved name of the associated form.

If you do not use the AR_SESS_CONTROL_PROP_API_OVERLAYGROUP variable, the BMC Remedy AR System server uses the default overlay group at run time. For information about configuring the default overlay group, see the description for Overlay-mode in ar-cfg-or-ar-conf-options-N-R.

changedSince

A time stamp that limits the forms retrieved to those modified after the specified time. Specify 0 for this parameter to retrieve schemas with any modification time stamp.

schemaType

A value that indicates the form types to retrieve (some types are mutually exclusive).

To retrieve both visible and hidden forms, add 1024 (AR_HIDDEN_INCREMENT) to the form type. For example, specify AR_LIST_SCHEMA_ALL | AR_HIDDEN_INCREMENT for this parameter.

name

If the schemaType is AR_LIST_SCHEMA_UPLINK, this parameter specifies the form on which the retrieved forms depend. If the schemaType is AR_LIST_SCHEMA_DOWNLINK, this parameter specifies the form that depends on the retrieved forms. This parameter is ignored if you do not specify AR_LIST_SCHEMA_UPLINK or AR_LIST_SCHEMA_DOWNLINK as the schemaType.

fieldIdList

A list of zero or more internal IDs that specify the fields to retrieve. Specify NULL for this parameter (or zero fields) if you do not want to qualify the forms returned by the fields they contain. For example, specify the four reserved server event fields (800, 801, 802, 803) in this list to retrieve the server event schema.

vuiLabel

Label for the specific VUI from which to retrieve aliases. The system returns aliases from the default VUI if you specify NULL or if the specified VUI does not exist.

objPropList

List of server-managed object properties to search for. Returns all schemas that match the object properties, for example, the application owner. See Server-managed object property tags.

Return values

nameList

A list of zero or more (accessible) schemas that match the criteria defined in the schemaType, changedSince, fieldIDList, and objPropList parameters. The system returns a list with zero items if no forms match the specified criteria.

aliasList

A list of zero or more VUI aliases that:

Match the schemas in the nameList parameter.
Are aliases from the form that the name parameter specifies.
Conform to the locale that the control parameter specifies.

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.