Insert (2)

The Insert operation (B_INSERT) inserts a record into a file. The transactional interface adjusts the B‑trees for the keys to reflect the key values for the new record.


	Op Code	Pos Block	Data Buf	Data Buf Len	Key Buffer	Key Number
Sent
Returned

•

The file must be open.

•

The record to be inserted must be the proper length, and the key values must conform to the keys defined for the file.

1

Set the Operation Code to 2.

2

Pass the Position Block for the file.

3

In the Data Buffer, store the record to be inserted.

4

Specify the Data Buffer Length. This value must be at least as long as the fixed-length portion of the record.

5

Specify the Key Number that the transactional interface uses to establish positioning information (currency). To use the NCC option, specify -1 (0xFF) for the Key Number. To use the system-defined log key (also called system data), specify 125.

Note: When using the no-currency-change (NCC) option, the Insert operation does not update the value of the Key Buffer parameter; it does not return any information in that parameter.

If the Insert operation is successful, the transactional interface places the new record in the file, updates the B-trees for the keys to reflect the new record, and returns the value of the specified key in the Key Buffer. If you insert a record that contains an AUTOINCREMENT key value initialized to binary 0, the transactional interface also returns the inserted record in the Data Buffer, including the AUTOINCREMENT value assigned by the transactional interface. An NCC Insert operation does not change the value of the Key Buffer parameter.

If the Insert operation is unsuccessful, the transactional interface returns one of the following status codes:


2	The application encountered an I/O error.
3	The file is not open.
5	The record has a key field containing a duplicate key value.
18	The disk is full.
21	The key buffer parameter is too short.
22	The data buffer parameter is too short.

An Insert operation that does not specify the NCC option establishes the complete logical and physical currencies and makes the inserted record the current one. The logical currency is based on the specified key.

An NCC Insert operation establishes physical currency without affecting logical currency. This means that an application, having performed an NCC Insert operation, has the same logical position in the file as it had prior to the Insert operation. In such a situation, operations that follow an NCC Insert—such as Get Next (6), Get Next Extended (36), Get Previous (7), and Get Previous Extended (37)—return values based on the application’s logical currency prior to the NCC Insert.

Note: The transactional interface does not return any information in the Key Buffer parameter as the result of an NCC Insert operation. Therefore, an application that must maintain the logical currency must not change the value of the Key Buffer following the NCC Insert operation. Otherwise, the next Get operation has unpredictable results.

The transactional interface establishes the physical currency to a newly inserted record for both the standard Insert and the NCC Insert operations. Operations following an NCC Insert operation—such as Step Next (24), Step Next Extended (38), Step Previous (35), Step Previous Extended (39), Update (3), Delete (4), and Get Position (22)—operate based on the new physical currency.