z/VM: CP Commands and Utilities Reference - z/VM - IBM

TRACE
Authorization
Purpose
Usage Notes
Privilege Class: G
Use the TRACE command to monitor events that occur in your virtual machine.
z/VM lets you trace a number of events, including:
v Instruction execution
v Storage alteration
v Register alteration
v I/O activity.
Each traced event results in a trace entry, a command response that you can have
sent to your virtual console, to a virtual printer, or to both. The trace entry is made
up of significant information about the event. You can use trace entries to analyze
the operation of your virtual machine and to debug problems.
Note that in this manual the TRACE documentation is primarily for reference.
For a full explanation of how to use the trace facility, along with examples, see
z/VM: Virtual Machine Operation.
(General for TRACE)
1. All of the primary TRACE operands establish trace traps. A trace trap is a
programming function that, as its name implies, captures information about an
event in your virtual machine.
When you establish a trap, you can assign it any unique 1-character to
4-character name (with the exception of the name ALL). If you do not assign a
name, the system assigns the trap a unique number from 1 to 9999. You use
this unique identifier (name or number) to alter a trap with the TRACE TRAP
command or to delete a trap with the TRACE DELETE command.
The options (unique and common) available with each primary operand and
with the TRAP operand allow you to specify exactly how you want the trap to
process. For example, you may want the trap to function only when an event
occurs within a particular address range. In this case, you specify the common
option FROM with the address range you choose. At the same time, you may
want to trace events only when your virtual machine is running in supervisor
state. In this case, you also specify the common option SUPERVISOR.
2. All trace traps must be contained in units of control called sets. A “trace set” is
a collection of one or more traps that run together.
You create a set using the TRACE GOTO command. When you create the set,
you assign it a unique 1-character to 8-character name. If you do not assign
the set a name, the system assigns a unique name for you.
If you do not create a set before you establish a trap, z/VM creates a set for
you named INITIAL.
Only one set may be active at any given time.
The following commands exist for manipulating sets:
v TRACE GOTO
v TRACE CALL
v TRACE RETURN
TRACE
Chapter 2. CP Commands 1601