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