Document revision date: 15 July 2002

By default, duplicate keys are not allowed for the primary key and its value cannot change.

If the XABKEY control block is not initialized by the $XABKEY macro, then the defaults for alternate keys are the same as for primary keys and null key values are not used. However, if the XABKEY control block is initialized by the $XABKEY macro, the following defaults apply to alternate keys:

• Duplicate key values are allowed.
• Key values can change.
• Null key values are not allowed.

These defaults are applied only if the entire XAB$B_FLG field is defaulted.

Note that RMS supports alternate indexes that do not allow duplicate key values but do allow key values to change for Update services. Older versions of RMS-11 (in contrast to RMS) do not allow this particular combination of attributes for alternate indexes. This factor should be considered when you create files with RMS that may also be processed by RMS-11.

This option corresponds to the FDL attribute KEY NULL_KEY.

14.13 XAB$B_IAN Field

The index bucket area number (IAN) field contains a numeric value in the range 0 through 254, representing an area identification number contained in the XAB$B_AID field of a XABALL present in the same chain. The default is 0 (that is, area 0).

When you create an indexed file, you use this argument to specify the area of the file that the index buckets are to reside in only when both of the following are true:

• You are creating a new indexed file.
• You are using allocation XABs to define areas.

When the XABKEY describes the primary key, the index level of the index consists of all levels of the tree-structured primary index down to and including the level containing pointers to the user data records themselves. However, when the key definition describes an alternate key, the index level of the index comprises all levels of the tree-structured alternate index down to, but not including, the level containing buckets with pointer arrays that describe the user data records. For directions about how to place the lowest level of the index in a location separate from the higher levels, see the description of the XAB$B_LAN field.

This field corresponds to the FDL attribute KEY INDEX_AREA.

14.14 XAB$B_IBS Field

After an Open or Display service, the index bucket size (IBS) field contains the size of the index level (level 1 to n buckets, in virtual blocks, for the key described by the XAB).

14.15 XAB$W_IFL Field

The index bucket fill size (IFL) field contains a numeric value representing the maximum number of bytes in an index bucket. The maximum possible fill size is the bucket size, in blocks, multiplied by 512. The default value is 0, meaning 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 argument to specify the number of bytes you want in each index bucket. If you specify less than the total possible bucket size, you indicate that the index buckets are to contain some amount of free space. At run time, RMS uses the fill size specified at creation time if the LOA option is specified in the RAB$L_ROP (record-processing options) field of the RAB; otherwise, RMS fills the buckets.

When a XABKEY describes the primary key, the XAB$W_IFL field describes the space in the buckets in all levels of the primary index down to and including the level containing pointers to the user data records. When a XABKEY describes an alternate key, the XAB$W_IFL field describes the space in the buckets in all levels of the alternate index down to, but not including, the level containing buckets with pointer arrays that describe the user data records.

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

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

14.16 XAB$L_KNM Field

The key name buffer address (KNM) field contains the symbolic address of a buffer that is available for assigning a user-specified name to the key being defined. The name buffer must be at least 32 bytes in length and you may use any 32-character string you choose to name the key field.

If the default value is taken (0), no name is to be assigned to the key. RMS does not use this string but retains it in the file as part of the key definition information for documentation purposes.

This field corresponds to the FDL attribute KEY NAME.

14.17 XAB$B_LAN Field

The lowest level of index area number (LAN) field contains a numeric value (0 through 254) representing an area identification number contained in the XAB$B_AID field of a XABALL present in the same XAB chain. If the XAB$B_LAN field is not specified (that is, if the value is 0), the value in the XAB$B_IAN field is used as a default; in other words, the lowest level of the index occupies the same area of the file as the remainder of the index.

This field permits you to separate the lowest level (level 1) of the index from all higher levels (levels 2+) of the index in an indexed file; you can use the XAB$B_LAN field to specify an area of the index wherein the lowest level of the index resides, separate from the area (or areas) specified by the XAB$B_IAN field (wherein all other levels of the index reside). See XAB$B_IAN for additional information.

You can specify the XAB$B_LAN field only when both of the following conditions exist:

