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:
| Integer that specifies the data type of the field (see the following table). |
| Limits to assign (represented by structures appropriate to the type of value). |
0 | AR_FIELD_LIMIT_NONE | Field has no defined limits. |
1 | AR_DATA_TYPE_KEYWORD | Integer that specifies the particular keyword (defined in the ar.h file). |
2 | AR_DATA_TYPE_INTEGER | Lower and upper range limits, defined by using |
3 | AR_DATA_TYPE_REAL | Lower and upper range limits, defined by using |
4 | AR_DATA_TYPE_CHAR | Maximum field length, defined by using 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 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 |
7 | AR_DATA_TYPE_TIME | UNIX-style date/time stamp (number of seconds since midnight January 1, 1970). |
8 | AR_DATA_TYPE_BITMASK | 32-bit unsigned integer in which each bit represents a flag turned on or off. |
9 | AR_DATA_TYPE_BYTES | List of bytes containing binary data (represented the ARByteList structure). |
10 | AR_DATA_TYPE_DECIMAL | Lower and upper range limits, defined by using |
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 |
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 |
13 | AR_DATA_TYPE_DATE | Lower and upper range limits, defined by using |
14 | AR_DATA_TYPE_TIME_OF_DAY | Time 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 |
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 |
40 | AR_DATA_TYPE_ULONG | 32-bit unsigned integer. |
41 | AR_DATA_TYPE_COORDS | List of ( x, y ) coordinate pairs. |
42 | AR_DATA_TYPE_VIEW | View field, defined by using |
43 | AR_DATA_TYPE_DISPLAY | Values for flashboards for display fields, defined by using |
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 oneARPropList
structure. Those specific to a particular schema view
These display properties are collected in a series of additionalARPropList
structures, each linked to a particular view (VUI). These view-specific property lists are represented by zero or moreRDisplayInstanceStruct
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 anARDisplayInstanceList
structure (see the following figure).
Structures used to define field display properties
ThedInstanceList
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:
| Integer that specifies the display property. For a list of valid integers, see Server object property tags. |
| 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:
| Internal ID associated with the schema view. |
| 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:
| Integer that specifies the type of field (see the following table). |
|
|
|
|
|
|
|
|
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:
| Integer that specifies the member schema the field maps to (see the following table). |
| 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.
Comments
Log in or register to comment.