The start/stop routine receives
control to start or stop tracing
for the application, or to change trace options. The routine can determine
what action to take by checking bits in the CTSSFLGS field of the
component trace parameter list (CTSS), which is passed to the start/stop
routine. If the CTSSSTRT bit is on, the request is to start tracing.
If the CTSSSTOP bit is on, the request is to stop tracing.
When
the start/stop routine receives control to start tracing for
the application or to change the trace options, the routine can do
the following:
- Parse the options in the OPTIONS parameter
passed to the routine
(either from the REPLY operator command or a CTncccxx parmlib
member). If the routine detects errors, it can issue a WTO using the
console ID and CART specified in the CTSS, and set a failing return
code.
- Check for other errors.
- Obtain storage for trace
buffers in common storage, in the private
area, or in a data space. IBM® recommends
that you allocate multiple buffers. You might have to schedule an
SRB, post a task, or switch the primary address space to get to the
right mode to obtain storage.
- If any problems occur locating
the desired address space or obtaining
storage, set the appropriate return and reason codes.
- If you
plan to externalize your data through a dump data set,
anchor the trace buffers in an area that the CTRACE buffer find exit
routine can access when running under IPCS. See z/OS MVS IPCS Customization for
information about writing this routine.
- Use the 16 bytes of
user data in the CTSSUSRD field of the CTSS
to assist in locating the trace buffers. The application can specify
this user data on CTRACE DEFINE with the USERDATA parameter, or in
the CTSSUSRD field when the start/stop routine gets control.
- Set
a bit (CTSSRNSS) in the CTSS to indicate whether the start/stop
routine for sublevel traces defined with the LIKEHEAD keyword should
be called individually by component trace.
- Save ASIDs, JOBNAMEs,
and the results of the OPTIONS parse in
storage where the application can access them during its tracing activity.
- If the routine receives control indicating connection to an external
writer (the CTSSWCON flag is on), pass the token contained in the
CTSSWTKN field to the application. The application needs this token
when it issues the CTRACEWR macro to write buffers to DASD or tape.
See Externalizing trace data through the external writer for information about the external
writer.
For
multiple traces in an application, each routine receives a unique
token, whether the CTRACE DEFINE macro contains LIKEHEAD=NO or LIKEHEAD=YES.
Specifying these unique tokens in the CTRACEWR macros differentiates
the buffers for the head level and sublevel trace entries. You can
use IPCS to view a sublevel's entries from one of its buffers or,
with the IPCS MERGE subcommand, to group a sublevel's buffers and
view the grouped entries. any likehead traces.
- When deleting
a trace with CTRACE DELETE, the head level start/stop
routine will get control with the CTSSRNSS bit on, indicating that
as a default, the start/stop routine for any likehead traces will
also run. If you do not want these routines to run, code the head
level start/stop routine to turn the CTSSRNSS bit off.
- When
changing a trace, if the routine receives control indicating
disconnection from an external writer (the CTSSWDIS flag is on), determine
if the application has any more buffers to write. If so, use the
CTRACEWR macro with the SYNCH=YES keyword to write the current buffer
to the external dataset. See Externalizing trace data through the external writer and Using multiple traces for
further information.
- If the routine detects no errors, set
the return code to zero
and perform the requested action to turn on the application's trace
or change options.
- Establish the returned general purpose
registers. See Return specifications for the return specifications.
- Return control to component trace.
When the start/stop
routine receives control to stop tracing for
the application, the routine should do the following:
- Stop
tracing or revert to the minimum level of tracing. If the
application specified MINOPS on CTRACE DEFINE, the tracing should
revert to the minimum level as defined by the application.
- If
the application trace is also connected to an external writer,
then the CTSSWDIS bit will also be on, indicating that the application
must also disconnect from the external writer. Use the CTRACEWR macro
with the SYNCH=YES keyword to write the current buffer to the external
dataset. See Externalizing trace data through the external writer and Using multiple traces for
further
information.
- Set the return code in general purpose register
(GPR) 15. See Return code specifications for the return code
specifications.
- Return control to component trace.
Figure 1 illustrates the interaction
between the application,
its start/stop exit routine, and the operator.
Figure 1. Tracing with Component
Trace.
Interaction between the application, its start/stop
exit routine, and the operator.