• You are creating a new indexed file.
• You are using allocation XABs to define areas.

Note that the area specified by the XAB$B_LAN field must have the same bucket size as the area specified by the XAB$B_IAN field.

This field corresponds to the FDL attribute KEY LEVEL1_INDEX_AREA.

14.18 XAB$B_LVL Field

Following an Open or Display service, the level of root bucket (LVL) field contains the level of the root bucket for the key described by the XAB.

14.19 XAB$W_MRL Field

Following an Open or Display service, the minimum record length (MRL) field contains the minimum record length (in bytes) needed to contain the key field for the key described by the XAB.

If the key described by the XAB is the primary key (XAB$_REF is 0), then a record must be equal to or greater than the minimum record length returned in XAB$W_MRL to be inserted or updated in the file.

If the key described by the XAB is an alternate key (XAB$_REF is greater than 0), then a record must be equal to or greater than the minimum record length returned in the XAB$W_MRL field to be recorded in the associated index for that alternate key.

14.20 XAB$B_NSG Field

Following an Open or Display service, the number of key segments (NSG) field contains the number of key segments that make up the key field for the key described by the XAB (see the XAB$W_POS0 through XAB$W_POS7 field).

14.21 XAB$B_NUL Field

Normally, RMS updates all indexes to reflect the values in the corresponding key fields of the records written to an indexed file. The XAB$B_NUL field permits you to instruct RMS not to make an entry in an alternate index if a record being entered in an indexed file contains a specified null alternate key value. To specify the XAB$B_NUL field, three conditions must be satisfied:

• The XABKEY must define an alternate key.
• The XAB$B_FLG field XAB$V_NUL option must be set when you create the file (see XAB$B_FLG).
• The key data type must be string.

You can use any ASCII character in the null (NUL) field when you define a string-type alternate key (string, descending string, collated, descending collated). If you do not specify a null value, RMS assigns the key a default null value of 0.

This field corresponds to the FDL attribute KEY NULL_VALUE.

14.22 XAB$L_NXT Field

The next XAB address (NXT) field contains the symbolic address of the next XAB. A value of 0 (the default) indicates that the current XAB is the last (or only) XAB in the chain.

14.23 XAB$W_POS0 Through XAB$W_POS7 Field

There are two types of keys: simple keys and segmented keys.

A simple key is made up of one or more contiguous bytes and it may be used with any data type, including the string data type. For simple keys, the first byte of the key position field contains a byte offset relative to the beginning of the record buffer that defines the starting position of the key. The remaining bytes contain zeros.

Segmented keys include two through eight strings of key data (segments) and can only be used with string data type key fields. The key segments need not be contiguous nor must they be in a particular order. Key segments may overlap except for primary keys used with Prolog 3 files. If your application requires overlapping key segments in a Prolog 3 file, consider using an alternate segmented key. If you must have a primary key with overlapping segments, RMS requires you to use either a Prolog 2 or Prolog 1 structure (which it automatically assigns if the XAB$B_PROLOG field is not specified).

For segmented keys, the first word of the key position field specifies the starting position of the first segment and each succeeding byte specifies the starting position of one of the remaining segments. When processing records that contain segmented keys, RMS regards a segmented key field as a single, logically contiguous string beginning with the first segment and ending with the last.

You should note that the XAB$W_POS0 through XAB$W_POS7 and the XAB$B_SIZ0 through XAB$B_SIZ7 (key size) fields must define the same number of key position values and key size values.

This field corresponds to the FDL attributes KEY POSITION and SEGn_LENGTH.

14.24 XAB$B_PROLOG Field

The prolog (PROLOG) field defines the version or structure level of the file index. It contains a numeric value from 0 through 3.

The XAB$B_PROLOG field is input to the Create service, and it is returned by the Display and Open services.

This field must only be used to define a primary key.

Prolog 3 is the default prolog level, unless the primary key contains overlapping segments. RMS examines the key characteristics and determines the correct prolog structure to apply to the file. If the XAB$B_PROLOG field is not specified (that is, if the value is 0), the process default prolog level is examined, then the system default prolog level is used. These default values are set by the DCL command SET RMS_DEFAULT/PROLOG.

