HP OpenVMS Systems Documentation
OpenVMS Record Management Services Reference Manual
1.2.3 Control Blocks for Record Services
Record services use a control block known as the record access block, or RAB. Some of the arguments the user must store in the RAB include the address of the related FAB, the address of input and output record buffers, the type and size of general I/O buffers, whether a file's records will be accessed directly or sequentially, certain tuning options, and other information.
An extended attribute block (XAB) can both supersede and supplement the record characteristics specified in the RAB. As with a XAB that supersedes and supplements a FAB, a XAB that supersedes and supplements a RAB has a 6-letter mnemonic name consisting of the prefix "XAB" followed by three letters. Note that there are only two XAB types used for record operations, the terminal XAB (XABTRM) and, on VAX systems only, the recovery unit XAB (XABRU).
The XABTRM defines the symbolic address and length of a user-supplied argument list that defines the terminal operation and provides more flexibility than using RAB fields.
See the RMS Journaling for OpenVMS Manual for details relating to the use of the XABRU on
For this reason, certain programs specifically allocate a NAM or NAML block or one or more XABs dedicated to receiving information returned by RMS. Typically, such information can be examined to determine how the file should be processed.
In most cases, however, control blocks are used both to transmit and to receive information between the application program and RMS, and should not be located in a read-only program section.
Be sure that control block fields not currently used by a particular service have valid default values, because future versions of RMS may use them. This applies also to control block fields that are currently described as "ignored for DECnet for OpenVMS operations" because future versions of RMS or DECnet for OpenVMS may support those fields.
A name (NAM) block supplements the file specification information stored in the related FAB. It is especially useful for locating and opening files when the file specification is entered by an interactive user or when a file specification includes a wildcard character or a search list logical name representing multiple files.
On Alpha systems, a long name block (NAML) can optionally take the place of a NAM block. The NAML allows OpenVMS Alpha users to locate and use file specifications that are longer than 255 bytes. For an extra level of file specification defaults, RMS may apply defaults using additional NAM or NAML blocks that contain the file specifications of related files.
|ccc||3 letters||Identifies the type of control block: FAB, NAM, XAB (for all XABs), or RAB.|
|$||1 character||Separates the control block identifier from the field length identifier; a dollar sign ($).|
|x||1 letter||Identifies the length of the field: B for byte, W for word, L for longword, Q for quadword, T for text buffer address. Symbolic length fields are identified by the letter S in this position. For example, the value field XAB$S_CACHE_TMO specifies the number of bytes allocated for defining the value of the cache timeout. See text for exceptions.|
|_||1 character||Separates the field length identifier from the field name; always an underscore (_).|
3 or more
|Identifies the mnemonic name of the field, which is used in the VAX MACRO control block macro. Some mnemonics contain more than three letters; for example, symbolic offset XAB$B_PROLOG (from XABKEY).|
For example, the FAB field whose mnemonic is ALQ has a length of one longword and is identified by the symbolic offset FAB$L_ALQ. The field NAM$L_RLF is a NAM longword field whose mnemonic RLF reflects its name, the related file field.
When a control block field contains options identified by bits, each valid bit location has a symbolic offset name. Certain control block fields are binary options fields consisting of bit values. For these bits in a binary options field, the format of symbolic names resembles the format of the field names, except for the length indicator. Instead of identifying the field length, which is always one bit, the length field indicates whether a mask value (M) or bit offset (V) is defined by the symbolic name, as described in the following table.
|xxx$M_fff||Indicates a mask value in a binary options field, typically where multiple bit options can be chosen. Used to set or clear bit values.|
|xxx$V_fff||Indicates the symbolic bit offset (number of bits from the beginning of the binary options field). Used to test bit values or to set bit values.|
The xxx identifies the control block (FAB, NAM, XAB, or RAB); the $ and _ are separator characters, and the fff defines the mnemonic for the bit option. For example, the option CTG in the FAB file-processing options (FOP) field has a symbolic bit offset of FAB$V_CTG and a mask value of FAB$M_CTG.
Constant (or keyword) fields can contain only a limited set of values, thus there are no mask values or symbolic bit offsets. In some instances, the letter K is used to denote a constant (keyword) value field in place of the letter C; otherwise, the naming convention is the same.
Note that the letter C replaces the letter M, denoting that this field is a constant (keyword) value field, not a mask value field. For example, the file organization (ORG) field of the FAB (FAB$B_ORG) can contain only the values FAB$C_IDX (indexed), FAB$C_REL (relative), or FAB$C_SEQ (sequential).
When specifying control block field locations, avoid using actual byte
displacement values to identify control block field locations; instead,
use the supplied symbolic offsets. RMS control block field locations
may not always be the same from release to release; however, the
symbolic offset names that identify the field locations always identify
the same fields.
2.3 RMS Calling Sequence
RMS uses the appropriate OpenVMS standard calling sequence and conventions, and preserves all general registers across a call, except for register 0 (R0) and register 1 (R1). When the service completes execution, it returns control to the calling program, passing a condition value in R0. You should analyze the completion value to determine the success or failure of the service and to alter the flow of execution of your program, if necessary. Where applicable, you should use the STS field and the STV field of the appropriate control block for signaling errors, instead of R0. For additional information about RMS completion values, see Section 2.4.
When a service invokes an AST-level completion routine, it passes the address of the associated control block (FAB or RAB) as the AST argument value in the AST argument list.
The argument list sent to the service is from two to four longwords in length, as shown in Figure 2-1. (The Rename service, however, uses a 5-longword argument list.)
Figure 2-1 Argument List Format
This section describes various service completion scenarios. The events
associated with completing an RMS service call depend to some extent on
how the user calls the service. The user may specify either the
synchronous or asynchronous option in the control block (FAB or RAB)
passed to the service, and the user may or may not specify an AST.
2.4.1 Illformed Calls to RMS
Every RMS service call requires an interface data structure (FAB or RAB) which is writable in caller's mode and not currently in use for another operation. If these requirements are not met, the call is illformed, and one of the following errors is returned in R0:
|RMS$_BLN||Invalid block length field (either FAB or RAB)|
|RMS$_BUSY||User structure (FAB/RAB) still in use|
|RMS$_FAB||FAB not writable or invalid block ID field|
|RMS$_RAB||RAB not writable or invalid block ID field|
|RMS$_STR||User structure (FAB/RAB) became invalid during operation|
Since the FAB or RAB data structure is invalid or inaccessible, RMS will not attempt to store the error code in the status (FAB/RAB$L_STS) field. The error will only be returned in R0, and if an error completion AST was specified, it will not be delivered.
Also, if the application deletes, overmaps, or alters the contents of the memory containing the interface data structure while the service is active, the results are unpredictable.
These illformed calls are not considered in the remaining discussion in
this section on service completion.
2.4.2 Setting Synchronous or Asynchronous Option
The ASY option in the FOP field of the FAB or the ROP field of the RAB
must be set to specify asynchronous completion. If this option is clear
(the default), the service completes synchronously.
2.4.3 Synchronous Completion
If the user chooses synchronous completion, RMS does not return control to the application program until the I/O operation terminates. The service returns the completion status value in R0 as well as in the status field (FAB/RAB$L_STS). The status RMS$_SYNCH or RMS$_PENDING is never returned in the synchronous case.
If the user specifies an AST routine to the service, the AST routine
executes prior to returning control from the service call, unless it is
called from AST level or AST delivery is disabled.1
2.4.4 Asynchronous Completion
Asynchronous completion allows the application to continue execution while RMS completes the requested service, if the completion requires an I/O or synchronization stall. Asynchronous completion is enabled by setting the ASY option (FAB$V_ASY or RAB$V_ASY, as appropriate).
The called service clears the completion status field (FAB/RAB$L_STS). When the service completes, the (nonzero) completion status is returned.
The status returned (in R0) from an asynchronous RMS service may depend on whether the SYNCSTS option is set. The SYNCSTS option (FAB/RAB$V_SYNCSTS) allows the application to avoid the overhead of processing a completion AST, if the RMS service is completed before returning from the service call.
Applications must not make assumptions about completion timing for specific services.
The possible statuses returned in R0 and the implication each has on AST delivery are as follows:
|RMS$_SYNCH||The operation is complete. This status is returned only if the user specified the SYNCSTS option. The actual completion status is stored in FAB/RAB$L_STS. No completion AST (success or failure) is delivered.|
The operation had not completed when the RMS service call returned.
When the requested operation completes, the actual completion status is stored in FAB/RAB$L_STS and any requested success or error AST will be delivered. 1
|Any other status||The operation is complete. Any requested success or error AST has been delivered (or is queued for delivery). 1 The completion status is stored in FAB/RAB$L_STS, which is also the service return value in R0.|
When using asynchronous completion, the application can determine that the operation is complete by:
In general, you may receive one of many error or success codes from an operation. The discussion of each service in Part 3 includes a list of the possible condition values that you can receive when you invoke the service.
$RMSDEF gives you the names of the condition values returned by RMS. See the OpenVMS system messages documentation for a list of all RMS status codes.
|001 (1)||Success (low-order bit set).|
|011 (3)||Information (low-order bit set).|
|000 (0)||Warning; indicates a nonstandard condition. The operation may have performed some, but not all, of the requested function.|
|010 (2)||Error; you must recognize that a problem exists and provide a contingency plan in your program for such a condition.|
|100 (4)||Severe error; normally caused by program logic errors or other unrecoverable conditions.|
The usual method of testing the completion status is to examine register 0 for success, failure, or specific completion values. For certain completion values, RMS returns additional information in the status value field (STV) of the control block. The description of the codes presented in the OpenVMS system messages documentation indicates the instances when the STV contains such information.
The STS and STV fields should be used to signal RMS errors to ensure that the error message includes all relevant information. For the file processing and file naming services, use the STS and STV fields of the specified FAB (use the old FAB for the Rename service). For record processing and block I/O processing services, use the STS and STV fields of the corresponding RAB. (Consult Table 1-1 if you are not sure of the group to which a particular service belongs.)
The recommended way to signal RMS errors is to provide both the STS and STV fields of the RAB or FAB as arguments to the run-time library (RTL) routine LIB$SIGNAL (or LIB$STOP). Certain languages provide a built-in means of signaling errors, such as by providing a system-defined function. For a more detailed explanation of condition signaling and invoking RTL routines, see the OpenVMS RTL Library (LIB$) Manual.
1 When operating in a Compaq POSIX Threads Library environment, consult your POSIX Threads Library documentation.