Reads a single record from a specified input file  and  assigns  the
  contents of the record to a specified symbol name.

  Format:


    READ  logical-name[:] symbol-name

Additional information available:

ParametersCommand QualifiersExamples

 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 a 1- through 255-alphanumeric character symbol name to  be
  equated  to  the  contents  of the record being read.  A symbol name
  must start with an alphabetic letter, underscore, or 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 is already 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

 /DELETE

 Specifies that a record be deleted 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 READ/DELETE.

 /END_OF_FILE=label

 Specifies the label on a line in the current command procedure  where
  control  is  transferred  after  the  last record in a file is read.
  When the last record in the file is read, the VAX Record  Management
  Services   (VAX  RMS)  return  an  error  condition  indicating  the
  end-of-file.   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, then control is given to the error
  label  specified  with  the /ERROR qualifier when the end-of-file is
  reached.  If neither /ERROR nor /END_OF_FILE is specified, then  the
  current ON condition action is taken.

 /ERROR=label

 Specifies a label on a line  in  the  command  procedure  to  receive
  control  if  the  read  request  results  in  an error.  If no error
  routine is specified and an error occurs during the reading  of  the
  file, the current ON condition action is taken.

  The error routine specified for this qualifier takes precedence over
  any action statement indicated in an ON command.

  If an error occurs  and  the  target  label  is  successfully  given
  control, the reserved global symbol $STATUS retains the code for the
  error that caused the error path to be taken.

 /INDEX=n

 Specifies the index (n) to be used to look up keys  when  reading  an
  indexed file.

  If you omit the /INDEX qualifier, the primary index (0) is assumed.

 /KEY=string

 Requests that a record  having  a  key  that  matches  the  specified
  character  string be read.  Binary and integer keys are not allowed.
  This qualifier, when used together with /INDEX,  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.

  In order 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 will access  records  in
  the indexed file sequentially.

 /MATCH=option

 Specifies the indexed key match algorithm that is  to  be  used  when
  reading a record.  You can specify the following options:

  EQ    Selects keys that are equal to the specified key.

  GE    Selects keys that are greater than or equal to  the  specified
        key.

  GT    Selects keys that are greater than the specified key.

  If you use the  /MATCH  qualifier,  you  must  specify  one  of  the
  options.     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 is not to be  locked,  and  also
  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 read.

 /PROMPT=string

 Specifies an alternate prompt string to  be  displayed  when  reading
  from  the  terminal.   By  default,  the  prompt  string,  DATA:, is
  displayed.

 /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, and the value must  be  from  0
  through 255.

  If you entered both the /ERROR=label and /TIME_OUT  qualifiers,  and
  if the time limit expires, then 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.   $ 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.