日誌列印公用程式 (CSQ1LOGP)

使用此公用程式來列印 IBM® MQ 日誌資料集或 BSDS 中包含的資訊。

呼叫 CSQ1LOGP 公用程式

您以 z/OS® 批次程式執行 IBM MQ 日誌列印公用程式。您可以指定：

引導資料集 (BSDS)
作用中日誌資料集 (不含 BSDS)
保存日誌資料集 (不含 BSDS)

圖 1、圖 2、圖 3 及圖 4中顯示用於呼叫 CSQ1LOGP 公用程式的範例 JCL。

必須提供下列資料定義陳述式:

SYSPRINT: 所有錯誤訊息、異常狀況及明細報告都會寫入此資料集。邏輯記錄長度 (LRECL) 為 131。
SYSIN: 可以在此資料集中指定輸入選取準則。如需相關資訊，請參閱輸入控制參數。
邏輯記錄長度 (LRECL) 必須為 80 ，但只有直欄 1 到 72 有效; 系統不處理直欄 73 到 80。最多可以使用 50 筆記錄。直欄 1 中具有星號 (*) 的記錄會解譯為註解，並被忽略。
SYSSUMRY: 如果要求摘要報告，請指定參數 SUMMARY ( YES ) 或 SUMMARY (僅限 )，則會將輸出寫入此資料集。邏輯記錄長度 (LRECL) 為 131。
BSDS: 引導資料集 (BSDS) 的名稱。
ACTIVEn: 您要列印的作用中日誌資料集名稱 (n = 數字)。
保存式: 您要列印的保存日誌資料集名稱。

如果您指定關鍵字 EXTRACT ( YES ) ，請提供下列一或多個 DD 陳述式，視您要擷取的資料類型而定。請勿指定 LRECL ，因為它是由公用程式在內部設定。這些 DD 是輸出資料集所需的 DCB 參數。

CSQBACK: 此資料集包含在指定日誌範圍期間由已回復的工作單元寫入日誌的持續訊息。
CSQCMT: 此資料集包含在指定日誌範圍期間由已確定的工作單元寫入日誌的持續訊息。
CSQBOTH: 此資料集包含在指定日誌範圍期間由已確定的或已回復的工作單元寫入日誌的持續訊息。
CSQINFLT: 此資料集包含在指定日誌範圍期間保持進行中的工作單元寫入日誌的持續訊息。
CSQOBJS: 此資料集包含在指定日誌範圍期間發生的物件變更相關資訊。

對於每一個 DD 陳述式，記錄格式 (RECFM) 是 VB ，邏輯記錄長度 (LRECL) 是 32756 ，區塊大小 (BLKSIZE) 必須是 32760。

如果您正在處理作用中日誌資料集，且至少使用 SHAREOPTIONS (2 3) 來定義 BSDS 和作用中日誌資料集，則即使 IBM MQ 正在執行，公用程式也會執行。

圖 1. 使用 BSDS 來呼叫 CSQ1LOGP 公用程式的範例 JCL


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

圖 2. 使用作用中日誌資料集來呼叫 CSQ1LOGP 公用程式的範例 JCL


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

圖 3. 使用保存日誌資料集來呼叫 CSQ1LOGP 公用程式的範例 JCL


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

圖 4. 顯示 EXTRACT 關鍵字之其他陳述式的 JCL 範例


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

EXEC 陳述式可以使用選用參數 TIME (RAW) 來變更格式化時間戳記的方式。


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

這會導致格式化時間戳記，而不套用格式化系統的時區或閏秒偏移。例如，在格式化遠端站台上建立的日誌資料時，或在日光節約時間變更之前，您可以使用此作業模式。

如果未指定任何參數，則預設行為是使用時區來格式化時間戳記，並對執行格式化的系統進行閏秒更正。

受此參數影響的格式化時間是與下列相關的那些時間:

檢查點時間
重新啟動時間
UR 開始時間

輸入控制參數

下列清單中說明您可以在 SYSIN 資料集中使用的關鍵字。

您可以指定各種選取準則來限制所處理的日誌記錄。它們是：

日誌範圍，使用 RBASTART-RBAEND 或 LRSNSTART-LRSNEND
頁集，使用 PAGESET
回復單元，使用 URID
記錄內容，使用 DATA
資源管理程式，使用 RM

可以結合不同類型的選取準則; 只會處理符合所有準則的記錄。

