Setting up a cataloged procedure

PGM=AHLGTF

Calls for the system to run program AHLGTF.

PARM='parm, parm...'

Options specified on the PARM parameter specify where GTF writes trace data and the amount of storage needed for GTF to collect and save trace data in various dump types. parm can be any of the following:

   MODE={INT|EXT|DEFER}
   SADMP={nnnnnnK|nnnnnnM|40K}
   SDUMP={nnnnnnK|nnnnnnM|40K}
   NOPROMPT
   ABDUMP={nnnnnnK|nnnnnnM|0K}
   BLOK={nnnnn|nnnnnK|nnnnnM|40K}
   SIZE = {nnnnnnK|nnnnnnM|1024K}
   TIME=YES
   DEBUG={YES|NO}

MODE={INT|EXT|DEFER}

Defines where GTF writes the trace data. MODE=INT directs data to a trace table in virtual storage, and MODE=EXT directs data to a data set on tape or DASD.

If MODE=INT, each instance of GTF will direct the trace data to a separate trace table in virtual storage, and will ignore any DD statements that define GTF output data sets. Choose this option when it is very important to you to maintain good system performance while GTF runs. The trace table cannot contain as much GTF trace data as a data set, but will not impact performance as much as a data set because there is no I/O overhead.

If MODE=EXT or MODE=DEFER, each instance of GTF directs the output to a separate trace data set defined by GTFOUTxx or IEFRDER DD statements. MODE=EXT is the default value. Choose MODE=EXT or MODE=DEFER when you want to collect more data than will fit in a trace table. Writing trace data to a data set does involve I/O overhead, so choosing one of these options will impact system performance more than MODE=INT.

MODE=DEFER will place the trace data in the GTF address space until you enter the STOP GTF command. Every instance of GTF runs in its own address space. During GTF end processing, each instance of GTF will transfer the data from its address space to the output data set.

The amount of data transferred for MODE=EXT or MODE=DEFER is one of the following:

• The default amount
• The amount specified on the SADMP|SA keyword

When the trace output data set is full, GTF continues as follows:

• Direct access: GTF resumes recording at the beginning of the data set, when the primary allocation is full. Thus, GTF writes over earlier trace data.
• Tape: GTF writes an end-of-file record. The tape is rewound and unloaded, then a new volume is mounted on the tape unit. If GTF has only one tape data set and only one unit for the data set, GTF does not write trace records while the tape is unavailable, thus losing trace data.
  GTF can write to multiple tape units in two ways:

  • Multiple GTFOUTxx DD statements can specify tape data sets. When GTF fills one data set, it changes to the next data set.
  • The IEFRDER DD statement can specify two tape units; in this case, GTF resumes writing the current trace data on the other unit, while rewinding and unloading the full volume.

SADMP|SA=nnnnnnK|nnnnM|40K}

Specifies the amount of storage needed to save GTF trace data for stand-alone dumps. Specify the amount of storage in terms of either kilobytes (K) or megabytes (M). The minimum amount is 40K, and the maximum is 2048M minus 400K, or 2096752K. GTF rounds up the amount to the block size boundaries for DASD data sets, or 32K boundaries for tape data sets or internal mode. The default value for this parameter is 40K (rounded up to the correct boundary).

SDUMP|SD={nnnnnnK|nnnnM|40K}

Specifies the amount of storage needed to save GTF trace data for SVC dumps. Specify the amount of storage in terms of either kilobytes (K) or megabytes (M). The minimum amount is zero, and the maximum cannot exceed the maximum amount of storage defined by the SADMP parameter. GTF rounds up the amount to the block size boundaries for DASD data sets, or 32K boundaries for tape data sets or internal mode. The default value for this parameter is 40K (rounded up to the correct boundary).

NOPROMPT|NP

If specified, indicates that you will not be prompted to specify trace options. Message AHL125A and AHL100A will not be issued. Use this parameter when you have a parmlib member set up with the desired GTF options and you want to avoid multiple replies in a sysplex environment.

ABDUMP|AB={nnnnnnK|nnnnM|0K}

Specifies the amount of GTF trace data to be formatted in an ABEND or SNAP dump. Specify the amount of trace data in terms of either kilobytes (K) or megabytes (M). The minimum amount is zero, and the maximum cannot exceed the maximum amount of storage defined by the SADMP parameter. GTF rounds up the amount to the block size boundaries for DASD data sets, or 64K boundaries for tape data sets or internal mode. The default value for this parameter is 0K, which means that no GTF data will appear in ABEND or SNAP dumps.

For ABEND or SNAP dumps. GTF formats only those records that are directly associated with the failing address space. GTF does not format the channel program trace data associated with the failing address space.

BLOK={nnnnn|nnnnnK|nnnnnM|40K}

Specifies the amount of virtual storage (E)CSA that GTF will use to collect trace data. Specify this storage amount in 4096-byte pages (nnnnn), or in bytes (nnnnnK or nnnnnM). The maximum amount is 99999; the default is 40K. If the amount is less than 40K, GTF will use the default.

SIZE={nnnnnK|nnnnnM|1024K}

Specifies the size of the buffers. Specify this amount in bytes (nnnnnK or nnnnnM). The range for the size keyword is 1M to 2046M. The maximum amount is 2046M; the default is 1024K. If the amount is less than 1024K, GTF will use the default.

TIME=YES

Specifies that every GTF trace record have a time stamp, as well as the block time stamp associated with every block of data. The time stamp is the eight-byte time of day (TOD) clock value at the local time in which GTF puts the record into the trace table. GTF does not accept TIME=NO; all output records will have time stamps. Local time is calculated using a time zone offset that GTF establishes at the time that the trace starts. If the system time zone offset is changed during tracing, e.g. in response to daylight saving time going into effect, local times formatted by GTF will not correspond with system times afterward.

When you use IPCS to format and print the trace records, a time stamp record follows each trace record. You can use these time stamp records to calculate the elapsed time between trace entries. The time stamp record is described in Time stamp records.

DEBUG={YES|NO}

Specifies whether GTF should attempt recovery after it encounters an error. If DEBUG=YES, GTF will not attempt any recovery. Instead, GTF will issue an error message and end after encountering any error, so that the contents of the trace table immediately prior to the error remain intact.

If DEBUG=NO, which is the default, GTF does the following:

• For errors in GTF processing, GTF continues processing after doing one or more of the following:
  • Flagging the trace record or trace record field associated with the error
  • Issuing a message to the console to inform that an error occurred
  • Suppressing the error or function in which the error occurred.
• For errors that do not occur in GTF itself, GTF ends abnormally. If GTF stops processing, that will not cause any other task to also stop.

• Specify MODE=EXT or MODE=DEFER
• Use the default MODE=EXT

If you code a procedure that does not contain a SYSLIB DD statement, GTF issues message AHL100A to prompt for options after the START GTF command. In response, you can supply the desired trace options through the console. See Specifying or changing GTF trace options through system prompting for examples of specifying options through the console.