Insert Extended (40)

The Insert Extended operation (B_EXT_INSERT) inserts one or more records into a file. The transactional interface adjusts the B-trees for the keys to reflect the key values for the new records.

Parameters


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

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

Prerequisites

The file must be open.

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

Procedure

Set the Operation Code to 40.

Pass the Position Block for the file.

Specify the Data Buffer according to the structure shown in Table 2-16.

Specify the Data Buffer Length. This value must be exactly the size of the Data Buffer structure.

Specify the Key Number that the transactional interface uses to establish 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.

Details

The following table shows the data buffer structure.

Table 2-16 Data Buffer Structure for the Insert Extended Operation
Element	Length (in Bytes)	Description
Fixed portion	2	Number of records inserted.
Repeating portion (one for each record)
	2	Length of the record image.
	n	Record image.

Result

If the Insert Extended operation is successful, the transactional interface places the new records in the file, updates all the B-trees to reflect the new records that were inserted, and (except for NCC Insert Extended operation) returns in the Key Buffer the value of the specified key from the last record inserted. In addition, in the first word of the returned Data Buffer, the transactional interface places the number of records that were successfully inserted into the file. Following the first word of the Data Buffer, the transactional interface stores the addresses of the inserted records.

If the operation is only partially successful and the transactional interface returns a nonzero status code, the first word of the Data Buffer equals the number of records that were successfully inserted. The record that caused the error is the number of records that were successfully inserted plus one.

If the Insert Extended 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.

Positioning

An Insert Extended operation that does not specify the NCC option establishes the complete logical and physical currencies and makes the last inserted record the current one (unless the inserted record's key value is null). The logical currency is based on the specified key.

An NCC Insert Extended operation establishes physical currency without affecting logical currency. This means that an application, having performed an NCC Insert Extended operation, has the same logical position in the file as it had prior to the operation. In such a situation, operations that follow an NCC Insert Extended operation-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 Extended operation.

Note
The transactional interface does not return any information in the Key Buffer parameter as the result of an NCC Insert Extended operation. Therefore, an application that must maintain the logical currency must not change the value of the Key Buffer following the NCC Insert Extended 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 Extended and the NCC Insert Extended operations. Therefore, operations following an NCC Insert Extended 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.

An NCC Insert Extended operation is useful when an application must save its logical position in the file prior to executing the Insert Extended operation in order to perform another operation based on the original logical currency, such as a Get Next operation (6).

To achieve this effect without an NCC Insert Extended operation, your application would have to execute the following steps:

Get Position (22)-Obtains the 4-byte physical address for the logical current record. The application saves this value and passes it back in Step 3.

Insert Extended (40)-Inserts the new records. This operation establishes new logical and physical currencies.

Get Direct/Record (23)-Re-establishes logical and physical currencies as they were in Step 1.

The NCC Insert Extended operation has the same effect in terms of logical currency, but can have a different effect in terms of physical currency. For example, executing a Get Next (6) operation after either procedure produces the same result, but executing a Step Next (24) might return different records.