Document revision date: 15 July 2002

The Flush service writes out all modified I/O buffers and file attributes associated with the file. This ensures that all record activity up to the point at which the Flush service executes is actually reflected in the file.

RAB64 Users (Alpha Only) On Alpha systems, RAB64 can replace the RAB or RAB prefix wherever it is used with the Flush service on OpenVMS Alpha systems.

Format

SYS$FLUSH 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 Flush 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 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

Explicit invocation of the Flush service is useful when an application program must be certain that all file changes are represented on disk (as in protecting against a crash).

The Close service includes an implicit Flush service, so an application program need not invoke a Flush service prior to invoking a Close service.

On VAX systems with recovery unit journaling, no explicit call to the Flush service is required because invoking the Commit service causes an implicit flush.

During asynchronous operations, you must wait for any I/O activity to complete before issuing a Flush service. You can also issue a Flush service after receiving notification of completion through an asynchronous system trap (AST).

On a flush, the EOF value written to the file header is only accessible to subsequent accessors. Any process that has the file open at the time of the flush cannot access the new EOF value without some explicit action.

Table RMS-39 lists the control block fields read as input by the Flush service. For additional information on the fields accessed by this service, see Part 2.

Table RMS-39 Flush Service RAB Input Fields

Field Name	Option	Description
RAB$W_ISI		Internal stream identifier (required).
RAB$L_ROP		Record-processing option.
	RAB$V_ASY	Performs Flush services asynchronously.

Table RMS-40 lists the control block fields written as output by the Flush service.

Table RMS-40 Flush Service RAB Output Fields

Field Name	Description
RAB$L_STS	Completion status code (also returned in register 0).
RAB$L_STV	Additional status information.

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.

The Free service unlocks all records that were previously locked for the record stream.

RAB64 Users (Alpha Only) On Alpha systems, RAB64 can replace the RAB or RAB prefix wherever it is used with the Free service on OpenVMS Alpha systems.

Format

SYS$FREE 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 Free 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 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

The Free service unlocks all records previously locked for the record stream (see also $RELEASE). If no records are locked for the record stream, RMS returns a status code of RMS$_RNL.

Table RMS-41 lists the control block fields used as input by the Free service. For additional information on the fields accessed by this service, see Part 2.

Table RMS-41 Free Service RAB Input Fields

Field Name	Option	Description
RAB$W_ISI		Internal stream identifier (required).
RAB$L_ROP		Record-processing option.
	RAB$V_ASY	Asynchronous: performs Free services asynchronously.

Table RMS-42 lists the control block fields written as output by the Free service.

Table RMS-42 Free Service RAB Output Fields

Field Name	Description
RAB$L_STS	Completion status code (also returned in register 0).
RAB$L_STV	Additional status information.

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.

The Get service retrieves a record from a file.

Note When you invoke the Get service, RMS takes control of the record buffer and may modify it. RMS returns the record size and guarantees the contents only from where it accessed the record to the completion of the record.

RAB64 Users (Alpha Only) On Alpha systems, RAB64 can replace the RAB or RAB prefix wherever it is used with the Get service on OpenVMS Alpha systems.

Format

SYS$GET 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 Get 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 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

The Get service uses one of three record access modes, as specified by the record access (RAB$B_RAC) field. The three record access modes are sequential (SEQ), which is the default, random by key (KEY), and random by record file address (RFA).

Relevant Record Access Modes

The sequential access mode is relevant for all file organizations as well as for all devices. It is the only access mode allowed for nondisk devices, such as terminals, mailboxes, and magnetic tape devices. In this mode, records are retrieved from a given file in the same order in which they were written to that file. This is not the case, however, for records retrieved from indexed files. Sequential Get services for indexed files return records by key value in the specified sort order, ascending or descending. The next record's key of reference for sequential access to indexed files is established by one of the following services:

• Connect
• Rewind (see $REWIND)
• Find or Get using random access by key
• Find or Get using random access by RFA

When you use random access by key with any operations related to these services, the key of reference is established by the key of reference field (RAB$B_KRF). When you use random access by RFA in conjunction with a Find or Get service, however, the key of reference is always set to the primary key.

You can use random access by key to retrieve records by key value. For relative files and sequential files having fixed-length records, the key value is the relative record number. For indexed files, the key value depends on the data type of the specified key of reference. The key value is used to search the index of the specified key of reference to locate the desired record. A random access by key also establishes the next record for subsequent sequential retrieval. This type of access may be used in this way to establish a starting point for sequential retrieval of records at other than the beginning of the file.

You can use random access by RFA to retrieve records directly from files residing on disk devices. However, a record's address can be determined only if the record has been accessed previously. The Find, Get, and Put services each return the RFA value as output in the RAB$W_RFA field.

Random access of records in a file is prohibited when you open the file and select the FAB$V_SQO option; that is, if you specify sequential operations only.

