Interpreting the trace information on z/OS
The GTFTRACE produced by IBM MQ can be examined to determine possible errors with invalid addresses, invalid control blocks, and invalid data.
When you look at the data produced by the GTFTRACE command, consider the following points:- If the control block consists completely of zeros, it is possible that an error occurred while copying data from the user's address space. This might be because an invalid address was passed.
- If the first part of the control block contains non-null data, but the rest consists of zeros, it is again possible that an error occurred while copying data from the user's address space, for example, the control block was not placed entirely within valid storage. This might also be due to the control block not being initialized correctly.
- If the error occurred on exit from IBM MQ, it is possible that IBM MQ might not write the data to the user's address space. The data displayed is the version that it was attempting to copy to the user's address space.
The following tables show details of the control blocks that are traced.
Table 1 illustrates which control blocks are traced for different MQI calls.
| MQI call | Entry | Exit |
|---|---|---|
| MQCB | MQCBD, MQMD, MQGMO | MQCBD, MQMD, MQGMO |
| MQCLOSE | None | None |
| MQGET | MQMD, MQGMO | MQMD, MQGMO, and the first 256 bytes of message data |
| MQINQ | Selectors (if SelectorCount is greater than 0) | Selectors (if SelectorCount is
greater than 0)
Integer attributes (if IntAttrCount is greater than 0) Character attributes (if CharAttrLength is greater than 0) |
| MQOPEN | MQOD | MQOD |
| MQPUT | MQMD, MQPMO, and the first 256 bytes of message data | MQMD, MQPMO, and the first 256 bytes of message data |
| MQPUT1 | MQMD, MQOD, MQPMO, and the first 256 bytes of message data | MQMD, MQOD, MQPMO, and the first 256 bytes of message data |
| MQSET | Selectors (if SelectorCount is
greater than 0)
Integer attributes (if IntAttrCount is greater than 0) Character attributes (if CharAttrLength is greater than 0) |
Selectors (if SelectorCount is
greater than 0)
Integer attributes (if IntAttrCount is greater than 0) Character attributes (if CharAttrLength is greater than 0) |
| MQSTAT | MQSTS | MQSTS |
| MQSUB | MQSD, MQSD.ObjectString, MQSD.SubName, MQSD.SubUserData, MQSD.SelectionString, MQSD.ResObjectString | MQSD, MQSD.ObjectString, MQSD.SubName, MQSD.SubUserData, MQSD.SelectionString, MQSD.ResObjectString |
| MQSUBRQ | MQSRO | MQSRO |
This is because, although the application has issued a single MQGET call, the adapter is performing the wait on behalf of the application and when a message becomes available it reissues the call. So in the trace it appears as a second MQGET call.
Information about specific fields of the queue request parameter list is also produced in some circumstances. The fields in this list are identified as follows:
| Identifier | Description |
|---|---|
| Action | Requested action |
| BufferL | Buffer length |
| CBD | Address of callback descriptor |
| CompCode | Completion code |
| CharAttL | Character attributes length |
| DataL | Data length |
| Hobj | Object handle |
| Hsub | Subscription handle |
| IntAttC | Count of integer attributes |
| pObjDesc | Object descriptor |
| Oper | Operation |
| Options | Options |
| pBuffer | Address of buffer |
| pCharAtt | Address of character attributes |
| pCTLO | Address of control callback options |
| pECB | Address of ECB used in get |
| pGMO | Address of get message options |
| pIntAtt | Address of integer attributes |
| pMsgDesc | Address of message descriptor |
| pPMO | Address of put message options |
| pSD | Address of subscription descriptor |
| pSelect | Address of selectors |
| pSRQOpt | Address of subscription request options |
| pSTS | Address of status structure |
| Reason | Reason code |
| RSVn | Reserved for IBM |
| SelectC | Selector count |
| Thread | Thread |
| Type | Requested type |
| UOWInfo | Information about the unit of work |
| Userid | CICS or IMS user ID, for batch or TSO this is zero |