Fetch Next by Key (FN)

Command title

Fetch Next by Key

Description

This command fetches a row from a table and places it in xxxx-ROW-AREA.

COBOL syntax 

MOVE 'FN'                   TO xxxx-COMMAND.
CALL 'TBLBASE' USING        TB-PARM
                            xxxx-COMMAND-AREA
                            xxxx-ROW-AREA
                            [xxxx-KEY-AREA].

C syntax 

memcpy( tbCommArea.tbCommand, "FN", 2 );
TBLBASE( &tbParm, &tbCommArea, pRowArea, pKeyArea );

Parameters

xxxx-ROW-AREA

xxxx-KEY-AREA (optional)

Explanation

This command locates a row that is equal to or greater than the key specified in the xxxx-KEY-AREA parameter. If the xxxx-KEY-AREA parameter is omitted, the key is taken from the key location in the xxxx-ROW-AREA parameter.

The table is searched for the first row having the key that is equal to or greater than the key when the table is in ascending order, and for the first row having a key that is less than or equal to the key when the table is in descending order. FOUND is set to Y, a copy of the row is moved into the xxxx-ROW-AREA and COUNT is set to the subscript of the fetched row. FOUND is set to N only if the end of the table has been reached and key has not been found. In this case the COUNT contains the subscript for one past the end of the table.

Return value

Error 0021 is returned if the table organization is not S or D.

Notes

Table organization must be ascending or descending.

FN can be used in conjunction with Date-Sensitive Processing.

To use the FN command to move through a table with ascending organization, increment the key by the smallest unit possible. This will cause FN to find a row that is greater than or equal to the new key which is slightly larger than the key given in the previous FN command. FN will loop through each row in the table regardless of gaps in the key sequence. For tables in descending order, decrement the key.

Exceptions

None

See also

Date-sensitive processing

3. FOUND (1 byte)

8. COUNT (fullword binary)