Document revision date: 15 July 2002

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 VAX systems.

1.2.4 Dual Purpose of Control Blocks

Control blocks provide input to and output from record management services, including the following run-time information:

• Detailed file characteristics, including file organization, record format, and record size
• Device characteristics
• File, directory, and device identifiers
• The address (location) and length of a requested record
• Returned condition values

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.

This section introduces the application program interface with RMS that is applicable to all OpenVMS languages in terms of the following:

• The run-time processing environment
• RMS symbol-naming conventions
• The calling sequence for record management services
• Allowable program execution modes
• Condition values returned by record management services

The RMS run-time processing environment consists of a set of blocks and the run-time services. The control block fields accessed by each service specify the appropriate file and record operations. Depending on the operation, RMS uses one or more control blocks by referring to one or more fields as input to, or output from, the operation.

To use RMS, you must do the following:

1. Allocate the appropriate control block, usually at assembly time or compilation time. Control blocks must not reside in read-only storage and should be aligned on a longword boundary to maximize efficiency.
2. Insert the appropriate values into the control block fields before you invoke the related service.
3. Invoke the appropriate service. As part of this step, a condition value should always be examined.

To perform advanced RMS functions, you may need to set various control block field values at run time between the time the file is opened and when the appropriate service is invoked.

Note that OpenVMS languages perform some of these steps transparently when a particular language statement or macro is present in a source program.

Two fields in each control block---the block length (BLN) field and the block identifier (BID) (or block code [COD] field in a XAB)---define the length of the control block (in bytes) and identify the control block type, respectively. These internal fields are always used as input arguments by the service that accesses the control block, and must be set before the control block can be used. After the block length and block identifier fields are established, you must treat them as read-only fields until the control block is no longer needed.

Part 2 describes each control block field in detail, including its length and its symbolic name.

Part 3 lists the calling format for each service together with the input control block fields and the output control block fields for each service.

2.2 Conventions for Naming Fields

RMS uses mnemonics to identify control block fields. For example, the mnemonic name for the FAB allocation quantity field is ALQ.

The mnemonic name (usually consisting of three characters) serves as a suffix to a symbolic name that identifies the location of each control block field. You should use the symbolic names to be sure you place values in the correct control block fields. RMS defines each symbolic name as a constant value equal to the offset, in bytes, from the beginning of the control block to the beginning of the field. These field names are thus called symbolic offsets.

Symbolic offset names are defined when the appropriate VAX MACRO control block initialization macro is used, when the appropriate VAX MACRO control block symbol definition macro is used, and when some languages invoke RMS. Alternatively, all control block symbolic offset names are available when you use the VAX MACRO $FABDEF, $RABDEF, $NAMDEF, and $XAB...DEF macros in a VAX MACRO program or procedure.

The format of the symbolic offsets consists of a 3-letter control block identifier (FAB, NAM, XAB, or RAB), a dollar sign ($), a 1-letter indicator of the length of the field (B, W, L, Q, or T), an underscore (_), and the field mnemonic, which is usually three letters.

The general format of the symbolic offset is shown in the following example:

ccc$x_fff

The components of the symbolic offset format are summarized in the following table.

Component	Length	Description
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 (_).
fff	3 or more letters	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.

Exceptions to the length designation are NAM$W_DID, NAM$W_FID, XAB$W_RFI, and RAB$W_RFA, each of which is three words in length rather than one word.

The length of a T field is specified by the corresponding S field; for example, the length of the NAM$T_DVI field is specified by the symbolic value field named NAM$S_DVI.

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.

Format	Description
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.

Unlike a binary options field, each possible value is identified by a symbolic constant value, in the following form:

xxx$C_fff

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 calling a service, you must provide an argument list to specify the associated control block (FAB or RAB) and, optionally, any completion routines.

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

RMS interprets the fields in the argument list as follows:

• The argument count field contains a binary value, from 1 through 3, representing the number of arguments in the argument list. For the Rename service only, set this value to 4.
• The control block address field contains the address of either the FAB (for file operations) or the RAB (for record operations).
• The error completion routine address field optionally contains the address of the entry mask of a user-written completion routine to be called if the requested operation fails. If used, the completion routine executes as an asynchronous system trap (AST).
• The success completion routine address field optionally contains the address of the entry mask of a user-written completion routine to be called if the requested operation completes successfully. If used, the completion routine executes as an asynchronous system trap (AST).
• The new FAB address field (not shown in Figure 2-1) contains the address of the FAB that contains the new file name for the Rename service. This field applies only to the Rename service.

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:

Error	Meaning
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.¹

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:

Status Returned	Meaning
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.
RMS$_PENDING	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:

• Checking periodically for a nonzero status in FAB/RAB$L_STS
• Specifying success and error AST routines
• Calling SYS$WAIT when the application has completed other work, and now wishes to wait for the service to complete

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.

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.

	privacy and legal statement
4523PRO_001.HTML