The log print utility (CSQ1LOGP) on z/OS

Use this utility to print information contained in the IBM MQ log data sets or the BSDS.

Invoking the CSQ1LOGP utility

You run the IBM MQ log print utility as a z/OS batch program. We can specify:

A bootstrap data set (BSDS)
Active log data sets (with no BSDS)
Archive log data sets (with no BSDS)

Sample JCL to invoke the CSQ1LOGP utility is shown in Figure 1, Figure 2, Figure 3 and Figure 4.

These data definition statements must be provided:

SYSPRINT: All error messages, exception conditions, and the detail report are written to this data set. The logical record length (LRECL) is 131.
SYSIN: Input selection criteria can be specified in this data set. See Input control parameters for more information.
The logical record length (LRECL) must be 80, but only columns 1 through 72 are significant; columns 73 through 80 are ignored. At most 50 records can be used. Records with an asterisk (*) in column 1 are interpreted as comments and are ignored.
SYSSUMRY: If a summary report is requested, by specifying the parameter SUMMARY ( YES ) or SUMMARY ( ONLY), the output is written to this data set. The logical record length (LRECL) is 131.
BSDS: Name of the bootstrap data set (BSDS).
ACTIVEn: Name of an active log data set we want to print (n=number).
ARCHIVE: Name of an archive log data set we want to print.

If you specify the keyword EXTRACT ( YES ), provide one or more of the following DD statements, depending on what types of data we want to extract. Do not specify an LRECL, as it is set internally by the utility. These DDs are the required DCB parameters for the output data set.

CSQBACK: This data set contains persistent messages written to the log by units of work that were rolled back during the log range specified.
CSQCMT: This data set contains persistent messages written to the log by units of work that were committed during the log range specified.
CSQBOTH: This data set contains persistent messages written to the log by units of work that were either committed or rolled back during the log range specified.
CSQINFLT: This data set contains persistent messages written to the log by units of work that remained in flight during the log range specified.
CSQOBJS: This data set contains information about object alterations that occurred during the log range specified.

For each DD statement, the record format (RECFM) is VB, the logical record length (LRECL) is 32756, and the block size (BLKSIZE) must be 32760.

If we are processing active log data sets, the utility runs even if IBM MQ is running, if the BSDS and active log data sets are defined by using at least SHAREOPTIONS(2 3).

Figure 1. Sample JCL to invoke the CSQ1LOGP utility using a BSDS

