Data Manipulation Language Statements › @OBTAIN (LRF)—retrieves the named logical record › @OBTAIN (LRF) Parameters

@OBTAIN (LRF) Parameters

NEXT/FIRST,REC=logical-record-name

Retrieves a logical record and places it in program variable storage. Logical-record-name must specify a logical record defined in the subschema.

NEXT/FIRST

Specifies which occurrence of the logical record is to be retrieved.

NEXT

(Default); retrieves a subsequent occurrence of the named logical record. @OBTAIN NEXT is generally used to serially retrieve logical-record occurrences.

When LRF receives repeated @OBTAIN NEXT commands, it replaces field values in program variable storage with new values obtained through repeated access to database records.

If the program issues an @OBTAIN NEXT statement without issuing an @OBTAIN FIRST, or if the last path status returned for the path was LR-NOT-FOUND, LRF interprets the @OBTAIN NEXT as @OBTAIN FIRST. After LR-ERROR or a DBA-defined path status, LRF does not interpret @OBTAIN NEXT as @OBTAIN FIRST.

FIRST

Retrieves the first occurrence of the logical record. @OBTAIN FIRST is generally used to retrieve the first in a series of logical-record occurrences.

If an @OBTAIN FIRST statement is followed by an @OBTAIN NEXT statement to retrieve a series of occurrences of the same logical record, the @OBTAIN statements must direct LRF to the same path. For this reason, you must ensure that the selection criteria specified in the WHERE clauses accompanying the @OBTAIN FIRST and @OBTAIN NEXT statements describe the same attributes of the desired logical record.

IOAREA=alt-logical-record-location

Identifies an alternative location in variable storage into which LRF is to place the retrieved logical record.

Any subsequent @MODIFY, @STORE, or @ERASE statements for a logical record placed in the named location should name that area. LRF is to obtain the data to be used to update the logical record from the named area. Alt-logical-record-location must identify a record location defined in the program.

ONLRSTS=path-status,GOTO= branch-location

Tests for the indicated path status. Path-status is a quoted literal program variable (1 to 16 bytes). If path-status results from this @OBTAIN statement, the action specified by GOTO=branch-location is performed.

Note: For more information about how to code this clause, see ON Clause later in this chapter.

WHERE boolean-expression

Specifies the selection criteria to be applied to the specified logical record.

Note: For details about how to code the WHERE clause, see WHERE Clause later in this chapter.