Coding macros for application traces
This information describes the coding for CTRACE, CTRACECS and CTRACEWR macros. The CTRACE macro is needed to define the application to component trace and delete the application from component trace. CTRACECS manages trace buffers and CTRACEWR writes the buffers to an external data set. The following is a high level sequence of events for your application's tracing with component trace.
Sequence of events for trace:
- The application issues CTRACE DEFINE macro during initialization.
- The application's start/stop routine receives control when the
operator turns the trace on.
- The routine obtains trace buffers and TBWC (Trace Buffer Writer Control) block of storage.
- Each buffer has an associated TBWC control area to store the state of the buffer and sequence number associated with the buffer. A unique buffer sequence number must be maintained for every CTRACEWR macro invocation.
- The routine initializes the TBWC for each buffer to the available state.
- The application creates trace entries according to options.
- If component trace is active, it finds an available buffer by
looping through TBWCs, issuing the CTRACECS macro to put the buffer
in the filling state if the buffer is currently in the available state,
until one is marked filling.
The CTRACECS macro serializes changing the state and sequence number in the TBWC.
- The application fills the buffer with trace data, and issues CTRACECS macro to put the buffer in the full state if the buffer is currently in the filling state.
- If the external writer is active, the application issues the CTRACEWR macro to write the buffer to the external data set. Otherwise, if buffers are being wrapped in storage, the application issues the CTRACECS macro to mark the buffer available.
- If component trace is active, it finds an available buffer by
looping through TBWCs, issuing the CTRACECS macro to put the buffer
in the filling state if the buffer is currently in the available state,
until one is marked filling.
- During SDUMP or standalone dump, dump component buffers.
- The application provides a locate trace buffer exit for dumps.
- The application provides a unique filter exit.
- The IPCS CTRACE subcommand provides common functions like time stamp, ASID, and JOBNAME filtering.
- Each trace entry that passes all of the filters is formatted according to the application's format table definition.