| 1 | Qualified user index name | Input | Char(20) |
| 2 | Extended attribute | Input | Char(10) |
| 3 | Entry length attribute | Input | Char(1) |
| 4 | Entry length | Input | Binary(4) |
| 5 | Key insertion | Input | Char(1) |
| 6 | Key length | Input | Binary(4) |
| 7 | Immediate update | Input | Char(1) |
| 8 | Optimization | Input | Char(1) |
| 9 | Public authority | Input | Char(10) |
| 10 | Text description | Input | Char(50) |
| 11 | Replace | Input | Char(10) |
| 12 | Error code | I/O | Char(*) |
| 13 | Domain | Input | Char(10) |
| 14 | Usage tracking | Input | Char(1) |
| 15 | Index size option | Input | Char(1) |
The Create User Index (QUSCRTUI) API creates a user index in either the user domain or the system domain. A system-domain user index cannot be saved to a release prior to Version 2 Release 3 Modification 0. A user-domain user index can be directly manipulated with MI instructions and can also be accessed using system APIs at all security levels. On a system with the QSECURITY system value set to 40 or greater, you must use system APIs to access system-domain user indexes. If you create a permanent object by using this API, you cannot delete the object by using the MI instruction DESINX when the system security level is set to 40 or greater. You would have to delete the object by using the Delete User Index (QUSDLTUI) API.
Note: If the user index is larger than 4 gigabytes, it cannot be saved to a release prior to Version 5 Release 2 Modification 0.
If the user index was created prior to Version 2 Release 2 Modification 0, the size of the user index is limited to a maximum of 1 gigabyte. (A user index with a size greater than 1 gigabyte cannot be saved to or restored from a release prior to Version 2 Release 2 Modification 0.) If the user index was created on or after Version 2 Release 2 Modification 0, the size of the object is limited to a maximum of 4 gigabytes. The size is dependent on the amount of storage needed for the number and size of index entries and excludes the size of the associated space, if any.
Note: You can tell whether a user index object can be saved to a release prior to Version 2 Release 2 Modification 0:
Note: For performance reasons, the *USRIDX object is created before checking to see if it exists in the library specified for the qualified user index name. If you have an application using this API repeatedly, even if you are using *NO for the replace parameter, permanent system addresses will be used.
The name of the user index being created, and the library in which it is to be located. The first 10 characters contain the user index name, and the second 10 characters contain the library name.
You can use this special value for the library name:
| *CURLIB | The job's current library |
User indexes created in the QTEMP and QRPLOBJ libraries are not forced to permanent storage; they are deleted when those libraries are cleared at sign-off and system IPL, respectively.
The extended attribute of the user index. For example, an object type of *FILE could have an extended attribute of PF (physical file), LF (logical file), DSPF (display file), or SAVF (save file).
The extended attribute must be a valid *NAME. You can enter this parameter in uppercase, lowercase, or mixed case. The API automatically converts it to uppercase.
Whether there are fixed-length or variable-length entries in the user index. The valid values are:
| F | Fixed-length entries |
| V | Variable-length entries |
The length of entries in the index.
The valid values for fixed-length entries are from 1 through 2000.
Valid values for variable length entries are 0 or -1. A value of 0 enables a maximum entry length of 120 bytes and a key length from 1 through 120. A value of -1 enables a maximum entry length of 2000 and a key length from 1 through 2000.
Note: A user index created with an entry length greater than 120 cannot be saved or restored to a release prior to Version 2 Release 2 Modification 0.
Whether the inserts to the index are by key. The valid values are:
| 0 | No insertion by key |
| 1 | Insertion by key |
The length of the key where the first byte of an entry is the beginning of the key for the index entries. The value for this parameter must be 0 for no insertion by key. If you specify key length insertion, this value is from 1 through 2000.
Whether the updates to the index are written to auxiliary storage on each update to the index. The valid values are:
| 0 | No immediate update |
| 1 | Immediate update |
The type of access in which to optimize the index. The valid values are:
| 0 | Optimize for random references |
| 1 | Optimize for sequential references |
The authority you give to users who do not have specific private or group authority to the user index. Once the user index has been created, its public authority stays the same when it is moved to another library or restored from backup media.
If the replace parameter is used and an existing user index is replaced, this parameter is ignored. All authorities are transferred from the replaced user index to the new one.
The valid values for this parameter are:
| *ALL | The user can perform all authorized operations on the user index. |
| Authorization list name | The user index is secured by the specified authorization list, and its public authority is set to *AUTL. The specified authorization list must exist on the system when this API is issued. If the list does not exist, the create process fails, and an error message is returned to the application. |
| *CHANGE | The user has read, add, update, and delete authority for the user index and can read the object description. |
| *EXCLUDE | The user cannot access the user index in any way. |
| *LIBCRTAUT | The public authority for the user index is taken from the CRTAUT value for the target library when the object is created. If the CRTAUT value for the library changes later, that change does not affect user indexes already created. If the CRTAUT value contains an authorization list name and that authorization list secures an object, do not delete the list. If you do, the next time you call this API with the *LIBCRTAUT parameter, it will fail. |
| *USE | The user can read the object description and contents but cannot change the user index. |
A brief description of the user index.
Whether you want to replace an existing user index. Valid values for this parameter are:
| *NO | Do not replace an existing user index of the same name and library. *NO is the default value. |
| *YES | Replace an existing user index of the same name and library. |
If the user index already exists, you can replace it with a new user index of the same name and library. The new user index is subject to the same authorities. The user index being replaced is destroyed if both:
If the user index is in the system domain, it is moved to the QRPLOBJ library. If QALWUSRDMN is set to *ALL or if it contains QRPLOBJ, the replaced user index is moved to QRPLOBJ, which is cleared at system IPL. For details about authorities, ownership, and renaming, see the discussion of the REPLACE parameter in the Control language topic collection.
The structure in which to return error information. For the format of the structure, see Error code parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.
The domain into which the user index should be created. If this parameter is not specified, the value of *DEFAULT will be assumed by the API. Valid values for this parameter are:
| *DEFAULT | Allows the system to decide into which domain the object should be created. |
| *SYSTEM | Creates the user index object into the system domain. The API can always create a user index into the system domain, regardless of the security level running. However, if you are running at security level 40 or greater, you must use APIs to access system-domain user index objects. |
| *USER | Attempts to create the user index object into the user domain. This is not always possible. If the library you are creating the user index into does not appear in the QALWUSRDMN system value, the API cannot create the user index into the user domain. An error message will be returned. |
The API uses the following criteria to determine into which domain to create the user index. The destination library is the library you specified in the qualified user index name parameter. The optional domain parameter is the information specified in the domain parameter.
| QALWUSRDMN System Value | Destination Library | Optional Domain Parameter | Domain of Created Object |
|---|---|---|---|
| *ALL | Any | *DEFAULT | User domain |
| *ALL | Any | *SYSTEM | System domain |
| *ALL | Any | *USER | User domain |
| QTEMP | QTEMP | *DEFAULT | User domain |
| QTEMP | QTEMP | *SYSTEM | System domain |
| QTEMP | QTEMP | *USER | User domain |
| Does not contain library name | Library name | *DEFAULT | System domain |
| Does not contain library name | Library name | *SYSTEM | System domain |
| Does not contain library name | Library name | *USER | None; error is returned |
| Note: The QALWUSRDMN system value lists the libraries into which the user domain objects can be created. Valid libraries are the special value *ALL or a list of one or more library names. | |||
If your system is at security level 40 or greater, you must use APIs to access system-domain user indexes using APIs. You cannot use MI instructions to directly access system-domain user indexes.
You can use the Retrieve Object Description (QUSROBJD) API or the List Object (QUSLOBJ) API to determine into which domain the user index object was created.
The usage tracking state. Usage tracking provides machine checkpoints to improve availability of user indexes. If a user index is found to be a state of partial change, it will be marked as damaged. The valid values are:
| 0 | Do not track usage state. 0 is the default value. |
| 1 | Track usage state. |
The maximum size of the user index. The valid values are:
| 0 | The maximum size of the user index is 4 gigabytes. |
| 1 | The maximum size of the user index is 1 terabyte. |
Some of the parameters are interdependent and are shown in the following table:
| Entry Length Attribute | Entry Length (n) | Key Insertion | Key Length (x) |
|---|---|---|---|
| Fixed | 1 <= n <= 2000 | No | 0 |
| Fixed | 1 <= n <= 2000 | Yes | 1 <= x <= n |
Note: For the
following entry lengths:
|
|||
| Variable | 0, -1 | No | 0 |
| Variable | 0 | Yes | 1 <= x <= 120 |
| Variable | -1 | Yes | 1 <= x <= 2000 |
| Message ID | Error Message Text |
|---|---|
| CPF2143 E | Cannot allocate object &1 in &2 type *&3. |
| CPF2144 E | Not authorized to &1 in &2 type *&3. |
| CPF2283 E | Authorization list &1 does not exist. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF3C0A E | Value &1 for entry length parameter is not valid. |
| CPF3C0B E | Value &1 for immediate update parameter is not valid. |
| CPF3C0C E | Value &1 for key length parameter is not valid. |
| CPF3C0D E | Value &1 for key insertion parameter is not valid. |
| CPF3C0E E | Value &1 for the optimization parameter is not valid. |
| CPF3C03 E | User index &2 not created. |
| CPD3C01 D | Object name &1 is not valid. |
| CPD3C02 D | Value &1 for entry length attribute parameter is not valid. |
| CPD3C03 D | Extended attribute &1 is not valid. |
| CPD3C05 D | Value &1 for authority parameter is not valid. |
| CPD3C0A D | Value &1 for entry length parameter is not valid. |
| CPD3C0B D | Value &1 for immediate update parameter is not valid. |
| CPD3C0C D | Value &1 for key length parameter is not valid. |
| CPD3C0D D | Value &1 for key insertion parameter is not valid. |
| CPD3C0E D | Value &1 for the optimization parameter is not valid. |
| CPF3C2A E | Value &1 for entry length attribute parameter is not valid. |
| CPF3C2B E | Extended attribute &1 is not valid. |
| CPF3C2D E | Value &1 for authority parameter is not valid. |
| CPF3C29 E | Object name &1 is not valid. |
| CPF3C34 E | Value &1 for replace option is not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C45 E | Value &1 not valid for domain parameter. |
| CPF3C49 E | Request for user domain object cannot be granted. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3C93 E | Value &1 not valid for usage tracking parameter. |
| CPF3C95 E | Value &1 not valid for index size option parameter. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| 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. |
| CPF9870 E | Object &2 type *&5 already exists in library &3. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
[ Back to top | Object APIs | APIs by category ]