Retrieve User Index Attributes (QUSRUIAT) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Qualified user index name | Input | Char(20) |
| 5 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve User Index Attributes (QUSRUIAT) API retrieves information about the current attributes and the current operational statistics of the user index.
The QSYS2.USER_INDEX_INFO view can be used as an alternative to this API. See USER_INDEX_INFO view for more information.
Authorities and Locks
- User Index Library Authority
- *EXECUTE
- User Index Authority
- *USE
- User Index Lock
- *SHRUPD
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The variable that is to receive the information requested. You can specify the size of this area to be smaller than the format requested if you specify the length of receiver variable parameter correctly. As a result, the API returns only the data that the area can hold.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable. If the length is larger than the size of the receiver variable, the results may not be predictable. The minimum length is 8 bytes.
- Format name
- INPUT; CHAR(8)
The format of the index information returned.
The format name supported is:
IDXA0100 Basic information Refer to IDXA0100 Format for details on the format.
- Qualified user index name
- INPUT; CHAR(20)
The user index for which you want to retrieve information, 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
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
IDXA0100 Format
The following information is returned for the IDXA0100 format. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(10) | User index name |
| 18 | 12 | CHAR(10) | User index library name |
| 28 | 1C | CHAR(1) | Entry length attribute |
| 29 | 1D | CHAR(1) | Immediate update |
| 30 | 1E | CHAR(1) | Key insertion |
| 31 | 1F | CHAR(1) | Optimized processing mode |
| 32 | 20 | CHAR(1) | Index size option |
| 33 | 21 | CHAR(3) | Reserved |
| 36 | 24 | BINARY(4) | Entry length |
| 40 | 28 | BINARY(4) | Maximum entry length |
| 44 | 2C | BINARY(4) | Key length |
| 48 | 30 | BINARY(4) | Number of entries added |
| 52 | 34 | BINARY(4) | Number of entries removed |
| 56 | 38 | BINARY(4) | Number of retrieve operations |
Field Descriptions
Bytes available. The length of all data available to return. All available data is returned if enough space is provided.
Bytes returned. The length of the data actually returned.
Entry length. For user indexes with fixed-length entries, this is the length of each index entry. For user indexes with variable-length entries, this is equal to the longest entry that has ever been inserted into the index. Valid values are from 1 through 2000.
Entry length attribute. The types of entries in the user index.
Possible values are:
| F | Fixed-length entries |
| V | Variable-length entries |
Immediate update. Whether or not the updates to the index are written to auxiliary storage on each update to the index.
The possible values are:
| 0 | No immediate update |
| 1 | Immediate update |
<Index size option. The maximum size of the user index.
The possible values are:
| 0 | The maximum size of the user index is 4 gigabytes. |
| 1 | The maximum size of the user index is 1 terabyte. |
Key insertion. Whether or not the inserts to the index are by key.
| 0 | No insertion by key |
| 1 | Insertion by key |
Key length. The length of the key where the first byte of an entry is the beginning of the key for the index entries. This field will be 0 for a nonkeyed user index.
Maximum entry length. The maximum entry length any user index entry can have.
Number of entries added. The number of entries added to the user index. The number of entries currently in the index can be obtained by subtracting the number of entries removed from the number of entries added.
Number of entries removed. The number of entries removed from the user index.
Number of retrieve operations. The number of times either the FNDINXEN (find independent index entry) MI instruction or Retrieve User Index Entry (QUSRTVUI) API has been used on this user index. The QUSRUIAT API or MATINXAT (materialize independent index attributes) MI instruction sets the number of retrieve operations to 0 after the retrieve or materialize operation is completed.
Optimized processing mode. Whether the user index is maintained in a manner that optimizes performance for:
| 0 | Random references |
| 1 | Sequential references |
Reserved. An ignored field.
User index library name. The name of the library containing the user index. This information is helpful when *CURLIB or *LIBL is specified in the qualified user index name parameter.
User index name. The name of the user index.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| 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. |
| 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 ]