Directives 

READ

Read Data from File

Format

READ (filespec[,fileopt])varlist 

Where:

filespec

Can be a numeric expression indicating the open channel number to use or a string expression containing the pathname or table name (if string is prefixed by the keyword TABLE) of the file to use.

fileopt

Supported file options (see File Options):

BSY=stmtref

Traps Error #0: Record/file busy

DIR=num

Direction indicator (Not supported with [WDX] tag)

DOM=stmtref

Missing record transfer

END=stmtref

End-of-File transfer

ERR=stmtref

Error transfer

IND=num

Record index

KEY=string$/num

Record key

KNO=num | name$

File access key number (num) or name (name$)

REC=name$

Record prefix where the name of the variable (rather than its contents) defines the prefix. (REC=VIS(name$) can also be used where the contents of the name$ variable defines the prefix.)

For more information on using the REC= option, see Prefixing Variables in an IOList via REC=.

RNO=num

Record number

RTY=num

Number of retries (one-second intervals). This overrides the value defined by the 'WT' system parameter.

SIZ=num

Number characters to read

TBL=stmtref

Data translation table

TIM=num

Maximum time-out value in integer seconds

stmtref

Program line number or statement label to which to transfer control

varlist

Comma-separated list of variables, literals or IOL= options.

(TABLE support was added in PxPlus 2018.)

Description

Use the READ directive to read data from the file you identify by channel. When it is read, the data will be split into one or more fields, either separated by the currently defined separator character or defined by embedded formats, with the contents of the first field placed in variable 1, the second field in variable 2, etc. The system will convert numeric data automatically on a READ statement when moving it to numeric variables. Numeric data converted during a READ directive does not use the 'DP' (Decimal Point Symbol) or 'TH' (Thousands Separator) system parameters for European decimal settings.

If you want to skip a field in the record, use an * (asterisk) as a placeholder instead of a variable name. You can refer to an IOList instead of using a list of variables in varlist. To do this, use IOL=iolref. The iolref can be a line number or statement label for the line containing an IOList, or it can be a string containing a compiled IOList.

If you do not include variables in the READ directive, the system will use the IOL= option (if you included one) in the OPEN statement for the given file. If varlist contains more variables than there are current fields in the record, the additional variables are set to either 0 (for numeric variables) or a null string (for string variables).

The READ directive will advance the file position to the next record (or if you use a KEY= or IND= option, to the record you identify then) and if you use the KNO= option, the current access key will be changed accordingly.

Automatic Padding with KEY= Option

When you use KEY=string$:string$[:string$][...], the system automatically pads key segments. This is valid only if you have Keyed files with segmented key definitions. The system right pads the key segment using $00$ (nulls) to the segment's full length. The last segment in a compound key will not be padded.

Example:

keyed "TEST",[1:1:5]+[2:1:6]+[3:1:8]
read (1,key=A$:B$:C$)

… is the same as:

read (1,key=pad(A$,5,$00$)+pad(B$,6,$00$)+C$)

Read Next Physical

If you specify KNO=* on the READ directive, the system will read and return the next physical record from the file. The read will not utilize any of the key tables in order to access the data. This significantly reduces the overhead involved in the data retrieval process.

Use of the Read Next Physical capability can greatly reduce the time it takes to process a file where the order of the data is not important.

(The ability to read next by physical location was added in PxPlus v6.30.)

See Also

FIND Locate and Read Data
EXTRACT Read and Lock Data
OPEN Open a File for Processing
*MEMORY* Create and Use Memory File

Example

0410 read (1,err=1000,dom=1200)A,B,*,*,E$