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

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

ARGetMultipleFields

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 one or more field definitions for a specified form. This function performs the same action as ARGetField but is easier to use and more efficient than retrieving information about multiple fields one by one.

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

Privileges

This operation can be performed by users with any level of access permission for the fields in the specified form. Access to permissions information is limited to users with BMC Remedy AR System administrator privileges.

Synopsis

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

int ARGetMultipleFields(
   ARControlStruct *control,
   ARNameType schema,
   ARInternalIdList *fieldId,
   ARBooleanList *existList,
   ARInternalIdList *fieldId2,
   ARNameList *fieldName,
   ARFieldMappingList *fieldMap,
   ARUnsignedIntList *dataType,
   ARUnsignedIntList *option,
   ARUnsignedIntList *createMode,
   ARUnsignedIntList *fieldOption,
   ARValueList *defaultVal,
   ARPermissionListList *assignedGroupListList,
   ARPermissionListList *permissions,
   ARFieldLimitList *limit,
   ARDisplayInstanceListList *dInstanceList,
   ARTextStringList *helpText,
   ARTimestampList *timestamp,
   ARAccessNameList *owner,
   ARAccessNameList *lastChanged,
   ARTextStringList *changeDiary,
   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 description for Overlay-mode in Configuration settings N-R.

schema

The name of the form containing the field to retrieve.

fieldId

The internal ID list of fields to retrieve. Specify NULL or fieldIdList.numItems=0 for this parameter to retrieve data for all the fields in the form.

Return values

existList

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

fieldId2

The list of internal IDs of the fields retrieved. Specify NULL for this parameter if you do not want to retrieve the field IDs.

fieldName

The list of names of the fields. Specify NULL for this parameter if you do not want to retrieve the field names.

fieldMap

A mapping to the underlying form from which to retrieve the field. Useful for join forms. Specify NULL for this parameter if you do not want to retrieve the field mapping. See Mapping fields in schemas.

dataType

The list data types of the fields. See ARCreateField for a description of the possible values. Specify NULL for this parameter if you do not want to retrieve the data types.

option

A list of flags that indicate whether users must enter a value in the fields. See ARCreateField for a description of the possible values. Specify NULL for this parameter if you do not want to retrieve this flag.

createMode

A list of flags that indicate the permission status for the fields when users submit entries. See ARCreateField for a description of the possible values. Specify NULL for this parameter if you do not want to retrieve this value.

fieldOption

A list of bitmasks that indicates whether the field is to be audited or copied when other fields are audited.

Bit 0:

Audit this field. (AR_FIELD_BITOPTION_AUDIT)

Bit 1:

Copy this field when other fields in the form are audited. (AR_FIELD_BITOPTION_COPY)

Bit 2:

Indicates this field is for Log Key 1. (AR_FIELD_BITOPTION_LOG_KEY1)

Bit 3:

Indicates this field is for Log Key 2. (AR_FIELD_BITOPTION_LOG_KEY2)

Bits 2 and 3:

Indicates this field is for Log Key 3. (AR_FIELD_BITOPTION_LOG_KEY3)

defaultVal

The list of values to apply if a user submits an entry with no field value (only applicable to data fields). The system returns 0 (AR_DEFAULT_VALUE_NONE) if the field has no default. Specify NULL for this parameter if you do not want to retrieve the default values.

assignedGroupListList

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

permissions

A list of lists containing zero or more groups who can access the fields retrieved, 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 the permissions.

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

limit

The list of value limits for the fields and other properties specific to the individual fields' respective types. See Defining field limits for a description of the contained structure that applies to the type of field that you are creating. Specify NULL for this parameter if you do not want to retrieve the limits and properties.

dInstanceList

A list of lists containing zero or more display properties associated with the fields. See ARCreateField for a description of the possible values. The system returns 0 (AR_DPROP_NONE) if the field has no display properties. Specify NULL for this parameter if you do not want to retrieve this list.

helpText

The list of help text associated with the fields. Specify NULL for this parameter if you do not want to retrieve the help text.

timestamp

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

owner

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

lastChanged

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

changeDiary

The list of change diary entries associated with the fields. 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.

objPropListList

A list of server object property lists that correspond to the fields in fieldId. If this parameter is set to NULL, no properties are returned. See Server object properties and structures.

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

ARCreateField, ARDecodeDiary, ARDeleteField, ARDeleteMultipleFields, ARGetField, ARGetListField, ARGetMultipleActiveLinks, ARGetMultipleEntries, ARGetMultipleExtFieldCandidates, ARGetMultipleLocalizedValues, ARGetMultipleSchemas, ARGetSchema, ARSetField. See FreeAR for:FreeARBooleanList, FreeARAccessNameList, FreeARDisplayInstanceListList, FreeARFieldLimitList, FreeARFieldMappingList, FreeARInternalIdList, FreeARNameList, FreeARPermissionListList, FreeARStatusList, FreeARTextStringList, FreeARTimestampList, FreeARUnsignedIntList, FreeARValueList.

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

Comments