Document revision date: 30 March 2001

## OpenVMS Record Management Services Reference Manual

Previous | Contents | Index

## Chapter 17
Recovery Unit XAB (XABRU)

The recovery unit XAB (XABRU) control block supports the use of recovery units to assure data file integrity. See the RMS Journaling for OpenVMS Manual for details.

## Chapter 18
Summary XAB (XABSUM)

The summary XAB (XABSUM) can be associated with a FAB at the time a Create, Open, or Display service is invoked. The presence of this XAB during these calls allows RMS to return to your program the total number of keys and allocation areas defined and the version number when the file was created. Note that a XABSUM is used only with indexed files.

## 18.1 Summary of Fields

The symbolic offset, the size, and a brief description of each XABSUM field are presented in Table 18-1.

Table 18-1 XABSUM Fields
Field Offset | Size | Description
--- | --- | ---
XAB$B_BLN 1 | Byte | Block length
XAB$B_COD 1 | Byte | Type code
XAB$B_NOA 2 | Byte | Number of allocation areas defined for the file
XAB$B_NOK 2 | Byte | Numbers of keys defined for the file
XAB$L_NXT | Longword | Next XAB address
XAB$W_PVN 2 | Word | Prolog version number

1This field is statically initialized by the $XABSUM macro to identify this control block as a XABSUM.
2This field cannot be initialized by the $XABSUM macro.

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

## 18.2 XAB$B_BLN Field

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

## 18.3 XAB$B_COD Field

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

## 18.4 XAB$B_NOA Field

The number of allocation areas (NOA) field indicates the number of allocation areas defined when the file was created. Refer to Chapter 9 for information about multiple allocation areas.

## 18.5 XAB$B_NOK Field

The number of keys (NOK) field indicates the number of keys defined when the file was created. Refer to Chapter 14 for more information.

## 18.6 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.

## 18.7 XAB$W_PVN Field

The prolog version number (PVN) contains a numeric value that indicates the prolog number defined when the file was created. For more information about prolog numbers, refer to Chapter 14.

## Chapter 19
Terminal XAB (XABTRM)

The terminal XAB (XABTRM) allows extended terminal read operations to occur when a Get service is used for a terminal device. Unlike most other XABs, the XABTRM is associated with a RAB (record stream). The XABTRM provides information that the terminal driver uses to process a user-defined item list that defines the terminal read operation.

## 19.1 Summary of Fields

The symbolic offset, the size, and a brief description of each XABTRM field are presented in Table 19-1.

Table 19-1 XABTRM Fields
Field Offset | Size (Bytes) | Description
--- | --- | ---
XAB$B_BLN 1 | 1 | Block length
XAB$B_COD 1 | 1 | Type code
XAB$L_ITMLST | 4 | Item list address
XAB$W_ITMLST_LEN | 2 | Item list length
XAB$L_NXT | 4 | Next XAB address

1This field is statically initialized by the $XABTRM macro to identify this control block as a XABTRM.

To perform the extended terminal read operation, the following information is required:

- In the RAB, the RAB$L_ROP field RAB$V_ETO option must be specified (set).
- In the RAB, the RAB$L_XAB field must contain the address of the XABTRM.
- In the XABTRM, the XAB$L_ITMLST and XAB$W_ITMLST_LEN fields must contain the starting address and length of a valid terminal driver read function item list.
- The item list must be supplied according to the conventions described for creating an item list for the terminal driver in the OpenVMS I/O User's Reference Manual.

An item list consists of one or more item list entries, where each item defines an attribute of the terminal read operation. Instead of defining terminal read arguments in the RAB, all such arguments (including certain arguments only available with the item list method) are defined in the item list. The following list shows the RAB$L_ROP options related to a terminal read operation and the equivalent item codes:

