The log print utility (CSQ1LOGP) on z/OS

Invoking the CSQ1LOGP utility

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

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 you 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).

//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)
/*

//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)
/*

//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
/*

//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)

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

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.

Input control parameters

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

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

LRSNSTART (hexadecimal-constant)

Specifies the logical record sequence number (LRSN) from which to begin processing. You 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.

You 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). You can use this keyword only with LRSNSTART.

You can also use the form ENDLRSN.

Specify this keyword only once.

RBASTART (hexadecimal-constant)

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

You 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). You can use this keyword only with RBASTART.

You 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. You 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 you must use. If you know the URID for a particular UR that you are interested in, you 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.

You 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.

You 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 you 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 you 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)

Specifying 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 you 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 you 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

1. If your queue manager is in a queue sharing group, you can specify the log range required by either LRSNSTART (optionally with LRSNEND) or RBASTART (optionally with RBAEND). You cannot mix LRSN and RBA specifications.

   If you need 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.

2. If your queue manager is not in a queue sharing group, you cannot use LRSN specifications; you must use RBA specifications.
3. If you are using a BSDS, RBASTART or LRSNSTART must be specified.
4. 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.
5. Normally you 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

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.

//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

Table 1. Samples for printing and interpreting EXTRACT data

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: You 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:

Table 2. Record layout for the output data set

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 MQPUTRP the message was put with properties 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.