Document revision date: 19 July 1999

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.

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

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.

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

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.

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).

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.

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.

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).

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).

	privacy and legal statement
4523PRO_019.HTML