Updated: 11 December 1998 |
OpenVMS Record Management Services Reference
Manual
Previous | Contents | Index |
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.
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.
Key compression and index compression are not permitted with collating keys. |
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 . . . |
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:
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:
The string data-type keys include STRING, DSTRING, COLLATED, and DCOLLATED keys. |
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.
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 |
Previous | Next | Contents | Index |
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
4523PRO_016.HTML
|