Document revision date: 15 July 2002

The journaling XAB (XABJNL) control block supports file journaling operations. See the RMS Journaling for OpenVMS Manual for details.

You must provide a key definition XAB (XABKEY) for each key in an indexed file in order to define the key's characteristics. Before you create an indexed file, you must establish the contents of the XABKEY fields for the primary key and for each alternate key.

When you invoke an Open or Display service for an existing indexed file, you can use XABKEYs if you want to provide your program with one or more of the key definitions specified when the file was created. Alternatively, the summary XAB (see Chapter 18) provides the number of keys, the number of allocated areas, and the prolog version assigned to the file.

14.1 Summary of Fields

Table 14-1 lists the symbolic offset, the size, the FDL equivalent, and a brief description of each XABKEY field.

Table 14-1 XABKEY Fields

Field Offset	Size (Bytes)	FDL Equivalent	Description
XAB$B_BLN 1	1	None	Block length
XAB$B_COD 1	1	None	Type code
XAB$L_COLNAM	4	None	Collating sequence name
XAB$L_COLSIZ	4	None	Collating sequence table size
XAB$L_COLTBL	4	COLLATING_SEQUENCE	Collating sequence table address
XAB$B_DAN	1	KEY DATA_AREA	Data bucket area number
XAB$B_DBS 2	1	None	Data bucket size
XAB$W_DFL	2	KEY DATA_FILL	Data bucket fill size
XAB$B_DTP	1	KEY TYPE 3	Data type of the key
XAB$L_DVB 2	4	None	First data bucket virtual block number
XAB$B_FLG	1	KEY 3	Key options flag
XAB$B_IAN	1	KEY INDEX_AREA	Index bucket area number
XAB$B_IBS 2	1	None	Index bucket size
XAB$W_IFL	2	KEY INDEX_FILL	Index bucket file size
XAB$L_KNM	4	KEY NAME	Key name buffer address
XAB$B_LAN	1	KEY LEVEL1_INDEX_AREA	Lowest level of index area number
XAB$B_LVL 2	1	None	Level of root bucket
XAB$W_MRL 2	2	None	Minimum record length
XAB$B_NSG 2	1	None	Number of key segments
XAB$B_NUL	1	KEY NULL_VALUE	Null key value
XAB$L_NXT	4	None	Next XAB address
XAB$W_POSn	2	KEY POSITION and SEGn_POSITION	Key position, XAB$W_POS0 to XAB$W_POS7
XAB$B_PROLOG	1	KEY PROLOG	Prolog level
XAB$B_REF 4	1	KEY n	Key of reference
XAB$L_RVB 2	4	None	Root bucket virtual block number
XAB$B_SIZn	1	KEY LENGTH and SEGn_LENGTH	Key size XAB$B_SIZ0 to XAB$B_SIZ7
XAB$B_TKS 2	1	None	Total key field size

Unless otherwise indicated, each field is supported for DECnet for OpenVMS operations on files at remote OpenVMS nodes. For information about the support of RMS options for remote file access to other systems, see the DECnet for OpenVMS Networking Manual.

14.2 XAB$B_BLN Field

The block length (BLN) field is a static field that defines the length of the XABKEY, in bytes. Once set, this field must not be altered unless the control block is no longer needed. The $XABKEY macro initializes the XAB$B_BLN field to the symbolic value XAB$C_KEYLEN.

14.3 XAB$B_COD Field

The type code (COD) field is a static field that identifies this control block as a XABKEY. Once set, this field must not be altered unless the control block is no longer needed. The $XABKEY macro initializes the XAB$B_COD field to the symbolic value XAB$C_KEY.

14.4 XAB$L_COLNAM Field

When you invoke the Display service, RMS uses this field to return a pointer to a memory buffer containing the name of the collating sequence for this key.

The name buffer is in the form of an ASCII counted string where the first byte indicates the length of the name and the remaining bytes are the ASCII representation of the name itself. The maximum length of the buffer is 32 bytes, 1 byte for the count and 31 bytes for the name.

14.5 XAB$L_COLSIZ Field

When you invoke the Display service, RMS returns the size, in bytes, of the collating sequence used with this key to this field.

14.6 XAB$L_COLTBL Field

