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

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

Fields and structures

The following section describes some of the structure types related to creating, retrieving, and modifying field definitions. Each of the structures is used as a parameter type for the following functions:

Defining field limits

The limit parameter defines the value limits for a data field. The field's data type determines the type of limits you can specify. This parameter is a pointer to an ARFieldLimitStruct structure (see the following figure).

Structures used to define field value boundaries 

 

ARFieldLimitStruct enables you to define value limits for data fields of any type, much like ARValueStruct enables you to specify values of any data type (see Structures used to represent any value).

The ARFieldLimitStruct structure has the following elements:

Data Type

Integer that specifies the data type of the field (see the following table).

Limit

Limits to assign (represented by structures appropriate to the type of value).

0

AR_FIELD_LIMIT_NONE

Field has no defined limits.

1AR_DATA_TYPE_KEYWORDInteger that specifies the particular keyword (defined in the ar.h file).

2

AR_DATA_TYPE_INTEGER

Lower and upper range limits, defined by using ARIntegerLimitsStruct.

3

AR_DATA_TYPE_REAL

Lower and upper range limits, defined by using ARRealLimitsStruct. You can also specify the display precision to use.

4

AR_DATA_TYPE_CHAR

Maximum field length, defined by using ARCharLimitsStruct. Specify zero to indicate no maximum. You can also specify a character menu to attach (and whether selecting from the menu appends or overwrites text already in the field), a default query-by-example qualification type, a field character pattern, and whether the field is indexed for full text search (FTS).

Note: For more information about storing long character strings, see the Input Length database property in Field Properties

5

AR_DATA_TYPE_DIARY

Specifies whether the field is indexed for FTS by using ARDiaryLimitStruct.

Note: For more information about storing long character strings, see the Input Length database property in Field Properties

6

AR_DATA_TYPE_ENUM

Values for an enumerated list, defined by using AREnumListsStruct (required). Only AR_ENUM_STYLE_REGULAR is implemented. The set of integers (beginning with zero) represents possible selection values; the field value limit is defined by using ARNameList as a string of values for each selection. For the form of the list structure, see Lists and structures.

7AR_DATA_TYPE_TIMEUNIX-style date/time stamp (number of seconds since midnight January 1, 1970).
8AR_DATA_TYPE_BITMASK32-bit unsigned integer in which each bit represents a flag turned on or off.
9AR_DATA_TYPE_BYTESList of bytes containing binary data (represented the ARByteList structure).

10

AR_DATA_TYPE_DECIMAL

Lower and upper range limits, defined by using ARDecimalLimitsStruct . You can also specify the precision.

11

AR_DATA_TYPE_ATTACH

Maximum size of the attachment and attachment type (embedded is the only type supported at this time), defined by using ARAttachLimitsStruct.

12

AR_DATA_TYPE_CURRENCY

Schema currency field value. Lower and upper range limits, precision, allowable currency definitions, and functional currency definitions, defined by using ARCurrencyLimitsStruct.

13

AR_DATA_TYPE_DATE

Lower and upper range limits, defined by using ARDateLimitsStruct.

14AR_DATA_TYPE_TIME_OF_DAYTime of day field. The value is the integer number of seconds since 12:00:00 a.m.

33

AR_DATA_TYPE_TABLE

Number of columns, search qualification, maximum number of rows to retrieve, schema name, and server name of the table, defined by using ARTableLimitsStruct.

34

AR_DATA_TYPE_COLUMN

Parent field ID, data field ID (the remote field ID from the data source), data source (the data source for the data field, which can be a data field on a display-only field), and number of characters to display, defined by using ARColumnLimitsStruct.

40AR_DATA_TYPE_ULONG32-bit unsigned integer.
41AR_DATA_TYPE_COORDSList of ( x, y ) coordinate pairs.

42

AR_DATA_TYPE_VIEW

View field, defined by using ARViewLimits.

43

AR_DATA_TYPE_DISPLAY

Values for flashboards for display fields, defined by using ARDisplayLimits.

Defining field display properties

Field display properties (AR_DPROP_*) fall into these categories:

  • Those common to all schema views
    These display properties are collected in one ARPropList structure.
  • Those specific to a particular schema view
    These display properties are collected in a series of additional ARPropList structures, each linked to a particular view (VUI). These view-specific property lists are represented by zero or more RDisplayInstanceStruct structures.

    Note

    For information about field object properties (AR_OPROP_*), see Server object properties and structures.

    Both display property types are represented as lists of zero or more properties in an ARPropList structure. All of these structures are collected in an ARDisplayInstanceList structure (see the following figure).

    Structures used to define field display properties

       
    The dInstanceList parameter is a pointer to a structure of this type and is used to pass all field display properties when field definitions are created, retrieved, or modified.

