ARGetMultipleContainers

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 container objects.

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

Privileges

All users.

Synopsis

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

int ARGetMultipleContainers (
   ARControlStruct *control,
   ARTimestamp changedSince,
   ARNameList *nameList,
   ARContainerTypeList *containerTypes,
   unsigned int attributes,
   ARContainerOwnerObjList *ownerObjList,
   ARReferenceTypeList *refTypes,
   ARBooleanList *existList,
   ARNameList *containerNameList,
   ARPermissionListList *assignedGroupListList,
   ARPermissionListList *groupListList,
   ARInternalIdListList *admingrpListList,
   ARContainerOwnerObjListList *ownerObjListList,
   ARTextStringList *labelList,
   ARTextStringList *descriptionList,
   ARUnsignedIntList *typeList,
   ARReferenceListList *referenceList,
   ARTextStringList *helpTextList,
   ARAccessNameList *ownerList,
   ARTimestampList *timestampList,
   ARAccessNameList *lastChangedList,
   ARTextStringList *changeDiaryList,
   ARPropListList *objPropListList,
   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 Overlay-mode option in Configuration settings N-R.

changedSince

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

nameList

The names of the containers to retrieve.

containerTypes

A list of values that indicate the container types to retrieve.

`0:`	Retrieve all container types (`ARCON_ALL`).
`1:`	Retrieve all guide containers (`ARCON_GUIDE`).
`2:`	Retrieve all application containers (`ARCON_APP`).
`3:`	Retrieve all packing list containers (`ARCON_PACK`).
`4:`	Retrieve all filter guide containers (`ARCON_FILTER_GUIDE`).

attributes

Specify AR_HIDDEN_INCREMENT for this parameter to retrieve both visible and hidden containers. Specify NULL for this parameter to retrieve only visible containers.

ownerObjList

A list of schemas that own this container. This parameter can be NULL if the container exists globally.

refTypes

A list of the types of references (for example, forms and filters) to retrieve. You can specify individual types of references to retrieve, specify that all (ARREF_ALL) or none (ARREF_NONE) of the references be retrieved, or specify negative numbers to treat the types of references as exclude reference types. The exclude reference types take precedence over the include list; this means that if you specify a type as positive as well as negative, then all references of that type are excluded.

Return values

existList

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

containerNameList

The array of container names retrieved.

assignedGroupListList

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

groupListList

A list of zero or more groups who can access this container, 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 container, this list will be the same as the assignedGroupListList.

admingrpListList

A list of zero or more groups who can administer this container (and the referenced objects). If ownerObj does not return NULL, this list is the Subadministrator group list of the owning form. Users must belong to both a specified group and the Subadministrator group to obtain these privileges. Specify NULL for this parameter if you do not want to retrieve the administrator group list.

ownerObjListList

A list of schemas that own this container. Specify NULL for this parameter if you do not want to retrieve this value. If this parameter returns NULL, the container exists globally.

labelList

A list of labels for this container. Specify NULL for this parameter if you do not want to retrieve the list.

descriptionList

The list of descriptions for this container. Specify NULL for this parameter if you do not want to retrieve the list.

typeList

The list of the container's type.

`0:`	Retrieve all container types (`ARCON_ALL`).
`1:`	Retrieve all guide containers (`ARCON_GUIDE`).
`2:`	Retrieve all application containers (`ARCON_APP`).
`3:`	Retrieve all packing list containers (`ARCON_PACK`).
`4:`	Retrieve all filter guide containers (`ARCON_FILTER_GUIDE`).

referenceList

The list of pointers to the objects (for example, forms or filters) referenced by this container. Specify NULL for this parameter if you do not want to retrieve the list.

helpTextList

A list of the help texts associated with the containers. 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 instances of these objects exist).

ownerList

The list of owning users for the containers. Specify NULL for this parameter if you do not want to retrieve the list.

timestampList

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

lastChangedList

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

changeDiaryList

The list of change diary entries associated with the containers. The server adds the user making the change and a time stamp when it saves the change diary. Use ARDecodeDiary to parse the change diary into user, time stamp, and text components. 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 server object property lists that correspond to the containers in nameList. If this parameter is set to NULL, no properties are returned. See Server object properties.

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.