| 1 | Qualified user queue name | Input | Char(20) |
| 2 | Extended attribute | Input | Char(10) |
| 3 | Queue type | Input | Char(1) |
| 4 | Key length | Input | Binary(4) |
| 5 | Maximum message size | Input | Binary(4) |
| 6 | Initial number of messages | Input | Binary(4) |
| 7 | Additional number of messages | Input | Binary(4) |
| 8 | Public authority | Input | Char(10) |
| 9 | Text description | Input | Char(50) |
| 10 | Replace | Input | Char(10) |
| 11 | Error code | I/O | Char(*) |
| 12 | Domain | Input | Char(10) |
| 13 | Pointers | Input | Char(10) |
| 14 | Number of queue extensions | Input | Binary(4) |
| 15 | Reclaim storage | Input | Char(1) |
The Create User Queue (QUSCRTUQ) API creates a user queue in either the user domain or the system domain, based on the input parameters. A user-domain user queue can be directly manipulated with MI instructions. If you are running at security level 40 or greater, you cannot directly manipulate a system-domain user queue using MI instructions.
If the number of queue extensions is not specified, user queues can grow to a maximum of 16MB in size, though some of that is used for the queue definition. If the number of queue extensions is specified and non-zero, the queue will be extended by the number of additional messages specified until either the number of queue extensions is reached or the storage limit of 2GB is reached.
The system can automatically extend user queues, so you should create a small queue and allow the system to extend the queue as needed. Smaller queues provide better performance and use less storage. However, the system does not automatically reduce the size of the queue if it is too large. If you specify the additional number of messages as 0, the system does not extend the user queue you create when the queue is full.
To decrease the size of a user queue, a user must delete the queue and create it again.
There are no APIs to manipulate user queue entries. If you must access a user queue object in a library that does not permit user-domain user objects, you must use data queue objects. For information about data queues, refer to the CL Programming topic.
If you need to know into which domain the user queue object was created, use either of the following APIs to retrieve that information:
Note:User queues created with either the number of queue extensions parameter specified with a positive, non-zero number or the reclaim storage parameter specified to reclaim the user queue storage are not eligible to save to a pre-V4R5 system.
The first 10 characters contain the user queue name, and the second 10 characters contain the name of the library where the user queue is located. The only special value supported is *CURLIB.
User queues 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 queue. For example, an object type of *FILE has an extended attribute of PF (physical file), LF (logical file), DSPF (display file), SAVF (save file), and so on.
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.
The sequence in which messages are to be dequeued from the queue. The valid values are:
| F | First-in first-out |
| K | Keyed |
| L | Last-in first-out |
The length in bytes of the message key from 1 to 256 if you specify the queue type as keyed. If you specify that the queue is not a keyed queue, the value must be 0.
The maximum allowed size of messages to be placed on the queue. The API truncates messages that are longer than the value you specify. The maximum size allowed is 64 000 bytes.
The initial number of messages that the queue can contain.
The amount to increase the maximum number of messages value when the queue is full. When this parameter is set to 0, the queue is not extended if an overflow occurs and an error message is sent to the program attempting to place a message on the queue.
The authority you give to the users who do not have specific private or group authority to the user queue. Once the user queue 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 a user queue exists to be replaced, this parameter is ignored. All authorities are transferred from the replaced user queue to the new one.
The valid values for this parameter are:
| *ALL | The user can perform all authorized operations on the user queue. |
| Authorization list name | The user queue 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 it 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 to the user queue and can read the object description. |
| *EXCLUDE | The user cannot access the user queue in any way. |
| *LIBCRTAUT | The public authority for the user queue 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 queues 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 the user queue's contents but cannot change them. |
A brief description of the user queue.
Whether to replace an existing user queue. Valid values for this parameter are:
| *NO | Do not replace an existing user queue of the same name and library. *NO is the default. |
| *YES | Replace an existing user queue of the same name and library. |
The user queue being replaced is destroyed if both:
If the QRPLOBJ library is specified in the QALWUSRDMN system value, then the replaced user-domain user queue is moved to the QRPLOBJ library. If the user queue is in the system domain, it is moved to the QRPLOBJ library, which is cleared at system IPL. For details about authorities, ownership, and renaming, see the discussion of the REPLACE parameter in Control Language (CL) information.
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 queue 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 queue object into the system domain. The API can always create a user queue into the system domain regardless of the security level you are running at. However, system-domain user queues can only be used at security level 30 and below because there are no APIs to access user queues. |
| *USER | Attempts to create the user queue object into the user domain. This is not always possible. If the library you are creating the user queue into does not appear in the QALWUSRDMN system value, the API cannot create the user queue 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 queue. The destination library is the library you specified in the qualified user queue 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. The libraries include special value *ALL or a list of one or more library names. | |||
Whether or not the user queue messages can contain pointer data or not. If this parameter is not specified, *NO is assumed.
| *YES | Messages can contain pointer and scalar data. Messages to be enqueued must be 16-byte aligned, regardless of whether or not the message contains pointer data. Only user-domain user queues can contain pointer data; therefore, queues that support pointers cannot be created in or restored to a library that is not permitted by system value QALWUSRDMN. User queues that can contain pointers cannot be saved to a release prior to Version 2 Release 3 Modification Level 0. |
| *NO | Messages can contain scalar data only. (User queues created prior to Version 2 Release 3 Modification Level 0 contain scalar data only). The user queue can be in either the system domain or the user domain. |
The maximum number of extensions allowed for the user queue. A value of -1 indicates that the maximum number of extensions will be chosen by the machine. If this parameter is not specified, 0 is assumed.
Whether storage reclaim will be attempted when the number of currently enqueued messages in the user queue reaches zero. Allowable values are:
| 0 | Do not reclaim storage when the user queues have no currently enqueued messages. 0 is the default value. |
| 1 | Reclaim storage when the user queues have no currently enqueued 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. |
| CPF3C02 E | User queue &1 not created. |
| CPD3C01 D | Object name &1 is not valid. |
| CPD3C03 D | Extended attribute &1 is not valid. |
| CPD3C05 D | Value &1 for authority parameter is not valid. |
| CPD3C06 D | Number of messages requested, &1, is too large for this queue. |
| CPD3C07 D | Value &1 for queue type parameter is not valid. |
| CPD3C08 D | Initial number of queue messages specified, &1, is not valid. |
| CPD3C09 D | Extension parameter value &1 for queue overflow is not valid. |
| CPD3C10 D | Value &1 for key length parameter is not valid. |
| CPD3C11 D | Value &1 for maximum message size parameter is not valid. |
| CPF3C08 E | Initial number of queue messages specified, &1, is not valid. |
| CPF3C09 E | Extension parameter value &1 for queue overflow is not valid. |
| CPF3C10 E | Value &1 for key length parameter is not valid. |
| CPF3C11 E | Value &1 for maximum message size parameter is not valid. |
| CPF3C2B E | Extended attribute &1 is not valid. |
| CPF3C2D E | Value &1 for authority parameter is not valid. |
| CPF3C2E E | Number of messages requested, &1, is too large for this queue. |
| CPF3C2F E | Value &1 for queue type parameter 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. |
| CPF3C46 E | Value &1 not valid for pointers parameter. |
| CPF3C47 E | Pointers not valid for system domain user queue. |
| CPF3C49 E | Request for user domain object cannot be granted. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3C94 E | Value &1 not valid for reclaim storage 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. |
| Top | Object APIs | APIs by category |