Add User Index Entries (QUSADDUI) API

The Add User Index Entries (QUSADDUI) API inserts one or more entries into the user index by the insert type. Each entry is inserted into the index at the appropriate location based on the binary value of the entry. No other collating sequence is supported. Every entry added causes the number of entries added parameter to be incremented by 1; you can retrieve the current number of entries added by using the Retrieve User Index Attributes (QUSRUIAT) API.

When you request to add multiple entries to a user index, the request may be partially successful in the following situations:

• One or more of the entries you requested to add already exists in the index.
• The index becomes full as the entries are added.
• The user profile storage limit is exceeded as entries are added.
• One or more of the entry lengths or offsets are not valid.

When an error occurs, you should check the number of entries added parameter to see if all entries were successfully added. If the number of entries added parameter and the number of entries parameter are not equal, then all entries were not added.

Note:If you add new entries with an entry length longer than the user index is expecting, the entries are truncated to the right. No error is given.

If you are using a fixed length index and the entries you are adding are less than the fixed length, you may get undesirable results. The entries are not padded with blanks before being entered into the user index. The API checks the length of index entries parameter to ensure that the length you pass is a multiple of the length of one index entry.

Authorities and Locks

User Index Library Authority

*EXECUTE

User Index Authority

*CHANGE

User Index Lock

*SHRUPD

Required Parameter Group

Returned library name

OUTPUT; CHAR(10)

The name of the library that contains the user index to which the entries were added if they were added successfully. This parameter is not set if no entries were successfully added. This information helps you identify the specific library used when *LIBL or *CURLIB is specified in the qualified user index name parameter.

Number of entries added

OUTPUT; BINARY(4)

The number of entries successfully added to the specified user index. If an error is received while processing the entries, this number indicates how many were added before the error occurred.

Qualified user index name

INPUT; CHAR(20)

The user index to which you want to add entries and the library in which it is located. The first 10 characters contain the user index name, and the second 10 characters contain the library name.

You can use these special values for the library name:

*CURLIB	The job's current library
*LIBL	The library list

Insert type

INPUT; BINARY(4)

The type of insert to be performed against all entries that are to be added.

Valid values are:

1	Insert unique argument This value is only valid for nonkeyed user indexes. If the entry is already in the index or the index entries are keyed, an error is returned.
2	Insert with replacement This value requests to replace the nonkey portion of the index entry if the key is already in the user index. It is only valid for keyed user indexes. If the entry does not exist, it will be inserted into the user index. If the index entries are nonkeyed, an error is returned.
3	Insert without replacement This value requests to insert the entry only if the key is not already in the user index. It is only valid for a keyed user index. If the entry does not exist, it will be inserted into the user index. If the entry is already in the index or the index entries are nonkeyed, an error is returned.

Index entries

INPUT; CHAR(*)

The actual entry or entries to be added to the user index. If the user index contains fixed length entries, this parameter is processed using the entry length specified when the user index was created. If the user index contains variable length entries, this parameter is processed using the information contained in the entry lengths and entry offsets parameter.

When using an index that contains fixed length entries, this parameter should be the same length as the length of index entries parameter.

Length of index entries

INPUT; BINARY(4)

The length of the index entries parameter. This value must be greater than 0.

Entry lengths and entry offsets

INPUT; ARRAY(*) of CHAR(8)

If the user index contains variable length entries, this parameter is a data-structure array that is used to parse through the index entries parameter. In this case, an entry length and entry offset need to be provided for all entries that are to be added. This parameter is ignored for user indexes containing fixed length entries.

The size of the entry lengths and entry offsets parameter must be at least eight times the number of entries parameter; otherwise, an error will be returned.

See Format for Entry Lengths and Entry Offsets for details on the data structure.

Number of entries

INPUT; BINARY(4)

The number of entries that are to be added to the user index. Valid values are 1 through 4095.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Format for Entry Lengths and Entry Offsets

The following table defines the format for the entry lengths and entry offsets parameter. This information is needed to parse through the index entries parameter.For detailed descriptions of the fields in the table, see Field Descriptions.

Field Descriptions

Entry length The length of the entry to be inserted into the index. Valid values are 1-2000. This value depends on how the user index was created.

Entry offset. For the first entry, the offset is the number of bytes from the beginning of the index entries parameter to the first byte of the first entry. For each subsequent entry, the offset is the number of bytes from the beginning of the previous entry to the first byte of the next entry. Each entry offset value must be greater than or equal to 0 and must refer to an entry within the index entries parameter.

Error Messages