Starting the Generalized Trace Facility

Use the START GTF command to start the generalized trace facility.

 
S {GTF|membername}[.identifier][,devicetype|,[/]devnum][,volumeserial]
     [([,MODE={INT|DEFER|EXT}][,TIME=YES][,DEBUG=YES]
          [,BLOK={numpages|nnnK|nnM}][,MEMBER=xxxxxxxx][,REGION=nnnnK]
     [,{SADMP|SA}={nnM|nnnk}][,{SDUMP|SD}={nnM|nnnk}]
          [,{NOPROMPT|NP}][,{ABDUMP|AB}={nnM|nnnk}])]
     [,keyword=option[,keyword=option]...]

The parameters are:

GTF

The name of the IBM-supplied cataloged procedure that invokes GTF.

membername

The name of the member that contains the source JCL that invokes GTF. The source JCL can be either a cataloged procedure (for example, residing in SYS1.PROCLIB) or a job residing in a partitioned data set. The name can be either the IBM-assigned name (GTF) or a user-assigned name.

identifier

The user-determined name identifying this specific GTF session. If you omit an identifier, the system automatically uses the job name as the identifier.

devicetype

The device type, such as 3211, of the writer to be started. The device type provided in the IBM-supplied cataloged procedure for GTF is used unless overridden by this command.

Note: devicetype and devnum are mutually exclusive.

[/]devnum

The device number of the writer to be started. A device number is 3 or 4 hexadecimal digits. A slash (/) must precede a 4-digit number and is optional before a 3-digit number.

Note: devicetype and devnum are mutually exclusive.

volumeserial

The serial number of a magnetic tape or direct access volume to receive the trace data.

MODE=INT

Trace data is to be maintained in the GTF address space.

MODE=DEFER

Trace data is to be maintained in the GTF address space until the operator enters STOP GTF. Then, during end processing GTF will transfer the data from its address space to the output data set.

MODE=EXT

Trace data is to be maintained in an external data set.

BLOK=

Reserves common storage buffers to collect GTF data.

nnnK or nnM: The decimal number for the amount of storage in kilobytes(K) or megabytes(M). The minimum amount, also the default amount, is 40K.
numpages: The decimal number for the amount of 4096-byte pages of storage.

TIME=YES

Each logical trace record is to be time-stamped. If this parameter is omitted, individual records will be time-stamped. TIME=NO is not supported.

DEBUG=YES

GTF stops whenever an error is encountered while a trace record is being created. If this parameter is not specified, GTF attempts to recover from the error condition but might not be able to record future events of the same type.

MEMBER=xxxxxxxx

The parmlib member to be accessed by this invocation of GTF. If this parameter is omitted, GTFPARM is used.

REGION=nnnnK

The maximum size of the GTF address space in bytes. You can specify any number from 832K to 2880K.

keyword=option

Any appropriate keyword specified to override the corresponding parameter in the cataloged procedure. The maximum length of each keyword=option is 66 characters. No individual value within this field may be longer than 44 characters in length. If you are overriding a symbolic parameter, do not use any of the DD keywords. For example, do not use UNIT= to override the devicetype positional parameter in the cataloged procedure.

SADMP= or SA={nnnK or nnM}

The number of bytes of GTF data that will appear in a stand alone dump. The default is 40K.

SDUMP= or SD={nnnK or nnM}

The number of bytes of GTF data that will appear in an SVC dump (SDUMP). The default is 40K.

NOPROMPT or NP

If specified, indicates that the operator 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= or AB={nnnK or nnM}

The number of bytes of GTF data that will appear in a SNAP or ABEND dump. The default is 0 K, which means that no GTF output data will appear in a SNAP or ABEND dump.

This data will only be included in dumps for userids which have access to the IEAADB.DMPAKEY facility. Refer to Example of defining the IEAABD.DMPAKEY profile in z/OS Security Server RACF Security Administrator's Guide for an example of how that is done. End of change

Example 1:

This example starts a GTF session with the identifier EXAMPLE and with trace data maintained in the GTF address space. The DSN keyword is entered to override a symbolic parameter defined in the cataloged procedure.

S GTF.EXAMPLE,,,(MODE=INT),DSN=NULLFILE

Example 2:

This example starts a GTF session with the trace data recorded on an external device. Because it is not apparent which is the GTF recording device, you have to display active jobs with the D A,LIST command before you can stop GTF. The GTF session started in this example could run in an address space of a maximum of one megabyte.

S GTF,,,(MODE=EXT),REGION=1000k