@READ - Read a SAM file

The @READ statement fully or partially reads a SAM file from disk or tape into the current work file.

Operation	Operands	F mode, L mode
@READ	[file] [(ver)] [lines[,...] ] [:cols[,...]:] [ {RECORDS | KEY} ] [STRIP]

file	Name of the SAM file that is to be read in. The name must correspond to the SDF data type <filename 1..54> or must consist of the special specification '/'. If there is as yet no local @FILE entry for the work file then, if the statement is successful, the specified file name is entered as an implicit local @FILE entry. If the file, operand is not specified then the explicit local @FILE entry, if present, and otherwise the global @FILE entry is used as the file name (see also @FILE statement). If neither an explicit local nor a global @FILE entry is defined (e.g. there is only an implicit local file entry) then the @READ statement is rejected with the error message EDT5484. If the specified file does not exist or cannot be accessed as required then the statement is rejected with a corresponding error message. If the file link name EDTSAM is assigned to a file then the user simply needs to specify '/' in order to read this file (see chapter “File processing”).
ver	Version number of the file that is to be read. If the specified version number does not match the file's version number, the message EDT0902 is output and the file is read in nevertheless.
lines	One or more line ranges that are to be read in from the SAM file. If symbolic line numbers are specified then their values are determined from the current work file and therefore usually have nothing to do with the record structure of the file specified in file. If lines is specified together with RECORDS then lines refers to the file's logical line numbers (see RECORDS). If lines is specified without RECORDS then the result is the same as specifying lines with KEY. If lines is not specified, the entire file is read in.
cols	One or more column ranges which define the section to be read in from each record. The ranges may repeat and overlap. The column specifications refer to the characters in the file that is to be read in. In the case of files which are present in a Unicode character set, they do not usually correspond to the byte positions within a record. If column values which exceed the record length are specified then blanks are read into the work file in their place. If KEY is specified (or lines without RECORDS) then the column count starts after the key in the record. If no column range is specified then the lines are read in full.
KEY	EDT interprets the first 8 characters of each read in record as a key. The records that are read into the work file are assigned this key as a line number and not as part of the line content. The KEY operand is the default value if lines has been specified. In this case, EDT checks whether a valid key is present in the first 8 characters of each line. To be valid, the key may consist only of the digits 0 to 9. Otherwise, the @ READ statement is aborted with the error message EDT4984. The records read up to this point are taken over into the work file. If a record has the key 0 then it is treated in the same way as a record with the key 1 (line number 0.0001) and the warning EDT2900 is issued. If lines is used to select lines then EDT assumes that the records in the file have ascending keys. If they do not, it is possible that not all the expected records will be read in.
RECORDS	Specifies that a line range (see lines operand) is to be selected via the file's logical line numbering. The logical line number of the first line is 0.0001, that of the second line 0.0002 etc. The records that are read in are inserted at the position in the work file determined by the current line number (see below). If STRIP is not specified then the RECORDS keyword can be abbreviated to R. The RECORDS operand is the default value if lines has not been specified.
STRIP	Causes any blanks at the end of each generated work file line to be deleted. If a line consists solely of blanks then all the blanks except one are deleted.

If KEY is specified (or lines without RECORDS) then lines shorter than 8 characters are ignored.

If lines or cols is specified then line numbers or column numbers may repeat, thus resulting in the corresponding lines or columns being read in several times.

If the read operation is performed without a KEY specification then the line numbers are assigned as a function of the current line number and current increment (see section “Line number assignment”).

The file is only opened temporarily during the read operation. If the file to be read in is empty, warning EDT2903 is output.

If the current work file is empty and has the character set *NONE then it is assigned the character set of the file that is to be read in. If this character set is *NONE then the work file is assigned the character set EDF03IRV.

If the work file already has a character set then the records that are to be read in are converted from the file's character set into the work file's character set. If the file that is to be read contains characters which cannot be displayed in the work file's character set then these are replaced by a substitute character if such a character has been specified (see @PAR SUBSTITUTION-CHARACTER), otherwise file read is aborted and the error message EDT5453 is output. This also applies if there are invalid characters outside of the column range that is to be read. In contrast, invalid characters outside of the line range that is to be read are ignored.

If the file is present in a Unicode character set and contains an illegal byte sequence, e.g. surrogate characters, then it will be impossible to read it even if SUBSTITUTION-CHARACTERS is specified. In this case, the read operation is rejected with the message EDT5454.

If the statement is interrupted with [K2] and the EDT session is continued with /INFORM-PROGRAM then the processing of the statement is aborted and message EDT5501 is output.

Note

If an attempt is made to use @READ to read an ISAM file then EDT issues the error message EDT1901 and sets the switch for EDT errors. It nevertheless reads the specified file by performing an internal @GET for this file.
In this case, the operands STRIP, RECORDS and KEY are ignored.

If file is specified then it is still possible, for reasons of compatibility, to abbreviate @READ to R in F mode.