ARCreateMultipleFields

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 ARCreate* function creates a custom object that belongs to that group. If no group is specified, the function creates an origin object. To specify an overlay group, use the AR_SESS_CONTROL_PROP_DESIGN_OVERLAYGROUP variable of the ARSetSessionConfiguration function (see ARGetSessionConfiguration).

schema

The name of an existing form on the server. The fields are created on that form.

fieldIdList

A list of the internal IDs of the fields to create. The IDs of all fields and form views (VUIs) associated with a given form must be unique. If an element of this list is zero, the server generates and returns the ID for the corresponding field. Else, specify a value between 536868912 and 2147483647 (limited by AR_MAX_RESERVED_FIELD_ID in arstruct.h). If you specify a reserved ID, the system generates an error unless the corresponding element in the reservedIdOKList parameter is set to 1 (TRUE). For more information, see Reserved-field-ranges.

reservedIdOKList

A list of flags that specify whether the server should create the corresponding field with a reserved ID. Specify 1 (TRUE) for any element of this parameter to allow a reserved ID for the corresponding field. Specify 0 (FALSE) if you want the system to generate an error when you specify a reserved ID for the corresponding field.

fieldNameList

A list of pointers to the names of the fields to create. The names of all fields and VUIs associated with a given form must be unique. The system uses this name when it creates the SQL view of the form for report writing purposes. The field name is used to identify a field in a workflow object more easily.

The field name is different from the field label in that it is specific to a form, but not specific to a view of the form. See dInstanceListList for information about how to specify a field label. If you want the server to create a default name for a field based on the field ID, specify a NULL field name pointer in the corresponding location in this list.

Specify NULL for this parameter if you want the system to create default names for all the fields.

fieldMapList

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

dataTypeList

A list of the data types of the fields.

optionList

A list of flags that specify whether users must enter a value in the field.

createModeList

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

fieldOptionList

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

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. Specify NULL (or AR_DEFAULT_VALUE_NONE) in the list for trim, control, panel, and panel holder fields or if you do not want to define a default value for a data field.

permissionsListList

A list of pointers to lists of zero or more groups who can access the corresponding field. Specify NULL or an empty permission list for a field to make it accessible to only administrators. Specifying group ID 0 (Public) provides 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.

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 that you define must be of the same data type as the field. Specify NULL (or AR_FIELD_LIMIT_NONE) for trim and control fields or if you do not want to define any limits or properties for the corresponding field.

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 that 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 NULL display instance list pointer in the list if you do not want to define any display properties for the corresponding field.

helpTextList

A list of pointers to the help text associated with the corresponding field. The text can be of any length. Specify a NULL pointer in the list if you do not want to specify help text for the corresponding field.

ownerList

A list of pointers to the owner for the corresponding field. Specify a NULL pointer in the list if you want to default the owner, for the corresponding field, to the user performing the operation.

changeDiaryList

A list of pointers to the change diary text associated with the corresponding field. This text can be of any length. The server adds the user making the change and a time stamp when it saves the change diary. Specify a NULL pointer in the list if you do not want to specify change diary text for the corresponding field.

objPropListList

A list of server object property lists that correspond to the fields in fieldIdList. If this parameter is set to NULL, a list with zero properties is associated with each object, and zero properties are returned when an ARGetField is performed. See Server-object-properties-and-structures.

Return values

fieldIdList

See fieldIdList.

status

A list of zero or more notes, warnings, or errors generated from a call to this function. This function returns error code 488 (AR_ERROR_CREATE_MULT_FIELD_POSITION) when an error occurs in the creation of an individual field. The zero-based position of that field in the list parameters is returned in the appended text of the status item in ASCII character format. Any additional status items refer to the field creation error that occurred. If an error occurs creating an individual field, no fields are created. For a description of all possible values, see Error-checking.