Retro1.org codex

TRACE                                                    CP Privilege Class:  G

Use the TRACE command to trace specified virtual machine activity and to record
the results at the terminal, on a virtual spooled printer, or on both terminal
and printer.  The TRACE command can use operands in a cumulative manner; that
is, operands specified for the first time are activated, whereas those
specified with new modifiers are updated.  The RUN and NORUN operands, however,
can be specified in different TRACE commands for different tracing functions
and do not cause a conflict.

Also see the PER command.

The format of the TRACE command is:
+----------+------------------------------------------------------------------+
| TRace    | SVC|I/O|PROgram|EXTernal|PRIV|SIO|CCW|BRanch|INSTruct|ALL|CSW    |
|          |    [options]                                                     |
|          | END                                                              |
|          |                                                                  |
|          | options:                                                         |
|          |   PRINter      TERMinal|BOTH      NORun|RUN      OFf             |
+----------+------------------------------------------------------------------+
More than one of these activities may be traced by using a single TRACE
command.  For example:
   TRACE SVC PROGRAM SIO PRINTER

where:

SVC      traces virtual machine SVC interrupts.

I/O      traces virtual machine I/O interrupts.

PROgram  traces virtual machine program interrupts.

EXTernal traces virtual machine external interrupts.

PRIV     traces all virtual machine non-I/O privileged instructions.

SIO      traces TIO, CLRIO, HIO, HDV, and TCH instructions for all virtual
         devices both spooled and non-spooled.  SIO and SIOF instructions will
         not be traced for spooled devices or consoles.  It also traces SIO
         instructions to attached remote printers and dedicated remote graphics
         terminals.

CCW      traces virtual and real CCWs for nonspool nonconsole device I/O
         operations.  Virtual and real CCWs are not traced for remote and
         VM/VTAM dialed devices.  When CCW tracing is requested, SIO and TIO
         instructions to all devices are also traced.

BRanch   traces virtual machine interrupts, PSW instructions, and successful
         branches.

INSTruct traces all instructions, virtual machine interrupts, and successful
         branches.

ALL      traces all instructions, interrupts, successful branches, privilege
         instructions, and virtual machine I/O operations.

CSW      provides contents of virtual and real channel status words at I/O
         interrupt.

END      terminates all tracing activity and prints a termination message.

PRINter  directs tracing output to a virtual spooled printer.  If PRINTER is
         specified, RUN is assumed; however neither RUN nor NORUN can be
         specified.  Tracing output goes to that virtual printer that has the
         lowest virtual address.

TERMinal directs tracing output to the terminal (virtual machine console).

BOTH     directs tracing output to both a virtual spooled printer and the
         terminal.

OFf      halts tracing of the specified activities on both the printer and
         terminal.

NORun    stops program execution after the trace output to the terminal and
         enters the CP command environment.

         Note:  If a Diagnose code X'08' is being traced, NORUN has no effect
         and program execution does not stop.

RUN      continues the program execution after the trace output to the terminal
         has completed and does not enter the CP command environment.


Usage notes:

1.  If your virtual machine has the virtual=real option and NOTRANS set on, CP
    forces CCW translation while tracing either SIO or CCW.  When tracing is
    terminated with the TRACE END command, CCW translation is bypassed again.

2.  If VM/370 hardware assist is enabled on your virtual machine, CP turns it
    off while tracing SVC, PRIV, BRANCH, INSTRUCT, or ALL activities.  If
    virtual interval timer support is available on your processor and is active
    (that is, SET ASSIST TMR is in effect), CP turns the timer support off
    while tracing external interrupts.  After the tracing is terminated with
    the TRACE END command, CP turns hardware assist on again.

