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 values for MQ/204 errors
$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 API 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 API 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 API 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 API level MQPUT failed. $STATUSD is set to the WebSphere MQ reason code.	MQPUT
16	WebSphere MQ API 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 API 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 values that indicate a %variable substitution error
$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.

Identifying invalid options by $STATUSD value
$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.