READ Verb

Syntax

READ {(channelno{options})}{inputlist}
READ RECORD{(channelno{options})}{strvar}

NOTE:INPUT, EXTRACT, and FIND use the same syntax as READ and READ RECORD.

Description

For BBj specific information, see the READ Verb - BBj.

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:

$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:

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: "string"=lineref If the input data matches the character string constant, PRO/5 branches to lineref. $xxxx$=lineref Same as ""string"=lineref" above, except this is a hex string constant. LEN=intA,intB The length of the input data cannot be less than intA or greater than intB. This option must be the last item in the list. If none of the verifyoptions are met, PRO/5 issues an error.
numvar{:(verifyoptions)}	If no verifyoptions are given, PRO/5 converts the field input to the internal numeric format and assigns it to the designated numeric variable. See the Numeric Input Verification section in the User's Reference Guide. If verifyoptions is given, PRO/5 delays the assignment, while it verifies the data. String input is allowed, for example, where entering "END" is an option. PRO/5 allows the following verifyoptions: "string"=lineref If the input data matches, the character string constant branches to lineref. $xxxx$=lineref Same as ""string"=lineref" above, except this is a hex string constant. num A numeric expression can impose range and precision on the numeric input. If given, this must be the last item on the list. At this point, PRO/5 assigns the numeric value. Verification continues. If num is positive, then the input must be a positive value ranging from zero to num. If num is negative, then the input must be a value ranging from -num to +num. In either case, the number of digits following a decimal point in num determines the number of digits following the decimal point allowed in the input.
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= or IND= 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 of KEY= and IND= is subject to the type of file being accessed.
Data is read.
If the EXTRACT verb is used, the file pointer is not moved. If the FIND verb 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. The DIR= option affects the increment used when advancing the file pointer.
The READ data 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)