The trace selection parameters for DFHTU640

You code the trace selection parameters to define the number of lines to be printed on a page and to define which trace records you want to select for printing in the DFHAXPRM DD statement, or in the PARM parameter. For example:

//PRINT  EXEC PGM=DFHTU640,PARM='selection_parameter,selection_parameter,...'
PAGESIZE=(value)
specifies the number of lines printed on a page. You can specify a value in the range 20 through 9999 lines per page. If you specify an incorrect value, CICS® issues an error message and stops the trace. The default value is 55.
Note:
This parameter is not valid for printing GTF trace entries.
ABBREV|SHORT|FULL
specifies how much of each trace entry you want printed. If you specify this statement, it must always be the first statement in either the PARM parameter or the DFHAXPRM data set.
ABBREV
indicates that you require the abbreviated, one-line-per-entry, form of trace print.
SHORT
indicates that you require the short formatted print of the data in each entry. This consists of the information in the abbreviated format entry, and the following elements from the interpretation string of the fully formatted entry:
  • Interpreted parameter list
  • Return address
  • Time
  • Interval
FULL
indicates that you want a fully formatted print of all the data in each entry. This is the default.
ALL
specifies that all trace entries in the auxiliary trace data set are to be printed. This is the default.
ENTRY_NUM=({nnnnnn|nnnnnn-nnnnnn}[,{nnnnnn|nnnnnn},.,.,.])
specifies the sequence numbers of one or more trace entries that you want to print. Each sequence number can be up to six digits in length. If you specify a range of sequence numbers by using xxxxxx-yyyyyy, the second sequence number (yyyyyy) must be larger than the first (xxxxxx).
EXCEPTION
specifies that only exception trace entries in the auxiliary trace data set are to be printed.
Note:
This parameter is not valid for printing GTF trace entries.
INTERVAL={00.128|number of seconds}
specifies the interval between auxiliary trace entries after which entries highlighted with an asterisk as follows:

If successive auxiliary trace entries are written at intervals equal or greater than this limit, they are highlighted in the same manner.

If successive auxiliary trace entries are written at intervals less than this limit, they are not highlighted. They are, however, written, formatted and printed.

If you specify no INTERVAL value, a default of 0.128 seconds applies.

You can specify interval values in the range zero seconds (where all trace entries would be highlighted) through 99.9999999999 seconds.

Note:
The interval extends to ten decimal places. Zeros are padded from the right.
KE_NUM=(xxxx[,xxxx,.,.])
specifies that only the entries for tasks with the specified hexadecimal kernel task numbers are printed.
PAGESIZE=(value)
specifies the number of lines printed on a page. You can specify a value in the range 20 through 9999 lines per page. If you specify an incorrect value, CICS issues an error message and stops the trace. The default value is 55.
Note:
This parameter is not valid for printing GTF trace entries.
TASKID=({id|id-id}[,,{id|id-id},.,..])
specifies the task identifiers (id) of one or more tasks for which trace entries are to be printed. An id value can be in any of the following forms, to compare with the task field in the formatted trace data:

You can specify a range of task identifiers of the five decimal digit form by using a hyphen (for example, TASKID=nnnnn-nnnnn).

TERMID=(tttt[,tttt,.,.,.])
specifies the terminal identifiers (tttt) of one or more terminals for which trace entries are to be printed.

If you use the TERMID parameter to specify the trace entries you want formatted, the DFHTU640 program selects all the trace entries that are associated with any transaction-attach trace entries it finds containing the terminal identifier(s) you specify. For more information about how trace entries for tasks are associated with transaction-attach trace entries, see Identifying trace entries from their transaction-attach entries.

TRANID=(tttt[,tttt,.,.,.])
specifies the transaction identifiers of one or more transactions for which trace entries are to be printed.

If you use the TRANID parameter to specify the trace entries you want formatted, the DFHTU640 program selects all the trace entries that are associated with any transaction-attach trace entries it finds that contain the transaction identifier(s) you specify. For more information about how trace entries for tasks are associated with transaction-attach trace entries, see Identifying trace entries from their transaction-attach entries.

TIMERG=(hhmmss-hhmmss[,hhmmss-hhmmss,.,.,.])
specifies the time period or periods for which trace entries are to be printed. Time periods are shown by pairs of values represented as hours (hh), minutes (mm), and seconds (ss) separated by a hyphen. The ending value of each pair must be later than the starting value.

The DFHTU640 program converts the store-clock (STCK) values in the trace entries to whole seconds prior to comparing against the time range you specify. Fractions of a second are ignored; that is, all times are rounded down to the nearest whole second, which means in effect that the minimum time span can be up to two seconds. For example, if you specify TIMERG=153000-153001, the DFHTU640 program includes all trace entries with times of 153000.00000000 to 153001.99999999 inclusive.

Note:
This parameter is not valid for printing GTF trace entries.
TYPETR=({ddxxxx|ddxxxx-xxxx}[,{ddxxxx|ddxxxx-xxxx}])
specifies the trace entry identifiers for the particular domain entries, specified by the domain id and a point id within the domain.
dd
represents the domain identifier:
AP
Application
DD
Directory manager
DE
DCE services
DM
Domain manager
DS
Dispatcher
DU
Dump
EJ
Enterprise Java™ domain
EX
External CICS interface
GC
Global catalog
II
IIOP domain
KE
Kernel
LC
Local catalog
LD
Loader
LG
Log manager
LM
Lock manager
ME
Message
MN
Monitoring
NQ
Enqueue
OT
Object Transaction Service domain
PA
Parameter manager
PG
Program manager
Start of changePIEnd of change
Start of changePipeline manager domainEnd of change
PT
Partner domain
RM
Recovery manager
RZ
Request streams domain
SJ
JVM domain
SM
Storage manager
SO
Socket domain
ST
Statistics
TI
Timer
TR
Trace
US
User
XM
Transaction manager
XS
Security manager
xxxx
represents the point ID within the domain in the form of a four-character hexadecimal value (0000-FFFF). You can specify a range of point IDs by using a hyphen.
UPPERCASE
specifies that you want the trace output in uppercase only. If you want trace output in mixed case (the default), do not code this parameter.

