TRACE

Authorization

Privilege Class: G

Purpose

Use the TRACE command to monitor events that occur in your virtual machine. z/VM® lets you trace a number of events, including:
  • Instruction execution
  • Storage alteration
  • Register alteration
  • 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 Tracing Programs in Your Virtual Machine in z/VM: Virtual Machine Operation.

Usage Notes

(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:
    • TRACE GOTO
    • TRACE CALL
    • TRACE RETURN
    • TRACE CLEAR
    • TRACE END
    • TRACE APPEND.
  3. You can define up to 255 trace sets and trace traps in any combination during a single trace session. (For example, you can create two trace sets with no more than 253 traps between them, five trace sets with no more than 250 traps between them, or 20 trace sets with no more than 235 traps between them).
  4. If you have RUN set ON, it will be turned off when a trace trap is established in a non-suspended trace set.
  5. For information on how to display your current trace settings, see the QUERY TRACE command. The QUERY TRACE command can be especially useful if you need to know the identifiers the system has assigned to your traps or sets. The command QUERY TRACE ALL displays the attributes of all trace traps within all trace sets.
  6. The IPL command for z/VM suspends all user tracing through the TRACE command during the IPL process. Tracing is then automatically reset as it was and continues normally.
  7. DATOFF is a synonym for NODAT. DATOFF is allowed whenever NODAT is allowed.
  8. Depending on the model, TRACE events for general register alteration may or may not be recognized for vector instructions.
  9. Self-modifying instructions or instructions that change the contents of registers used to compute operand addresses cause erroneous processing of trace output. For this reason, question marks (?) are displayed in the address field instead of erroneous output.
  10. If your virtual machine initiates full-screen I/O operations to your virtual console while CP is displaying trace entries there, the full-screen I/O operations may not complete successfully. This is most likely to occur if TERMINAL CONMODE has been set to 3270.
  11. The TRACE command will fail if issued when VMRELOCATE is in progress.
  12. When z/VM does not provide full trace support for an instruction, the command response will not include operand addresses. See TRACE RESPONSE for more details

Messages

  • HCP002E Invalid operand - operand
  • HCP003E Invalid option - {option|command contains extra option(s) starting with option}
  • HCP009E Invalid range - range
  • HCP010E Invalid register - register
  • HCP013E Conflicting option - option
  • HCP026E Operand missing or invalid
  • HCP033E Hexloc missing or invalid
  • HCP167E The mask is invalid for the specified data range.
  • HCP180E Trace not in effect
  • HCP1001E An operand is missing for - option
  • HCP1005E An invalid character was encountered.
  • HCP1025E A recursive trace call cannot be done.
  • HCP1026E The trace return cannot be done because there is no matching trace call.
  • HCP1027I An active trace set has turned RUN off.
  • HCP1032E A syntax error was encountered.
  • HCP1035E A trace set cannot be appended to itself.
  • HCP1036E {traceset|The current trace set} is an empty trace set.
  • HCP1037E The command cannot be processed because the maximum number of TRACE traps is already defined.
  • HCP1040E TRACE suspended - Incompatible with virtual machine's use of PER instruction-fetching-nullification facility.
  • HCP2106I TRACE caused a guest transaction at tbegin_address to be aborted at abort_address
  • HCP2107E The virtual machine's use of PER Event Suppression conflicts with TRACE txsusp.
  • HCP6150E An option has been specified that is not valid in {ESA/390|ESA/XC|z/Architecture®|z/XC} mode.
  • HCP6151E Storage {operand} is not addressable because of { a protection |an addressing | a segment translation | a page translation | a translation specification | an ASN translation | an AFX translation | an ASX translation | an ALET translation | an ALEN translation | an ALE sequence | an ASTE validity | an ASTE sequence } exception.
  • HCP6156E Access register | ALET |ASIT | Address Space Identifier (spaceid) does not designate an address space to which you have the appropriate access.
  • HCP6577E Invalid ALET - alet
  • HCP6578E Invalid {access register|ASIT|address space identifier} - option