HP OpenVMS Systems Documentation

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.

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.

10.7 XAB$L_NXT Field

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

10.8 XAB$Q_RDT Field

The revision date and time (RDT) field contains a 64-bit binary value representing the date and time when the file was last revised. The Open and Display services use this field to read the revision date and time. The Create service uses this field to set the revision date and time. However, a subsequent Close service overrides the value set by the Create service by using the value in the XAB$Q_RDT field of the XABRDT.

If the application program specifies this field as 0 (either explicitly or by default), the Create service uses the current date and time as the revision date and time. Note that this field is limited to a granularity of 1 second for remote files.

This field corresponds to the FDL attribute DATE REVISION.

10.9 XAB$W_RVN Field

The revision number (RVN) field contains a numeric value that indicates the number of times this file was opened for write operations.

This field corresponds to the FDL attribute FILE REVISION.

10.10 XAB$Q_RCD Field (VAX Only)

On VAX systems, the XAB$Q_RCD (RCD) field contains a 64-bit binary value expressing the date and time that the file was recorded.

This field is applicable only to ISO 9660 files and has no corresponding FDL attribute.

10.11 XAB$Q_EFF Field (VAX Only)

On VAX systems, the XAB$Q_EFF (EFF) field contains a 64-bit binary value expressing the date and time when the file information may be used. If no value is specified in this field, the data may be used immediately.

This field is applicable only to ISO 9660 files and has no corresponding FDL attribute.