RMS provides you with a way to use alternative (non-ASCII) collating sequences with indexed file keys. You can define a collating sequence for each key of reference, yielding, for example, a file sorted in German by one key, French by another key, and so forth.

This feature is based on the National Character Set utility, which permits you to define alternative collating sequences for special characters and to establish and maintain a library of collating sequences. This eliminates having to redefine an alternative collating sequence when the application requires it. See the OpenVMS National Character Set Utility Manual for details.

To access an alternative collating sequence for a key, enter the symbolic address of the appropriate collating table in the XAB$L_COLTBL field. For example, you might enter the following:

DST_KEY0: $XABKEY . . . COLTBL=FRENCH, - ;symbolic address of French collating table . . .

RMS responds by storing the specified collating table in the initial blocks of the indexed file immediately following the area descriptors. Collating tables are typically about one block long.

When you invoke the Display or the Open service, RMS returns the address of the collating table in this field.

This field corresponds to the FDL attribute COLLATING_SEQUENCE.

14.7 XAB$B_DAN Field

The data bucket area number (DAN) field contains a numeric value that identifies the area where the data buckets for this key reside. The number reflects the value in the XAB$B_AID field of the XABALL for this XAB chain. The numeric value may range from 0 through 254, but the default is 0; that is, area 0.

When you create a new indexed file or when you use allocation XABs to define areas (see Chapter 9), you must specify a value for this field to identify the file area where the data buckets are to reside.

When a XABKEY describes the primary key, the data level of the index consists of buckets that contain the actual data records of the file. However, when the key definition describes an alternate key, the data level of the index consists of buckets in which RMS maintains pointers to the actual data records.

The XAB$B_DAN field corresponds to the FDL attribute KEY DATA_AREA.

14.8 XAB$B_DBS Field

After an Open or Display service, the data bucket size (DBS) field contains the size of the data level (level 0) buckets, in virtual blocks, for the key described by the XAB.

14.9 XAB$W_DFL Field

The data bucket fill size (DFL) field contains a numeric value that indicates the maximum number of bytes (of data) in a data bucket. The largest possible fill size is the bucket size, in blocks, multiplied by 512. The default value is 0, which is interpreted as the maximum available space (that is, no unused space). If the specified size is not 0, but is less than one-half of the bucket size (in bytes), then the fill size used is one-half of the bucket size.

When you create an indexed file, you use this field to specify the number of bytes of data you want in each data level bucket. If you specify a value that is less than the actual bucket size, the data buckets contain some amount of free space. At run time, RMS uses the fill size specified when the file was created only if the RAB$L_ROP (record-processing options) field RAB$V_LOA option is specified in the RAB; otherwise, RMS fills the buckets.

When a XABKEY describes the primary key, the XAB$W_DFL field describes the space in the buckets containing actual user data records. When a XABKEY describes an alternate key, the XAB$W_DFL field describes the space in the buckets containing pointers to the user data records.

It is advantageous to use the XAB$W_DFL field if you expect to execute numerous random Put and Update services on the file after it has been initially populated. You can minimize the movement of records (bucket splitting) by specifying less than the maximum bucket fill size when you create the file. To use the free space reserved in the buckets, programs that execute Put or Update services on the file should not specify the RAB$L_ROP field RAB$V_LOA option.

This field corresponds to the FDL attribute KEY DATA_FILL (which is expressed as a percentage).

14.10 XAB$B_DTP Field

The XAB$B_DTP field specifies the key data type and the key sort order, ascending or descending.

In this keyword value field, each key data type option is defined by a symbolic value. If the key sort order is descending, the letter D is prefixed to the symbolic value; if the sort order is ascending, the prefix is omitted. For example, a XAB$B_DTP field having the value XAB$C_DBN2 is an unsigned, 2-byte binary number that is sorted in descending order. On the other hand, a XAB$B_DTP field having the value XAB$C_BN2 is an unsigned, 2-byte binary number that is sorted in ascending order.

Only one option can be specified. It is identified by a symbolic constant value; for example, the STG (string) option has the constant value XAB$C_STG.

The options for the XAB$B_DTP field are listed in the following table:

