Insert by Count (IC)

Command title

Insert by Count

Description

This command inserts a new row into a table.

COBOL syntax

MOVE 'IC'                   TO xxxx-COMMAND.
CALL 'TBLBASE' USING        TB-PARM
                            xxxx-COMMAND-AREA
                            xxxx-ROW-AREA.

C syntax

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

Parameters

xxxx-ROW-AREA—contains the content to be inserted into the new row.

Explanation

The content of xxxx-ROW-AREA is inserted into the position within the table identified by the value of COUNT.

No checking of key sequence is performed using this command. Insert by Count should only be used when the subscript of the row to be inserted is known, usually through a previous retrieval.

If the table is sequential or user ordered, all rows with a subscript greater than that of the COUNT field will be moved up in position to make space for the new row to be inserted.

If the table is randomly ordered, an Insert by Count always results in the new row being added to the end of the table. The value in the COUNT field, if valid, is ignored.

Return value

If the COUNT field of xxxx-COMMAND-AREA is valid, the insert will be performed.

ERROR 0006 subcodes 1 and 2 indicate that the COUNT specified is out of bounds.

Notes

If Insert by Count is used inappropriately; for instance, against a table with a hash index, rows may get out of sequence causing unpredictable results. If you cannot ensure exclusive access to the table, via a LOCK-LATCH password in a multi-user environment such as CICS, it is preferable to use an Insert by Key command.

In a multi-tasking or multi-user online environment, results for commands that utilize a count or sequential accessing of table rows may get unexpected results if another task/user is updating or deleting rows in the same table.

Exceptions

None

See also

8. COUNT (fullword binary)