Create User Index (QUSCRTUI) API
Required Parameter Group:
| 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) |
Optional Parameter Group 1:
| 11 | Replace | Input | Char(10) |
| 12 | Error code | I/O | Char(*) |
Optional Parameter Group 2:
| 13 | Domain | Input | Char(10) |
Optional Parameter Group 3:
| 14 | Usage tracking | Input | Char(1) |
Optional Parameter Group 4:
| 15 | Index size option | Input | Char(1) |
Default Public Authority: *USE
Threadsafe: Yes
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:
- By ensuring that the current object size is less than 1 gigabyte by using
one of the following:
- The Display Object Description (DSPOBJD) command
- The List Objects (QUSLOBJ) API
- The Retrieve Object Description (QUSROBJD) API
- By ensuring that the key length field is 120 bytes or less by using either
of the following:
- The Materialize Index Attributes (MATINXAT) MI instruction
- The Retrieve User Index Attributes (QUSRUIAT) API
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.
Authorities and Locks
- Library Authority
- *READ and *ADD.
- User Index Authority
- *OBJMGT, *OBJEXIST, and *READ. These authorities are required only if the
replace parameter is used and there is an existing user index to replace.
- User Index Lock
- *EXCL. This applies to both the user index being created and an existing user index being replaced.
Required Parameter Group
- Qualified user index name
- INPUT; CHAR(20)
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.
- Extended attribute
- INPUT; CHAR(10)
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.
- Entry length attribute
- INPUT; CHAR(1)
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
- Entry length
- INPUT; BINARY(4)
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.
- Key insertion
- INPUT; CHAR(1)
Whether the inserts to the index are by key. The valid values are:
0 No insertion by key 1 Insertion by key
- Key length
- INPUT; BINARY(4)
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.
- Immediate update
- INPUT; CHAR(1)
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 - Optimization
- INPUT; CHAR(1)
The type of access in which to optimize the index. The valid values are:
0 Optimize for random references 1 Optimize for sequential references
- Public authority
- INPUT; CHAR(10)
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.
- Text description
- INPUT; CHAR(50)
A brief description of the user index.
Optional Parameter Group 1
- Replace
- INPUT; CHAR(10)
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:
- The allow user domain (QALWUSRDMN) system value is not set to *ALL or does not contain the QRPLOBJ library.
- The user index you are replacing is in the user domain.
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.
- Error code
- I/O; CHAR(*)
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.
Optional Parameter Group 2
- Domain
- INPUT; CHAR(10)
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.
Optional Parameter Group 3
- Usage tracking
- INPUT; CHAR(1)
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.
Optional Parameter Group 4
- Index size option
- INPUT; CHAR(1)
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.
Dependencies between Parameters
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 |
Error Messages
| 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. |
API introduced: V1R3
[ Back to top | Object APIs | APIs by category ]