Retrieve Nonprogram Message Queue Attributes (QMHRMQAT) API
Required Parameter Group:
| 1 | Message queue information | Output | Char(*) |
| 2 | Length of message queue information | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Qualified message queue name | Input | Char(20) |
| 5 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve Nonprogram Message Queue Attributes (QMHRMQAT) API provides information about the attributes of a nonprogram message queue. For more information on the attributes of nonprogram message queues, see the Create Message Queue (CRTMSGQ) command and the Change Message Queue (CHGMSGQ) command documentation in the online help.
Authorities and Locks
- Message queue
- *USE
- Message queue library
- *EXECUTE
Required Parameter Group
- Message queue information
- OUTPUT; CHAR(*)
The parameter to receive the message queue information. The format of the returned data is specified in RMQA0100 Format.
- Length of message queue information
- INPUT; BINARY(4)
The size of the area to contain the message information, in bytes. If the length specified is larger than the actual size of the message queue information parameter, the results may not be predictable. The minimum length is 8 bytes.
- Format name
- INPUT; CHAR(8)
The format of the information to be returned. You must use the following format name:
RMQA0100 This format is described in RMQA0100 Format.
- Qualified message queue name
- INPUT; CHAR(20)
The message queue and the library in which the message queue is located. The first 10 characters contain the message queue name, and the second 10 characters contain the message queue library. 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.
RMQA0100 Format
The following table shows the information returned in the message queue information parameter for the RMQA0100 format. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(10) | Message queue used |
| 18 | 12 | CHAR(10) | Message queue library used |
| 28 | 1C | BINARY(4) | Number of messages on queue |
| 32 | 20 | BINARY(4) | Current storage size |
| 36 | 24 | BINARY(4) | Increment storage size |
| 40 | 28 | BINARY(4) | Number of increments |
| 44 | 2C | BINARY(4) | Maximum increments |
| 48 | 30 | BINARY(4) | Severity code filter |
| 52 | 34 | CHAR(7) | Delivery |
| 59 | 3B | CHAR(10) | Break-handling program name |
| 69 | 45 | CHAR(10) | Break-handling program library |
| 79 | 4F | CHAR(4) | Force to auxiliary storage |
| 83 | 53 | CHAR(50) | Text description |
| 133 | 85 | CHAR(1) | Allow alerts |
| 134 | 86 | CHAR(2) | Reserved |
| 136 | 88 | BINARY(4) | Coded character set identifier (CCSID) |
| 140 | 8C | CHAR(10) | Message queue full action |
| 150 | 96 | CHAR(10) | Allow other jobs to reply |
Field Descriptions
Allow alerts. Whether this message queue allows alerts to be generated from alert messages sent to it. The values are:
| 1 | Allow alerts to be generated |
| 0 | Do not allow alerts to be generated |
See the Alerts
Support 
manual for information on
alerts.
Allow other jobs to reply. Whether other jobs can reply to messages on the message queue when it is in *BREAK delivery mode with a break-handling program other than *DSPMSG specified.
The field is set to *ALWRPY if the queue is in break mode and *DSPMSG is the break-handling program.
The field is set to blanks if the queue is not in break mode.
The possible values follow:
| *NOALWRPY | When the message queue is in *BREAK mode with a break-handling program other than *DSPMSG specified, other jobs can display the message queue but cannot reply to inquiry messages on the message queue. |
| *ALWRPY | When the message queue is in *BREAK mode with a break-handling program other than *DSPMSG specified, other jobs can reply to inquiry messages on the message queue. |
Break-handling program library. The library that is specified for the break-handling program.
If the message queue is not in break mode or the break-handling program name is specified as *DSPMSG, this field is set to blanks.
The following special values or a specific library may be returned:
| *LIBL | The library list is used to locate the program. |
| *CURLIB | The current library for the job is used to locate the program. |
Break-handling program name. The program that is called when messages are sent to this message queue. The delivery field must be set to *BREAK. The severity of the message sent to the queue must be equal to or greater than the value shown in the severity code filter field.
The field is set to *DSPMSG if the queue is in break mode and there is no break-handling program set.
The field is set to blanks if the queue is not in break mode.
Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.
Bytes returned. The number of bytes of data returned.
Coded character set identifier (CCSID). The coded character set identifier (CCSID) that is associated with this message queue. A special value of 65535 means that no conversions are to occur when sending or receiving messages from this message queue. A special value of 65534 means to use the CCSID associated with the message when conversions are to occur. For more information about message handler and its use of CCSIDs, see CCSID support for messages.
Current storage size. The current storage size of the message queue in bytes.
Delivery. How the messages that are sent to this message queue are delivered. The method of delivery is in effect only as long as the message queue is allocated to a job. When the queue is no longer allocated, the delivery mode is changed to *HOLD for work-station, system-operator, and user message queues. The possible values follow:
| *HOLD | The messages are held in the message queue until they are requested by a user or program. |
| *BREAK | When a message arrives at the message queue, the job to which the message queue is allocated is interrupted. Then the program specified on the break-handling program name field is called. If the break-handling program name is set to *DSPMSG, the Display Message (DSPMSG) command is processed. |
| *NOTIFY | When a message arrives at the message queue, an interactive job to which the message queue is allocated is notified. The message light turns on and a buzzer sounds (if the feature is available). |
| *DFT | Messages requiring replies are answered with their default reply. No messages are added to the message queue unless the message queue is QSYSOPR. |
Force to auxiliary storage. Whether changes made to the message queue description or messages added to or removed from the queue are immediately forced into auxiliary storage. If the value is *YES and a system failure occurs, the changes to the message queue are not lost.
One of the following modes is returned:
| *YES | All changes to the message queue description and to the messages in the queue are immediately forced into auxiliary storage. |
| *NO | Changes made to the message queue description, including its messages, are not immediately forced into auxiliary storage. |
Increment storage size. The number of bytes added each time the message queue is increased in size.
Maximum increments. The maximum number of times the message queue can be incremented. If *NOMAX is specified for this attribute when the message is created, the value determined by the system as the maximum number of times that the message queue can be incremented is returned.
Message queue full action. The action to take when the message queue becomes full. The possible values follow:
| *SNDMSG | When the queue is full, message CPF2460 (Message queue could not be extended) will be sent to the program or user that sends a message to the full message queue. |
| *WRAP | When the queue is full, it is wrapped by removing messages from the queue to make space for new messages to be added to the queue. |
Message queue library used. The actual library name that contains the message queue.
Message queue used. The name of the message queue whose attributes were returned.
Number of increments. The number of times that the message queue has been increased in size.
Number of messages on queue. The number of messages currently on the message queue.
Severity code filter. The lowest severity level that a message can have and still be delivered to a user in break or notify mode. Messages arriving at the message queue whose severities are lower than that specified here do not interrupt the job or turn on the message waiting light. Valid values are 0 through 99.
Reserved. An ignored field.
Text description. Text that briefly describes the message queue.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF2401 E | Not authorized to library &1. |
| CPF2403 E | Message queue &1 in &2 not found. |
| CPF2408 E | Not authorized to message queue &1. |
| CPF2477 E | Message queue &1 currently in use. |
| CPF2536 E | Value &1, for the length of message queue information not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF8127 E | &8 damage on message queue &4 in &9. VLIC log-&7. |
| CPF8176 E | Message queue for device description &4 damaged. |
| 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 | Message Handling APIs | APIs by category ]