Using the CTRACE macro to define the application to component trace

To use component trace, you must first define the application to component trace by issuing the CTRACE macro with the DEFINE parameter (CTRACE DEFINE). CTRACE DEFINE defines the application as being available for activities such as starting and stopping a trace, displaying trace information, and formatting trace data. Through parameters on CTRACE DEFINE, you specify information about the application, such as:

• The application name (NAME parameter). The operator uses this name on the TRACE CT command (COMP parameter). When formatting trace data with IPCS, use this name on the IPCS CTRACE subcommand (COMP parameter). The application name is required.
  Note: Do not use names that begin with the prefix SYS. The prefix SYS is reserved for use by IBM®.
• A parmlib member name (PARM parameter). Identifying a parmlib member establishes the initial tracing options for an application. These options can be overridden by operator commands. This parameter is optional. (See Using parmlib members for more information.)
• A head level (HEAD parameter) and a sublevel trace name (SUB parameter). These parameters are related to multiple traces. (See Using multiple traces for more information).
• The load module that contains the CTRACE format table (FMTTAB parameter), which controls trace formatting in the IPCS CTRACE subcommand.
• The name of the start/stop exit routine (STARTNAM parameter). The system gives this routine control when the operator enters a TRACE CT command or when you specify the PARM parameter on CTRACE DEFINE.
• The name of the display trace exit routine (DISPNAM parameter). The system gives this routine control when the operator enters a DISPLAY TRACE command.
• A list of default, user-defined tracing options (MINOPS parameter). If you specify MINOPS, tracing with these options will be in effect at all times and cannot be turned off.
• An indication that the application supports an external writer (WTR and WTRMODE parameters).

Here is an example of how you might specify a parmlib member for application ABC on CTRACE DEFINE:

CTRACE DEFINE,NAME=ABC,PARM=CTXABC01...

The parmlib member CTXABC01 might contain the following to turn tracing on for address space 01 with specific options:

TRACEOPTS
ON
ASID(01)
OPTIONS('original options')

The CTXABC01 parmlib member takes the place of the following operator commands:

TRACE CT,ON,COMP=ABC
REPLY xx,ASID=(01),OPTIONS=('original options'),END

Using multiple traces: To use multiple traces, you must create a head level and sublevel traces. A head level is a control level with sublevel traces associated with it. Figure 1 uses an inverted tree structure to depict the relationship of a head level and sublevel traces for application APPLABC.

Creating a head level: A head level is a control level set up to support sublevel traces, and can itself be a trace. Create a head level by specifying HEAD=YES on CTRACE DEFINE. If you want sublevel traces to be able to share the attributes, options, and mode of the head level, specify both of the following:

• HEADOPTS=YES on CTRACE DEFINE when you create the head level
• LIKEHEAD=YES on CTRACE DEFINE when you create the sublevel traces.

Creating sublevel traces: Create a sublevel trace by specifying SUB=subname on CTRACE DEFINE. Obtain separate trace buffers for each sublevel trace. You can define sublevel traces as either:

• Independent traces with unique tracing features (LIKEHEAD=NO on CTRACE DEFINE)
• Traces that use a head level's attributes, options and mode (LIKEHEAD=YES on CTRACE DEFINE).

Turning a sublevel trace on or off or changing its options cancels its LIKEHEAD status. A status of LIKEHEAD simply means that the sublevel trace has the same status and options as its head level. When a sublevel trace has its LIKEHEAD status cancelled, subsequent changes to its head level do not affect the sublevel trace except when the head level is turned off. When a head level trace is turned off, sublevel traces that were defined with LIKEHEAD=YES on the CTRACE DEFINE macro will also be turned off, regardless of their LIKEHEAD status.

A sublevel trace can also serve as a head level. Specify HEAD=YES and SUB=subname to define a sublevel that is also a head level. In this case, all of the sublevel and head level attributes, options, and status apply to the subsequent sublevels if they are likehead. In Figure 3, ASID(01) is a sublevel trace of APPLABC, and a head level for FUNCTION5 and FUNCTION7. FUNCTION5 and FUNCTION7 use the attributes, options and status of both ASID(01) and APPLABC. The inverted tree structure illustrates how an application named APPLABC supports separate traces for each user, and has multiple functions in use in the same address space. In addition, the same function (FUNCTION5) is active in two address spaces. A description of the steps in defining the tree structure follows:

1. During initialization, APPLABC issues CTRACE DEFINE and specifies APPLABC as the head level (by specifying HEAD=YES and NAME=APPLABC on CTRACE DEFINE). APPLABC also specifies HEADOPTS=YES to allow its sublevel traces to share its attributes, options, and status.
2. The first time APPLABC gets control in address space ASID(01), APPLABC issues CTRACE DEFINE for sublevel ASID(01), with LIKEHEAD=YES and HEAD=YES. Now, ASID(01) is established as a sublevel trace with the same tracing attributes, options, and status as its head level, APPLABC, and ASID(01) is also established as a head level.
3. APPLABC issues another CTRACE DEFINE for sublevel trace FUNCTION5, with LIKEHEAD=YES. Now FUNCTION5 is established as a sublevel trace, and uses all the attributes, options, and status from its head level, ASID(01), and ASID(01)'s head level, APPLABC.
4. APPLABC defines FUNCTION7 in the same way as FUNCTION5.
5. When APPLABC gets control in address space ASID(02), APPLABC issues CTRACE DEFINE to establish itself as a head level, and again to establish ASID(02) as a sublevel trace with the same parameters as ASID(01).
6. APPLABC establishes FUNCTION5 and FUNCTION6 as sublevel traces. Even though FUNCTION5 is also in ASID(01), FUNCTION5 can have unique tracing features in ASID(02) by specifying LIKEHEAD=NO (or taking the default).

Figure 4 illustrates how you would issue CTRACE DEFINE to set up the multiple traces for APPLABC.