3.  If trace output is being recorded at the terminal, the virtual machine
    stops execution and CP command mode is entered after each output message.
    This simulates the instruction step function.

    However, all processing associated with the event being traced is completed
    and, therefore, execution may have stopped after an instruction has
    executed and the PSW has been updated.

    For example, a privileged instruction traced with the PRIV operand stops
    after the privileged instruction executes, whereas the same instruction
    traced with the ALL operand stops before the instruction executes.

    To determine whether the traced instruction has executed, display the
    virtual machine PSW.

    To resume operation of the virtual machine, the BEGIN command must be
    entered. If the RUN operand is specified, the virtual machine is not
    stopped after each output message.

4.  If trace output is being recorded on a virtual spooled printer, a CLOSE
    command must be issued to that printer in order for the trace output to be
    printed on the real printer.

5.  When tracing I/O, you cannot detach devices with the DETACH command.
    Attempts to detach a device are rejected and the following message is
    issued:
       DMKVDD273E  DETACH rejected; virtual machine tracing I/O

6.  Successful branches to the next sequential instruction and branch-to-self
    instructions are not detected by TRACE.

7.  RUN and NORUN can be specified in different TRACE commands with no conflict
    as long as the functions being traced are different.

8.  Instructions that modify or examine the first two bytes of the next
    sequential instruction cause erroneous processing for BRANCH and INSTRUCT
    tracing.

9.  When tracing on a virtual machine with only one printer, the trace data is
    intermixed with other data sent to the virtual printer.  To separate trace
    information from other data, define another printer with a lower virtual
    address than the previously defined printer.  For example, on a system with
    00E defined as the only printer, define a second printer as 00B.  The
    regular output goes to 00E and the trace output goes to 00B.

10. If the BRANCH, INSTRUCT, or ALL activities are being traced by a virtual
    machine using a shared system, the user receives a warning message and the
    virtual machine is unshared from (given a private copy of) the named
    system.  Other users of the segment continue to operate with an unchanged
    copy of that segment.

11. I/O operations for virtual channel-to-channel devices, with both ends
    connected to the same virtual machine, cannot be traced.

12. Use the TRACE command to trace specified virtual machine activity and to
    record the results at the terminal, at a virtual printer, or at both.  This
    command is useful in debugging programs because it allows you to trace only
    the information that pertains to a particular problem.

13. If your virtual machine is doing I/O that results in program-controlled
    interruptions (PCIs), and you are tracing I/O or CSW activity, some of the
    PCIs may not be traced.  This situation arises when the system is extending
    its free storage area and the additional demand on available free storage
    can cause a system abend.

14. The PA1 key on a 3270 display terminal should not be pressed with trace all
    run active while the display screen indicates RUNNING status, as a
    subsequent CP command entered from the console may result in interleaved
    output.

15. There are some modules in CMS that do not issue SIOs.  The I/O operation is
    initiated via DIAGNOSE instructions.

Responses:

The following symbols are used in the responses received from TRACE:
   vvvvvv          virtual storage address
   tttttt          virtual transfer address or new PSW address
   rrrrrr          real storage address
   xxxxxxxx        virtual instruction, channel command word, CSW status
   yyyyyyyy        real instruction, CCW
   ss              argument byte (SSM-byte) for SSM instruction
   ns              new system mask after execution of STOSM/STNSM
   zz              low order byte of R1 register in an execute instruction (not
                   shown if R1 register is register 0)
   zzzzzzzz        referenced data
   type            virtual device name (DASD, TAPE, LINE, CONS, RDR, PRT, PUN,
                   GRAF, DEV)
   V vadd          virtual device address
   R radd          real device address
   mnem            mnemonic for instruction
   int             interruption type (SVC, PROG, EXT, I/O)
   code            interruption code number (in hexadecimal)
   CC n            condition-code number (0, 1, 2, or 3)
   IDAL            Indirect data address list
   ***             virtual machine interrupt
   :::             privileged operations
   ==>             transfer of control
   SEEK            read/write position on count-key-data device
   REAL EXTENT     real block location on a fixed-block device
   VIRT EXTENT     virtual block location on a fixed-block device
   LOCATE          read/write block position within extent

