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

Additional information available:

PARAMETERSQUALIFIERS

Examples

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.

Additional information available:

/DELETE/END_OF_FILE/ERROR/INDEX/KEY/MATCH
/NOLOCK/PROMPT/TIME_OUT

   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 VMS
   Record Management Services (VMS 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 /END_OF_FILE 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 /ERROR nor /END_OF_FILE 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 primary index is
   used (/INDEX=0). If you specify the /INDEX qualifier without a
   value, the default is the most recent value that was explicitly
   specified.

      /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 specified key.

   If you are reading indexed files and you do not use the /MATCH
   qualifier, the default is /MATCH=EQ.

   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.

   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.