Option | Item Code
--- | ---
RAB$V_CVT | TRM$_MODIFIERS, bit TRM$M_TM_CVTLOW
RAB$V_PMT | TRM$_PROMPT
RAB$V_PTA | TRM$_MODIFIERS, bit TRM$M_TM_PURGE
RAB$V_RNE | TRM$_MODIFIERS, bit TRM$M_TM_NOECHO
RAB$V_RNF | TRM$_MODIFIERS, bit TRM$M_TM_NOFILTR
RAB$V_TMO | TRM$_TIMEOUT

Each item code required for the terminal read operation is placed in an item list along with other required information. Each item code is made up of three longwords. Note that RMS does not validate the item list. If the item list is invalid, RMS returns RMS$_QIO status in the RAB$L_STS field and the specific terminal driver QIO status in the RAB$L_STV field (see the OpenVMS I/O User's Reference Manual).

The XABTRM is not supported for DECnet for OpenVMS operations between two OpenVMS systems. There are no equivalent FDL attributes for the XABTRM fields.

## 19.2 XAB$B_BLN Field

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

## 19.3 XAB$B_COD Field

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

## 19.4 XAB$L_ITMLST Field

The item list address (ITMLST) field contains the symbolic address of the item list that defines the extended terminal read operation.

## 19.5 XAB$W_ITMLST_LEN Field

The item list length (ITMLST_LEN) field contains a numeric value that indicates the length of the item list, in bytes.

## 19.6 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.

## Part 3
OpenVMS RMS Services

Part III lists the format of each record management service and describes each service in detail. Each service is documented in a structured format. See OpenVMS Programming Concepts Manual, Volume II for a discussion of the format and how it is used.

Note that the calling format for each service requires a placeholder (a comma) if you omit the first optional argument (err) but include the second optional argument (suc).

## $CLOSE

> The Close service terminates file processing and closes the file. This service performs an implicit Disconnect service for all record streams associated with the file.

### Format

> SYS$CLOSE fab [,[err] [,suc]]

### RETURNS

> OpenVMS usage: | cond_value
> type: | longword
> access: | write only
> mechanism: | by value

> The value is returned in symbolic offset FAB$L_STS. Symbolic offset FAB$L_STV may contain additional status information.

### Arguments

> #### fab

> OpenVMS usage: | fab
> type: | longword (unsigned)
> access: | modify
> mechanism: | by reference

> FAB control block whose contents are to be used as indirect arguments for the Close service call. The fab argument is the address of the FAB control block.

> #### err

> OpenVMS usage: | ast_procedure
> type: | procedure value
> access: | call without stack unwinding
> mechanism: | by reference

> AST-level error completion routine that the service invokes if the operation is unsuccessful. The err argument is the address of the entry mask of this user-written completion routine.

> #### suc

> OpenVMS usage: | ast_procedure
> type: | procedure value
> access: | call without stack unwinding
> mechanism: | by reference

> AST-level success completion routine that the service invokes if the operation is successful. The suc argument is the address of the entry mask of this user-written completion routine.

### Description

> You can invoke the Close service only when no operation is currently under way (by your process) for the file being processed; that is, when no RMS requests for the file are outstanding.

> When the Close service is invoked properly, RMS disconnects all RABs for you, performs the various cleanup procedures (including file option processing and XAB processing), and closes the file. The only types of XABs that the Close service processes are the file protection XAB (XABPRO) and revision date and time XAB (XABRDT). It processes these XABs only if the file was opened or created for write access.

> On a $CLOSE, the EOF value written to the file header is "seen" only by subsequent accessors. Any process that has the file open at the time of the $CLOSE does not "see" the new EOF value without some explicit action.

> If a process tries to implement the Truncate service when closing a sequential file, it must have sole write access to the file. If other processes have write access to the file, it remains accessible until all processes have completed. If other processes have the file open for read access, RMS defers the truncation until the final process having read access closes the file.

> Table RMS-1 lists the control block fields read as input by the Close service. Note that if the FAB$V_DLT, FAB$V_SCF, or the FAB$V_SPL bits are set by the associated Open or Create service, RMS does not act on them for the Close service. For example, if you open the file and specify that it be deleted on close by setting the FAB$V_DLT bit, RMS deletes it when it is closed regardless of the bit's state when the Close service is invoked.

> For additional information on the fields accessed by this service, see Part 2.

> Table RMS-1 Close Service FAB and XAB Input Fields
> Field Name | Option or XAB Type | Description
> --- | --- | ---
> FAB$W_IFI 1 |  | Internal file identifier.
> FAB$L_FOP |  | File-processing options.
> | FAB$V_ASY | Asynchronous; indicates that the specified task is to be done asynchronously.
> | FAB$V_DLT | Deletes file on close.
> | FAB$V_RWC | Rewinds a magnetic tape volume.
> | FAB$V_SCF 2 | Submits a file as a batch job (sequential files only).
> | FAB$V_SPL 2 | Submits a file to the print queue (sequential files only).
> | FAB$V_TEF | Truncates data at the end of the file (sequential files only).
> FAB$L_XAB |  | Next XAB address.
> | XABPRO | Modifies file protection and ownership.
> | XABRDT | Modifies revision date and number.

1This field is required input to the FAB.
2This field is not supported for DECnet for OpenVMS operations.

Table RMS-2 lists the control block fields written as output by the Close service.

Table RMS-2 Close Service FAB and XAB Output Fields
Field Name | Option or XAB Type | Description
--- | --- | ---
FAB$W_IFI |  | Internal file identifier (cleared only when the file is closed).
FAB$L_STS |  | Completion status (also returned in register 0).
FAB$L_STV |  | Status value.
FAB$L_XAB |  | Next XAB address.
| XABRDT | New revision date and number returned.

### Condition Values Returned

> The following condition values can be returned. Use the Help Message utility to access online message descriptions. For more information about interpreting condition values, see Section 2.4.

RMS$_ACT | RMS$_ATR | RMS$_ATW
RMS$_BLN | RMS$_BUG_DAP | RMS$_BUSY
RMS$_CCF | RMS$_CDA | RMS$_COD
RMS$_CRC | RMS$_DAC | RMS$_DME
RMS$_DNR | RMS$_EXENQLM | RMS$_FAB
RMS$_IFI | RMS$_IMX | RMS$_MKD
RMS$_NET | RMS$_NETFAIL | RMS$_NORMAL
RMS$_PRV | RMS$_SPL | RMS$_STR
RMS$_SUC | RMS$_SUP | RMS$_SUPPORT
RMS$_SYS | RMS$_WBE | RMS$_WER
RMS$_WLK | RMS$_WPL | RMS$_XAB

Note that even though a failure is indicated by the completion status code value, the file is truly closed only if RMS clears the internal file identifier value (FAB$W_IFI).

## $CONNECT

> The Connect service establishes a record stream by associating and connecting a RAB with a FAB. You can invoke the Connect service only for files that are already open.

> RAB64 Users RAB64 can replace the RAB or RAB prefix wherever it is used with the Connect service on OpenVMS Alpha systems.

### Format

> SYS$CONNECT rab [,[err] [,suc]]

### RETURNS

> OpenVMS usage: | cond_value
> type: | longword
> access: | write only
> mechanism: | by value

> The value is returned in symbolic offset RAB$L_STS. Symbolic offset RAB$L_STV may contain additional status information.

### Arguments

> #### rab

> OpenVMS usage: | rab
> type: | longword (unsigned)
> access: | modify
> mechanism: | by reference

> RAB control block whose contents are to be used as indirect arguments for the Connect service call. The rab argument is the address of the RAB control block.

> #### err

> OpenVMS usage: | ast_procedure
> type: | procedure value
> access: | call without stack unwinding
> mechanism: | by reference

> AST-level error completion routine that the Connect service invokes if the operation is unsuccessful. The err argument is the address of the entry mask of this user-written completion routine.

> #### suc

> OpenVMS usage: | ast_procedure
> type: | procedure value
> access: | call without stack unwinding
> mechanism: | by reference

> AST-level success completion routine that the Connect service invokes if the operation is successful. The suc argument is the address of the entry mask of this user-written completion routine.

### Description

> Any number of RABs can be connected to a FAB if the multistream (FAB$V_MSE) option is selected when the file is opened or created. Each RAB represents an independent record stream.

> When you issue a Connect service, RMS allocates an internal counterpart for the RAB. This counterpart consists of the internal controls needed to support the stream, such as record pointers and request status information. All required I/O buffers are also allocated at this time.

> The Connect service also initializes the next record pointer to the first record. In indexed files, the key of reference establishes the index of the next record pointer.

> If you set the end-of-file (RAB$V_EOF) option in the RAB$L_ROP field when issuing a Connect service, RMS examines the organization of the file being processed to determine the end-of-file positioning strategy.

> For sequential or relative files, RMS goes to the next record beyond the last currently existing record in the file. (The next record is inserted at the logical end of the file, and the service returns RMS$_EOF status in response to a request for sequential access.)

> For indexed files, RMS verifies that the first record is inserted in the proper sort order. If the record cannot be inserted in the proper sort order because of user action, RMS returns a sequence error (RMS$_SEQ).

> Get services that specify the sequential record access mode (RAB$B_RAC is RAB$C_SEQ) return an RMS$_EOF status. Get services that specify the random access mode (RAB$B_RAC is RAB$C_KEY) ignore (turn off) the end-of-file positioning. Positioning to end-of-file is supported for all indexed files, regardless of how many indexes the file contains. However, the EOF positioning is supported only when you access a file by the primary key. If the specified key of reference is a secondary key, an RMS$_ROP message is returned.

> In most cases, setting the RAB$V_EOF bit guarantees that the next record is inserted at the logical end of the file. However, if a relative file or an indexed file is shared by two or more active processes, the following scenario may develop.

> Assume that process A has invoked the Connect service after setting the RAB$V_EOF bit and is positioned to the end of the file. Before process A can do a $PUT, process B inserts a record into the file and changes the current record position. When process A attempts to do a $PUT into the position that was formerly the end of the file, the record may be inserted improperly. It may be inserted either before or after the record inserted by process B, depending on the respective key values. Or, the $PUT operation may even fail if the keys have the same value and duplicates are not allowed.

> Table RMS-3 lists the control block fields read as input by the Connect service. For additional information about the fields accessed by this service, see Part 2.

> Table RMS-3 Connect Service RAB Input Fields
> Field Name | Option or XAB Type | Description
> --- | --- | ---
> FAB$W_GBC |  | Global buffer count.
> RAB$L_FAB 1 |  | File access block address (required to access the internal file identifier field, FAB$W_IFI).
> RAB$W_ISI 1 |  | Internal stream identifier (must be 0).
> RAB$B_KRF |  | Key of reference (applies only to indexed files).
> RAB$B_MBC 2 |  | Multiblock count (applies only to sequential files residing on disk devices).
> RAB$B_MBF 2 |  | Multibuffer count. 4
> RAB$L_ROP |  | Record-processing options:
> | RAB$V_ASY | Asynchronous: performs Connect service asynchronously.
> | RAB$V_BIO | Block I/O: specifies that only block I/O operations are permitted. The FAB$B_FAC field FAB$V_BRO or FAB$V_BIO option must be specified to the Open or Create service.
> | RAB$V_EOF 3 | End-of-file: positions to the end of the file upon execution of the Connect service.
> | RAB$V_RAH 2 | Read ahead: allocates at least two buffers for multibuffering (applies only to sequential files on disk devices).
> | RAB$V_WBH 2 | Write behind: allocates at least two buffers for multibuffering (applies only to sequential files on disk devices).

1This field is a required input to the Connect service.
2This field is not supported for DECnet for OpenVMS operations.
3Refer to text for exceptions.
4Optionally, you can specify the multibuffer count using the XAB$_MULTIBUFFER_COUNT XABITM.

Previous | Next | Contents | Index

| privacy and legal statement |
4523PRO_020.HTML