HP OpenVMS DCL Dictionary
READ
Reads a single record from a specified input file and assigns the
record's contents to a specified symbol name.
Format
READ logical-name[:] symbol-name
Parameters
logical-name[:]
Specifies the logical name of the input file from which a record is to
be read. Use the logical name assigned by the OPEN command when the
file was opened. (The OPEN command assigns a logical name to a file and
places the name in the process logical name table.)
In addition, you can specify the process-permanent files identified by
the logical names SYS$INPUT, SYS$OUTPUT, SYS$ERROR, and SYS$COMMAND.
symbol-name
Specifies the name of a symbol to be equated to the contents of the
record. The name must be 1 to 255 alphanumeric characters and must
start with an alphabetic letter, an underscore (_), or a dollar sign
($).
When you specify a symbol name for the READ command, the command
interpreter places the symbol name in the local symbol table for the
current command level. If the symbol has already been defined, the READ
command redefines it to the new value being read.
Description
The READ command can read data from sequential, relative, or indexed
files. After each record is read from the specified file, the READ
command positions the record pointer at the next record in the file;
however, if you are reading an indexed file, you can use the /INDEX and
/KEY qualifiers to read records randomly.
The maximum size of any record that can be read in a single READ
command is 2048 bytes. The reading of a 2048-byte record from a remote
file opened by DCL requires that the system default network block count
be increased to a minimum value of 25 (DCL SET RMS_DEFAULT/NETWORK=25).
To read a file, the file must be opened by using the /READ qualifier
with the OPEN command. The process-permanent files identified by the
logical names SYS$INPUT, SYS$OUTPUT, SYS$ERROR, and SYS$COMMAND do not
have to be opened explicitly to be read.
If the READ command is executed interactively and the logical name is
specified as one of the process-permanent files, SYS$INPUT, SYS$OUTPUT,
SYS$COMMAND, or SYS$ERROR, the command interpreter prompts for input
data. The READ command accepts data exactly as you enter it. The READ
command does not convert characters to uppercase, remove extra spaces
and tabs, or remove quotation marks (" "). Also, the READ command does
not perform symbol substitution. See the /PROMPT qualifier for more
information on issuing prompts with the READ command.
Qualifiers
/DELETE
Deletes a record from an indexed file after it has been read. An
indexed file must be opened with the /READ and /WRITE qualifiers in
order to use the READ/DELETE command.
/END_OF_FILE=label
Transfers control to the location specified by the label
keyword (in the current command procedure) when the end of the file is
reached. When the last record in the file is read, the OpenVMS Record
Management Services (RMS) returns an error condition indicating the
end-of-file (EOF). If the /END_OF_FILE qualifier is specified, the
command interpreter transfers control to the command line at the
specified label.
If the /END_OF_FILE qualifier is not specified, control is given to the
error label specified with the /ERROR qualifier when the end of the
file is reached. If neither the /ERROR nor the /END_OF_FILE qualifier
is specified, then the current ON condition action is taken.
/ERROR=label
Transfers control to the location specified by the label
keyword (in the current command procedure) when a read error occurs. If
no error routine is specified and an error occurs during the reading of
the file, the current ON condition action is taken.
Overrides any ON condition action specified.
If an error occurs and the target label is successfully given control,
the reserved global symbol $STATUS retains the error code.
/INDEX=n
Specifies the index (n) to be used to look up keys when
reading an indexed file.
If you do not specify the /INDEX qualifier, the most recent /INDEX
qualifier value is used. If a previous value was not specified, the
primary index is used (/INDEX=0).
/KEY=string
Reads a record with the key that matches the specified character
string. Binary and integer keys are not allowed. This qualifier, when
used together with the /INDEX qualifier, allows you random access to
indexed files.
Key matches are made by comparing the characters in the /KEY string to
characters in the record key.
To read records at random in an indexed file, you must specify the /KEY
qualifier. Once a record is read randomly, all subsequent reads without
the /KEY qualifier access records in the indexed file sequentially.
/MATCH=option
Specifies the key match algorithm to be used when searching for
matching keys. Specify one of the following options:
|
EQ
|
Selects keys equal to the match value (default).
|
|
GE
|
Selects keys greater than or equal to the match value.
|
|
GT
|
Selects keys greater than the match value.
|
|
LE
|
Selects keys less than or equal to the match value.
|
|
LT
|
Selects keys less than the match value.
|
If you are reading indexed files and you do not use the /MATCH
qualifier, the default is /MATCH=EQ.
/NOLOCK
Specifies that the record to be read not be locked and enables a record
to be read that has been locked by other accessors.
By default, records are locked as they are read and unlocked on the
next I/O operation on the file.
/PROMPT=string
Specifies an alternate prompt string to be displayed when reading from
the terminal. The default prompt string is DATA:.
/TIME_OUT=n
/NOTIME_OUT (default)
Specifies the number of seconds after which the READ command is
terminated if no input is received. If you enter the /TIME_OUT
qualifier, you must specify a value from 0 to 255.
If you enter both the /ERROR=label and /TIME_OUT qualifiers, and the
time limit expires, the error branch is taken.
/WAIT
Sets RAB$V_WAT to make a process wait for a record in a file. Can be
used in combination with /TIME_OUT to restrict how long the process
should wait before timing out upon failure to find the record.
Examples
| #1 |
$ OPEN IN NAMES.DAT
$ LOOP:
$ READ/END_OF_FILE=ENDIT IN NAME
.
.
.
$ GOTO LOOP
$ ENDIT:
$ CLOSE IN
|
The OPEN command opens the file NAMES.DAT for input and assigns it the
logical name of IN. The READ command reads records from the file IN and
places the contents into the symbol NAME. The READ command specifies
the label ENDIT to receive control when the last record in the file has
been read. The procedure loops until all records in the file have been
processed.
| #2 |
$ READ/ERROR=READERR/END_OF_FILE=OKAY MSGFILE CODE
.
.
.
$ READERR:
$ CLOSE MSGFILE
.
.
.
$ OKAY:
$ CLOSE MSGFILE
$ EXIT
|
The READ command reads records from the file MSGFILE and places the
contents into the symbol CODE. The READ command also uses the /ERROR
and /END_OF_FILE qualifiers to specify labels to receive control at the
end-of-file (EOF) and on error conditions. At the EOF, control is
transferred to the label OKAY. On other read errors, control is
transferred to the READERR label.
| #3 |
$ READ SYS$COMMAND DATA_LINE
$ WRITE OUTPUT_FILE DATA_LINE
.
.
.
|
The READ command requests data from the current SYS$COMMAND device. If
the command procedure containing these lines is executed interactively,
the command issues a prompt to the terminal, accepts a line of data,
and equates the data entered to the symbol name DATA_LINE.
Then the WRITE command writes the value of the symbol DATA_LINE to the
file identified by the logical name OUTPUT_FILE.
| #4 |
$ OPEN/READ INPUT_FILE TRNTO::INVENTORY.DAT
$ OPEN/APPEND OUTPUT_FILE RECEIVE.DAT
$ READ INPUT_FILE DATA_LINE
$ WRITE OUTPUT_FILE DATA_LINE
|
The OPEN/READ command opens the file INVENTORY.DAT at the remote node
TRNTO for reading and assigns it the logical name INPUT_FILE. The
OPEN/APPEND command opens the file RECEIVE.DAT in the current default
directory. The READ command requests data from the file INVENTORY.DAT
at the remote node TRNTO. The WRITE command writes the value of the
symbol DATA_LINE to the end of the local file RECEIVE.DAT.
| 
