READ and READ RECORD Verbs
Syntax
READ {(channelno{options})}{inputlist}
READ RECORD{(channelno{options})}{strvar}
Description
The READ verbs input data from the file or device OPENed on the specified
channel. If channelno{options}
is not specified, PRO/5 defaults to channel 0.
The options allow some input error trapping and branching to error-handling routines, file pointer placement and data translation, and the use of verifyoptions within the inputlist. These options also provide a method to verify numeric and string input and to branch to different lines, depending on the input.
Options
The following options can be used in any order:
| Applicable Verbs | Option | Description |
|---|---|---|
| READ/INPUT/EXTRACT/FIND | ,ERR=lineref | Branch to be taken if an error occurs during the execution of the statement. Higher priority error branches override ERR=. However, ERR= overrides SETERR for the duration of the current verb. |
| READ/INPUT/EXTRACT/FIND | ,END=lineref | Branch to be taken at end-of-file (!ERROR=2). END= overrides ERR= for end-of-file cases. |
| READ/FIND/INPUT | ,DIR=int | Following a successful READ/INPUT/FIND, ,DIR=int moves the file pointer the number of records specified by the absolute value of int in the direction specified by the sign of int. This option does not affect the behavior of an EXTRACT. A READ that does not specify a DIR=int option has an implicit DIR=1. When the DIR= option is used for INPUT on keyed files and read on a stream-oriented device such as a terminal, serial port, or string file, it returns an !ERROR=13 - Improper Access. |
| READ/EXTRACT/FIND | ,DOM=lineref | Branch to be taken if a key cannot be found in a keyed file. DOM= overrides ERR= for duplicate/missing key errors. |
| READ/EXTRACT/FIND | ,IND=index | Moves the file pointer to the specified record or byte before the data transfer takes place. |
| READ/EXTRACT/FIND | ,KEY=string | Moves the file pointer to the record in a keyed file corresponding to string. If the key does not exist, PRO/5 issues an error and leaves the file pointer at the first key greater than the missing key (except in the FIND verb). Use KEY= to move to the middle of a keyed file before sequentially scanning it. KEY= has no defined effect on devices. |
| READ/INPUT/EXTRACT | ,TBL=lineref | Translates data as it is read. lineref must reference a TABLE statement. See TABLE for additional information. Key values are not translated. |
| READ/INPUT/EXTRACT/FIND | ,TIM=int | If data is not yet available from a device, or a record is locked by another user, PRO/5 waits int seconds before it returns an error. PRO/5 retries the requested I/O operation until the wait time has expired and defaults to a 10-second timeout for disk files if a TIM= option is not given. A READ from the keyboard will not time out if a TIM= option is not specified. The default for other devices varies from system to system. PRO/5 guarantees a range of 0 to 255 for int. Some devices treat TIM=0 as TIM=1. The TIM=int option is not available with I/O operations involving C-ISAM files. |
| READ/INPUT/EXTRACT | ,SIZ=int | Maximum number of bytes allowed for any item in the inputlist. SIZ= is required when a READ RECORD is performed on a byte-oriented file because there is no concept of a record. SIZ=0 is the same as no SIZ= option. When reading from a device, a negative SIZ value indicates that PRO/5 is to return, without error, up to ABS(SIZ) bytes, if the READ times out. |
| READ/INPUT/EXTRACT | ,LEN=int | Maximum number of bytes allowed for any item in the inputlist. The LEN= option is similar to the SIZ= option in restricting the length of the input. LEN= is different from SIZ= in that LEN= discards characters past the LEN= length until a terminator is found. LEN=0 is the same as no LEN= option. |
| READ/EXTRACT/FIND | ,KNUM=int | Selects a key chain when accessing files. |
Input Lists
inputlist consists of variables
that will be assigned values from the data read and possible output items.
For example, PRO/5 outputs any constants in the inputlist
as though they are part of a PRINT statement. Each input variable is assigned
a field from the incoming data.
A field is an arbitrary number of bytes followed by a field terminator byte. PRO/5 recognizes the following values for field terminators:
| Bytes | Value |
|---|---|
| $00$ | null (record filler) |
| $0D$ | carriage return |
| $0A$ | linefeed |
| $1C$, $1D$, $1E$, $1F$ | special function characters |
PRO/5 also recognizes the standard newline character for a particular
system as a field terminator, usually a linefeed. The STBL(!TERMS) variable
can be used to set a new set of termination characters for terminal devices.
See the User's Reference Guide
for additional information.
For each input item, PRO/5 scans the incoming data for a field terminator
until it reaches the maximum size specified by the SIZ= option. The field
terminator is not kept as part of the field. Before PRO/5 assigns the
contents of the field to the variable, it provides some verification of
the data and converts it (see strvar
below). The CTL variable determines which field terminator was last encountered.
See the CTL for additional
information. PRO/5 resumes scanning for the next field with the following
byte.
The following are the legal inputlist items:
| inputlist Item | Description |
|---|---|
| strvar{:(verifyoptions)} |
A string variable receives the next field scanned. See Assigning Data to String Variables and Substrings in the Language Concepts section of the User's Reference Guide. verifyoptions is a list of items separated by commas. If verifyoptions is present, PRO/5 verifies input after assigning the string. PRO/5 verifies the actual data input, not the data assigned. This makes a difference when assigning to a substring where the data may be truncated. (See String Input Verification in the Language Concepts section of the User's Reference Guide.) The following are allowable verify items:
|
| numvar{:(verifyoptions)} |
|
| array[ALL] | PRO/5 enters an entire numeric or string array. For example, array X has been dimensioned to 5 elements (0 to 4). X[ALL] is identical to X[0], X[1], X[2], X[3], X[4]. Each element input is a field. Arrays in PRO/5 are row major. |
| * | PRO/5 skips the field indicated by an asterisk in an inputlist and scans the field, as it would for any other input, but does not assign the data. |
| IOL=lineref | Refers to the IOLIST statement at lineref for more inputlist items. PRO/5 operates as if the items in the IOLIST were in place of the IOL= option. Several IOL= items can appear in an inputlist. An IOLIST can also invoke other IOLISTs with the IOL= option until all the memory is used. If there is no IOLIST at lineref, PRO/5 issues an error. |
In addition to the input items above, all output items such as the @(col{,row})
mnemonic described under the WRITE verb are allowed. If PRO/5 encounters
an output item in an input list, it outputs the item. Output during input
is allowed only with terminals.
READ RECORD reads data without regard to field terminators. PRO/5 assigns
the contents of the record to the string variable using the rules listed
in the Assigning Data to String Variables
and Substrings section in the User's
Reference Guide. READ RECORD can read binary data that may be otherwise
misinterpreted as field terminators and is the most efficient way to read
data.
The SIZ= option can be used to read part of a record. If SIZ= specifies
more data than the record contains, only the record is read, and no error
is issued. SIZ= must be given if READ RECORD is performed on a byte file.
The CTL value is not affected by READ RECORD.
File Input Sequence
The following sequence of events takes place during input from a file:
-
PRO/5 evaluates any options.
-
If
KEY=orIND=is given, PRO/5 moves the file pointer to the appropriate record. If a key or index is not requested, PRO/5 defaults to the current record. The proper use ofKEY=andIND=is subject to the type of file being accessed. -
Data is read.
-
If the
EXTRACTverb is used, the file pointer is not moved. If theFINDverb is used and the record is not found, the file pointer is not moved. Otherwise, the file pointer is advanced to the next byte in a byte file or to the next record in a record file. TheDIR=option affects the increment used when advancing the file pointer. -
The
READdata is assigned to the variables in the input list.
An end-of-file error occurs if the program tries to read beyond the
last record in a file.
FIND handles missing keys differently than other input verbs. If the KEY=
option requests a key that does not exist, FIND leaves the file pointer
where it was before the FIND operation. In some applications, the file
pointer is not moved and using FIND in these cases saves time in some
implementations. For non-keyed files, FIND and READ are identical.
EXTRACT locks the record just read from other users. The record remains
locked until another I/O operation is performed on that channel or until
the channel is closed. See Locking
Files (LOCK) in the User's Reference
Guide. EXTRACT does not advance the file pointer at the end of
the statement as other verbs do. READ and INPUT are identical in execution.
C-ISAM File Behavior
The following are important behaviors for C-ISAM files:
The FIND verb resets the file pointer. Subsequent KEY()- function calls
and unkeyed READ operations can result in an !ERROR=2.
It is possible to READ a record currently extracted by another process.
An extracted C-ISAM record is released on the next READ, FIND, or EXTRACT
operation on the channel before the operation is performed.
TCP and UDP Behavior
On a TCP client, READ and READ RECORD will generate an !ERROR=2 when
the connection is closed by the server.
READ will not function with UDP sockets and will not report errors.
READ RECORD will function with UDP sockets, but the correct size of
the record must be specified. An incorrect size produces an !ERROR=3 TCB(10)=10040,
and the record will not be read.
Examples
1000 READ(1,KEY="TEST",ERR=9500)A$,B$,C$
1400 READ RECORD(1,IND=X,ERR=9500)A$
1200 EXTRACT(2,KEY=Q$,DOM=1300)IOL=0205
1000 FIND (1,KEY="000G/L000")*,K1$
2000 INPUT (0,ERR=1000)@(5,20),'CE',"ENTER NAME:"
2000:,N$:("FRED"=2100,"MARY"=3000)