ETRACE

Purpose

Use the ETRACE command to enable or disable the recording of events in a spool file for a virtual machine or virtual machine group.

GCS supports external tracing — the recording of events in a spool file. For more information on External Tracing Facility, see the z/VM: Diagnosis Guide. You control when this external tracing is active by using the ETRACE command.

You can enable (activate) or disable (deactivate) external tracing for a particular virtual machine or an entire virtual machine group. You can specify a certain list of events for one virtual machine and a totally different set of events for all other virtual machines in the group.

Before any external tracing actually takes place, though, a class C user must enter the TRSOURCE command for the virtual machines to be traced.

Parameters

END

Disables external tracing of all events.

ALL

Enables or disables external tracing of all events.

DSP

Enables or disables external tracing of each task switch (dispatch of a different task).

EXT

Enables or disables external tracing of each external interrupt.

FRE

Enables or disables external tracing of FREEMAIN events started through SVC and Branch Entry calls.

GET

Enables or disables external tracing of GETMAIN events started through SVC and Branch Entry calls.

GTrace

Specifies that you want data, passed from the GTRACE macro, to be recorded in a spool file.

I/O

Enables or disables external tracing of each I/O interrupt.

PRG

Enables or disables external tracing of each program interrupt.

SIO

Enables or disables external tracing of each request by the supervisor for I/O. This includes execution of the following instructions: SIO, DIAGNOSE I/O, TIO, CLRIO, HIO, HDV, SIOF, and TCH.

Note: The event is not recorded when the instruction is executed by an application program.

SSS

Enables or disables detailed external tracing of IUCV interrupts on the Signal System Service path.

SVC

Enables or disables external tracing of each SVC interrupt.

SYN

Enables external tracing of APPC/VM synchronous events.

OFF

Disables external tracing of events for the specified types.

Omitting the OFF operand enables external tracing of events for the specified type.

GRoup

Specifies that this command is to affect the virtual machine group, of which the issuer of the command is a member. If this operand is omitted, the command is applied only to the issuer's virtual machine.

If external tracing of certain types of events is enabled for the group, then they are automatically enabled for any virtual machine that may join the group later.

The GROUP operand can be used only by an authorized member of a virtual machine group. That is, by a member of the group placed on the list of authorized users in the GCS configuration file.

An unauthorized group member cannot deactivate tracing enabled by the GROUP operand. However, an authorized virtual machine can disable external tracing for itself although ETRACE with the GROUP operand was specified by another authorized virtual machine.

Usage

1. To enable external tracing, you must enter TRSOURCE in either BLOCK or EVENT mode and then enter ETRACE.
2. To disable external tracing in an orderly sequence, you should enter ETRACE END and then disable TRSOURCE, or trace records can be lost.
3. When ETRACE END is issued and EXTERNAL tracing is in BLOCK mode, the buffer is sent to CP.
4. When GCS loses control from a CP perspective (such as a system reset), the data in the buffer cannot be sent to CP and will not appear in the external trace records.
5. When running in EVENT mode, trace records do not get lost, but the performance gain of the BLOCK support is not realized.

Messages

For more information on messages, see z/VM: Other Components Messages and Codes.

Return Codes