# Directives

EXTRACT RECORD | Read-Lock Data Record

## Format

EXTRACT 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
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

Use the EXTRACT RECORD directive to read a record from the file you specify (channel). PxPlus will return the record's complete data portion in the string variable you specify.

Apply the EXTRACT RECORD statement when dealing with native-mode operating system files, when exchanging data with non-PxPlus applications, or when you want to read a complete record (including data field separators).

The EXTRACT RECORD directive advances the file position to the next record (or the record specified in a KEY= or IND= option). Use the KNO= option to change the current file access key.

#### Note:
This directive locks the record being read to prevent other users from using a FIND, FIND RECORD, READ, READ RECORD, EXTRACT RECORD or another EXTRACT RECORD to access it. This lock remains active until the next I/O request for the same file or until the file is closed.
Using a KEY= option or READ, FIND or EXTRACT statement to retrieve the next record while a record is locked will result in the locked record being returned instead.
You can enable read access for records that have been extracted by setting the 'XI' system parameter.

## See Also

FIND Locate and Read Data
READ Read Data from File
KEY( ) Return Key of Next Record

## Example

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