Insert by Key (IK)

Command title

Insert by Key

Description

This command inserts a new row into a table.

COBOL syntax

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

C syntax 

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

Parameters

xxxx-ROW-AREA

xxxx-KEY-AREA — included for backward compatibility. The table key is extracted from xxxx-ROW-AREA, and the xxxx-KEY-AREA parameter is ignored.

Explanation

The IK command searches the table for a row with a key matching the one specified. If it is not found, then the contents of xxxx-ROW-AREA are inserted into the proper position within the table based upon the results of the search and the table organization. For Random and User ordered tables, the new row is inserted at the end. If the key is found in the table, then the new row is not inserted as the key already exists.

Return value

If the row is inserted in the table, COUNT contains the subscript for the inserted row and FOUND is set to N. If the row is found, FOUND is set to Y, the row is not inserted in the table and COUNT is set to the subscript of the found row.

Notes

None

Exceptions

In a very large Random or User Ordered table, populating an entire table with this command could be quite slow, as this organization forces serial searches and these become slower as the table grows. If key uniqueness checking is not required the IC command is the fastest way to populate a Random table (see Insert by Count (IC)).

See also

3. FOUND (1 byte)

8. COUNT (fullword binary)