Prompting keywords

AHL101A SPECIFY TRACE EVENT KEYWORDS - keyword=,...,keyword=

• If you do not specify a reply for each of the keywords displayed in message AHL101A, GTF records all the events for that trace option, which increases the amount of storage that GTF requires. IBM® recommends that you specify values for each keyword displayed, selecting the values that will help you debug your problem.
• You can only enter values for keywords displayed in message AHL101A.
• GTF limits the number of specific values that you can supply through prompting, see Table 1 for the maximum number of values allowed for each keyword. If you specify more than the maximum values, GTF issues a message to which you reply by respecifying values for all appropriate keywords.
• Keep in mind that prompting increases the amount of storage that GTF requires, because storage requirements depend on the trace options you specify. See Determining GTF's storage requirements for further information.
• Within a given reply, each keyword that you specify must be complete. If you need more values for a keyword than will fit into one reply, repeat the keyword in the next reply, and code the additional values for that keyword. The following are examples of correct replies:

  REPLY 01 IO=(191-193),SVC=(1,2,3,4,5)
  REPLY 01 SVC=(6,7,8,9,10)

  The maximum number of values that GTF allows for a keyword does not change, regardless of whether you enter one or more replies to specify all the values for the keyword.

• After supplying all keywords and values, you must enter the END keyword, which signifies that the event definition is complete. If the system does not find the END keyword in a reply, the system issues message AHL102A to prompt for additional event keywords and values. When the system finds the END keyword, the system issues message AHL103I to list all of the trace options that are in effect.

ASID=(asid1[,asidn]...[,asid5])

Specifies one through five identifiers for address spaces in which you want GTF tracing to occur. The values ‘asid1’ through ‘asid5’ are hexadecimal numbers from X'0001' to the maximum number of entries in the address space vector table (ASVT). If you specify ASIDP, but do not specify ASID= before replying END, GTF traces all address space identifiers.

If the number of values for ASIDP requires more than one line, and a particular ASID value is incorrect, GTF allows you to respecify the correct value without having to reenter all ASIDs.

If you specify both ASIDP and JOBNAMEP, GTF will trace address spaces that ASIDP did not identify, if some of the jobs that JOBNAMEP identifies run in other address spaces.

CCW=([S|I|SI][,CCWN=nnnnn][,DATA=nnnnn][,IOSB][,PCITAB=n])

Specifies different options for tracing channel programs. If you specify CCW= more than once, GTF uses the last specification of CCW=.

If you specify CCWP, but do not specify a value for keyword CCW=, GTF's default CCW tracing depends on what other trace options were specified. The following table shows the defaults for CCW tracing depending on other trace options specified:

Table 2. CCW defaults for selected TRACE options

Other Trace Options Selected	CCW Subparameter Defaults
SSCH or SSCHP	S
IO or IOP or IOX or IOXP	I
SSCH or SSCHP or IO or IOP or IOX or IOXP	SI
PCI	PCITAB=1
SSCH or SSCHP or IO or IOP or IOX or IOXP	CCWN=50
SSCH or SSCHP or IO or IOP or IOX or IOXP	DATA=20

Examples:
TRACE=IO,CCWP            CCW defaults to: CCW=(I,CCWN=50,DATA=20)
TRACE=IOP,SSCH,PCI,CCWP  CCW defaults to: CCW=(SI,CCWN=50,DATA=20,PCITAB=1)

If you specify an option more than once in one line, GTF uses the last specification of that option. An exception is that GTF uses the first specification of S, I, or SI. If a line contains an error, GTF prompts you to respecify the value.

S|I|SI

Specifies the type of I/O event for which you want channel programs traced. If you specify more than one option, GTF uses the first option.

S

Specifies GTF tracing of channel programs for start subchannel and resume subchannel operations. CCW=S works only with the SSCH or SSCHP trace options.

I

Specifies GTF tracing of channel programs for I/O interruptions, including program-controlled interruptions if you specify PCI as a trace option. CCW=I works only with the IO or IOP trace options.

SI

Specifies GTF tracing of channel programs for start subchannel and resume subchannel operations and I/O interruptions. CCW=SI works only with either SSCH or SSCHP and either IO or IOP as trace options.