Input from Stream Format Files

For stream format files, RMS fills the user buffer with data until a terminator is reached. If the buffer fills before a terminator is encountered, the remainder of the data preceding the terminator is discarded, and an RMS$_RTB error is returned. If the terminator for stream format (FAB$B_RFM contains FAB$C_STM) is not CRLF (carriage return followed by line feed), the terminator is stored in the buffer following the record and included in the size of the record.

Input from Terminal Devices

There are two methods of obtaining input from a terminal using RMS:

• Using the RAB$L_ROP field to define the terminal input operation. Certain options applicable to the RAB$L_ROP field are used for terminal device input, such as whether a prompt is to be displayed and whether a time limit between characters is enforced. These options may require certain information to be placed in other fields of the RAB (see Chapter 7). The maximum buffer size is 512 bytes.
• Using an item list to define the terminal input operation in conjunction with a terminal XAB (XABTRM). The ETO option of the RAB$L_ROP field must be set and the user must provide an item list in the calling program, which RMS passes to the terminal driver using the item list address and length specified in the XABTRM (see Chapter 19). This method allows use of any terminal input option supported by the terminal driver, in contrast to the subset of RAB$L_ROP options available using the other method. The maximum buffer size is 512 bytes.

RMS uses the standard terminator set when performing input operations from terminal devices. The second longword of the I/O status block used is returned in the RAB$L_STV field. The terminating character is returned in the lower word of the status value field (RAB$W_STV0); however, note that with extended terminal operations, the terminating character is in the first byte of RAB$W_STV0, not in the entire RAB$W_STV0 word. More information about the second longword of the I/O status block is available in the OpenVMS I/O User's Reference Manual. The RAB$W_STV0 field is device dependent for terminal devices.

The Ctrl/Z character terminates the Get service and acts as an end-of-file marker. If you enter a Ctrl/Z in response to a request for data, RMS returns the completion status code for end-of-file (RMS$_EOF). RMS takes the data you enter before the Ctrl/Z but the next Get service returns a single end-of-file error (RMS$_EOF) without accepting any further input from the device. RMS resumes taking input if you request a subsequent Get service.

RMS also supports the use of escape sequences from terminal devices that are accessed locally and have escape sequences enabled. Escape sequences for a terminal are enabled by the SET TERMINAL command (described in the OpenVMS DCL Dictionary). Escape sequences are returned in the record buffer. The record size (RAB$W_RSZ) is the offset within the buffer (RAB$L_RBF) to the beginning of the escape sequence. The high-order word of the status value field (RAB$W_STV2) contains the length of the escape sequence, except for extended terminal operations. In this case, the escape sequence length is returned in the first byte of RAB$W_STV2, not the entire RAB$W_STV2 word, and the terminator position is returned in the second byte of the RAB$W_STV2 word. When a partial escape sequence warning (RMS$_PES) is returned, the remaining characters in the escape sequence are returned by the next read request from the terminal.

Input from Mailbox Devices

Mailboxes may be used to synchronize activity across cooperating processes. Normally, a Get service from a mailbox device is not completed until a record is present in the mailbox. When the Get service is completed, the status value field (RAB$L_STV) contains the process identification (PID) of the process that put the record into the mailbox. However, if the timeout (TMO) record option is specified with a value of 0 in the timeout field and if no messages are present in the mailbox, then the Get service returns an end-of-file error (RMS$_EOF). This technique assures your process of an immediate return, whether or not messages are present in the mailbox.

Using the RAB$L_STV Field

The RAB$L_STV field contains additional status information for a number of situations. When the completion status is a record-too-big warning (RMS$_RTB), RAB$L_STV contains the total record size. For record-oriented devices such as terminals and mailboxes, the second longword of the I/O status block is returned in the RAB$L_STV field, whenever the completion status (RAB$L_STS) is a success code. The alternate field definitions of RAB$W_STV0 and RAB$W_STV2 are provided to reference the respective low- and high-order words of the RAB$L_STV field. The record size field (RAB$W_RSZ) always reports the amount of data returned, regardless of the completion status (RAB$L_STS). The presence of valid data on error conditions may then be detected by checking the record size field.

User Record Area

The Get service always requires the presence of a user record area, as specified by the user record buffer address and user buffer area size fields in the RAB. The traditional fields used are RAB$L_UBF and RAB$W_USZ. However, OpenVMS Alpha users can code -1 in RAB64$L_UBF to direct the Get service to use the alternative fields RAB64$PQ_UBF and RAB64$Q_USZ. RAB64$PQ_UBF can hold either a 64-bit address or a 32-bit address sign-extended to 64 bits.

For undefined format files, the user buffer area size field (RAB$W_USZ or RAB64$Q_USZ) defines the amount of data to be returned on each Get service.

RAB Control Block Fields