You should not specify a prolog level 1 because RMS decides whether a Prolog 1 or Prolog 2 file should be created, depending on the key type defined for the file. If you want to select a prolog level other than Prolog 3, you should select either 0 or 2.

For more detailed information regarding the options for selecting a specific prolog level, see the description of the Create service in Part 3.

This field corresponds to the FDL attribute KEY PROLOG and it is not supported for DECnet for OpenVMS operations; the default prolog in effect at the remote node is used.

14.25 XAB$B_REF Field

The key of reference (REF) field defines a key as either the primary key or some alternate key.

This field contains a numeric value in the range 0 through 254. A value of 0 indicates that this is the primary key; a value of 1 indicates the first alternate key; a value of 2 indicates the second alternate key, and so on. The order of the XABKEYs is irrelevant.

Note that RMS can process an indexed file with 255 defined keys; each defined key field, however, has an associated cost in processing and I/O time. The time required to build and maintain the index for the key field and the disk storage required to contain the index for each key field should be considered when you decide whether the field should be an alternate key field. A file with six to eight defined keys (the primary key and five to seven alternate keys) should be considered as a maximum; a file with two or three defined keys is typical.

This field corresponds to the FDL attribute KEY n, where n is the number of the key being defined.

14.26 XAB$L_RVB Field

After an Open or Display service, the root index bucket virtual block number (RVB) field contains the virtual block number for the root bucket of the index for the key described by the XAB.

14.27 XAB$B_SIZ0 Through XAB$B_SIZ7 Field

The key size (SIZ) field defines the length of the key field within each record. This field contains a numeric value representing the length, in bytes, of the key within the record. Up to eight values can be assigned; maximum values depend on the type of key.

The XAB$B_SIZ0 through XAB$B_SIZ7 field defines the length (in bytes) of the key whose starting position is defined in the key position field of the XAB. Two types of keys can be defined: simple and segmented (see the XAB$W_POS0 through XAB$W_POS7 field).

For a simple key, the XAB$B_SIZ0 through XAB$B_SIZ7 field contains only one key size value (in XAB$B_SIZ0).

For a segmented key, the XAB$B_SIZ0 through XAB$B_SIZ7 field contains a key size value for each segment of the key. You should note that the XAB$B_SIZ0 through XAB$B_SIZ7 field and the XAB$W_POS0 through XAB$W_POS7 field must contain the same number of key size values and key position values. RMS associates the first key position value with the first key size value to define the location and length of the first segment of a segmented key, and so forth.

When the data type of the key is string, the total size (sum of all sizes) of the key must be less than 256 bytes.

When the data type of the key is 2-byte integer or 2-byte binary, XAB$B_SIZ0 must equal 2 and XAB$B_SIZ1 through XAB$B_SIZ7 must contain 0. If the size is 0, it defaults to 2.

When the data type of the key is 4-byte integer or 4-byte binary, XAB$B_SIZ0 must equal 4 and XAB$B_SIZ1 through XAB$B_SIZ7 must contain 0. If the size is 0, it defaults to 4.

When the data type of the key is 8-byte integer or 8-byte binary, XAB$B_SIZ0 must equal 8 and XAB$B_SIZ1 through XAB$B_SIZ7 must contain 0. If the size is 0, it defaults to 8.

When the data type of the key is packed decimal, the size specified by XAB$B_SIZ0 must be from 1 through 16, and XAB$B_SIZ1 through XAB$B_SIZ7 must contain 0.

This field corresponds to the FDL attribute KEY LENGTH or KEY SEG n_LENGTH, where n is the number of the segment being defined.

14.28 XAB$B_TKS Field

After an Open or Display service, the total key size (TKS) field contains the total key size (the sum [in bytes] of XAB$B_SIZ0 through XAB$B_SIZ7) for the key described by the XAB.

The protection XAB (XABPRO) specifies the ownership, accessibility, and protection for a file. Although an application program typically uses a XABPRO as input to establish file protection when it creates a file, it can also use the XABPRO to change file protection when it closes a file. The program that opened the file can change file protection when it closes the file only if it accessed the file to make modifications (FAC = PUT, UPDATE, DELETE, or TRUNCATE) and has control access. Control access grants to the file accessor all of the file access privileges of the file owner.

