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