LRSNSTART (hexadecimal-constant)

指定要開始處理的邏輯記錄序號 (LRSN)。您無法將此關鍵字與 RBASTART 一起使用。只有在佇列管理程式位於佇列共用群組中時，才使用此關鍵字。

LRSN 值一律大於 A00000000000; ; 如果指定較低的值，則會使用此值作為起始值。

您也可以使用表單 STARTLRSN 或 STRTLRSN 或 LRSNSTRT。僅指定此關鍵字一次。

LRSNEND (hexadecimal-constant)

指定要掃描的最後一筆記錄的邏輯記錄序號 (LRSN)。預設值為 FFFFFFFFFFFFFF (資料集的結尾)。此關鍵字只能與 LRSNSTART 一起使用。

您也可以使用表單 ENCLRSN。

僅指定此關鍵字一次。

RBASTART (hexadecimal-constant)

指定要開始處理的日誌 RBA。此關鍵字不能與 LRSNSTART 一起使用。

您也可以使用表單 STARTRBA 或 ST。僅指定此關鍵字一次。

RBAEND (hexadecimal-constant)

指定要處理的最後一個有效日誌 RBA。如果省略此關鍵字，則會繼續處理到日誌結尾 (如果使用 6 個位元組的 RBA ，則為 FFFFFFFFFFFFFFFFFFFFFF ，如果使用 8 個位元組的 RBA ，則為 FFFFFFFFFFFFFFFFFF)。此關鍵字只能與 RBASTART 一起使用。

您也可以使用表單 ENDRBA 或 EN。僅指定此關鍵字一次。

頁集 (decimal-integer)

指定頁集 ID。數字必須在 00 到 99 的範圍內。您最多可以指定 10 個 PAGESET 關鍵字。如果指定 PAGESET 關鍵字，則只會處理與您指定的頁集相關聯的日誌記錄。

URID (hexadecimal-constant)

指定十六進位回復單元 ID。資料變更發生在 IBM MQ 回復單元的環境定義中。日誌上由 BEGIN UR 記錄識別回復單元。該 BEGIN URR 記錄的日誌 RBA 是您必須使用的 URID 值。如果您知道您感興趣之特定 UR 的 URID ，則可以將日誌中的資訊擷取限制為該 URID。

十六進位常數可以由 1 到 16 個字元 (8 個位元組) 組成，不需要前導零。

您最多可以指定 10 個 URID 關鍵字。

資料 (hexadecimal-string)

以十六進位指定資料字串。

字串可以由 2 到 48 個字元 (24 個位元組) 組成，且必須具有偶數個字元。

您最多可以指定 10 個 DATA 關鍵字。

如果指定 DATA 關鍵字，則只會處理至少包含其中一個字串的日誌記錄。

附註: 雖然您可以一起使用 DATA 和 EXTRACT 參數，但很難從輸出可靠地衍生意義，除非您充分瞭解 IBM MQ的內部實作。這是因為只會處理包含所要求 DATA 的低階個別日誌記錄，因此您不會擷取邏輯上與資料相關聯的完整輸出，只會擷取實際出現該 DATA 序列的記錄。例如，您可能只會取得與放置訊息相關聯的記錄，而不會取得與取得訊息相關聯的記錄，或者您可能只會取得長訊息的資料的第一部分，因為資料的其餘部分位於不包含所要求 DATA 字串的其他日誌記錄中。

RM (resource_manager)

指定特定的資源管理程式。只會處理與這個資源管理程式相關聯的記錄。此關鍵字的有效值如下:

回復: 回復日誌管理程式
資料: Data Manager
緩衝區: 緩衝區管理程式
IMSBRIDGE: IMS 橋接

摘要 (YES|NO|ONLY)

指定是否要產生摘要報告:

YES: 除了明細報告之外，還產生摘要報告。
NO: 不產生摘要報告。
僅: 僅產生摘要報告 (無明細報告)。

預設值為 NO。

EXTRACT (YES|NO)

指定 EXTRACT (YES) 會將每一個符合輸入選取準則的日誌記錄寫入適當的輸出檔，如 EXTRACT 函數頁面上所說明。預設值為 NO。

解壓縮 (YES|NO)

指定是否要展開任何壓縮日誌記錄:

YES: 在執行「搜尋」、「列印」或「擷取」功能之前，將展開任何壓縮的日誌記錄
NO: 在執行「搜尋」或「列印」功能之前，不會展開任何壓縮日誌記錄。請勿將 DECOMPRESS (NO) 與 Extract 函數搭配使用

