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.

ARGetMultipleFilters

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 from the specified server information about the filters whose names are specified by the nameList parameter. This function performs the same action as ARGetFilter but is easier to use and more efficient than retrieving information about multiple filters one by one. Information is returned in lists for each item, with one item in the list for each filter returned. For example, if the second item in the list for existList is TRUE, the name of the second filter is returned in the second item in the list for filterNameList.

Privileges

All users.

Synopsis

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

int ARGetMultipleFilters(
   ARControlStruct *control,
   ARTimestamp changedSince,
   ARNameList *nameList,
   ARBooleanList *existList,
   ARNameList *filterNameList,
   ARUnsignedIntList *orderList,
   ARWorkflowConnectList *workflowConnectList,
   ARUnsignedIntList *opSetList,
   ARUnsignedIntList *enableList,
   ARQualifierList *queryList,
   ARFilterActionListList *actionListList,
   ARFilterActionListList *elseListList,
   ARTextStringList *helpTextList,
   ARTimestampList *timestampList,
   ARAccessNameList *ownerList,
   ARAccessNameList *lastChangedList,
   ARTextStringList *changeDiaryList,
   ARPropListList *objPropListList,
   ARUnsignedIntList *errorFilterOptionsList,
   ARNameList *errorFilterNameList,
   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 Configuration settings N-R.

changedSince

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

nameList

The names of the filters to retrieve. The nameList can be passed as a NULL or as an empty list, as in:

ARNameList emptyNameList = {0, 0};
   ...
   ARGetMultipleFilters(control, changedSince, &emptyNameList, ...)



In this case information is returned for every filter that passes the changedSince condition.

Return values

existList

A list of flags and corresponding Boolean values that indicate whether the filters exist. Values: TRUE means the filter exists; FALSE means the filter does not exist.

filterNameList

A list of zero or more filters that match the criteria defined in the changedSince and nameList parameters. The system returns a list with zero items if no filters match the specified criteria.

orderList

A list of values between 0 and 1000 (inclusive) that determines the filter execution order. When multiple filters are associated with a form, the value associated with each filter determines the order in which they are processed (from lowest to highest). Specify NULL for this parameter if you do not want to retrieve this value.

workflowConnectList

A list of the items that ARGetFilter returns one at a time, which are the schemas to which the filter is attached.

opSetList

Each member of opSetList is an integer bit mask that indicate on which conditions the filter executes: form get, create, delete, update, and merge. For more information, see ARCreateFilter.

enableList

A list of flags that specify whether the filter is disabled (0) or enabled (1). Specify NULL for this parameter if you do not want to retrieve these flags.

queryList

A list of qualifications that determines whether the filters are executed. The system returns zero (AR_COND_OP_NONE) if the filters have no qualifications. Specify NULL for this parameter if you do not want to retrieve the queries.

actionListList

A list of the sets of actions performed if the condition defined by the query parameter is satisfied. This list can contain from 1 to 25 actions (limited by AR_MAX_ACTIONS). Specify NULL for this parameter if you do not want to retrieve the action lists.

elseListList

A list of the sets of actions performed if the conditions defined by the query parameter is not satisfied. This list can contain from 0 to 25 actions (limited by AR_MAX_ACTIONS). Specify NULL for this parameter if you do not want to retrieve the else list.

helpTextList

A list of help text items associated with the filters. Specify NULL for this parameter if you do not want to retrieve the help text (which is useful if you are calling this function to verify whether an instance of these objects exists).

timeStampList

A list of time stamps that specify the last change to the filters. Specify NULL for this parameter if you do not want to retrieve this value.

ownerList

A list of owning users for the filters. Specify NULL for this parameter if you do not want to retrieve this value.

lastChangedList

A list of users who made the last change to the filters. Specify NULL for this parameter if you do not want to retrieve this value.

changeDiaryList

A list of change diaries associated with the filters. Use ARDecodeDiary to parse the change diary into user, time stamp, and text components. The server adds the user making the change and a time stamp when it saves the change diary. Specify NULL for this parameter if you do not want to retrieve the change diary list. This value can be large, so do not retrieve it if the program does not need it, for example, if the program is only checking it an object exists.

objPropListList

A list of object property lists that correspond to the filters in nameList. If this parameter is set to NULL, no properties are returned. See Server object properties.

errorFilterOptionsList

A list of error handler option bitmaps. An item in the list is AR_FILTER_ERRHANDLER_ENABLE if the error handler filter is enabled, zero if not. Specify NULL for this parameter if you do not want to retrieve this value.

errorFilterNameList

A list of names of error handler filters. An item in the list is NULL if no error handler is specified for the filter. Specify NULL for this parameter if you do not want to retrieve this value.

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.

See also

ARCreateFilter, ARDecodeDiary, ARDeleteFilter, ARGetFilter, ARGetListFilter, ARSetFilter. See FreeAR for: FreeARFilterActionList, FreeARPropList, FreeARQualifierStruct, FreeARStatusList.

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

Comments