Document revision date: 15 July 2002

The allocation control XAB (XABALL) provides additional control over file or area space allocation on disk devices in order to optimize performance. In the following descriptions, the terms file and area are synonymous for sequential and relative files because these file organizations are limited to a single area (Area 0).

9.1 Summary of Fields

When RMS uses a XAB to create or extend an area, the following XABALL fields duplicate and take precedence over associated fields in the related FAB:

• The allocation quantity (ALQ) field, XAB$L_ALQ, overrides FAB$L_ALQ
• The bucket size (BKZ) field, XAB$B_BKZ, overrides FAB$B_BKS
• The default extension quantity (DEQ) field, XAB$W_DEQ, overrides FAB$W_DEQ
• The XAB$V_CBT and XAB$V_CTG options of the allocation options field, XAB$B_AOP, override the FAB$V_CBT and FAB$V_CTG options of the file-processing options field, FAB$L_FOP

When opening a file or displaying a file's attributes, RMS outputs appropriate information to your program using these fields.

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

Table 9-1 XABALL Fields

Field Offset	Size (Bytes)	FDL Equivalent	Description
XAB$B_AID	1	AREA n	Area identification number
XAB$B_ALN	1	AREA POSITION 1	Alignment boundary type
XAB$L_ALQ	4	AREA ALLOCATION	Allocation quantity
XAB$B_AOP	1	AREA 1	Allocation options
XAB$B_BKZ	1	AREA BUCKET_SIZE	Bucket size
XAB$B_BLN 2	1	None	Block length
XAB$B_COD 2	1	None	Type code
XAB$W_DEQ	2	AREA EXTENSION	Default extension quantity
XAB$L_LOC	4	AREA POSITION	Location
XAB$L_NXT	4	None	Next XAB address
XAB$W_RFI	6	AREA POSITION FILE_ID or FILE_NAME	Related file identifier
XAB$W_VOL	2	AREA VOLUME	Related volume number

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.

9.2 XAB$B_AID Fields

RMS uses the area identification number (AID) field to determine which area within a file is supported by this XAB. Note that sequential and relative files are limited to area 0.

The area is identified by a numeric value in the range 0 through 254 (default is 0) and is most appropriate for use with index files having multiple areas allocated.

This field corresponds to the FDL attribute AREA n, where n indicates the area number.

9.3 XAB$B_ALN Field

The alignment boundary type (ALN) field gives you several options for aligning the allocated area. RMS uses this field in conjunction with the XAB$L_LOC field and with the XAB$W_RFI field to provide precise positioning control of the area or area extension.

The XAB$B_ALN field is a keyword value field in which an alignment boundary option is defined by a symbolic constant value. For example, the cylinder boundary option has a symbolic constant value of XAB$C_CYL.

Note that if no value is defined for this field, RMS assumes the XAB$C_ANY option (no additional positioning control desired). Additional positioning control is not supported for DECnet for OpenVMS operations.

The XAB$B_ALN field corresponds to the FDL attribute AREA POSITION.

Options

XAB$C_ANY

Any allocation; specifies that no positioning control over the area is desired. If this option is selected, the XAB$L_LOC and XAB$W_RFI fields are ignored.

This option corresponds to the FDL attribute AREA POSITION NONE.

XAB$C_CYL

Specifies that the area boundary begin at the cylinder number identified by the location field XAB$L_LOC.

This option corresponds to the FDL attribute AREA POSITION CYLINDER.

XAB$C_LBN

Specifies that the area boundary begin at the logical block number identified by the location field XAB$L_LOC.

This option corresponds to the FDL attribute AREA POSITION LOGICAL.

XAB$C_RFI

This option is used only for extending an area. It specifies that the area extension begin as close as possible to the file identified by the related-file-identification field (XAB$W_RFI), and that the extent begin with the VBN specified by the location field XAB$L_LOC.

This option corresponds to the FDL attribute AREA POSITION FILE_ID or AREA POSITION FILE_NAME. If you try to use this option with DECnet for OpenVMS operations, RMS replaces it with the XAB$C_ANY option.

