TraceSignal — Signal a Trace Event

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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