ARGetField
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 information about the form field with the indicated ID from the specified server.
Privileges
This operation can be performed by users with access permission for the field's parent 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 ARGetField(
ARControlStruct *control,
ARNameType schema,
ARInternalId fieldId,
ARNameType fieldName,
ARFieldMappingStruct *fieldMap,
unsigned int *dataType,
unsigned int *option,
unsigned int *createMode,
unsigned int *fieldOption,
ARValueStruct *defaultVal,
ARPermissionList *assignedGroupList,
ARPermissionList *permissions,
ARFieldLimitStruct *limit,
ARDisplayInstanceList *dInstanceList,
char **helpText,
ARTimestamp *timestamp,
ARAccessNameType owner,
ARAccessNameType lastChanged,
char **changeDiary,
ARPropList *objPropList,
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 of the field to retrieve.
Return values
fieldName
he name of the field. Specify NULL
for this parameter if you do not want to retrieve the field name.
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 data type of the field. See ARCreateField for a description of the possible values. Specify NULL
for this parameter if you do not want to retrieve the data type.
option
A flag that indicates whether users must enter a value in the field. 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 flag that indicates the permission status for the field 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 flag.
fieldOption
A bitmask 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 value 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 value.
assignedGroupList
A list of zero or more groups that are directly assigned permission to the field.
permissions
A list of zero or more groups who can access this field, 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 assignedGroupList
.
limit
The value limits for the field and other properties specific to the field's type. See Defining field limits for a description of the contained structure that applies to the type of field that you are creating. Specify NULL
(or AR_FIELD_LIMIT_NONE
) for trim and control fields or if you do not want to retrieve the limits and properties.
dInstanceList
A list of zero or more display properties associated with the field. 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 help text associated with the field. Specify NULL
for this parameter if you do not want to retrieve the help text. 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.
timestamp
A time stamp that specifies the last change to the field. Specify NULL
for this parameter if you do not want to retrieve this value.
owner
The owning user for the field. Specify NULL
for this parameter if you do not want to retrieve this value.
lastChanged
The user who made the last change to the field. Specify NULL
for this parameter if you do not want to retrieve this value.
changeDiary
The change diary associated with the field. 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. 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
, no object properties list is 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, ARGetMultipleFields, ARGetSchema, ARGetListField, ARSetField. See FreeAR for: FreeARDisplayInstanceList
, FreeARFieldLimitList
, FreeARPermissionList
, FreeARStatusList
, FreeARValueStruct
.
Comments
Log in or register to comment.