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
- Input control parameters
- Usage notes
- The EXTRACT function
- CSQ1LOGP output
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 you want to print (n=number).
- ARCHIVE
- Name of an archive log data set you 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 you 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 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 pageset 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)'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
- 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
you must use. If you know the URID for a particular UR that you 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 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 we 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)
- 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 we can use the DATA and EXTRACT parameters together, it is difficult to reliably derive meaning from the output, unless we 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.
If you need to coordinate the log information from the different queue managers in the queue sharing group, use LRSN specifications.
- If your queue manager is not in a queue sharing group, we cannot use LRSN specifications; you must use RBA specifications.
- If you 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 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
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 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.
- 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:
The following table lists the samples that are provided to allow you to print and interpret the data generated when EXTRACT(YES) is usedBA1 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
Note: You should not run the CSQ4LOGS program from an APF authorized library. In some circumstances you receive an abend code if we do so.Sample Description thlqual.SCSQLOAD(CSQ4LOGS) Sample C program to: - Report on the UOW activity and object defines and alters
- 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
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 Type Length Name Description Dec Hex 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: 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.