The common display properties are represented by an embedded ARPropList structure. This list contains zero or more items, each representing one display property. The ARPropStruct structure has the following elements:

Property Tag

Integer that specifies the display property. For a list of valid integers, see Server object property tags.

Value

Value for the property represented by ARValueStruct (see Group information and structures).

 The instance display properties are represented as a series of ARDisplayInstanceStruct structures, each of which has the following elements:

VUI ID

Internal ID associated with the schema view.

Display Properties

Field display properties specific to that view represented by ARPropList .

 Each ARDisplayInstanceStruct represents a display instance for the field. Specifying a schema view in the ARDisplayInstanceList structure includes the field in the view, even if you do not define any display properties specific to that view. In this case, the system uses properties defined in the common properties list.

Note

The ARPropList structure is also used by the ARCreateVUI, ARGetVUI, and ARSetVUI functions (see BMC Remedy AR System C API functions). The dPropList parameter is a pointer to a structure of this type and is used to pass view-type display properties. This data structure is also used for handling object properties (see Server object properties and structures for more information).

Using ARCoordList to specify field size and location

To specify the size and location of certain fields and their components, use the ARCoordList data type. These values are scaled by BMC Remedy AR System clients so that fields appear consistent across different user environments.

Bounding boxes and coordinate lists

  • AR_DPROP_BBOX and AR_DPROP_COORDS display properties are ARCoordList structures.
  • AR_DPROP_BBOX properties identify the bounding box, or screen boundaries, for screen elements.
  • AR_DPROP_COORDS identifies the screen location for lines and boxes.

When specifying coordinate values for these properties, remember this:

  • The order in which you specify coordinate pairs is important.
  • Horizontal and vertical are the only line orientations currently supported by BMC Remedy Developer Studio. Neither client displays diagonal lines for lines or boxes if you specify coordinates that are not on the same x - or y -axis.

Coordinate value scaling

To minimize display differences across a variety of operating systems and screen resolutions, clients normalize all coordinate values before storing them in the database. They map these values to pixels in the current environment on retrieval. For BMC Remedy Developer Studio to display a field correctly, apply the same translation algorithms when specifying or retrieving coordinate data.

Use this algorithm to normalize coordinate values before storing them:

Normalized = (Pixel * AR_FIXED_POINT_PRECISION * staticFontMetric) / (dynamicFontMetric *  platformScale)



Use this algorithm to map coordinate values to pixels on retrieval:

Pixel = ((Normalized * dynamicFontMetric / staticFontMetric / platformScale) + (AR_FIXED_POINT_PRECISION / 2)) / AR_FIXED_POINT_PRECISION

The value for AR_FIXED_POINT_PRECISION is 100 on all platforms. The other equation values are platform-specific. This table lists the Windows values:

Equation component

x value

y value

Static Font Metric

9

13

Dynamic Font Metric (using System font style)

(Average character width + maximum character width) / 2

Font height

Platform Scale

1.0

1.0

Mapping fields in schemas

Because schemas (including join, view, and external forms) are logical objects, not actual data tables, you must map each field in a schema to a field in an underlying base schema. This mapping is specified by the fieldMap parameter, which is defined as a pointer to an ARFieldMappingStruct structure (see the following figure).

Structures used to map join fields to schema fields

The ARFieldMappingStruct structure has the following elements:

Field Type

Integer that specifies the type of field (see the following table).

Join Mapping

ARJoinMappingStruct structure that defines the join field mapping. It is described in the next paragraph.

Vendor Mapping

ARVendorMappingStruct that contains the name of the field in the external database table.

View Mapping

ARViewMappingStruct that contains the name of the field in the external database table.

Inheritance Mapping

ARInheritanceMappingStruct is defined for future use. Its use in ARFieldMappingStruct is not suppported.

  

1

AR_FIELD_REGULAR

Field in a base schema.

2

AR_FIELD_JOIN

Field in a join schema.

3

AR_FIELD_VIEW

Field in a view schema.

4

AR_FIELD_VENDOR

Field in a vendor schema.

The ARJoinMappingStruct structure has the following components:

Schema Index

Integer that specifies the member schema the field maps to (see the following table).

Field ID

Internal ID associated with the field.

  

0

AR_FIELD_MAPPING_PRIMARY

Primary schema in a join.

1

AR_FIELD_MAPPING_SECONDARY

Secondary schema in a join.

If the member schema is also a join schema, you must create fields in all nested join schemas until you can map the field to an underlying base schema.

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

Comments