CCWN=nnnnn

Specifies the maximum number of CCWs or DCWs traced for each event. The value nnnnn is any decimal number from 1 to 32767. The default is 50.

DATA=nnnnn

Specifies the maximum number of bytes of data traced for each CCW or DCWs. The value nnnnn is any decimal number from 0 to 32767. The default is 20.

GTF traces nnnnn bytes of data for each CCW on the data chain. GTF traces nnnnn bytes of data for each word in an indirect data addressing word (IDAW) list, a modified indirect addressing word (MIDAW) list, or a transport indirect addressing word (TIDAW) list.

For start subchannel or resume subchannel operations, GTF does not trace data for read, read backwards, or sense commands in the channel programs. If no data is being transferred, regardless of the type of I/O operation, GTF does not trace data for read, read backwards, or sense commands.

When the data count in the CCW or DCW is equal to or less than nnnnn, GTF traces all data in the data buffer. When the data count in the CCW or DCW is greater than nnnnn, GTF traces data only from the beginning and end of the data buffer. If you examine the traced data, you can tell whether the channel completely filled the buffer on a read operation.

GTF uses a different CCW or DCW tracing method for a data transfer that is in progress when an I/O interruption occurs. Instead of using the data count in the CCW or DCW, GTF tracing depends on the transmitted data count. The transmitted data count is the difference between the data count in the CCW or DCW and the residual count in the subchannel status word (SCSW), for non-zHPF channel programs and the transport status block (TSB), for zHPF channel programs.

• When the residual count is greater than the data count in the CCW or DCW, then GTF traces all of the data in the CCW or DCW.
• When the transmitted data count is less than or equal to nnnnn, GTF traces all of the transmitted data.
• When the transmitted data count is greater than nnnnn, GTF traces data only from the beginning and end of the transmitted data.

IOSB

Specifies tracing of the input/output supervisor block (IOSB), the input/output block extension (IOBE), for zHPF channel programs, and, if available, the error recovery procedure work area (EWA), for all CCW events. If you do not specify IOSB, then GTF performs IOSB and EWA tracing only if GTF encounters an exceptional condition when tracing a channel program.

PCITAB=n

Specifies a decimal number of 100-entry increments for GTF to allocate in an internal program-controlled interruption (PCI) table. The value of n is an integer from 1 to 9. The default is 1 (100 entries).

The PCI table keeps track of the channel programs that use PCI. One entry in the PCI table contains information about a program-controlled interruption in one channel program. An entry in the PCI table includes a CCW address and an IOSB address.

IO=(DEVCLASS=xxxx,DEVCLASS=xxxx,devnum1 [,devnumn...,devnum])

Specifies devices for which you want I/O interruptions traced. Devices are specified by entering a device number or a device class.

The device number must be specified in hexadecimal and is not the same as the subchannel number. If you specify any combination of IO= and SSCH=, and IO=SSCH=, the combined number of device numbers for all prompting keywords is unlimited. Specify device numbers individually, or as a range of device numbers with a dash (-) or colon (:) separating the lowest and highest number in the range. For example, to trace I/O interruptions for device numbers 193 through 198, you specify IO=(193-198).

The device class must be specified with the DEVCLASS= keyword parameter, which provides the ability to trace all devices in the specified device class. The allowable keyword parameters are:

     TAPE  (magnetic tape devices)
     COMM  (communications)
     DASD  (direct access storage device)
     DISP  (display)
     UREC  (unit/record)
     CTC   (channel to channel)

If you specify IOP, IOXP, or SYSP and does not specify IO= in the response to the prompting messages, GTF processing proceeds as if you specified IO, IOX or SYS event keywords respectively.

For the following examples, the I/O device numbers and associated device types listed below are used:

I/O Device Number

Device Type

230

3390 DASD

450

3490 Tape Drive

575

3480 Tape Drive

663

3380 DASD

020

3274 Communications Controller

       IO=(DEVCLASS=DASD,450)

       IO=(DEVCLASS=DASD,DEVCLASS=TAPE,020)

       IO=(450-663)