EXTRACT

Read Data and Lock Record

This directive is used to READ data from a file and/or prevent anyone from WRITEing to that data space (and associated key space) until another action is taken on the designated input/output channel.

Syntax

[P]EXTRACT (channel [, I/O-opts]) [variable-list]
[, IOL=line-ref]

[P]EXTRACT RECORD (channel [, I/O-opts]) string-variable

channel: is an integer in the range of 0 to 32764 indicating the channel of an OPEN file.
I/O-opts: is one or more of the following specifiers:
Record: IND=numeric-value KEY=string-value SRT=sort-name
Branching: ERR=line-ref DOM=line-ref END=line-ref
Miscellaneous: TBL=line-ref ERC=error-code
variable-list: is a list of numeric and/or string variable names that receive values from the record.
line-ref: is the program line number or label containing an IOLIST directive that defines a variable list (the IOL= option may be used by itself or together with a variable list; the comma preceding IOL= is used only when a variable precedes IOL=), or the program line number or label to branch to if the specified error occurs.
string-variable: is the name of a string variable that receives the entire record as data.

Remarks

Starting with release level 8.2, a format may be specified to receive the data retrieved by the directive.

The attempt to reference a format name that the data dictionary or the current program does not recognize, results in an ERR=161.

The PEXTRACT directive is generally available starting with release level 8.0.

The only difference between PEXTRACT and EXTRACT comes when the directive is executed without using the KEY= option. In this case, EXTRACT obtains the next record based on the next logical KEY value (the next highest collating sequence key) and PEXTRACT obtains the next record based on the next logical PKY value (the next lowest collating sequence key, or previous key).

Access to an EXTRACTed record is restricted to the task and I/O channel combination until, using the same channel, that task performs a different I/O operation or EXTRACTs another record in the file.

A programmer can EXTRACT a record on one channel, which has already been READ on another channel. Any attempt to reREAD the same record on the original READ channel results in an ERR=0. Any attempt to WRITE the same record on the original channel or any other channel except the EXTRACT channel results in an ERR=0.

I/O options include:

IND=: specifies the index number of the record to access.
KEY=: specifies the key value of the record to access.
SRT=: specifies which sort key to use for MSORT files.
ERR=: specifies the program line number or label to branch to if an error is produced by this directive.
DOM=: specifies the program line number or label to branch to if an attempt is made to access a record using KEY= and no such key value is found (ERR=11). DOM= takes precedence over ERR= in the same EXTRACT directive.
END=: specifies the program line number or label to branch to if the end of the file is reached (ERR=2). End of file for PEXTRACT signifies an attempt to process a record less than the first key of the file. END= takes precedence over the ERR= in the same EXTRACT directive.
TBL =: specifies the program line number or label of the TABLE directive to be used for code conversion for the incoming data (see TABLE directive).
ERC=: specifies a programmer-defined error code, which enables programmers to define and manage errors without branching. ERC= provides a structured programming alternative to ERR=.

The IND= and KEY= options are mutually exclusive in the same EXTRACT directive. If neither the IND= or KEY= options are used EXTRACT accesses the next logical record in the file.

For keyed-access files, after a normal READ, the KEY normally points to the next sequential record in the file, PKY points to the previous record in the file, and the record just READ is referred to as the current record. The EXTRACT directive causes KEY and PKY to point to the current record until another I/O directive is issued on that channel.

An EXTRACT/WRITE sequence processes the file in sequential order without the necessity of specifying Index or Key values for the records. (The WRITE updates the record pointer.)

For an EXTRACT without the RECORD clause, values from each field of the record being accessed are loaded into the variable list or IOLIST in sequential order (i.e., the value of the first field in the record is loaded into the first variable, the second value into the second variable, etc.). An “*” is used to specify a field that is skipped and does not have data entered into a variable. Fields in the record are separated by the hexadecimal character $8A$ (field separator).

Note:: For OPEN statements using the SEP= option, the field separator can be any character, i.e., OPEN (2,SEP=$8F$) file. This allows for variable-length fields in a record. Field separators are placed in the record by use of the WRITE directive without the RECORD clause.

The RECORD modifier for this directive allows the entire record, including any field separator characters, to be entered as data into a single string variable. This modifier cannot be used with the IOL= option.

An EXTRACT using the KEY= option on a SORT file does not actually access any data because SORT files contain only keys. However, the program can READ and WRITE SORT key values.

This directive should not be used to READ data from a terminal.

Specifying a sort-name with the SRT= option sets the default sort sequence to the sort-name key sequence. Subsequent [P]READ or [P]EXTRACT directives that do not use the SRT= option uses the new default sort sequence.

Starting with release 8.3.0, an attempt to reference a format or data name in the I/O list of a channel that was OPENed with OPT=“LINK” results in an ERR=172.

Examples

EXTRACT (1) A$, A

accesses the record with the next highest key in the file OPEN on channel 1 and transfers data from the first field to the variable A$ and from the second field to the variable A. Access to this record from all other channels or programs is prohibited.

PEXTRACT RECORD (1) B$

accesses the record with the next lowest key in the file OPEN on channel 1 and transfers the entire record, including any field separators, into the variable B$.

EXTRACT RECORD (1, IND=X, ERR=7999) B$

If X = 56 accesses the record having the Index number 56 and branches to program line 7999 if this directive produced any error condition, including End of File (ERR=2).

EXTRACT (1, KEY=I$) IOL=5000

If I$=“ASD#123” and program line 5000 is IOLIST A$,A, then this accesses the record with the key value “ASD#123” and expects to find two fields which are placed in A$ and A.

EXTRACT (1, KEY=K$)#DNFFMT

reads a record out of the OPENed file and loads it into the data area of the format named DNFFMT.

EXTRACT

Syntax

Remarks

Examples

See also