TRSOURCE

Authorization

Privilege Class: C

Purpose

Use the TRSOURCE command to support definitions and control of I/O, data, and guest tracing.

The TRSOURCE command is functionally organized as follows:
  • TRSOURCE ID defines a trace. TRSOURCE ID associates an event (such as execution of a particular piece of code or an interrupt on a specific device) with a name (traceid) and, optionally, with a set of other traces (traceset).
    The TYPE operand of TRSOURCE ID assigns a trace ID to one of the four trace types. These types are:
    1. IO (I/O tracing). The IO trace lets you trace all I/O activity for a specific real device or range of real devices. The times, channel programs, SCSWs and data transferred for each I/O operation to the specified devices are made available for data analysis.
    2. DATA (data tracing). The data trace allows the user to define trace entries dynamically to record execution of most code paths in CP. The LOC parameter specifies what instruction, when executed, triggers recording of information. Data link parameters define what information is collected when the trap starts.
    3. GT (guest tracing). The guest trace allows CMS or GCS to record events in a system trace file.
    4. LAN (LAN tracing). The LAN trace allows a virtual switch or guest LAN to be traced. The trace collects the network traffic flowing over the simulated LAN segment. The traffic flowing over the OSA port (in the case of a virtual switch) might also be recorded.
    5. MONITOR CALL instructions placed in code paths that execute in transactional-execution mode will cause the executing transaction to abort if a monitor event is recognized. This restriction affects the use of TRSOURCE GT and the deployment of class 10 MONITOR CALL instructions.
  • TRSOURCE ENABLE activates the tracing of individual trace IDs and of trace IDs within trace sets.
  • TRSOURCE DISABLE deactivates the tracing of individual trace IDs and of trace IDs within trace sets.
  • TRSOURCE DROP disables and drops all CP knowledge of individual trace IDs and trace IDs within trace sets.
  • TRSOURCE DISPLAY displays the status resulting from the TRSOURCE commands you have issued.

See Using the TRSOURCE Command in z/VM: Diagnosis Guide for examples that show how TRSOURCE is used.

Usage Notes

(General for TRSOURCE)
  1. All traces are disabled at system termination.
  2. The definitions of traces are not saved across system IPLs. Therefore, the definitions of any commonly defined traces should be saved in EXECs.
  3. When a new member of an enabled set is defined, that member is not automatically enabled. It must be enabled separately. Attempts to enable trace IDs that are already enabled do not alter anything and do not result in an error message.
  4. The definition of what is being traced for each trace ID cannot be altered while the trace ID is enabled. Any trace ID may be altered while it is disabled.
  5. Use of the DROP keyword directed toward a trace set removes any record of all the trace IDs in the set. To remove or ungroup a member of a set, either assign the trace ID to another, possibly unused, trace set name or assign the trace ID to a trace set name of NULL.
  6. The destination of trace data can be altered with the TRSAVE command while the trace is disabled. See TRSAVE for details.
  7. Enabling a trace for which TRSAVE has not been issued invokes the TRSAVE destination defaults.
  8. If an error message is generated for a trace definition, enter query trsource id traceid to verify that the trace definition is correct.
  9. Data traced from this command is stored as a system data file (SDF), specifically a trace file (TRF), as opposed to a printer or reader file. Use the TRACERED utility to merge and format the files. TRACERED can send the output to your virtual printer, to a CMS file, or to an OS QSAM file. For more information, see TRACERED.
  10. If an external security manager is installed on your system, you may not be authorized to issue this command. For additional information, contact your security administrator.

Examples

The following examples provide an overview of the ways TRSOURCE can be used. For further examples, see z/VM: Diagnosis Guide.
  1. This example defines and enables a trace ID of type DATA. The trace ID is DSPLOOP, it is defined at address 4B248, and the data link string specified is G4+8%.2. 'label' is a label that is included with the datalink data in the trace record to identify that datalink's data. The destination is specified as a system trace file for the issuer with a maximum size of 2000. 
    trsource id dsploop type data loc 4b248 5820c846
trsource id dsploop dl g4+8%.2=label
trsave id dsploop dasd to * size 2000
trsource enable id dsploop
  2. This example defines, enables, and disables two trace IDs of type IO. These trace IDs, IO1 and IO2®, are put into trace set IOSET. IO1 traces I/O to devices in the range C41-C47; up to 200 bytes of transferred data is traced. IO2 traces I/O for USER1 to devices in the range A81-A87; up to 400 bytes of transferred data is traced. The destination options default (because TRSAVE was not issued) and the trace files are named IO1 and IO2 with a maximum size of 256 pages and a maximum number of 2. 
    trsource id io1 set ioset type io