預設值為「是」。

使用注意事項

如果佇列管理程式位於佇列共用群組中，您可以指定 LRSNSTART (選擇性地使用 LRSNEND) 或 RBASTART (選擇性地使用 RBAEND) 所需的日誌範圍。您無法混合 LRSN 及 RBA 規格。
如果您需要協調佇列共用群組中不同佇列管理程式的日誌資訊，請使用 LRSN 規格。
如果佇列管理程式不在佇列共用群組中，則無法使用 LRSN 規格; 您必須使用 RBA 規格。
如果您使用 BSDS ，則必須指定 RBASTART 或 LRSNSTART。
CSQ1LOGP 會在包含 LRSN 或 RBA 值 (大於或等於 LRSNSTART 或 RBASTART 上指定的值) 的第一筆記錄上開始處理。
通常您只對日誌的最新新增項目感興趣。請小心選擇適合日誌範圍開頭的值，不要使用預設值。否則，您會建立大量資料，其中大部分對您沒有興趣。

EXTRACT 函數

EXTRACT 參數的一般用法如下:

請檢閱已在佇列中放置或取得哪些持續訊息，以及是否已確定要求。這容許重播訊息。
檢閱已放置或取得的持續訊息，但要求已取消。
顯示哪些應用程式已取消而非已確定。
探索佇列所處理的持續資料磁區，以識別高使用率佇列。
識別哪些應用程式設定物件屬性。
在主要失敗之後，為了回復目的而重建物件定義，僅適用於專用佇列。

當針對日誌資料集執行具有 EXTRACT 參數集的 CSQ1LOGP 時，它會處理資料集中的所有記錄或指定範圍內的所有記錄。處理如下:

找到確定要求時，如果 CSQCMT ddname 存在，則會將資料寫入此資料集。如果 CSQBOTH ddname 存在，則資料也會寫入此資料集。
當找到取消要求時，如果 CSQBACK ddname 存在，則會將資料寫入此資料集。如果 CSQBOTH ddname 存在，則資料也會寫入此資料集。
當偵測到物件的變更時，會將資訊寫入 CSQOBJS ddname 所識別的資料集。
處理最後一筆記錄時，剩餘工作單元的相關資訊會寫入 CSQINFLT ddname 所識別的資料集。

如果您不想收集一或多個這些類別的資訊，請省略適當的 DD 陳述式。

處理 EXTRACT 資料的範例

下列工作使用 DFSORT 機能來處理已確定記錄的檔案，以新增放入每一個佇列的位元組數。

圖 5. 累計放入每一個佇列的位元組數


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

這會產生下列格式的輸出:

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

下表列出所提供的範例，可讓您列印及解譯使用 EXTRACT (YES) 時所產生的資料

範例	說明
thlqual.SCSQLOAD(CSQ4LOGS)	C 程式範例: UOW 活動及物件定義和變更的報告選擇性地重播訊息。
thlqual.SCSQC37S(CSQ4LOGS)	範例 C 程式的來源
thlqual.SCSQC370(CSQ4LOGD)	C 標頭檔，用於對映使用 CSQ1LOGP 的 EXTRACT (YES) 函數時產生的記錄
thlqual.SCSQPROC(CSQ4LOGJ)	用來執行程式 CSQ4LOGS 的範例 JCL

附註: 您不應從 APF 授權程式庫執行 CSQ4LOGS 程式。在某些情況下，您會收到異常終止碼 (如果您這樣做的話)。

CSQ1LOGP 輸出

詳細報告

明細報告會從回應 SYSIN 指定的輸入選取準則開始，然後列印發現的每一個有效日誌記錄。詳細報告中的關鍵字定義如下:

RM

寫入日誌記錄的資源管理程式。

類型

日誌記錄的類型。

URID

此回復單元的 BEGIN UR ，請參閱先前的說明。

LRID

格式為 AAAAAAAA.BBBBBBCC 的邏輯記錄 ID ，其中:

AAAAAAAA: 是頁集號碼。
BBBBBB: 是頁集中的相對頁碼。
副本收件人: 是頁面上的相對記錄號碼。

LRSN

所掃描日誌記錄的邏輯記錄序號 (LRSN)。

SUBTYPE

日誌記錄類型的子類型。

變更長度

記載變更的長度。

CHANGE OFFSET