TRACE STARTED
   This response is issued when tracing is initiated.

TRACE ENDED
   This response is issued when tracing is suspended.

TCH, TIO, CLRIO, HIO, HDV, SIO, or SIOF
   I/O vvvvvv TCH xxxxxxxx type vadd CC n

TIO, CLRIO, HIO, or HDV
   I/O vvvvvv mnem xxxxxxxx type vadd CC n type radd CSW xxxx

SIO or SIOF
   I/O vvvvvv mnem xxxxxxxx type vadd CC n type radd CSW xxxx CAW vvvvvvvv

CCW:
   CCW vvvvvv xxxxxxxx xxxxxxxx rrrrrr yyyyyyyy yyyyyyyy
   CCW  IDAL  vvvvvvvv vvvvvvvv  IDAL  00rrrrrr 00rrrrrr
   CCW  SEEK  xxxxxxxx xxxxxx    SEEK  yyyyyyyy yyyy
   CCW  SEEK  HEAD     xxxxxx    SEEK  HEAD     yyyy
   CCW  REAL EXTENT yyyyyyyy yyyyyyyy yyyyyyyy yyyyyyyy
   CCW  VIRT EXTENT xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx
   CCW                            LOCATE    xxxxxxxx xxxxxxxx

The IDAL or SEEK lines, as well as the REAL EXTENT, VIRT EXTENT, or LOCATE
lines, are included only if applicable.  The virtual IDAL is not printed if the
real CCW operation code does not match the real CCW.  With a SEEK HEAD CCW,
virtual data is being used to execute at the hardware.  There is no arm
movement to the cylinder since it is already at the correct cylinder; there is
not data relocation.  Only the 2 bytes containing the head (track) are used.
Therefore, with the CCW trace for SEEK HEAD, only the head (track) is output.

Instruction Tracing:

Privileged Instruction:
   ::: vvvvvv SSM   xxxxxxxx ss           (normal SSM)
   ::: vvvvvv SSM   xxxxxxxx ss  tttttt   (switch to/from translate mode)
   ::: vvvvvv STOSM xxxxxxxx ns           (normal STOSM)
   ::: vvvvvv STOSM xxxxxxxx ns  tttttt   (switch to translate mode)
   ::: vvvvvv STNSM xxxxxxxx ns           (normal STNSM)
   ::: vvvvvv STNSM xxxxxxxx ns  tttttt   (switch from translate mode)
   ::: vvvvvv LPSW  xxxxxxxx     tttttttt  tttttttt   (WAIT bit on)
   ::: vvvvvv LPSW  xxxxxxxx ==> tttttttt  tttttttt   (WAIT bit not on)
   ::: vvvvvv mnem  xxxxxxxx                          (all others)

Executed Instructions:
   vvvvvv EX xxxxxxxx zz vvvvvv mnem xxxx xxxxxxxx

For an executed instruction, where zz (see preceding explanation of symbols) is
nonzero, the mnemonic for the executed instruction is given as if the zz byte
had been put into the instruction with an OR operation.

All Other Instructions:
   vvvvvv mnem xxxxxxxx xxxx

Successful Branch:
   vvvvvv mnem xxxxxxxx ==> tttttt

INTERRUPTION (SVC, PROGRAM, or EXTERNAL)
   *** vvvvvv int code ==> tttttt

I/O INTERRUPTION (First line given only if "CSW" was specified):
   CSW V vadd xxxxxxxx xxxxxxxx R radd yyyyyyyy yyyyyyyy
   *** vvvvvv I/O vadd ==> tttttt CSW xxxx

Branch Trace:  (ALL option selected)

Entry for 'branch from'   instruction
   vvvvvv mnem xxxxxxxx     tttttt

Entry for 'branch to'   instruction
   ==> vvvvvv mnem xxxxxxxxxxxx