For more information about control access, see the OpenVMS Guide to System Security.

RMS also uses the XABPRO to return file protection information to the application program by way of the Display service and the Open service.

15.1 Summary of Fields

The symbolic offset, the FDL equivalent, and a brief description of each XABPRO field are presented in Table 15-1.

Table 15-1 XABPRO Fields

Field Offset	FDL Equivalent	Description
XAB$L_ACLBUF 3	None	Address of buffer that contains ACL
XAB$L_ACLCTX 3	None	ACL positioning context
XAB$W_ACLLEN 3	None	Receives the length of an ACL during an Open or Display service
XAB$W_ACLSIZ 3	None	Length of buffer containing binary ACEs
XAB$L_ACLSTS 3	None	System error status for ACL processing
XAB$B_BLN 1	None	Block length
XAB$B_COD 1	None	Type code
XAB$W_GRP 2	FILE OWNER	Group number of file owner
XAB$W_MBM 2	FILE OWNER	Member number of file owner
XAB$B_MTACC	FILE MT_PROTECTION	Magnetic tape accessibility
XAB$L_NXT	None	Next XAB address
XAB$W_PRO	FILE PROTECTION	File protection; contains four separate fields denoting protection for system, owner, group, and world
XAB$B_PROT_OPT	None	File protection options
XAB$L_UIC	FILE OWNER	User identification code; contains both the group and member fields

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

15.2 XAB$L_ACLBUF Field

The ACL buffer field (ACLBUF) stores the address of a buffer area that contains an access control list (ACL) for this file. The ACL buffer contains one or more access control entries (ACE) in binary format. The system processes the ACL until it encounters an ACE with a length byte value of 0 or until it reaches the end of the buffer as indicated by XAB$W_ACLSIZ. The ACL buffer is used as input to a Create service and as output from an Open or Display service. The address in XAB$L_ACLBUF is used only as input to these services.

During a Create operation, if the XAB$L_ACLBUF field has a value other than 0, RMS attempts to create the file using the value in the ACL buffer. When the XAB$L_ACLBUF field has a value of 0 during a Create operation, the file has an ACL only if an ACL is specified by the systemwide defaults. Once a file has been created, the ACL cannot be changed using RMS.

During an Open or a Display operation, if the XAB$L_ACLBUF field has a value other than 0, RMS passes this address to the file system. The file system then fills the user's buffer with the file's ACL (in binary format). If the entire ACL does not fit into the user's buffer, the file system puts only as many ACEs as possible into the buffer. (See the XAB$L_ACLCTX field for more information.)

You can convert an ASCII ACL to binary format by using the $PARSE_ACL system service, and you can convert an ACL from binary format to ASCII using the $FORMAT_ACL system service. For information about using the $PARSE_ACL and $FORMAT_ACL services, see the OpenVMS System Services Reference Manual.

The use of this field for DECnet for OpenVMS remote file access is not supported.

15.3 XAB$L_ACLCTX Field

The XAB$L_ACLCTX field is used as a placeholder by RMS, and it is used as an input and output field by RMS during Open and Display operations when the XAB$L_ACLBUF field has a value other than 0. In order to read an ACL beginning with the first ACE, the XAB$L_ACLCTX field must have a value of 0. When the initial Open or Display operation is complete, RMS fills the XAB$L_ACLCTX field with a value that serves as a context field, allowing subsequent Open or Display operations that read the remainder of the ACL (if the entire list of ACEs did not fit into the user's buffer).

For example, suppose you perform an Open operation, find that the value of XAB$W_ACLLEN is greater than the ACL buffer, and then perform Display operations until all of the ACEs in the ACL have been returned. You can then reread the entire ACL on subsequent Opens or Displays only if you set the value of the XAB$L_ACLCTX field to 0.

The use of this field for DECnet for OpenVMS remote file access is not supported.

	privacy and legal statement
4523PRO_019.HTML