READ

Read Data from I/O Channel

This directive is used to READ data from a file or device.

Syntax

[P]READ [(channel [, I/O-opts])] [variable-list]
[, IOL=line-ref]

[P]READ RECORD [(channel [, I/O-opts])] string-variable

channel

is an integer in the range of 0 to 32764 indicating the channel of an OPEN file. If omitted, 0 is the default.

I/O-opts

is one or more of the following specifiers:

Branching

ERR=line-ref DOM=line-ref END=line-ref

Record

IND=numeric-value KEY=string-value SRT=sort-name

Miscellaneous

TBL=line-ref ERC=error-code

variable-list

is a list of numeric and/or string variable names that receive values from the record.

line-ref(IOL)

is the program line number or label containing an IOLIST directive that defines a variable list (the IOL= option may be used by itself or together with a variable list; the comma preceding IOL= is used only when a variable precedes IOL=), or the program line number or label to branch to if the specified error occurs.

string-variable

is the name of the string variable that receives the entire record as data

Remarks

On OpenVMS a non-existent record now returns a record of all nulls.

Starting with level 8.2, a format may be specified to receive the data retrieved by the directive.

The attempt to reference a format name that the data dictionary or the current program does not recognize results in an ERR=161.

The PREAD directive is available starting with release level 8.0.

The only difference between PREAD and READ comes when the directive is executed without using the KEY= I/O option. In this case, READ obtains the next record based on the next logical KEY value (the next highest collating sequence key) and PREAD obtains the next record based on the next logical PKY value (the next lowest collating sequence key, or previous key).

A programmer can READ a record on one channel, which has already been READ on another channel.

I/O options include:

ERR=

specifies the program line number or label to branch to if an error is produced by this directive.

DOM=

specifies the program line number or label to branch to if an attempt is made to access a record using KEY= and no such key value is found (ERR=11). DOM= takes precedence over ERR= in the same READ directive.

END=

specifies the program line number or label to branch to if the end of the file is reached (ERR=2). End of file for PREAD signifies an attempt to process a record less than the first key of the file. END= takes precedence over ERR= in the same READ directive.

IND=

specifies the index number of the record to access.

KEY=

specifies the key value of the record to access.

SRT=

specifies which sort key to use for MSORT files.

TBL =

specifies the integer program line number or label of the TABLE directive to be used for code conversion for the incoming data (see TABLE directive).

ERC=

specifies a programmer-defined error code, which enables programmers to define and manage errors without branching. ERC= provides a structured programming alternative to ERR=.

The IND= and KEY= options are mutually exclusive in the same READ directive. If neither the IND= or KEY= options are used READ accesses the next logical record in the file.

Starting with 8.2, a format may be specified to receive the data retrieved by the directive.

For a READ without the RECORD clause, values from each field of the record being accessed are loaded into the variable list or IOLIST in sequential order (i.e., the value of the first field in the record is loaded into the first variable, the second value into the second variable, etc.). An “*” is used to specify a field that is skipped and does not have data entered into a variable. Fields in the record are separated by the hexadecimal character $8A$ (field separator).

For OPEN statements using the SEP= option, the field separator can be any character, i.e., OPEN (2, SEP=$8F$) file. This allows for variable-length fields in a record. Field separators are placed in the record by use of the WRITE directive without the RECORD clause.

The RECORD modifier for this directive allows the entire record, including any field separator characters, to be entered as data into a single string variable. This modifier cannot be used with the IOL= option.

A READ using the KEY= option on a sort file does not actually access any data because Sort files contain only keys.

Starting with release level 8.2, the TIM=0 option on READRECORD from a terminal is available.

Specifying a sort-name with the SRT= option sets the default sort sequence to the sort-name key sequence. Subsequent [P]READ or [P]EXTRACT directives that do not use the SRT= option uses the new default sort sequence.

Starting with release 8.3.0, an attempt to reference a format or data name in the I/O list of a channel that was OPENed with OPT=“LINK” results in an ERR=172.

Starting with release level 8.3.1, you can us the READ RECORD (channel) string-variable directive to access a SORT file. Previously, you had to use a sequence such as K$ = KEY(channel); READ (channel) to access a SORT file. Now, you can specify a directive such as READ RECORD(channel) K$ to produce the same result. This capability adds increased performance to your applications.

For information on how to use the READ RECORD directive to request information from a DDE server when you use the Thoroughbred Environment under Microsoft Windows, please refer to the description of the OPEN directive.

Examples

READ (1) A$, A

accesses the record with the next highest key in the file OPEN on channel 1 and transfers data from the first field to the variable A$ and from the second field to the variable A.

PREAD RECORD (1) B$

accesses the record with the next lowest key in the file OPEN on channel 1 and transfers the entire record, including any field separators, into the variable B$.

READ RECORD (1, IND=X, ERR=7999) B$

If X = 56 accesses the record having the Index number 56 and branches to program line 7999 if this directive produced any error condition, including an End of File (ERR=2).

READ (1, KEY=I$) IOL=5000

If I$=“ASD#123” and program line 5000 is IOLIST A$, A then this directive accesses the record with the key value “ASD#123” and expects to find two fields which are placed in A$ and A.

READ (1, SRT = "ZIPCODE", KEY="10453") A$

changes to the “ZIPCODE” sort, and reads to the key “10453”.

Note:

Once the sort has been changed, it cannot be changed back.

READ (1,KEY=K$) #DNFFMT

reads a record out of the OPENed data file and loads it into the data area of the format names DNFFMT.

See also

LOCK, PREAD, and TABLE directives

From the Thoroughbred Basic Language Reference, Volume III: R–Z, version 8.9.1. Open this page in the PDF