Exit routine processing

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.
ieaa8tra
Parent topic: Coding a start/stop exit routine