Document revision date: 30 March 2001

## OpenVMS Record Management Services Reference Manual

Previous | Contents | Index

## $FLUSH

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

RMS$_ACT | RMS$_ATR | RMS$_ATW
RMS$_BLN | RMS$_BUG_DAP | RMS$_CDA
RMS$_DME | RMS$_DNR | RMS$_EXT_ERR
RMS$_ISI | RMS$_NET | RMS$_NETFAIL
RMS$_NORMAL | RMS$_OPNOTSUP | RMS$_PENDING
RMS$_RAB | RMS$_RSA | RMS$_STR
RMS$_SUC | RMS$_SUP | RMS$_SUPPORT
RMS$_SYS | RMS$_WBE | RMS$_WER
RMS$_WLK |  |

## $FREE

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

RMS$_ACT | RMS$_BLN | RMS$_BUG_DAP
RMS$_EXT_ERR | RMS$_ISI | RMS$_NET
RMS$_NETFAIL | RMS$_NORMAL | RMS$_OPNOTSUP
RMS$_PENDING | RMS$_RAB | RMS$_RNL
RMS$_RSA | RMS$_STR | RMS$_SUC
RMS$_SUP | RMS$_SUPPORT |

## $GET

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

1This field is not supported for DECnet for OpenVMS operations.
2The default for the RAB$B_RAC field is RAB$C_SEQ.
3This symbolic offset is logically synonymous with RAB$V_EQNXT.
4This symbolic offset is logically synonymous with RAB$V_NXT.

Previous | Next | Contents | Index

| privacy and legal statement |
4523PRO_026.HTML