//PRTLOG EXEC PGM=CSQ1LOGP
//STEPLIB  DD DISP=SHR,DSN=thlqual.SCSQANLE
//         DD DISP=SHR,DSN=thlqual.SCSQLOAD
//BSDS     DD DSN=qmgr.bsds.dsname,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSSUMRY DD SYSOUT=*
//SYSIN    DD *
* extract records for page set 3. Produce both summary and detail reports
PAGESET(3)
SUMMARY(YES)
/*

Figure 2. Sample JCL to invoke the CSQ1LOGP utility using active log data sets

//PRTLOG  EXEC PGM=CSQ1LOGP
//STEPLIB  DD DISP=SHR,DSN=thlqual.SCSQANLE
//         DD DISP=SHR,DSN=thlqual.SCSQLOAD
//ACTIVE1  DD DSN=qmgr.logcopy1.ds01,DISP=SHR
//ACTIVE2  DD DSN=qmgr.logcopy1.ds02,DISP=SHR
//ACTIVE3  DD DSN=qmgr.logcopy1.ds03,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSSUMRY DD SYSOUT=*
//SYSIN DD *
insert your input control statements here, for example:
Urid(urid1)
Urid(urid2)
/*

Figure 3. Sample JCL to invoke the CSQ1LOGP utility using archive log data sets

//PRTLOG  EXEC PGM=CSQ1LOGP
//STEPLIB  DD DISP=SHR,DSN=thlqual.SCSQANLE
//         DD DISP=SHR,DSN=thlqual.SCSQLOAD
//ARCHIVE  DD DSN=qmgr.archive1.ds01,DISP=SHR
//         DD DSN=qmgr.archive1.ds02,DISP=SHR
//         DD DSN=qmgr.archive1.ds03,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSSUMRY DD SYSOUT=*
//SYSIN    DD *
  insert your input control statements here
/*

Figure 4. Sample JCL showing additional statements for the EXTRACT keyword

//PRTLOG  EXEC PGM=CSQ1LOGP
...
//CSQBACK   DD DSN=backout.dataset,DISP=(NEW,CATLG)
//CSQCMT    DD DSN=commit.dataset,DISP=(NEW,CATLG)
//CSQBOTH   DD DSN=both.dataset,DISP=(NEW,CATLG)
//CSQINFLT  DD DSN=inflight.dataset,DISP=(NEW,CATLG)
//CSQOBJS   DD DSN=objects.dataset,DISP=(NEW,CATLG)

The EXEC statement can use an optional parameter TIME(RAW) which changes the way timestamps are formatted.

//PRTLOG EXEC PGM=CSQ1LOGP,PARM='TIME(RAW)'

This causes timestamps to be formatted without applying timezone or leap second offsets for the formatting system. We can use this mode of operation when formatting log data created at a remote site, or before a daylight saving time change, for example.

If no parameter is specified, the default behavior is to format timestamps using the timezone and leap second corrections of the system doing the formatting.

Formatted times affected by this parameter are those associated with:

checkpoint time
restart time
UR start time

Input control parameters

The keywords that we can use in the SYSIN data set are described in the following list.

We can specify various selection criteria to limit the log records that are processed. These are:

log range, using RBASTART-RBAEND or LRSNSTART-LRSNEND
page sets, using PAGESET
units of recovery, using URID
record contents, using DATA
resource manager, using RM

Different types of selection criteria can be combined; only records meeting all the criteria are processed.

LRSNSTART (hexadecimal-constant)

Specifies the logical record sequence number (LRSN) from which to begin processing. We cannot use this keyword together with RBASTART. Use this keyword only if your queue manager is in a queue sharing group.

LRSN values are always greater than A00000000000; this value is used as the start value if a lower value is specified.

We can also use the forms STARTLRSN or STRTLRSN or LRSNSTRT. Specify this keyword only once.

LRSNEND (hexadecimal-constant)

Specifies the logical record sequence number (LRSN) of the last record to be scanned. The default is FFFFFFFFFFFF (the end of the data sets). We can use this keyword only with LRSNSTART.

We can also use the form ENDLRSN.

Specify this keyword only once.

RBASTART (hexadecimal-constant)

Specifies the log RBA from which to begin processing. We cannot use this keyword together with LRSNSTART.

We can also use the forms STARTRBA or ST. Specify this keyword only once.

RBAEND (hexadecimal-constant)

Specifies the last valid log RBA that is to be processed. If this keyword is omitted, processing continues to the end of the log (FFFFFFFFFFFF if 6 byte RBAs are in use, or FFFFFFFFFFFFFFFF if 8 byte RBAs are in use). We can use this keyword only with RBASTART.

We can also use the forms ENDRBA or EN. Specify this keyword only once.

PAGESET (decimal-integer)

Specifies a page set identifier. The number must be in the range 00 through 99. We can specify a maximum of 10 PAGESET keywords. If PAGESET keywords are specified, only log records associated with the page sets you specify are processed.

URID (hexadecimal-constant)

Specifies a hexadecimal unit of recovery identifier. Changes to data occur in the context of an IBM MQ unit of recovery. A unit of recovery is identified on the log by a BEGIN UR record. The log RBA of that BEGIN UR record is the URID value we must use. If you know the URID for a particular UR that we are interested in, we can limit the extraction of information from the log to that URID.

The hexadecimal constant can consist of 1 through 16 characters (8 bytes), and leading zeros are not required.

We can specify a maximum of 10 URID keywords.

DATA (hexadecimal-string)

Specifies a data string in hexadecimal.

The string can consist of 2 through 48 characters (24 bytes), and must have an even number of characters.

We can specify a maximum of 10 DATA keywords.

If multiple DATA keywords are specified, only log records that contain at least one of the strings are processed. Note: Though we can use the DATA and EXTRACT parameters together, it is difficult to reliably derive meaning from the output, unless you have a good understanding of the internal implementation of IBM MQ. This is because only the low level individual log records that contain the requested DATA are processed so we do not extract the full output that is logically associated with the data, only the records where that DATA sequence actually appears. For example you might get only records associated with putting messages and not with getting messages, or you might get only the first part of the data for long messages because the rest of the data is in other log records that do not contain the requested DATA string.

RM (resource_manager)

Specifies a particular resource manager. Only records associated with this resource manager are processed. Valid values for this keyword are:

RECOVERY: Recovery log manager
DATA: Data manager
BUFFER: Buffer manager
IMSBRIDGE: IMS bridge

SUMMARY (YES|NO|ONLY)

Specifies whether a summary report is to be produced or not:

YES: Produce a summary report in addition to the detail report.
NO: Do not produce a summary report.
ONLY: Produce only a summary report (no detail report).

The default is NO.

EXTRACT (YES|NO)

Specify EXTRACT(YES) causes each log record that meets the input selection criteria to be written to the appropriate output file, as explained on page The EXTRACT function. The default is NO. Note: Though we can use the DATA and EXTRACT parameters together, it is difficult to reliably derive meaning from the output, unless you have a good understanding of the internal implementation of IBM MQ. This is because only the low level individual log records that contain the requested DATA are processed so we do not extract the full output that is logically associated with the data, only the records where that DATA sequence actually appears. For example you might get only records associated with putting messages and not with getting messages, or you might get only the first part of the data for long messages because the rest of the data is in other log records that do not contain the requested DATA string.

DECOMPRESS (YES|NO)

Specifies whether any compressed log records will be expanded:

YES: Any compressed log records will be expanded before a Search, Print or Extract function is performed
NO: Any compressed log records will not be expanded before a Search or Print function is performed. Do not use DECOMPRESS(NO) with the Extract function

The default is YES.

Usage notes

If your queue manager is in a queue sharing group, we can specify the log range required by either LRSNSTART (optionally with LRSNEND) or RBASTART (optionally with RBAEND). We cannot mix LRSN and RBA specifications.
For to coordinate the log information from the different queue managers in the queue sharing group, use LRSN specifications. Note that processing logs simultaneously from different queue managers in a queue sharing group is not supported.
If your queue manager is not in a queue sharing group, we cannot use LRSN specifications; you must use RBA specifications.
If we are using a BSDS, RBASTART or LRSNSTART must be specified.
CSQ1LOGP starts its processing on the first record containing an LRSN or RBA value greater than or equal to the value specified on LRSNSTART or RBASTART.
Normally we are only interested in the most recent additions to the log. Take care to choose a suitable value for the start of the log range, and do not use the defaults. Otherwise, you create an enormous amount of data, most of which is of no interest to you.

The EXTRACT function

Typical uses of the EXTRACT parameter are to:

Review which persistent messages were put to or got from a queue and whether the request was committed. This allows messages to be replayed.
Review persistent messages that were put or got, but the request was backed out.
Display which applications backed out rather than committed.
Discover the volume of persistent data processed by queues, to identify the high use queues.
Identify which applications set object attributes.
Re-create object definitions for recovery purposes after a major failure, for private queues only.

When CSQ1LOGP with the EXTRACT parameter set is run against a log data set it processes all records in the data set, or all those within a specified range. Processing is as follows:

When a commit request is found, if the CSQCMT ddname is present then the data is written to this data set. If the CSQBOTH ddname is present the data is also written to this data set.
When a backout request is found, if the CSQBACK ddname is present then the data is written to this data set. If the CSQBOTH ddname is present the data is also written to this data set.
When changes to objects are detected, the information is written to the data set identified by the CSQOBJS ddname.
When the last record has been processed, information about remaining units of work is written to the data set identified by the CSQINFLT ddname.

If we do not want to collect one or more of these classes of information, then omit the appropriate DD statements.

Example of processing EXTRACT data

The following job uses DFSORT facilities to process the file of committed records to add up the number of bytes put to each queue.

Figure 5. Accumulating bytes put to each queue

//TOOLRUN EXEC PGM=ICETOOL,REGION=1024K
//TOOLMSG  DD SYSOUT=*
//DFSMSG   DD SYSOUT=*
//TOOLIN   DD *
SORT FROM(IN) TO(TEMP1) USING(CTL1)
DISPLAY FROM(TEMP1) LIST(OUT1) ON(5,48,CH) ON(53,4,BI)
/*
//CTL1     DD *
* SELECT THE RECORDS WHICH WERE PUT                                    
  INCLUDE COND=(180,5,CH,EQ,C'MQPUT')                                  
* SORT BY QUEUE NAME                                                   
  SORT FIELDS=(112,48,CH,A)                                            
* ONLY COPY THE QUEUE NAME AND SIZE OF USER DATA TO OUTPUT REC         
  OUTREC FIELDS=(1,4,112,48,104,4)                                     
* ADD UP THE NUMBER OF BYTES PROCESSED                                 
* SUM FIELDS=(104,4,FI)  
/*
//IN       DD DISP=SHR,DSN=commit.dataset
//TEMP1    DD DISP=(NEW,DELETE),DSN=&TEMP1,SPACE=(CYL,(10,10))
//OUT1     DD SYSOUT=*

This produces output in the following format:

BA1	3605616
BA10	3572328
BA2	3612624
BA3	3579336
BA4	3572328
BA5	3491736
BA6	3574080
BA7	3532032
BA8	3577584
BA9	3539040
SYSTEM.ADMIN.CHANNEL.EVENT	186120
SYSTEM.ADMIN.QMGR.EVENT	384
SYSTEM.CHANNEL.SYNCQ	46488312

The following table lists the samples that are provided to allow you to print and interpret the data generated when EXTRACT(YES) is used

Sample	Description
thlqual.SCSQLOAD(CSQ4LOGS)	Sample C program to: Report on the unit of work activity, and on activity that defines (that is, creates) or alters an object. Optionally, replay messages.
thlqual.SCSQC37S(CSQ4LOGS)	Source for sample C program
thlqual.SCSQC370(CSQ4LOGD)	C header file to map records generated when using the EXTRACT(YES) function of CSQ1LOGP
thlqual.SCSQPROC(CSQ4LOGJ)	Sample JCL to run program CSQ4LOGS

Note: We should not run the CSQ4LOGS program from an APF authorized library. In some circumstances you receive an abend code if you do so.

CSQ1LOGP output

Detail report

The detail report begins by echoing the input selection criteria specified by SYSIN, and then prints each valid log record encountered. Definitions of keywords in the detail report are as follows:

RM

Resource manager that wrote the log record.

TYPE

Type of log record.

URID

BEGIN UR for this unit of recovery, see the previous description.

LRID

Logical record identifier in the form: AAAAAAAA.BBBBBBCC where:

AAAAAAAA: Is the page set number.
BBBBBB: Is the relative page number in the page set.
CC: Is the relative record number on the page.

LRSN

Logical record sequence number (LRSN) of the log record scanned.

SUBTYPE

Subtype of the log record type.

CHANGE LENGTH

Length of the logged change.

CHANGE OFFSET

Start position of the change.

BACKWARD CHAIN

Pointer to the previous page.

FORWARD CHAIN

Pointer to the next page.

RECORD LENGTH

Length of the inserted record.

Record layouts for the output data sets

The data sets produced when the EXTRACT keyword is specified contains information about persistent messages. Messages are identified by their queue name and an eight character key. Once a message has been got, the key can be reused by another message, so it is important to ensure that time sequence is maintained. In the records are times. A time stamp can be extracted only from a Begin-UR record or from an MQPUT request. Thus if there is only a long running transaction which is getting messages, the times when the gets occurred are the time the transaction started (the Begin-UR record). If there are many short units of work, or many messages being put, the time is reasonably accurate (within milliseconds). Otherwise the times become less and less accurate. Note: There is a 4 byte Record Descriptor Word at the front of each record because the files are Variable Blocked format. The first data byte of a variable-length record has relative position 5 and the first 4 bytes contain the record descriptor word. The field names correspond to those in the C header file CSQ4LOGD in thlqual.SCSQC370.

The information in the data sets has the following layout:

Offset (Dec)	Offset (Hex)	Type	Length	Name	Description
0	0	Character	21	csrecorddate	The approximate time the log was written, in the format yyyy.ddd hh:mm:ss.thm
21	15	Character	7	cstimedelta	Approximate time difference in milliseconds from the start of the unit of work. Right-aligned and padded with blanks.
28	1C	64-bit integer	8	dtodout	Estimated time that the log record was created, in STCK format.
36	24	Character	8	csurid	Queue manager-specific unique identifier of the unit of work that created the log record.
44	2C	Character	12	cscorrelator	Thread correlation identifier
56	38	Character	8	csauth	Authorization identifier (Userid associated with unit of work)
64	40	64-bit integer	8	dtime	Time that the unit of work was started, in STCK format
72	48	Character	8	csresource	Resource name
80	50	Character	8	cscnty	Connection type: one of BATCH, RRSBATCH, IMS, CICS, CHIN, or nulls for an internal task
88	58	Character	8	cscnid	Connection ID of thread that created this unit of work
96	60	Character	3	csstatus	Unit of work type: BUR for begin or CP for checkpoint information
99	63	Integer	4	ldatalen	Length of the message data (if any)
103	67	Character	4	csqmgrname	Name of queue manager
107	6B	Character	48	csqueuename	Name of queue, for get, put, or expired messages. This field can be question marks. Question marks appear when it is not possible to determine the user ID associated with the entry. This typically happens when the begin_ur record or the checkpoint record from which you might get the URID is not in the log range specified in the job, nor on the log data sets used.
155	9B	Character	12	cssqdmcp	Shared queue message key. Blank if not a shared queue
167	A7	Character	8	csdmcp	Non-shared queue message key. Blank if a shared queue.
175	AF	Character	8	csverb	Activity: ALTER the object was changed DEFINE the object was created MQGET the message was got MQPUT the message was put EXPIRE the message expired ABORT2 the message was backed out PHASE1 the first phase of two-phase commit PHASE2 the second phase of two-phase commit, or the only phase of one phase commit
183	B7	Character	1	cscmitstatus	Status of unit of work: B backed out C committed I inflight
184	B8	Character	1	csshunt	Shunted indicator: S shunted record N not shunted
185	B9	Character	8	cslogrba	RBA of log record
193	C1	Character	8	csshuntrba	RBA of shunted log record
201	C9	Character	1	csuowscope	UOW scope in hexadecimal: 01 local 02 shared
202	CA	Integer	4	lsegment	The segment number of the data, starting from 1.
206	CE		Variable		Data part
206	CE	Character	1	csbora	If csverb is ALTER, indicates whether the data is the 'before' or 'after' copy of the object. B before A after
207	CF	Character	Variable	csvardata	Message or object data. Length as given in ldatalen.

Parent topic: Use the IBM MQ utilities on z/OS