# Directives

READ RECORD | Read Record from File

## Format

READ RECORD (filespec[,fileopt])var$

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 (REC=VIS(string$) can also be used)
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
var$ | String variable. Receives the contents of the record being read.

(TABLE support was added in PxPlus 2018.)

## Description

READ RECORD reads a record from a file (chan) and returns the complete record's data portion to the string variable (var). A READ RECORD statement can be used when dealing with native-mode operating system files, when exchanging data between PxPlus and other applications, or to read a complete record, including data field separators.

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

PxPlus supports use of the READ RECORD directive with *MEMORY* (a memory-resident file or queue of records) and ZIP files.

## Automatic Padding with KEY= Option

When you use KEY=string$:string$[:string$][...], PxPlus will automatically pad key segments. This is valid only if you have Keyed files with segmented key definitions. Then, PxPlus right pads the key segment using $00$ (nulls) to the segment's full length but does not pad the last segment:

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

#### Note:
The last segment in a compound key will not be padded.

## See Also

RCD( ) Return Next Record
*MEMORY* Create and Use Memory File
Accessing ZIP Files

## Example

0010 open (1)"OLDFIL"
0020 open (2)"NEWFIL"
0030 lock (2)
0040 read record (1,end=1000)R$
0050 write record (2)R$
0060 goto 0040
1000 close (1); close (2)
1010 end