Insert Independent Index Entry (INSINXEN)


Op Code (Hex) Operand 1 Operand 2 Operand 3
04A3 Index Argument Option list
Operand 1: System pointer.

Operand 2: Space pointer.

Operand 3: Space pointer.

Bound program access
Built-in number for INSINXEN is 37.
INSINXEN (
          index         : address of system pointer
          argument      : address
          option_list   : address
)

Warning

The following information is subject to change from release to release. Use it with caution and be prepared to adjust for changes with each new release.

Description

Insert one or more new entries into the independent index identified by operand 1 according to the criteria specified in the option list (operand 3). Each entry is inserted into the index at the appropriate location based on the binary value of the argument. No other collating sequence is supported. The maximum length allowed for the independent index entry is set when the index is created. The MATINXAT instruction can be used to materialize this information.

The argument (operand 2) and the option list (operand 3) have the same format as the search argument and option list for the Find Independent Index Entry (FNDINXEN) instruction.

The rule option identifies the type of insert to be performed and has the following meaning:

Insert Type Value (Hex) Meaning Authorization
Insert
0001
Insert unique argument
Insert

Insert with replacement
0002
Insert argument, replacing the nonkey portion if the key is already in the index
Update
Insert without replacement
0003
Insert argument only if the key is not already in the index
Insert

The insert rule option is valid only for indexes not containing keys. The insert with replacement rule option and the insert without replacement rule option are valid for indexes containing either fixed- or variable-length entries with keys. The duplicate key argument in index  (hex 1801) exception is signaled for the following conditions:

The argument length and argument offset fields are ignored, however, the entry length and offset fields must be entered for every entry which is to be inserted into the index.

The occurrence count specifies the number of arguments to be inserted. This field is limited to a maximum value of 4,095. If this value is exceeded, a template value invalid  (hex 3801) exception is signaled.

If the index was created to contain both pointers and scalar data, then each entry to be inserted must be 16-byte aligned. If the index was created to contain variable-length entries, then the entry length and offset fields must be specified in the option list for each argument in the space identified by operand 2. The entry length is the length of the entry to be inserted.

If the index was created to contain both pointers and scalar data, the offset field in the option list must be supplied for each entry to be inserted. The offset is the number of bytes from the beginning of the previous entry to the beginning of the entry to be inserted. For the first entry, this is the offset from the start of the space identified by operand 2.

The return count specifies the number of entries inserted into the index. If the index was created to contain scalar data only, then any pointers inserted are invalidated.

This operation will cause an object domain or hardware storage protection violation  (hex 4401) exception if attempted from user state on an index object with the restrict index operations from user state at all security levels attribute set to binary 1.

Authorization Required

Lock Enforcement

Exceptions

02 Access Group

06 Addressing

08 Argument/Parameter

0A Authorization

10 Damage Encountered

18 Independent Index

1A Lock State

1C Machine-Dependent

20 Machine Support

22 Object Access

24 Pointer Specification

2E Resource Control Limit

36 Space Management

38 Template Specification

44 Protection Violation