MQ/204 monitoring and troubleshooting

From m204wiki
Revision as of 20:33, 27 October 2017 by ELowell (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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.

See also