CQS trace records

Analyze CQS trace records in a formatted dump to determine which function encountered an error, and whether a problem is environmental or internal.

Trace tables

Trace record eye catchers in a formatted dump provide clues about which functions resulted in errors. You might be able to correct environmental problems immediately. Refer internal IBM® problems to IBM with appropriate documentation, such as system console logs and dumps.

CQS trace records are written to one or more of the trace tables shown in the following table.
Table 1. Trace tables that contain CQS trace records
Table name Number of tables Table description
ERR 1 Errors
CQS 1 CQS activity, including errors
INTF 1 CQS interface events
OFLW 1 per structure (EMHQ, MSGQ) Structure overflow events
SEVT 1 per structure (EMHQ, MSGQ) Structure event activity
STR 1 per structure (EMHQ, MSGQ) Client activity for this structure, including errors

Each CQS trace record is 32 bytes long, except records in the SEVT and OFLW tables. Those tables use an expanded 64-byte format. In a standard 32-byte trace entry, the first byte is the trace code and the second byte is the trace subcode. Many trace records contain a structure ID that identifies which structure the trace record applies to: the MSGQ primary structure, the MSGQ overflow structure, the EMHQ primary structure, or the EMHQ overflow structure. Trace records that apply to a client request contain a client ID that identifies the client that issued the request. The last 8 bytes are the STCK time stamp of when the trace record was written. The mapping of the rest of the bytes in the trace record is unique to the trace code and subcode.

The expanded 64-byte format used by trace records in the SEVT and OFLW tables contains 16 words of trace data in the following format:

Word 0
Byte 0 contains the trace code of the event.
Byte 1 contains the trace subcode of the event.
Byte 2 contains data dependent on the type of event, typically the structure ID.
Byte 3 contains data dependent on the type of event, typically the client ID.
Word 1 - word 12
These 48 bytes contain trace data generated by the event. The exact content is dependent on the type of event.
Word 13
This word contains the ID of the event control block (ECB) of the task that wrote the trace record in the table.
Word 14 - word 15
These 8 bytes contain the time stamp of the event in STCK format.

CQS trace records are mapped by macros that use the naming convention CQSTRxxx, where xxx represents the function that is being traced. For example, CQSTRPUT maps trace records associated with the CQSPUT request. Trace record mapping is based upon the trace code and the trace subcode.

Find the CQS trace code in the following table to locate the CQS macro that maps the trace record. The following table shows the CQS trace codes, the macro that maps the trace code, and a description of the trace macro.
Table 2. CQS trace codes and mapping macros
Trace code Macro Description
3 CQSTRCON CQSCONN request
4 CQSTRDSC CQSDISC request
5 CQSTRRSY CQSRSYNC request
6 CQSTRINF CQSINFRM request
7 CQSTRPUT CQSPUT request
8 CQSTRRD CQSREAD request
9 CQSTRBRW CQSBRWSE request
0A CQSTRUNL CQSUNLCK request
0B CQSTRMOV CQSMOVE request
0C CQSTRRCV CQSRECVR request
0D CQSTRDEL CQSDEL request
E CQSTRQRY CQSQUERY request
0F CQSTRCHK CQSCHKPT request
10 CQSTRSHT CQSSHUT request
11 CQSTRUPD CQSUPD request
30 CQSTRICQ CQS initialization
31 CQSTRTCQ CQS termination
32 CQSTRYCH System checkpoint
40 CQSTRIST Structure initialization
41 CQSTRSTS Structure service
42 CQSTRTCH Structure checkpoint
43 CQSTRRBL Rebuild
44 CQSTROFL Overflow
45 CQSTRSTE Structure event
50 CQSTRLOG Log services
51 CQSTRTBL Table services
52 CQSTRDYA Dynamic allocation services
53 CQSTRDSS Data set services
54 CQSTRDSP Data space services
55 CQSTRLRR Log record router
56 CQSTRXCF z/OS® cross-system coupling facility interface
57 CQSTRCMD Command
60 CQSTRSTT Statistics
70 CQSTRINT CQS client interface

Trace codes for CQS requests are defined in the CQSRQTYP macro. Trace codes for other CQS functions are defined in the CQSCODES macro. CQS trace records in a formatted dump might contain eye catchers that provide clues about which function encountered an error, such as overflow, rbld, str chkpt, and duplex.

CQS request trace records sometimes contain a return code, reason code, and completion code from the request. CQS request return codes, reason codes, and completion codes are mapped by macros that use the naming convention CQSRRxxx, where xxx represents the function that is being traced. For example, the macro CQSRRPUT maps return codes, reason codes, and completion codes that are associated with the CQSPUT request. The following table shows the macros that define the return codes, reason codes, and completion codes for CQS requests.
Table 3. CQS mapping macros and request trace records
Macro CQS request macro for return codes, reason codes, and completion codes
CQSRRCON CQSCONN
CQSRRDSC CQSDISC
CQSRRRSY CQSRSYNC
CQSRRINF CQSINFRM
CQSRRPUT CQSPUT
CQSRRRD CQSREAD
CQSRRBRW CQSBRWSE
CQSRRUNL CQSUNLCK
CQSRRMOV CQSMOVE
CQSRRRCV CQSRECVR
CQSRRDEL CQSDEL
CQSRRQRY CQSQUERY
CQSRRCHK CQSCHKPT
CQSRRSHT CQSSHUT
CQSRRUPD CQSUPD

CQS trace records in formatted dumps contain eye catchers that identify the trace code and the trace subcode.

The following example shows a CQS trace record with eye catchers: 
INFRM: INF DONE FOR Q        06090101 05E3F3F2 F7F0D3C1 40404040              
                             40404040 05541160 AF975E81 59426906

The trace code is in the first byte (X'06'), which the CQSRQTYP macro documents as the CQSINFRM request. The eye catcher is INFRM. The CQSTRINF macro maps the trace records for trace code X'06'.

The trace subcode is in the second byte (X'09'), which the CQSTRINF macro documents as inform done for queue. The eye catcher is INF DONE FOR Q.

The CQSTRINF macro documents byte 3 for trace code X'06' as containing the structure ID (X'01'). Structure ID X'01' indicates the primary MSGQ structure.

The CQSTRINF macro documents byte 4 for trace subcode X'06' as containing the client ID (X'01'). Client ID X'01' represents the client that issued the CQSINFRM request. The CQSTRINF macro documents words 2, 3, 4, and 5 for trace subcode X'06' as containing the name of the queue for which the inform was done. This queue name is for queue type 05 (the IMS transaction queue). The queue name is T3270LA (X'E3F3F2F7F0D3C1').

The CQSTRINF macro documents word 6 for trace subcode X'06' as the ECB of the task that wrote this trace record (X'05541160').

The CQSTRINF macro documents words 7 and 8 as the STCK time of when the trace record was written.