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

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

ARSetField

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

Updates the definition for the form field with the indicated ID on the specified server.

If you perform a set operation on an overlay and you provide values for an inherited grain, the values are ignored. Only values for extended or overwritten grains of the overlay are set.

Privileges

BMC Remedy AR System administrator.

Synopsis

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

int ARSetField(
   ARControlStruct *control,
   ARNameType schema,
   ARInternalId fieldId,
   ARNameType fieldName,
   ARFieldMappingStruct *fieldMap,
   unsigned int *option,
   unsigned int *createMode,
   unsigned int *fieldOption,
   ARValueStruct *defaultVal,
   ARPermissionList *permissions,
   ARFieldLimitStruct *limit,
   ARDisplayInstanceList *dInstanceList,
   char *helpText,
   ARAccessNameType owner,
   char *changeDiary,
   unsigned int setFieldOptions,
   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.

If a valid overlay group is specified in the control record, the ARSet* function operates on the object that belongs to that group. If no group is specified, the function operates on the origin object. To specify whether to use an object's real or resolved name in an operation and whether to perform the operation only on objects in a specified overlay group, use the AR_SESS_CONTROL_PROP_DESIGN_OVERLAYGROUP variable of the ARSetSessionConfiguration function (see ARSetSessionConfiguration).

schema

The name of the form containing the field to update.

fieldId

The internal ID of the field to update.

fieldName

The new name for the field. The names of all fields and VUIs associated with a given form must be unique. Specify NULL for this parameter if you do not want to change the name of the field.

fieldMap

A pointer to a mapping structure that specifies the underlying form that contains the field to be updated. To update a field in a base form, specify a field type of 1 (AR_FIELD_REGULAR) in the structure. Otherwise, specify a field type of 2 (AR_FIELD_JOIN) and identify the member form (primary or secondary) and field ID for the new field. If the member form is also a join form, map the field to an underlying form. See Mapping fields in schemas. Specify NULL for this parameter if you do not want to change the field mapping.

option

A flag that indicates whether users must enter a value in the field.

1:

Required (data fields only) (AR_FIELD_OPTION_REQUIRED).

2:

Optional (data fields only) (AR_FIELD_OPTION_OPTIONAL).

3:

System (core data fields only) (AR_FIELD_OPTION_SYSTEM).

4:

Display-only (nondata fields only) (AR_FIELD_OPTION_DISPLAY).

 

Specify NULL* for this parameter if you do not want to change this flag.

createMode

A flag that indicates the permission status for the field when users submit entries. This parameter is ignored for display-only fields.

1:

Any user (including guest users) can enter data in the field when submitting (AR_FIELD_OPEN_AT_CREATE).

2:

Only users who have been granted permission can enter data in the field when submitting (AR_FIELD_PROTECTED_AT_CREATE).

 

Specify NULL for this parameter if you do not want to change 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. (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 value to apply if a user submits an entry with no field value (only applicable to data fields). The default value can be as many as 255 bytes in length (limited by AR_MAX_DEFAULT_SIZE) and must be of the same data type as the field. Specify 0 (AR_DEFAULT_VALUE_NONE) for trim and control fields or to assign no default. Specify NULL for this parameter if you do not want to change the default value.

permissions

A list of zero or more groups who can access this field. Specify an empty permission list to define a field accessible only by users with administrator capability. Specify group ID 0 (Public) to provide access to all users. The permission value that you assign for each group determines whether users in that group can modify the field. See Permissions and structures.

The permission list that you specify replaces all existing group privileges. Specify NULL for this parameter if you do not want to change the permissions.

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 modifying. The limits and properties that you assign must be of the same data type as the field. Specify 0 (AR_FIELD_LIMIT_NONE) for trim and control fields or if you do not want to assign any limits or field type-specific properties. Specify NULL for this parameter if you do not want to change the field limits and properties.

dInstanceList

A list of zero or more display properties to associate with the field. See ARCreateField for a description of the possible values. You can define both properties common to all form views (VUIs) and display properties specific to particular views. The system includes the field in each view that you specify, regardless of whether you define any display properties for those views. If you do not specify a property for a particular view, the system uses the default value (if defined). Specify a list with zero items to remove all display properties for the field. Specify NULL for this parameter if you do not want to change this list.

helpText

The help text associated with the field. This text can be of any length. Specify NULL for this parameter if you do not want to change the help text.

owner

The owning user for the field. Specify NULL for this parameter if you do not want to change the owner.

changeDiary

The additional change diary text to associate with the field. This text can be of any length and is appended at the end of any existing text. Existing change diary text cannot be deleted or changed. 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 add to the change diary.

setFieldOptions

A bitmask for requesting special treatment of display instance items. You can set either (but not both) of the following bits:

Bit 0:

The server replaces its display instance items for this field that are present in the ARDisplayInstanceList argument to ARSetField( ). The server does not modify or replace display instance items for this field that are not present in the list. (AR_SETFIELD_OPT_PRESERVE_UNLISTED_DISPLAY_INSTANCES)

Bit 1:

The server deletes the display instance items for this field present in the ARDisplayInstanceList arguments to ARSetField( ). The server does not modify, replace, or delete any other display instance item. (AR_SETFIELD_OPT_DELETE_LISTED_DISPLAY_INSTANCES)

 

If both bits are set to 0, the server replaces all display instance items for this field with the values passed in dInstanceList.

objPropList

A list of server object properties. If this parameter is set to NULL, no object properties are set. See Server object properties and structures.

Return values

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, ARDeleteField, ARGetField, ARGetListField, ARGetMultipleFields, ARSetMultipleFields. See FreeAR for: FreeARDisplayInstanceList, FreeARFieldLimitList, FreeARPermissionList, FreeARStatusList, FreeARValueStruct.

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

Comments