# Directives

EXTRACT | Read and Lock Data

## Format

EXTRACT[ RELEASE ] (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
DOM=stmtref | Missing record transfer
END=stmtref | End-of-File transfer
ERR=stmtref | Error transfer
IND=num | Record index
KEY=string$ | 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
varlist | Comma-separated list of variables, literals or IOL= options.
RELEASE | Indicates that any pending record lock for the specified file (filespec) can be released. When this option is specified, no varlist can be supplied and the only valid fileopt is ERR=stmtref.

(The EXTRACT RELEASE directive was added in PxPlus v11.00.)
(TABLE support was added in PxPlus 2018.)

## Description

Use EXTRACT to read data from the file you specify as the channel. When PxPlus reads the data, it is split into one or more fields (either separated by the current delimiter or in an embedded IOList format) with the contents of the first field placed into variable 1, the second field into variable 2, and so on.

PxPlus automatically converts numeric data when moving it into numeric variables while processing the EXTRACT directive. Numeric data converted during an EXTRACT directive does not use the 'DP' (Decimal Point Symbol) or 'TH' (Thousands Separator) system parameters for European decimal settings.

If you want a field to be skipped, use an * (asterisk) as a placeholder for a variable name. If you specify more variables than there are fields in the record, PxPlus will initialize the additional variables to either 0 (if a numeric variable) or a null string (if a string variable). The EXTRACT directive advances the file position to the next record (or a record you can specify using the KEY= or IND= option). Use the KNO= option to change the current file access key.

#### Note:
EXTRACT locks the record being read to prevent other users from using a FIND, FIND RECORD, READ, READ RECORD, EXTRACT RECORD or another EXTRACT to access it. This lock stays 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
EXTRACT Read and Lock Data
READ RECORD Read Record from File
KEY( ) Return Key of Next Record