MQ/204 monitoring and troubleshooting
Overview
This topic discusses:
- Installation considerations particular to MQ/204
- Tools available within Model 204 to develop and debug MQ/204 applications
Error handling with $STATUS and $STATUSD
$STATUS is the primary return code and $STATUSD is an ancillary or secondary return code. Certain $STATUS return codes automatically generate a $STATUSD return code. For other $STATUS return codes, the value of $STATUSD is 0.
$STATUS return codes
The following table lists the $STATUS return code values and text that is used for all MQ/204 SOUL statements. See MQ/204 and SOUL statements for a detailed description of each statement.
When an error can be returned by more than one statement, it has the same $STATUS value for all statements that can raise that error. This practice allows you to write a generic SOUL routine that is an error handler for all MQ/204 statements.
| $STATUS value |
Meaning | Statement |
|---|---|---|
| 1 | Queue or queue manager was not found. |
CLOSE QUEUE MODIFY QUEUE MQBACK MQCMIT MQGET MQPUT MQPUT1 OPEN QUEUE |
| 2 | Reply queue not found. |
MODIFY QUEUE MQPUT MQPUT1 OPEN QUEUE |
| 3 | Queue manager is not started. |
MQPUT1 OPEN QUEUE |
| 4 | No WebSphere MQ interface subtasks are available. |
MQPUT1 OPEN QUEUE |
| 5 | WebSphere MQ A PI level MQCONN failed. $STATUSD is set to the WebSphere MQ reason code. |
MQPUT1 OPEN QUEUE |
| 6 | Queue manager has been stopped. |
MQPUT1 OPEN QUEUE |
| 7 | Queue is already open. | OPEN QUEUE |
| 8 |
Storage allocation error. |
MODIFY MQ_BUFFER MQBACK MQCMIT MQGET MQPUT MQPUT1 OPEN QUEUE READ IMAGE WRITE IMAGE |
| 9 | WebSphere MQ A PI level MQOPEN failed. $STATUSD is set to the WebSphere MQ reason code. | OPEN QUEUE |
| 10 | %Variable substitution error, consult $STATUSD for more details. (See "Identifying invalid options by $STATUSD value.") |
MODIFY QUEUE MQGET MQPUT MQPUT1 OPEN QUEUE |
| 11 | Specified queue is not open. |
CLOSE QUEUE MODIFY QUEUE MQGET MQPUT MQPUT1 |
| 12 | WebSphere MQ A PI level MQGET failed. $STATUSD is set to the WebSphere MQ reason code. | MQGET |
| 13 | Browse was attempted on MQGET, but the queue was not open for browsing. | MQGET |
| 14 | Data truncation occurred on an MQGET. The target image or variable for the data area is too small. | MQGET |
| 15 | WebSphere MQ A PI level MQPUT failed. $STATUSD is set to the WebSphere MQ reason code. | MQPUT |
| 16 | WebSphere MQ A PI level MQPUT1 failed. $STATUSD is set to the WebSphere MQ reason code. | MQPUT1 |
| 17 | MQPUT was attempted, and the queue was not open for output. | MQPUT |
| 18 | WebSphere MQ A PI level MQCMIT failed. $STATUSD is set to the WebSphere MQ reason code. | MQCMIT |
| 19 | WebSphere MQ API level MQBACK failed. $STATUSD is set to the WebSphere MQ reason code. | MQBACK |
| 20 | WebSphere MQ API level MQCLOSE failed. $STATUSD is set to the WebSphere MQ reason code. | CLOSE QUEUE |
| 21 | User is not connected to the queue manager specified. |
MQBACK MQCMIT |
| 22 | Destructive get operation attempted, but the queue was not open for input. | MQGET |
| 23 | MQGET was issued, but no message was available. | MQGET |
| 24 | MQGET was issued with MSG_UNDER_CURSOR option, but the queue was not open for both input and browse. | MQGET |
| 25 | Data does not fit in the buffer and has been truncated. |
MQPUT MQPUT1 WRITE |
| 26 | No message is in the message buffer, so no message was put. |
MQPUT MQPUT1 |
| 27 | Statement tried to reference a remote queue, but MQDEQMAN was not set. |
CLOSE QUEUE MODIFY QUEUE MQGET MQPUT MQPUT1 OPEN QUEUE |
| 28 | An OPEN QUEUE statement was issued for a remote queue, but the mode option specified was not OUTPUT. | OPEN QUEUE |
| 30 | Context queue entity was not found. |
MODIFY QUEUE MQPUT MQPUT1 OPEN QUEUE |
| 31 | Context queue not specified or inherited when it was needed, because a PASS option was specified. |
MQPUT MQPUT1 OPEN QUEUE |
| 32 | Context queue not open for INPUT and SAVE_ALL_CONTEXT. |
MQPUT MQPUT1 |
| 33 | On PASS_USER_CONTEXT there was no user ID to pass. |
MQPUT1 OPEN QUEUE |
| 34 | Invalid value of SIZE on MODIFY MQ_BUFFER. |
MODIFY MQ_BUFFER |
| 35 | LIBUFF too small while parsing runtime options. |
CLOSE QUEUE MODIFY QUEUE MQGET MQPUT MQPUT1 OPEN QUEUE |
| 36 | Invalid or unrecognized option found while parsing runtime options. |
CLOSE QUEUE MODIFY QUEUE MQGET MQPUT MQPUT1 OPEN QUEUE |
| 37 | Unexpected end of option string while parsing runtime options. |
CLOSE QUEUE MODIFY QUEUE MQGET MQPUT MQPUT1 OPEN QUEUE |
| 38 | Duplicate options found while parsing runtime options. |
CLOSE QUEUE MODIFY QUEUE MQGET MQPUT MQPUT1 OPEN QUEUE |
| 39 | While parsing runtime options, keyword=%variable found, but %variable is undefined, $STATUSD set. (See "Identifying invalid options by $STATUSD value.") |
CLOSE QUEUE MODIFY QUEUE MQGET MQPUT MQPUT1 OPEN QUEUE |
| 40 | While parsing runtime options, keyword=value found, but value invalid, $STATUSD set. (See "Identifying invalid options by $STATUSD value.") |
CLOSE QUEUE MODIFY QUEUE MQGET MQPUT MQPUT1 OPEN QUEUE |
| 41 | While parsing runtime options, mutually exclusive options found. |
CLOSE QUEUE MODIFY QUEUE MQGET MQPUT MQPUT1 OPEN QUEUE |
| 42 | While parsing runtime options, invalid combination of options found, $STATUSD set. |
CLOSE QUEUE MODIFY QUEUE MQGET MQPUT MQPUT1 OPEN QUEUE |
| 43 | Local dynamic queue, but null dynamic queue name. |
OPEN QUEUE |
| 44 | Local dynamic queue, but null model queue name. |
OPEN QUEUE |
| 45 | Local dynamic queue, but no model queue entity. | OPEN QUEUE |
| 46 | Local dynamic queue, but dynamic queue already exists. | OPEN QUEUE |
| 47 | RFH2 expected but not received. | |
| 48 | RFH2 imaged specified, but too small | |
| 49 | Error moving data to image | |
| 50 | Size error with multiple images on PUT(1) | |
| 51 | GCORE error saving data with PUT(1) and RFH2 | |
| 52 | BUFLEN specified too small for RFH2 header |
%Variable substitution errors
The following table lists $STATUS values that indicate a %variable substitution error, when the option was evaluated, and how the option was initially specified. You specified the value of an option as a %variable. When the statement was executed, the %variable contained an invalid value for the option in question.
| $STATUS value | Evaluated at... | Option initially specified as... |
|---|---|---|
|
10 |
Compile time, as a %variable |
%Variable |
|
39 |
Runtime, as a ?%variable |
%Variable |
|
40 |
Runtime, as a ?%variable |
Literal |
To find out which $STATUS option had a problem, check the $STATUSD values, as listed in the following table.
$STATUSD return codes
On all $STATUS return codes that indicate a failure of a WebSphere MQ API level call, the value of $STATUSD is set to the WebSphere MQ reason code. The values and meanings of the reason codes are described in applicable IBM WebSphere MQ documents.
For reason codes, see WebSphere MQ for z/OS Messages and Codes V5.3.1, Appendix A.
To find out which option had a problem, check $STATUSD to determine which option, as listed in the following table.
| $STATUSD value |
Indicates invalid value for... |
|---|---|
| 1 | MSGTYPE |
| 2 | PRIORITY |
| 3 | REPLY_QUEUE |
| 4 | MSGID |
| 5 | CORRELID |
| 6 | EXPIRY |
| 7 | FEEDBACK |
| 8 | FORMAT |
| 9 | WAIT_TIME |
| 10 | CONTEXT |
| 11 | PUTAPPLTYPE |
| 12 | USERIDENTIFIER |
| 13 | ACCOUNTINGTOKEN |
| 14 | APPLIDENTITYDATA |
| 15 | PUTAPPLNAME |
| 16 | PUTDATE |
| 17 | PUTTIME |
| 18 | APPLORIGINDATA |
| 19 | MAXLEN |
| 20 | POSITION |
| 21 | BUFLEN |
| 22 | DESCRIPTOR |
| 23 | REPORT |
| 24 | MSGLEN |
| 25 | REPLY_QMGR |
| 26 | DYNAMICQNAME |
| 27 | MODEL |
| 28 | GROUPID |
| 29 | GSTATUS |
| 30 | Options that save context require queue to be open with an input option |
| 31 | Options that allow and pass context require queue to be open for output |
| 32 | APPLORIGINDATA, PUTAPPLNAME, PUTAPPLTYPE, PUTDATE, and PUTTIME options that require the SET_ALL_CONTEXT option |
| 33 | USERIDENTIFIER, ACCOUNTINGTOKEN, and APPLIDENTITYDATA options that require SET_IDENTITY_CONTEXT or SET_ALL_CONTEXT |
| 34 | DYNAMICQNAME and MODEL options that must be specified together |
| 35 | MSGTOKEN |
| 36 | SEQUENCE |
For all other values of $STATUS, $STATUSD is set to 0.
Debugging aid
Information recorded in the audit trail aids in debugging MQ/204 applications.
Audit trail
Each MQ/204 statement executed is logged to the audit trail as RK lines. Each RK line contains the following information:
- Current user ID
- Statement being executed, for example, OPEN QUEUE, MQGET, and so on.
- Queue manager name
- If the call is queue specific, the queue name
- Completion code and reason code returned by the WebSphere MQ API call
For OPEN QUEUE statements, an additional RK line is logged including:
- External queue manager name
- External queue name
For MQCONN and MQDISC calls, which are made on behalf of the user but are not strictly under the control of the SOUL program, a different RK line is logged containing the following information:
- Current user ID
- Function being performed, MQCONN or MQDISC
- Queue manager name
- External queue manager name
- Completion code and reason code returned by the WebSphere MQ API call
- Address of the associated subtask control block
Each of the RK lines has its own message number, so that each can be controlled independently with Model 204 MSGCTL parameter.
Wait types and statistics
To ensure that the system manager has full information, wait types identify waits that a user thread might perform when using MQ/204.
| Wait type | Value | Used when a thread is waiting for ... |
|---|---|---|
| MQAPI | 41 | WebSphere MQ operation to complete. The one exception is for the MQGWT wait type. |
| MQGWT | 42 | WebSphere MQ MQGET operations, where the WAIT option has been specified. |
| MQTSK | 40 | Subtask to become available (the MQWAIT parameter must be nonzero to have this type of wait). |
Measuring the throughput of the WebSphere MQ API
The following statistics attempt to measure the throughput of the WebSphere MQ API itself. To separate API execution time from time spent waiting within the API, MQGET calls with the WAIT option specified are measured separately. The following statistics measure all WebSphere MQ API calls except MQGET with the WAIT option.
| Statistic name | Tracks... |
|---|---|
| MQAPICNT | Number of MQAPI waits performed. See WebSphere MQ API wait types access control. |
| MQAPITIM | Elapsed time spent in MQAPI waits. See WebSphere MQ API wait types access control. |
Measuring MQGET calls with the WAIT options
The following statistics measure MQGET calls performed with the WAIT option and a finite WAIT_TIME value specified. MQGET calls with the WAIT option and WAIT_TIME=UNLIMITED specified are intentionally excluded from these measurements.
| Statistic name | Tracks... |
|---|---|
| MQGWTCNT | Number of MQGWT waits performed for MQGET calls with the WAIT option and a finite WAIT_TIME value specified. See WebSphere MQ API wait types access control. |
| MQGWTSUC | Number of MQGET calls performed with the WAIT option and a finite WAIT_TIME specified that succeeded; for example, where a message was actually returned. |
| MQGWTTIM | Elapsed time spent in MQGWT waits done for MQGET calls with the WAIT option and a finite WAIT_TIME value specified. See WebSphere MQ API wait types access control. |
| MQGWTTSP | Total WAIT_TIME specified on all MQGET calls performed with the WAIT option and a finite WAIT_TIME value specified. |