IB Statements/extract

From CometWiki

Revision as of 10:22, 20 May 2009

EXTRACT statement

Syntax: EXTRACT (lun, format-statement-label) [KEY=index] [,EXCP=statement-label]

Discussion: The EXTRACT statement performs the same function as the READ statement but prevents other users from accessing the same record at the same time (i.e., it locks the record).

Also see INQUIRE.

The optional index parameter is used to access a particular record in a keyed or indexed sequential file. If an index is not specified, the file is read in key-sequential order.

When the index parameter is used with keyed files, the index (key) can be any valid string expression. If the key index is shorter that the file key size, it is padded with trailing blanks prior to the key search. If it is longer than the key size, excess trailing characters are truncated prior to the key search. If the key index is not found in the key list, the file pointer is positioned at the next key and an exception 32 is encountered.

When the index parameter is used with indexed sequential files, the key index is equivalent to the record number to be extracted. The index may be any valid numeric expression (truncated to an integer before the record is extracted). A key index with a negative or zero value, or one with a value beyond the last record in the file, will produce an exception.

Unlike the READ statement, EXTRACT does not automatically advance the file pointer to the next record in the file. This allows a program to extract a record, modify the data, and write is back to the file without specifying a key index value.

A record that is locked by EXTRACT is released when the initiating user accesses the same logical unit number again, usually with a READ, EXTRACT, DELETE, WRITE, or CLOSE statement.

Example: 1000 FORMAT CUSTNUM$;NAME$;ADDRESS1$;ADDRESS2$;...

.

OPEN (1) "CUSTFILE"

. INPUT (0) CUSTNUM$

EXTRACT (1,1000) KEY=CUSTNUM$,EXCP=9999

This example shows how to use EXTRACT to read and lock a single data record. While this record is extracted, other users will not be able to access it -- any attempt to access this record from another program will result in an exception 33 for the other program.