Table RMS-43 lists the RAB control block fields read as input by the Get service. For additional information on the fields accessed by this service, see Part 2.

Table RMS-43 Get Service RAB Input Fields

Field Name	Option or XAB Type	Description
RAB$W_ISI		Internal stream identifier (required).
RAB$L_KBF		Key buffer address: used only if the RAB$B_RAC field contains RAB$C_KEY, or if the RAB$B_RAC field contains RAB$C_SEQ and you select the RAB$V_LIM option.
RAB$B_KRF		Key of reference: used only with indexed files and only if the RAB$B_RAC field contains RAB$C_KEY.
RAB$B_KSZ		Key buffer size: used only if the RAB$B_RAC field contains RAB$C_KEY, or if the RAB$B_RAC field contains RAB$C_SEQ and you select the RAB$V_LIM option.
RAB$L_PBF 1		Prompt buffer address (for terminal devices only).
RAB$B_PSZ 1		Prompt buffer size (for terminal devices only).
RAB$B_RAC		Record access mode (RAB$C_SEQ, RAB$C_KEY, RAB$C_RFA). 2
RAB$W_RFA		Record file address: used only if the RAB$B_RAC field contains RAB$C_RFA.
RAB$L_RHB		Record header buffer: used for the fixed-length control area of VFC records.
RAB$L_ROP		Record-processing options.
	RAB$V_ASY	Asynchronous: performs Get services asynchronously.
	RAB$V_CDK	Allows applications to look ahead for indexed file records with keys that duplicate the current key of reference.
	RAB$V_CVT 1	Convert: changes characters to uppercase for a Get service to a terminal device.
	RAB$V_ETO 1	Extended terminal operation: specifies that a XABTRM and an item list are used to define the terminal input operation. If this option is specified, no other RAB$L_ROP options applicable to terminal devices can be used.
	RAB$V_KGE 3	Search for equal key value or next key value according to sort order (for indexed files only).
	RAB$V_KGT 4	Search for next key value according to sort order; if neither the RAB$V_KGE (RAB$V_EQNXT) option nor the RAB$V_KGT (RAB$V_NXT) option is specified, RMS looks for a key match.
	RAB$V_LIM	Limit: specifies that the key value described by the RAB$L_KBF field and the RAB$B_KSZ field is to be compared with the value in the sequentially accessed record.
	RAB$V_LOC 1	Locate mode: specifies that Get service record operations use locate mode.
	RAB$V_NLK	No lock: specifies that the record accessed through the Get service is not to be locked.
	RAB$V_NXR	Nonexistent record processing: specifies that if the record directly accessed through a Get service does not exist, the service is to be performed anyway.
	RAB$V_PMT 1	Prompt: indicates that the contents of the prompt buffer are to be used as a prompt on a Get service to a terminal device.
	RAB$V_PTA 1	Purge type ahead: eliminates any information that may be in the type-ahead buffer on a Get service to a terminal device.
	RAB$V_RAH 1	Read ahead: used with multiple buffers to indicate read-ahead operations (sequential files only).
	RAB$V_REA	Lock for read: allows other users read access to the record.
	RAB$V_REV	Reverses search direction for random keyed access operations when used with either RAB$V_KGE or RAB$V_KGT (for indexed files only).
	RAB$V_RLK	Read of locked record allowed: specifies that a record locked for modification can be read by other users.
	RAB$V_RNE 1	Read no echo indicates that input data entered on the keyboard is not displayed on the terminal device.
	RAB$V_RNF 1	Read no filter: indicates that Ctrl/U, Ctrl/R, and DELETE are not to be considered control commands on terminal input, but are to be passed to the application program.
	RAB$V_RRL	Read regardless of lock: read the record even if another stream has locked the record.
	RAB$V_TMO 1	Timeout: indicates that the content of the timeout period field (RAB$B_TMO) is to be used.
	RAB$V_ULK	Manual unlocking: specifies that records cannot be unlocked automatically.
	RAB$V_WAT	Wait: if record is locked, wait until it is available.
RAB$W_ROP_2 1		Extended record-processing options.
	RAB$V_NQL	No query locking.
	RAB$V_NODLCKWT	No deadlock wait.
	RAB$V_NODLCKBLK	No deadlock blocking.
RAB$B_TMO 1		Timeout period: indicates the maximum number of seconds that RMS allows between characters for a Get service to terminal and mailbox devices, or the maximum number of seconds RMS waits for a locked record if you specify the RAB$V_TMO and RAB$V_WAT options in the RAB$L_ROP field.
RAB$L_UBF		User record buffer address (required).
RAB$W_USZ		User record buffer size (required).
RAB$L_XAB	XABTRM 1	Next XAB address: indicates the address of a XABTRM control block (the RAB$L_ROP field RAB$V_ETO option must be set for an extended terminal operation).

	privacy and legal statement
4523PRO_027.HTML