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-40 lists the control block fields written as output by the
Flush service.
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).
|
