- TraceSignal
-
- retcode
- reascode
- trace_type_id
- subtype_id
- data_buffer
- data_len
- fmtrtn_name
Purpose
Use the TraceSignal function to build a trace header record and signal a VMTRACE event.
Parameters
- retcode
- (output,INT,4) is a variable where the function stores the return code.
- reascode
- (output,INT,4) is a variable where the function stores the reason code.
- trace_type_id
- (input,INT,4) is a variable for specifying the trace type that is to be signaled. This value is
stored in the trace header as part of the event key when the VMTRACE event is signaled.
System-defined trace types supported by TraceControl may be used, as well as any user-defined trace
type. Trace types in the range of 0–31 are reserved for CMS. Only trace types defined by CMS may be
set or queried using TraceControl services.
- subtype_id
- (input,INT,4) is a variable for specifying the trace subtype that is to be signaled. This value
is stored in the trace header as part of the event key when the VMTRACE event is signaled.
- data_buffer
- (input,CHAR,data_len) is a variable for a buffer that holds the trace
data to be signaled. This data is appended to the trace header.
- data_len
- (input,INT,4) is a variable for specifying the length of the trace data contained in
data_buffer. This value must be greater than or equal to 0. If 0 is
specified, the event data being signaled contains only a trace header.
- fmtrtn_name
- (input,CHAR,8) is a variable for specifying the name of the format routine you wish to use when
processing trace records. If the format routine name is left blank, the default system routine, DVF,
is filled in.
Usage Notes
- The TraceSignal interface builds a header record in a format that matches the format used by
CMS. The mapping of the header is defined in the vm_trc_recfmt structure
in the language binding files.
- When a VMTRACE event is signaled using the TraceSignal interface, the entire trace record is
defined as the event key. Event monitors may be created specifying the header and data as the key,
or any portion of it using wildcarding.
- If tracing is on for a CMS trace type and that trace type is signalled by the application,
qualifying event monitors may have CMS trace data as well as the data from this TraceSignal for
retrieval. In general, the application should avoid using trace types reserved for CMS.
- Trace subtypes associated with CMS trace types are reserved for definition by CMS and are
defined in CMS Trace Record Formats.
Users should not add their own subtypes
for any of the CMS-defined types. If a user wants to trace events not listed as a CMS type or
subtype, then a new user type category can be defined, (with a type ID not in the range of 0 - 31),
and monitored using event services. TraceSignal may then be used to issue an event signal for that
event.
- A TraceSignal results in an event signal being issued for the specified
trace_type_id regardless of whether tracing was enabled for a CMS trace
type by TraceControl.
- If data_len plus the length of the trace header is greater than
X'7FFFFFFF', then an overflow condition occurs and an error return code is given with a
reason code of vm_trc_bad_datalen.
- If a TraceSignal is issued for a CMS trace type for vm_trc_comm or
vm_trc_disp events, accounting records will be affected if accounting is
on for vm_act_comm or vm_act_cpu.
- See Tips on Constructing Keys for a discussion of the use of
binary data in event data keys.
Return Codes and Reason Codes
Return Code |
Reason Code |
Meaning |
vm_trc_success |
vm_trc_success |
TraceSignal completed successfully |
vm_trc_error |
vm_trc_bad_datalen |
Data length specified is invalid |
vm_trc_error |
vm_trc_insufficient_storage |
No more storage available |
Programming Language Bindings
Language |
Language Binding File |
C |
VMCTRC H |
Assembler |
VMASMTRC MACRO |
REXX |
VMREXTRC COPY |