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

1. Data collection for trace IDs of trace type DATA occurs before execution of the
overlaid instruction. If no data links are specified for the trace ID, a trace entry
is created in the system trace file, but no data is collected.
2. To calculate the exact amount of data that can be collected in a trace record,
use the following formula:
(3 times the number of data links specified) + (the total lengths of the data
links) + (the total number of bytes to be collected).
The sum must be less than or equal to 4 KB (in decimal).
Also, the maximum number of data links allowed for any given trace ID is 255.
The maximum data link length is 250.
3. DATA traces should always be placed at instruction boundaries. The
TRSOURCE command can verify only that the specified location is on a
halfword boundary and that it contains a valid operation code; if these
conditions are not met, the command fails, with an error message.
If the verification is successful, the TRSOURCE command overlays the
specified location with a data trace SVC instruction. If the location is not an
instruction boundary, unpredictable results can occur, including a system
failure.
4. If an error is made while entering a data link, the entire trace must be dropped
and redefined to remove the data link from the definition. This is because there
is no way of deleting a data link from a trace definition. It is therefore
recommended that the definitions of commonly used type DATA traces be
saved in EXECs. Locations can be changed for defined but disabled DATA
traces.
5. Specification of extra data links for a defined but disabled trace results in an
addition to the definition.
6. The following is a list of restricted locations for the definition of trace points.
These locations are restricted because enabling DATA traces in them would
cause recursion or interlocks.
a. Locations not on halfword boundaries.
b. Locations not mapped in CP virtual storage.
c. Locations of already enabled DATA traces. Note that multiple DATA traces
may be defined at the same location but only one trace at a time may be
enabled at that location.
d. Locations within a module loaded with the CPXLOAD command.
e. Locations that contain a NOOP (4700xxxx) preceded by a Subtract
Halfword instruction. The HCPENTER macro contains this instruction
sequence.
f. Locations that contain an enabled dynamic CP exit.
7. Trace data is not collected during system termination.
TRSOURCE ID (Definition Operands)
8. It is recommended that records defined for any code path traveled when
writing a system trace file (including paging and spooling code paths and some
code paths in IOS) be kept under a page in length.
9. Users should avoid placing traces in code paths that hold spin locks, as this
situation increases the path length under the spin lock and seriously decreases
system performance.
10. Users should avoid placing data traces on instructions that are targets of
EXECUTE instructions; otherwise, results are unpredictable.
11. If interpretation of a data link string during execution results in a negative or
invalid address, a record is added to the system trace file to indicate that the
error occurred. However, there is no external indication that the error occurred.
Chapter 2. CP Commands 1691