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:

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:

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

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:

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:

The ARJoinMappingStruct structure has the following components:

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.