Keyword	Data Type	Sort Order
XAB$C_BN2	Unsigned 2-byte binary	Ascending
XAB$C_DBN2	Unsigned 2-byte binary	Descending
XAB$C_BN4	Unsigned 4-byte binary	Ascending
XAB$C_DBN4	Unsigned 4-byte binary	Descending
XAB$C_BN8	Unsigned 8-byte binary	Ascending
XAB$C_DBN8	Unsigned 8-byte binary	Descending
XAB$C_IN2	Signed 2-byte integer	Ascending
XAB$C_DIN2	Signed 2-byte integer	Descending
XAB$C_IN4	Signed 4-byte integer	Ascending
XAB$C_DIN4	Signed 4-byte integer	Descending
XAB$C_IN8	Signed 8-byte integer	Ascending
XAB$C_DIN8	Signed 8-byte integer	Descending
XAB$C_COL	Collating key	Ascending
XAB$C_DCOL	Collating key	Descending
XAB$C_PAC	Packed decimal string	Ascending
XAB$C_DPAC	Packed decimal string	Descending
XAB$C_STG 1	Left-justified string of unsigned 8-bit bytes	Ascending
XAB$C_DSTG	Left-justified string of unsigned 8-bit bytes	Descending

The string data type may consist of from one to eight detached key field segments that collectively make up the key. For more information about segmented keys, see the descriptions of the XAB$W_POS0 through XAB$W_POS7 field and the XAB$B_SIZ0 through XAB$B_SIZ7 field.

Integer, binary, and packed decimal key fields must be a contiguous set of bytes.

The formats of the binary and integer key field data types are presented in the following table.

Key Type	Format
XAB$C_BN2	LSB at A, MSB at A+1
XAB$C_DBN2	LSB at A, MSB at A+1
XAB$C_BN4	LSB at A, MSB at A+3
XAB$C_DBN4	LSB at A, MSB at A+3
XAB$C_BN8	LSB at A, MSB at A+7
XAB$C_DBN8	LSB at A, MSB at A+7
XAB$C_IN2	LSB at A, MSB and sign at A+1
XAB$C_DIN2	LSB at A, MSB and sign at A+1
XAB$C_IN4	LSB at A, MSB and sign at A+3
XAB$C_IN4	LSB at A, MSB and sign at A+3
XAB$C_IN8	LSB at A, MSB and sign at A+7
XAB$C_DIN8	LSB at A, MSB and sign at A+7

The collating key data types are used in conjunction with collating sequences located in the indexed file prolog. Collating sequences are used with multinational characters and are specified for each key. Note that key compression and index compression are not permitted with collating keys.

Note that although a collating key affects the stored order for records, the collating value does not govern record lookups. For example, a collating sequence may assign the same ordering for the keys "dog" and "DOG". However, both keys do not have the same access (lookup) value. Therefore, when doing lookups, a program should specify either the specific key value or a range of values that include the uppercase and lowercase combinations of the key. See the Guide to OpenVMS File Applications for more information about accessing indexed records.

A packed decimal string is a contiguous sequence of bytes specified by two attributes: the address (A) of the first byte of the string and a length (L) that is the number of digits in the packed decimal. The bytes of a packed decimal are divided into two 4-bit fields that must contain decimal digits, except for the first four bits (0 through 3) of the last (highest addressed) byte, which must contain a sign. The representation for the digits and signs is shown in the following table.

Digit or Sign	Decimal Value	Hexadecimal Value
0	0	0
1	1	1
2	2	2
3	3	3
4	4	4
5	5	5
6	6	6
7	7	7
8	8	8
9	9	9
+	10, 12, 14, or 15	A, C, E, or F
--	11 or 13	B or D

The preferred sign representation is 12 for plus (+) and 13 for minus (--). The length (L) is the number of digits in the packed decimal string (not counting the sign) and must be in the range 0 through 31. When the number of digits is even, an extra 0 digit must appear in the last four bits (4 through 7) of the first byte. Again the length in bytes of the packed decimal is L/2 + 1. The value of a zero-length packed decimal is 0; it contains only the sign byte, which also includes the extra 0 digit.

The address, A, of the packed decimal specifies the byte containing the most significant digit in its high order. Digits of decreasing significance are assigned to increasing byte addresses and from high to low within a byte. Thus, +123 has length 3 and is represented as follows:

Similarly, --12 has length 2 and is represented as follows:

This field corresponds to the FDL attribute KEY TYPE.

14.11 XAB$L_DVB Field

