ARSetMultipleFields

Description

Updates the definition for a list of fields with the specified IDs on the specified form on the specified server. A call to this function produces the same result as a sequence of ARSetField calls to update the individual fields, but it can be more efficient because it requires only one call from the client to the AR System server and because the server can perform multiple database operations in a single transaction and avoid repeating operations such as those performed at the end of each individual call.

The list input arguments define the field updates the server performs. Each list type consists of a count and a pointer to an array of values. If all values in a list are NULL, the argument can be NULL or a zero-length list. All list counts that are not zero must be equal.

If a failure occurs when modifying an individual field definition, the error is recorded in the setFieldStatusList return value, AR_WARN_SET_FIELD_FAILED is added to the status return value (if it is not already recorded), and the server continues to modify the other fields in the list. If errors occur only during individual field updates, no failure is recorded in the status return value, so the call is considered successful.

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

AR System administrator.

Synopsis

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 an existing form on the server. The fields must all be on that form.

fieldIdList

A list of the internal IDs of the fields to update.

fieldNameList

A list of pointers to new names for the fields. The names of all fields and VUIs associated with a given form must be unique.

To leave the name of a field unchanged, put a NULL field name pointer in corresponding list item. To leave all field names unchanged, pass NULL for this parameter.

fieldMapList

A list of pointers to mapping structures that specify the underlying form for each field to be updated. To update a fields in a base form, specify a field type of 1 (AR_FIELD_REGULAR) in all structures in the list. 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, create fields in all nested join forms until you can map the field to an underlying base form. See Mapping fields in schemas.

To leave the mapping for a field unchanged, put a NULL field mapping pointer in corresponding list item. To leave all field mappings unchanged, pass NULL for this parameter.

optionList

A list of pointers to values that specify whether users must enter a value in the field.

To leave the option unchanged for a field, put a NULL pointer in the corresponding list item. To leave all options unchanged, pass NULL for this parameter.

createModeList

A list of pointers to values that specify the permission status for the field when users submit entries. The list entry is ignored for display-only fields.

To leave the create mode unchanged for a field, put a NULL pointer in the corresponding list item. To leave all field create modes unchanged, pass NULL for this parameter.

fieldOptionList

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

To leave the field option unchanged for a field, put a NULL pointer in the corresponding list item. To leave all field options unchanged, pass NULL for this parameter.

defaultValList

A list of pointers to the values to apply to the corresponding data field when a user submits an entry with no field value. 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. To remove the default value for a field, put AR_DEFAULT_VALUE_NONE in the corresponding list item.

For trim, control, panel, and panel holder fields or to leave the default value for a data field unchanged, put NULL in the corresponding list item. To leave all default values unchanged, pass NULL for this parameter.

permissionsListList

A list of pointers to lists of zero or more groups who can access the corresponding field. To leave the permission list unchanged for a field, put a NULL pointer in the corresponding list item. To make a field accessible only by users with administrator capability, put an empty permission list in the corresponding list item. To provide access to all users, specify group ID 0 (Public). The permission value that you assign for each group determines whether users in that group can modify the field. See Permissions and structures.

To leave all permission lists unchanged, pass NULL for this parameter.

limitList

A list of pointers to the value limits for the corresponding 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. The limits and properties must be of the same data type as the field. For trim and control fields and to clear all limits and properties for field, put AR_FIELD_LIMIT_NONE in the corresponding list item.

To leave the limits and properties for a field unchanged, put NULL in the corresponding list item. To leave all field limits unchanged, pass NULL for this parameter.

dInstanceListList

A list of pointers to lists of zero or more display properties to associate with the corresponding field. You can define both display 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). To remove all display instance items for a field, put a pointer to a list of zero items in the corresponding list item. To leave the display instance items for a field unchanged, put NULL in the corresponding list item.

To leave all field display instance items unchanged, pass NULL for this parameter.

Compare the description of setFieldOptionList to understand how that parameter can affect the behavior of dInstanceListList.

helpTextList

A list of pointers to the help text associated with the corresponding field. The text can be of any length. To leave the help text for a field unchanged, put NULL in the corresponding list item.

To leave all field help text unchanged, pass NULL for this parameter.

ownerList

A list of pointers to the owner for the corresponding field. To leave the owner for a field unchanged, put NULL in the corresponding list item.

To leave all field owners unchanged, pass NULL for this parameter.

changeDiaryList

A list of pointers to the additional change diary text to add to the change diary of the corresponding field. The text can be of any length and is appended at the end of any existing change diary text. The 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. To leave the change diary for a field unchanged, put NULL in the corresponding list item.

To leave all field change diaries unchanged, pass NULL for this parameter.

setFieldOptionList

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

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

To specify default processing for all fields, pass NULL for this parameter.

objPropListList

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

Return values

setFieldStatusList

A list of status list structures corresponding to each field being modified. If an error occurs during the modification of a field, the corresponding status reports it. If any error occurs during any field modification, the status list contains a warning, AR_WARN_SET_FIELD_FAILED, to indicate that the detailed error information is in this parameter.

status

A list of zero or more notes, warnings, or errors generated from a call to this function. The warning, AR_WARN_SET_FIELD_FAILED, indicates that an error occurred during one or more of the field modifications. See the setFieldStatusList parameter for detailed error information. For a description of all possible values, see Error-checking.

See also

ARCreateMultipleFields, ARSetField. See FreeAR for: FreeARAccessNamePtrList, FreeARDisplayInstanceListPtrList, FreeARFieldLimitPtrList, FreeARFieldMappingPtrList, FreeARInternalIdList, FreeARNamePtrList, FreeARPermissionListPtrList, FreeARStatusList, FreeARTextStringList, FreeARUnsignedIntList, FreeARValuePtrList.