Add User Index Entries (QUSADDUI) API
Required Parameter Group:
| 1 | Returned library name | Output | Char(10) |
| 2 | Number of entries added | Output | Binary(4) |
| 3 | Qualified user index name | Input | Char(20) |
| 4 | Insert type | Input | Binary(4) |
| 5 | Index entries | Input | Char(*) |
| 6 | Length of index entries | Input | Binary(4) |
| 7 | Entry lengths and offsets | Input | Array(*) of Char(8) |
| 8 | Number of entries | Input | Binary(4) |
| 9 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: Yes
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.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| Note: The following fields will be repeated. The number of times they are repeated depends on the value specified in the number of entries parameter. | |||
| BINARY(4) | Entry length | ||
| BINARY(4) | Entry offset | ||
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
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C7B E | Length of index entries is not valid. |
| CPF3C7C E | User index is full. |
| CPF3C71 E | Insert type &1 is not valid. |
| CPF3C72 E | Number of entries &1 is not valid. |
| CPF3C73 E | Error occurred with index entries parameter. |
| CPF3C74 E | Entry is already in the index. |
| CPF3C75 E | Error occurred with entry lengths and offsets parameter. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9807 E | One or more libraries in library list deleted. |
| CPF9808 E | Cannot allocate one or more libraries on library list. |
| CPF9810 E | Library &1 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9830 E | Cannot assign library &1. |
| CPF9838 E | User profile storage limit exceeded. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R3
[ Back to top | Object APIs | APIs by category ]