Identifying trace entries from their transaction-attach entries

The AP domain writes a trace entry each time a transaction is attached for execution. It is this transaction-attach trace entry that contains the terminal and transaction identifiers. It also contains the task identifier that is unique to a particular instance of a transaction. This is illustrated in the diagram shown in Figure 25.

If you select trace entries by specifying the TRANID or TERMID parameters, the DFHTU640 program searches for any transaction-attach trace entries that contain the specified TERMID or TRANID. It then formats any associated trace entries, identified by the TASKID found in the transaction-attach trace entry data.

For example, if the entries in your auxiliary trace data set are as illustrated in Figure 25, you can obtain formatted trace output for task IDs 00123 and 00124 by specifying the TRANID parameters. This is possible because the associated transaction-attach trace entries are present (see record numbers 2 and 7 in the diagram). Note that as the transactions in this example were task-attached, not terminal-attached, they do not have a TERMID. If they did have a TERMID, you could specify this to select the entries. However, you cannot obtain formatted trace output for task ID 00120 by specifying a TERMID or TRANID, because the auxiliary trace data does not contain the transaction-attach trace entry for that task.

Rules for coding trace selection parameters

If you enter the control statements in the DFHAXPRM data set, enter them in columns 1 to 71 of the 80-character records. Leading blanks are ignored, and no imbedded blanks are allowed. The first blank in a line terminates the statements on that line; you can include comments after the first blank. The TERMID and TRANID entries are padded with blanks to four characters if necessary.

You can specify each control statement one or more times; for example,

TASKID(xxxx,zzzz,yyyy,aaaa,bbbb,cccc,dddd,eeee,ffff,gggg,hhhh,iiii,jjjj),
TASKID(kkkk,rrrr-uuuu,wwww)

You must use commas to separate keywords and entries in a list. Continuation to another record is allowed after any comma that separates keywords, provided the comma is in column 71 or is followed by a blank. Continuation records can start in any column.

For example, the following statements can be coded in DFHAXPRM:

TERMID=LP1,                  [Select entries for terminal LP1
TRANID=(ABRW,AORD,MYTR),     [Select entries for tranids ABRW, AORD, & MYTR
TIMERG=(123000-150000))      [Select entries timed between 1230 and 1500

The same example could be coded in the PARM parameter as follows:

//       EXEC  PGM=DFHTU640,PARM=('TERMID=LP1,TRANID=(ABRW,AORD,MYTR)',
//         'TIMERG=(123000-150000)')
Note:
The following example, with the transaction ID MYTR placed in a second record, would not work, because the list has been split within the keyword rather than between keywords:
TRANID=(ABRW,AORD,   [Select entries for tranids ABRW, AORD...
MYTR),                     & MYTR
Figure 25. Association of transaction-attach trace entries with task entries
 The figure shows an auxiliary trace data set with nine entries. The second and seventh entries in the data set are transaction-attach trace entries, and the rest of the entries are task entries. Each task entry includes a point ID, a task ID, and some trace data. The point ID is the four-character hexadecimal value representing a point within the domain. The trace points for transactions that have been terminal-attached are AP 1730, AP 1731, AP 1790, AP 1791, AP 17B0, AP 17B1, AP 17C0 and AP 17C1. AP represents the domain, and the four-character value is the point ID. The task ID is the ID for the instance of the transaction to which the task belongs, and it can be in various formats -- in our example, one of the task entries is for the task ID of 000119, three are for the task ID of 000120, two are for the task ID of 000123, and one is for the task ID of 000124. The two transaction-attach trace entries include, among other things, a point ID, the four-character ID of the transaction (TRANID), and a task ID (TASKID) for that instance of the transaction. The task IDs are 000123 and 000124. These two transaction-attach trace entries have a trace point of XM 1102, the trace point for task-attached transactions (XM represents the transaction manager domain, and 1102 is the point ID within the domain). As they are task-attached, instead of including a terminal ID (TERMID), they include another task ID field (also called TASKID) naming the task that attached them, TCP. The transaction-attach trace entry with the task ID 000123 can be matched up with the two task entries containing that task ID, so even though all the items are entered at different places in the data set, you can find them using the TRANID from the transaction-attach trace entry. If the transaction-attach trace entry had a TERMID, you could use that for the same purpose, but our examples do not have a TERMID. The same applies to the transaction-attach trace entry for task ID 000124. However, the transaction-attach trace entries for the other two task IDs in our example, 000119 and 000120, are not present in the data set, so you cannot find the task entries for these task IDs by searching on TERMID or TRANID -- the task entries do not include this information.
Note:
The trace point for transactions that have been task-attached is XM 1102. The trace points for transactions that have been terminal-attached are AP 1730, AP 1731, AP 1790, AP 1791, AP 17B0, AP 17B1, AP 17C0 and AP 17C1.

Related reference
Trace utility print program (DFHTU640)
The CICS trace utility program, DFHTU640
Using IPCS to print trace records written to GTF
[[ Contents Previous Page | Next Page Index ]]