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. ( |
Bit 1: | Copy this field when other fields in the form are audited. ( |
Bit 2: | Indicates this field is for Log Key 1. ( |
Bit 3: | Indicates this field is for Log Key 2. ( |
Bits 2 and 3: | Indicates this field is for Log Key 3. ( |
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
.
Comments
Log in or register to comment.