Reference > Commands

The form of the READ command is:

READ [(stream)] x [EREC = position] [.] [EFIL = position],

READ NEXT [(stream)],

READ REWIND stream,

where x denotes a buffer or a field.

The stream refers to one of the four input streams called A, B, C or D.

The READ command is used in the Data Stage to read a new record from an input data file.

The EREC and EFIL parameters can be used to transfer control to another part of the code if a new serial number is encountered or the end of the input data file is reached.

X denotes the location into which the record is to be read; if it is not specified, buffer 0 is assumed. If CARD CHARACTERS have been set, x must be a field.

The NEXT parameter offers a "look-ahead" facility.

The REWIND facility returns to the front of the file being read. If more than one data file is used for a stream only the current file is rewound. You cannot rewind a file after the end-of-file has been reached. For this reason you should add a dummy record to the end of the file to trap and prevent the file being closed before rewind. You cannot rewind stream A.

Data reading is usually handled automatically by CL, but the READ command is provided for you to specify your own data reading. This is useful for handling data sets containing more than one raw record per logical record and essential for handling sets containing trailer records (more than one raw record with the same card type identifier), which would be rejected by the automatic card reading facility as containing duplicate card types.

The EREC parameter allows you to jump to another part of the code at the end of a logical record. A logical record is defined as a sequence of cards all containing the same serial number or identifier, defined in the SERIAL command. The end of a logical record occurs when a card is read which contains a different serial number from the last card read. If the EREC parameter is set, the card is saved and execution continues at the position specified. When a READ command is next encountered, it is not executed; the saved card is stored in the designated buffer, and execution continues with the next command. This enables you to process some end-of-record processing, which typically will involve a WRITE command or passing through the end of the code and automatically writing a record.

The EFIL parameter allows you to jump to another part of the code at the end of the input data file. You are advised to ensure that the code commencing at the position ends in a STOP command, so that CL can terminate the run properly. The EFIL parameter allows you to insert some end-of-run processing, perhaps writing out a summary of some kind. The EFIL parameter may be needed when reading from more than one input stream, because the run will terminate automatically as soon as the end of one of the streams is reached.

The NEXT parameter tells CL to look ahead in the stream and read the next line (or card) into the designated buffer and remember it. This does not affect the normal flow of reading the file; the next ordinary READ after a READ NEXT will recall again the image read by the READ NEXT command. You cannot look further ahead than the next line (or card); two READ NEXT commands, not separated by an ordinary READ, will read the same line twice. Care should be taken when using the EREC and EFIL parameters on a READ NEXT command.

IMPORTANT: a READ following a READ NEXT copies the data from the holding buffer, not the file. This means that a READ cannot read more columns than a preceding READ NEXT because only the columns requested by the READ NEXT can be retrieved.

Note that unless run control parameter BRA is set, blank (empty) input lines (or cards) will be completely ignored by the Execution Step; every READ or READ NEXT will return with the next non-blank line (or card).

IMPORTANT: if READ is used with a field, a new record is always read. You cannot read different parts of the same record with different READ commands.

Examples of READ commands:

read $101-180 erec=50,

read (d) $1101-1190,

read erec=@endr.efil=@endf,

read (b) $1-80 efil=999,