ARGetMultipleActiveLinks

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 multiple active link definitions. This function performs the same action as ARGetActiveLink but is easier to use and more efficient than retrieving information about multiple active links one by one.

Information is returned in lists for each item, with one item in the list for each active link returned. For example, if the second item in the list for existList is TRUE, the name of the second active link is returned in the second item in the list for actLinkNameList.

Privileges

All users who have permission for the active link. Only BMC Remedy AR System administrators have access to groupList information.

Synopsis

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

int ARGetMultipleActiveLinks(
  ARControlStruct *control,
  ARTimestamp changedSince,
  ARNameList *nameList,
  ARBooleanList *existList,
  ARNameList *actLinkNameList,
  ARUnsignedIntList *orderList,
  ARWorkflowConnectList *schemaList,
  ARInternalIdListList *assignedGroupListList,
  ARInternalIdListList *groupListList,
  ARUnsignedIntList *executeMaskList,
  ARInternalIdList *controlFieldList,
  ARInternalIdList *focusFieldList,
  ARUnsignedIntList *enableList,
  ARQualifierList *queryList,
  ARActiveLinkActionListList *actionListList,
  ARActiveLinkActionListList *elseListList,
  ARTextStringList *helpTextList,
  ARTimestampList *timestampList,
  ARAccessNameList *ownersList,
  ARAccessNameList *lastChangedList,
  ARTextStringList *changeDiaryList,
  ARPropListList *objPropListList,
  ARUnsignedIntList *errorActlinkOptionsList,
  ARNameList *errorActlinkNameList,
  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 active links retrieved to those modified after the specified time. Specify 0 for this parameter to retrieve active links with any modification time stamp.

nameList

A list of names of the active links to retrieve that match the criteria in the changedSince argument. The system returns a list with zero items if no active links match the specified criteria.

Note

If you enter the same active link name two or more times in the nameList parameter, the server retrieves information for only the first occurrence, and ignores the information for the other repeat occurrences.

Return values

existList

A list of flags and corresponding Boolean values that indicate whether the active links exist and meet the qualifying criteria. Values: TRUE means the active link exists; FALSE means the active link does not exist.

actLinkNameList

A list of names of active links that this function returns. This argument returns names in the same order as the input list of active links to be retrieved. If namelist is not NULL, each return list maintains a corresponding position for each supplied name. As a consequence, you must see the existList returned to see if the active link in that position had any data returned for it.

orderList

A value between 0 and 1000 (inclusive) that determines the active link execution order. When multiple active links are associated with a form, the value associated with each active link 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.

schemaList

The list of form names the active link is linked to. The active link must be associated with a single form or a list of forms that currently exists on the server. Specify NULL for this parameter if you do not want to retrieve this value.

assignedGroupListList

A list of zero or more groups that are directly assigned permission to the active links.

groupListList

A list of zero or more groups who can access these active links, including the inheritance hierarchy in the case of hierarchical groups. Access to this information is limited to users with BMC Remedy AR System administrator privileges. Specify NULL for this parameter if you do not want to retrieve this value.

If the static inheritance property is not enabled for the active link, this list will be the same as the assignedGroupListList.

executeMaskList

A list of bitmasks that indicate the form operations that trigger the active links. See ARCreateActiveLink for a description of the possible values. Specify NULL for this parameter if you do not want to retrieve this value.

controlFieldList

A list of the IDs of the fields that represent the button, toolbar button, or menu items associated with executing the active links. The system returns zero if the executeMask does not include the AR_EXECUTE_ON_BUTTON condition. Specify NULL for this parameter if you do not want to retrieve this value.

focusFieldList

A list of the IDs of the fields associated with executing the active links by pressing Return or selecting a character menu item. The system returns zero if the executeMask does not include the AR_EXECUTE_ON_RETURN or AR_EXECUTE_ON_MENU_CHOICE conditions. Specify NULL for this parameter if you do not want to retrieve the focus fields.

enableList

A list of flags that specify whether the active link 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 active links are executed. The system returns zero (AR_COND_OP_NONE) if the active links 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 the help texts associated with the active links. Specify NULL for this parameter if you do not want to retrieve the help texts (which is useful if you are calling this function to verify whether instances of these objects exist).

timestampList

A list of time stamps that identify the last changes to the active links. Specify NULL for this parameter if you do not want to retrieve this value.

ownerList

A list of owners for the active links. Specify NULL for this parameter if you do not want to retrieve the owners.

lastChangedList

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

changeDiaryList

A list of the change diaries associated with the active link. 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. 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.

objPropList

A list of server object properties. If this parameter is set to NULL, a properties list with zero properties is associated with the object, and when an ARGetFilter action is performed, zero properties are returned. See Server object properties.

errorActlinkOptionsList

Reserved for future use. Set to NULL.

errorActlinkNameList