After an Open or Display service, the DVB field contains the starting virtual block number of the first data level bucket for the key described by the XAB.

14.12 XAB$B_FLG Field

The key options flag (FLG) field specifies the following conditions:

• Whether duplicate keys are permitted in the file
• Whether a key value can change
• Whether a null value has been defined for a key
• Whether data is compressed
• Whether string key options apply

  Note The string data-type keys include STRING, DSTRING, COLLATED, and DCOLLATED keys.

Primary key values cannot change, but alternate key values may change, depending on application requirements. Primary and alternate keys may be duplicated depending on the key field and the application. An alternate key field is more likely than a primary key field to use duplicates.

This field is a binary options field where each key characteristic has a corresponding bit assignment. Multiple key characteristics can be associated with each key (multiple bits can be set). Each option in the field has its own symbolic offset and mask value. For example, the CHG key characteristic has a symbolic offset of XAB$V_CHG and a mask value of XAB$M_CHG.

When you create an indexed file and are defining a string key, you can specify the XAB$V_IDX_NCMPR and XAB$V_KEY_NCMPR options, which are described in the following list.

Options

XAB$V_CHG

The key value within the record in the file can be changed by a program during an Update service. This option can be specified only for alternate keys.

This option corresponds to the FDL attribute KEY CHANGES.

XAB$V_DAT_NCMPR

Do not compress data. This option can be specified to override compression of data for Prolog 3 files for the primary key; that is, when XAB$_REF is 0. For additional information, see Guide to OpenVMS File Applications, Section 3.5, Tuning an Indexed File and Subsection 3.5.1.1, Prologs.

This option corresponds to the FDL attribute KEY DATA_RECORD_COMPRESSION.

This option is not supported for DECnet for OpenVMS operations; it is ignored.

XAB$V_DUP

The key value within the record in the file may have the same key value as another record (or other records) within the file.

This option corresponds to the FDL attribute KEY DUPLICATES.

XAB$V_IDX_NCMPR

Do not compress index. This option can be specified to override compression of keys in the index for Prolog 3 files. This option is valid only if a string key is being defined and the string is at least 6 bytes in length. For additional information, see Guide to OpenVMS File Applications, Section 3.5, Tuning an Indexed File and Subsection 3.5.1.1, Prologs.

This option corresponds to the FDL attribute KEY INDEX_COMPRESSION and it is not supported for DECnet for OpenVMS operations.

XAB$V_KEY_NCMPR

Do not compress key. This option can be specified to override compression of each key for Prolog 3 files. For a primary key (XAB$_REF is 0), the primary keys at the data level are not compressed; for each alternate key (XAB$_REF is greater than 0), the secondary index data records (SIDRs) that point to the data record location are not compressed. This option is valid only if a string key is being defined and the string is at least 6 bytes in length. For additional information, see Guide to OpenVMS File Applications, Section 3.5, Tuning an Indexed File and Subsections 3.5.1.1, Prologs.

This option corresponds to the FDL attribute KEY DATA_KEY_COMPRESSION and it is not supported for DECnet for OpenVMS operations.

XAB$V_NUL

The null key option permits you to exclude records from an alternate index by effectively removing the related key. Typically, you would use this in an application where performance is more critical than the indexing capability. This option can be specified only for alternate key indexes but it can be used with all key types.

When you set the XAB$V_NUL bit for a string-type key (string, descending string, collated, descending collated) RMS checks the XAB$B_NUL field to determine the null character you have defined for the related key. When you use the XAB$V_NUL option with the integer, binary, and packed decimal data types, RMS assigns a default null value of 0 and does not check the XAB$B_NUL field (see XAB$B_FLG and XAB$B_NUL).

The defaults and combinations of allowing changeable key values (XAB$V_CHG option) and duplicate key values (XAB$V_DUP option) depend on whether a primary or alternate key is being defined by this XABKEY. The allowed combinations and defaults for duplicate and changeable key values are described in the following table.

Combinations	Primary Key	Alternate Key
XAB$V_CHG and XAB$V_DUP both set	Error	Allowed
XAB$V_CHG set, XAB$V_DUP clear	Error	Allowed
XAB$V_CHG clear, XAB$V_DUP set	Allowed	Allowed
XAB$V_CHG and XAB$V_DUP both clear	Default	Default

	privacy and legal statement
4523PRO_018.HTML