變更的起始位置。

反向鏈結

前一頁的指標。

正向鏈結

指向下一頁的指標。

記錄長度

所插入記錄的長度。

輸出資料集的記錄佈置

指定 EXTRACT 關鍵字時所產生的資料集包含持續訊息的相關資訊。訊息由其佇列名稱和 8 個字元的索引鍵來識別。取得訊息之後，金鑰可以由另一個訊息重複使用，因此確保維護時間序列很重要。在記錄中是指時間。時間戳記只能從 Begin-UR 記錄或 MQPUT 要求中擷取。因此，如果只有一個長時間執行的交易正在取得訊息，則發生取得的時間是交易開始的時間 (「開始 UR」記錄)。如果有許多短工作單元，或放置許多訊息，則時間相當精確 (毫秒內)。否則，時間會變得越來越不準確。

附註: 因為檔案是「變數封鎖」格式，所以每筆記錄前面有一個 4 位元組的「記錄描述子單字」。可變長度記錄的第一個資料位元組具有相對位置 5 ，且前 4 個位元組包含記錄描述子字。欄位名稱對應於 thlqual.SCSQC370中 C 標頭檔 CSQ4LOGD 的那些名稱。

資料集中的資訊具有下列佈置:

偏移		類型	長度	姓名	說明
十二月	十六進位碼
0	0	字元	21	csrecorddate	寫入日誌的大約時間，格式為 yyyy.ddd hh:mm:ss.thm
21	15	字元	7	cstimedelta	從工作單元開始算起的大約時間差異 (毫秒)。靠右對齊並以空白填補。
28	1C	64 位元整數	8	dtodout	建立日誌記錄的估計時間 (STCK 格式)。
36	24	字元	8	丘裡德	建立日誌記錄之工作單元的佇列管理程式特定唯一 ID。
44	2C	字元	12	cscorrelator	執行緒相關性 ID
56	38	字元	8	喬思	授權 ID (與工作單元相關聯的使用者 ID)
64	40	64 位元整數	8	dtime	工作單元啟動的時間 (STCK 格式)
72	48	字元	8	csresource	資源名稱
80	50	字元	8	cscnty	連線類型: 內部作業的 BATCH、RSBATCH、 IMS、 CICS®、CHIN 或空值其中之一
88	58	字元	8	cscnid	建立此工作單元之執行緒的連線 ID
96	60	字元	3	csstatus	工作單元類型 :BUR 代表開始或 CP 代表檢查點資訊
99	63	整數	4	ldatalen	訊息資料的長度 (如果有的話)
103	67	字元	4	csqmgrname	佇列管理程式的名稱
107	6B	字元	48	csqueuename	用於取得、放置或過期訊息的佇列名稱。此欄位可以是問號。當無法判斷與項目相關聯的使用者 ID 時，會出現問號。這通常發生在 begin_ur 記錄或您可能從中取得 URID 的檢查點記錄不在工作中指定的日誌範圍內，也不在所使用的日誌資料集上。
155	9B	字元	12	cssqdmcp	共用佇列訊息鍵。如果不是共用佇列，則為空白
167	A7	字元	8	csdmcp	非共用佇列訊息鍵。如果共用佇列，則為空白。
175	AF	字元	8	csverb	活動： ALTER 物件已變更定義已建立物件 MQGET 收到訊息 MQPUT 已放置訊息到期訊息已過期 ABORT2 訊息已取消 PHASE1 兩階段確定的第一階段 PHASE2 兩階段確定的第二階段，或一個階段確定的唯一階段
183	B7	字元	1	cscmitstatus	工作單元的狀態: B 已取消 C 已確定 I 進行中 (inflight)
184	B8	字元	1	奇分流器	延遲指示器: S 延遲記錄 N 不分流
185	B9	字元	8	茨洛格爾巴	日誌記錄的 RBA
193	C1	字元	8	奇順特爾巴	延遲日誌記錄的 RBA
201	C9	字元	1	csuowscope	UOW 範圍 (十六進位): (01) 本端 02 共用
202	CA	整數	4	lsegment	資料的區段號碼，從 1 開始。
206	CE		變數		資料組件
206	CE	字元	1	奇博拉	如果 csverb 是 ALTER ，則指出資料是物件的 'before' 或 'after' 副本。 B 之前 A 之後
207	CF	字元	變數	csvarddata	訊息或物件資料。以 ldatalen 提供的長度。