XAB$C_VBN

This option applies to area extension only. It specifies that the area extension begin as close as possible to the virtual block number identified by the location field XAB$L_LOC.

This option corresponds to the FDL attribute AREA POSITION VIRTUAL.

The allocation quota field defines the number of blocks to be initially allocated to an area when it is created using a Create service, or the number of blocks to be added to an area when it is explicitly extended using an Extend service (as opposed to automatic extension). In both cases, this field overrides the allocation quantity in the associated FAB (see Chapter 4).

The XAB$L_ALQ field accepts numeric values of up to 4,294,967,295 for initial allocation, but the allocation is limited by the number of blocks available on the device.

When you create a new area using the Create service, RMS interprets the value in the XAB$L_ALQ field as the number of blocks for the area's initial extent. If the value is 0, RMS allocates a minimum number of blocks depending on the file organization. For example, RMS allocates only the number of blocks needed for the key and area definitions with indexed files.

When you use either the Create or Extend services with indexed files, RMS rounds the allocation quantity value up to the next cluster boundary and returns this value to the program in the XAB$L_ALQ field. RMS uses this value as the extension value when you extend an existing area using the Extend service, unless the program changes the value before invoking the Extend service. Note that the value 0 is not acceptable for extending an area.

9.5 XAB$B_AOP Field

The allocation options (AOP) field lets you specify a particular type of allocation.

This field is a binary options field where one or more options may be selected by setting the appropriate bits. Each option is identified by a symbolic offset and has a mask value; for example, the CBT option has an offset of XAB$V_CBT and a mask value of XAB$M_CBT.

Options

XAB$V_CBT

Contiguous best try; indicates that the allocation or extension should use contiguous blocks, on a "best effort" basis. This option overrides the FAB$L_FOP field FAB$V_CBT option.

This option corresponds to the FDL attribute AREA BEST_TRY_CONTIGUOUS.

XAB$V_CTG

Contiguous; indicates that the initial allocation extension must use contiguous blocks only; the allocation fails if the requested number of contiguous blocks is not available. If this is the initial allocation and only a single area is specified, the file is marked contiguous. This option overrides the FAB$L_FOP field FAB$V_CTG option.

This option corresponds to the FDL attribute AREA CONTIGUOUS.

XAB$V_HRD

Hard; indicates that if the requested alignment cannot be performed, an error will be returned. By default, the allocation is performed as near as possible to the requested alignment.

Note that the XAB$V_HRD option is applicable only to XAB$C_CYL and XAB$C_LBN alignment boundary types, specified by the XAB$B_ALN field.

This option corresponds to the FDL attribute AREA EXACT_POSITIONING.

XAB$V_ONC

On cylinder boundary; indicates that RMS is to begin the allocation on any available cylinder boundary.

This option corresponds to the FDL attribute AREA POSITION ANY_CYLINDER.

When RMS creates relative and indexed files, this field specifies bucket size using numeric values ranging from 0 through 63 to represent the number of blocks in a bucket. If this argument is omitted, or if a value of 0 is inserted, RMS uses a default size equal to the minimum number of blocks required to contain a single record. For RMS-11 processing, the bucket size must be less than or equal to 32 blocks.

When calculating the bucket size, you must consider the control information (overhead) associated with each bucket. Note that some record types contain control bytes and to calculate the overhead you must multiply the number of records per bucket by the number of control bytes per record. See the Guide to OpenVMS File Applications for more information.

The Edit/FDL utility can be used to calculate efficient bucket sizes for indexed files. (For information about the Edit/FDL utility, see the OpenVMS Record Management Utilities Reference Manual.)

When you create a file, RMS uses this field as input to determine the specified bucket size and, upon conclusion, uses the field to output the bucket size. Because relative files are limited to one area, this field specifies the size for all buckets in the file. For indexed files, you can specify a different size for each area using this field in the appropriate XABALL.

