READ

READ is a DCL command that reads a single record from a specified input file and assigns the record's contents to a specified local symbol name.

Syntax

READ  logical-name[:] symbol-name

logical-name is the device you are reading from, SYS$COMMAND, SYS$INPUT, or a logical name defined to an open file with the OPEN command (see example below).

symbol-name is a name for the symbol to read the record's contents into.

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.

$ OPEN/READ FILE FILE.LIS
$LOOP:
$ READ/END_OF_FILE=END FILE LINE
...
$ GOTO LOOP
$END:
$ WRITE SYS$OUTPUT "Finished"
$ CLOSE FILE
$ EXIT 1

In the example above, /END_OF_FILE is used to branch to label END when the end of file is reached.

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

$ OPEN/READ FILE FILE.LIS
$LOOP:
$ READ/END_OF_FILE=END /ERROR=ERROR FILE LINE
...
$ GOTO LOOP
$END:
$ WRITE SYS$OUTPUT "Finished"
$ CLOSE FILE
$ EXIT 0
$ERROR:
$ WRITE SYS$OUTPUT "Oops"
$ CLOSE FILE
$ EXIT 1

In the example above, /END_OF_FILE is used to branch to label END when the end of file is reached and /ERROR is used to branch to label ERROR when an error occurs.

• /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:.

$ READ SYS$COMMAND LINE /PROMPT="Enter data:"
Enter data:

In the example above, READ SYS$COMMAND is used to obtain data from the terminal. Whatever the user enters at the "Enter data:" prompt, will be saved as the value of the LINE symbol (case sensitive).

• /TIME_OUT=n 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. The default is /NOTIME_OUT. 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.