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.

ARCreateMultipleFields

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

Creates multiple fields in a form. A call to this function produces the same result as a sequence of ARCreateField calls to create the individual fields, but it can be more efficient. Using this function requires only one call from the client to the BMC Remedy AR System server. 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 ARCreateField call.

If an error occurs while creating an individual field, no fields are created.

The list input arguments define the fields that the server creates. 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.

Privileges

BMC Remedy AR System administrator.

Synopsis

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

int ARCreateMultipleFields(
   ARControlStruct *control,
   ARNameType schema,
   ARInternalIdList *fieldIdList,
   ARBooleanList *reservedIdOKList
   ARNamePtrList *fieldNameList,
   ARFieldMappingList *fieldMapList,
   ARUnsignedIntList *dataTypeList,
   ARUnsignedIntList *optionList,
   ARUnsignedIntList *createModeList,
   ARUnsignedIntList *fieldOptionList,
   ARValuePtrList *defaultValList,
   ARPermissionListPtrList *permissionListList,
   ARFieldLimitPtrList *limitList,
   ARDisplayInstanceListPtrList *dInstanceListList,
   ARTextStringList *helpTextList,
   ARAccessNamePtrList *ownerList,
   ARTextStringList *changeDiaryList,
   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.

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. Otherwise, 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 of 1 (AR_FIELD_REGULAR) in each structure 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 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 to create.

2

AR_DATA_TYPE_INTEGER

Integer

3

AR_DATA_TYPE_REAL

Real

4

AR_DATA_TYPE_CHAR

Character

5

AR_DATA_TYPE_DIARY

Diary

6

AR_DATA_TYPE_ENUM

Selection

7

AR_DATA_TYPE_TIME

Date/time

10

AR_DATA_TYPE_DECIMAL

Fixed-point decimal. Values must be specified in C locale, for example 1234.56

11

AR_DATA_TYPE_ATTACH

Attachment

12

AR_DATA_TYPE_CURRENCY

Currency

31

AR_DATA_TYPE_TRIM

Trim

32

AR_DATA_TYPE_CONTROL

Control

33

AR_DATA_TYPE_TABLE

Table

34

AR_DATA_TYPE_COLUMN

Column

35

AR_DATA_TYPE_PAGE

Panel

36

AR_DATA_TYPE_PAGE_HOLDER

Panel holder

 

optionList

A list of flags that specify 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).

4:

Display-only (data fields only). Works like an optional field but doesn't write to the database (AR_FIELD_OPTION_DISPLAY).

 

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.

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).

 

fieldOptionList

A list of bitmasks that specify 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)

 

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. Put 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.

Specify NULL for this parameter if you do not want to specify default values for all fields.

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 by users with administrator capability only. 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 Field permission values for.

Specify NULL for this parameter to make all fields accessible by users with administrator capability only.

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.

Specify NULL for this parameter if you do not want to specify limits for any 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.

Specify NULL for this parameter if you do not want to specify a display instance list for any 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.

Specify NULL for this parameter if you do not want to specify help text for any 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.

Specify NULL for this parameter if you want to default the owner to the user performing the operation for all fields.

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.

Specify NULL for this parameter if you do not want to specify any change diary text for any 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.

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 occurred 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.

See also

ARCreateField, ARSetMultipleFields. See FreeAR for: FreeARAccessNamePtrList, FreeARBooleanList, FreeARDisplayInstanceListPtrList, FreeARFieldLimitPtrList, FreeARFieldMappingPtrList, FreeARInternalIdList, FreeARNamePtrList, FreeARPermissionListPtrList, FreeARStatusList, FreeARTextStringList, FreeARUnsignedIntList, FreeARValuePtrList.

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

Comments