When you open an existing file, RMS uses this field to output the bucket size to your program.

The value in this field overrides the contents of the bucket size field of the FAB on a Create service (see Chapter 4).

You can specify multiple areas for a single index by having the XAB$B_IAN and XAB$B_LAN fields in the key definition XAB (XABKEY) indicate that the lowest level of the index and the remainder of that index occupy different areas (defined by different XABALLs). However, the number of blocks per bucket (XAB$B_BKZ value) must be the same for the entire index of a particular key. If multiple areas are specified for an index and if the XAB$B_BKZ values are not the same, RMS returns an error because the values for one index must be the same. However, if you specify the XAB$B_BKZ field for at least one area and use the default (0) for the XAB$B_BKZ field of a different area (or areas) of the same index, RMS uses the largest XAB$B_BKZ value specified among the XABALL control blocks to determine the bucket size for that index.

This field corresponds to the FDL attribute AREA BUCKET_SIZE.

9.7 XAB$B_BLN Field

The block length (BLN) field is a static field that defines the length of the XABALL, in bytes. Once set, this field must not be altered unless the control block is no longer needed. This field must be initialized to the symbolic value XAB$C_ALLLEN (this is done by the $XABALL macro).

9.8 XAB$B_COD Field

The type code (COD) field is a static field that identifies this control block as a XABALL. Once set, this field must not be altered unless the control block is no longer needed. This field must be initialized to the symbolic value XAB$C_ALL (this is done by the $XABALL macro).

9.9 XAB$W_DEQ Field

The default extension quantity (DEQ) field specifies the number (0 to 65,535) of blocks to be added when RMS extends the area. If you specify 0, the RMS provides a default extension value.

The value in this field overrides the contents of the default extension quantity field of the FAB (see Chapter 4).

This field corresponds to the FDL attribute AREA EXTENSION.

9.10 XAB$L_LOC Field

The location (LOC) field contains a numeric value that indicates the beginning point for area allocation. RMS refers to the location field when executing a Create or Extend service, but only if the XAB$B_ALN field specifies an alignment option. The way the XAB$L_LOC field is used depends on the value specified for the XAB$B_ALN field (a binary options field). The beginning point for the allocation is determined as follows:

• If the XAB$B_ALN field XAB$C_CYL option is specified, the location number is the cylinder number (0 through the maximum cylinder number on the volume) where the allocation begins.
• If the XAB$B_ALN field XAB$C_LBN option is specified, the location number is the logical block number (0 through the maximum number of blocks on the volume) where the allocation begins.
• If the XAB$B_ALN field XAB$C_VBN or XAB$C_RFI option is specified, the location number is the virtual block number (1 through the maximum number of blocks in the file) where the allocation begins. This applies only to the Extend service. If the number 0 is specified, or if the number is omitted during an Extend service, RMS places the file extension as near to the end of the file as possible.

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

9.12 XAB$W_RFI Field

The related file identification (RFI) field allows you to position files or areas of an indexed file close to a specified file.

This field contains the 3-word file identification value of the related file. A value of 0,0,0 (the default) indicates that the current file is to be used. Specifying the XAB$B_ALN field XAB$C_RFI option and specifying the XAB$W_RFI field as 0,0,0 are equivalent to specifying the XAB$B_ALN field XAB$C_VBN option.

You can view the file identification of a file using the DCL command DIRECTORY with the /FULL qualifier.

The file is created or extended as near to the specified related file as possible at the virtual block number specified by the LOC argument.

The XAB$W_RFI field is ignored unless the XAB$B_ALN field is set to XAB$C_RFI. It is also ignored for DECnet for OpenVMS operations.

This field corresponds to the FDL attribute AREA POSITION FILE_ID or AREA POSITION FILE_NAME.

9.13 XAB$W_VOL Field

The relative volume number (VOL) field indicates the specific member of a volume set upon which the file is to be allocated.

This field contains an integer in the range 0 through 255. The default is 0, specifying the "current" member of the volume set.