dev c41-c47 iodata 200
 
trsource id io2 set ioset type io
dev a81-a87 iodata 400 user user1
 
trsource enable set ioset
trsource disable id io1
trsource disable id io2
  3. This example defines, enables, and drops two trace IDs of type GT. These trace IDs, GT1 and GT2, are put into trace set GTSET. The destinations are specified as system trace files for user ID USER3 with a default size of 256 pages. 
    trsource id gt1 set gtset type gt for user user2
trsource id gt2 set gtset type gt for vmgroup gcsgroup
trsave id gt1 dasd to user3
trsave id gt2 dasd to user3
trsource enable id gt2
trsource enable id gt1
trsource drop set gtset

Messages

  • HCP002E Invalid operand - operand
  • HCP004E Invalid hexloc - hexloc
  • HCP013E Conflicting option - option
  • HCP020E Userid missing or invalid
  • HCP021E A real device number was not supplied or it is invalid.
  • HCP026E Operand missing or invalid
  • HCP045E userid not logged on
  • HCP289I {User|Group} {userid|group} already enabled by traceid traceid.
  • HCP347E Excessive datalinks supplied for traceid traceid
  • HCP348E Excessive data requested for traceid traceid.
  • HCP349E String supplied does not match storage contents.
  • HCP369E Invalid location for tracing; command rejected
  • HCP370E Invalid datalink string supplied - value
  • HCP371I Device rdev already enabled by traceid traceid.
  • HCP371I Logical device Lldev already enabled by traceid traceid.
  • HCP371I PCIF rpfid already enabled by traceid traceid
  • HCP427E type {rdev|vdev|name[userid]} system spool space full; file {closed|held|purged}
  • HCP428E type {rdev|name[userid]} spool error; file {held|purged|closed}
  • HCP429E type vdev spool error; file {held| purged}
  • HCP439E {User userid|*NSS|*IMG|*UCR|*NLS} spool fileid limit exceeded
  • HCP477E Traceid traceid not enabled; incomplete definition
  • HCP479E Traceid traceid currently enabled
  • HCP568E Maximum number of devices exceeded for traceid traceid.
  • HCP644E Unknown/unauthorized CP command: command
  • HCP816I {Traceid|Traceset} operand does not exist
  • HCP819I Traceid traceid disabled; group group enabled by traceid
  • HCP847E Maximum system spool file limit exceeded
  • HCP1003E {CP module name|rdev|ldev} {is|was} not found.
  • HCP1100E A logical device number was not supplied or it is invalid.
  • HCP6081I Ten trace files have been purged for {CP|traceid traceid[userid]}. Further warnings are suppressed.
  • HCP6084I The maximum number of trace files for {CP|traceid traceid[userid]} has been exceeded. The oldest file is purged.
  • HCP6086I Traceid traceid1 is no longer superseded by VMGROUP trace traceid2.
  • HCP6088I Trace data for traceid traceid[userid] was not saved by TRSAVE.
  • HCP6089E DEFERIO FRAMES specified causes total DEFERIO frames to exceed the amount of frames eligible for all DEFERIO traces.
  • HCP6091I The amount of frames used for DEFERIO trace exceeds the amount of pages that will be saved on DASD.
  • HCP6093E You are not allowed to switch modes for traceid traceid.
  • HCP6094I User userid will not be traced by trace traceid.
  • HCP6095I User userid is no longer being traced by trace traceid.
  • HCP6096I Trace traceid is being disabled.
  • HCP6097I User userid has restricted tracing to traces defined as BLOCK.
  • HCP6098E Trace traceid can not be enabled.
  • HCP6099E DEFERIO trace is invalid for a TYPE GT BLOCK mode trace.
  • HCP6160E token1 was not expected; xxxxx was expected.
  • HCP6161E Constant definition incorrect: reason.
  • HCP6162E Maximum nesting depth of IF statement exceeded.
  • HCP6163E Internal error during command processing: module + offset
  • HCP6426I {Allocating|Writing} the DEFERIO frames for traceid traceid.
  • HCP6427I X% of the DEFERIO frames for traceid traceid have been {allocated|written}.
  • HCP6525E External Security Manager is unavailable.