Note that volume placement will be performed only if an alignment type in the XAB$B_ALN field is either XAB$C_CYL or XAB$C_LBN (you cannot specify XAB$C_VBN or XAB$C_RFI alignment types). If the XAB$B_ALN field contains a value of 0, placement of the file within the volume set will be at the discretion of the system, regardless of the contents of the XAB$W_VOL field.

This field corresponds to the FDL attribute AREA VOLUME.

On Alpha systems for Files-11 B (ODS--2) media, the date and time XAB (XABDAT) block provides extended control of the date and time of the file's creation, revision (update), backup, and expiration.

10.1 Summary of Fields

RMS sets certain values for date and time and returns them in XABDAT fields for your inspection. You can override these system-supplied values by using a XABDAT as input to a Create service. Note that date-time values are expressed in either absolute (positive) or delta (negative) format, and several system services are available for date-time conversion and use (see Example B-1 in Appendix B of this manual and the OpenVMS System Services Reference Manual).

The symbolic offset, the size, the FDL equivalent (where applicable), and a brief description of each XABDAT field are presented in Table 10-1.

Table 10-1 XABDAT Fields

Field Offset	Size (Bytes)	FDL Equivalent	Description
XAB$Q_BDT 1	8	DATE BACKUP	Backup date and time
XAB$B_BLN 2	1	None	Block length
XAB$Q_CDT 1	8	DATE CREATION	Creation date and time
XAB$B_COD 2	1	None	Type code
XAB$Q_EDT	8	DATE EXPIRATION	Expiration date and time
XAB$L_NXT	4	None	Next XAB address
XAB$Q_RDT 1	8	DATE REVISION	Revision date and time
XAB$W_RVN 1	2	FILE REVISION	Revision number
XAB$Q_ACC 1	8	None	Last time file accessed
XAB$Q_ATT 1	8	None	Last time file attribute modified
XAB$Q_MOD 1	8	None	Last time file data modified

The Display service and the Open service always use the XABDAT fields as output. The Create service uses the XABDAT fields as input when it creates a new file. However, when it opens an existing file (see the description of the FAB$V_CIF option in Section 4.17), the Create service also uses the XABDAT fields as output.

No other RMS services use the XABDAT block.

Each XABDAT field is described in the following sections. Unless indicated otherwise, 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.

10.2 XAB$Q_BDT Field

The backup date and time (BDT) field contains a 64-bit binary value expressing the date and time when the file was most recently backed up. Note that this field is limited to a granularity of 1 second for remote files.

This field corresponds to the FDL attribute DATE BACKUP.

10.3 XAB$B_BLN Field

The block length (BLN) field is a static field that defines the length of the XABDAT in bytes. Once set, this field must not be altered unless the control block is no longer needed. This field must be initialized to the symbolic value XAB$C_DATLEN (this is done by the $XABDAT macro).

10.4 XAB$Q_CDT Field

The creation date and time (CDT) field contains a 64-bit binary value expressing the date and time when the file was created. Note that this field is limited to a granularity of 1 second for remote files. If the application program specifies this field as 0 (either explicitly or by default), the Create service uses the current date and time.

This field corresponds to the FDL attribute DATE CREATION.

10.5 XAB$B_COD Field

The type code (COD) field is a static field that identifies this control block as a XABDAT. Once set, this field must not be altered unless the control block is no longer needed. This field must be initialized to the symbolic value XAB$C_DAT (this is done by the $XABDAT macro).

10.6 XAB$Q_EDT Field

The expiration date and time (EDT) field contains a 64-bit binary value that indicates the date and time after which a file residing on a disk device may be considered for deletion by the system manager. For files residing on magnetic tape devices, the XAB$Q_EDT field sets the date and time after which you can overwrite the file. Note that this field is limited to a granularity of 1 second for remote files.

This field corresponds to the FDL attribute DATE EXPIRATION.

	privacy and legal statement
4523PRO_014.HTML