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:
Specifying
parmlib on CTRACE DEFINE: When you specify a parmlib
member
on CTRACE DEFINE, the system uses the tracing options specified in
that parmlib member. If that parmlib member contains instructions
to turn the trace on, then the system passes control to the application's
start/stop exit routine without operator intervention. If you update
the parmlib member, you change the tracing options used when the application
subsequently issues CTRACE DEFINE with that same parmlib member.
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
A
parmlib member you specify on CTRACE DEFINE can contain information
about only a single trace. If you are defining multiple traces, include
in each parmlib member options that pertain only to the specific head
level or sublevel trace. The following topic explains head level and
sublevel traces.
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.
Figure 1. Structure
of Multiple Traces for an Application
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).
Figure 2 lists
the characteristics, options, and status
associated with a trace. If an application defines a sublevel trace
to match its head level, LIKEHEAD, any changes to the head level options
and status are reflected in the sublevel trace.
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.
Figure 2. Trace FeaturesAttributes (parameters
on CTRACE macro)
- ASIDS=YES/NO
- JOBS=YES/NO
- MINOPS
- MOD=YES/NO
- BUFFER=YES/NO
- BUFMIN
- BUFMAX
- BUFDFLT
- BUFDEFIN=YES/NO
- WTR=YES/NO
Characteristics (parameters
on CTRACE macro)
- STARTNAM
- FMTTAB
- HEAD=YES/NO
- LIKEHEAD=YES/NO
- MANYSUBS=YES/NO
Options (parameters
on TRACE CT operator
command or in a parmlib member)
- ASID
- JOBNAME
- OPTIONS
- BUFSIZE
- WTR
Status (parameters
on TRACE CT operator command
or in a parmlib member)
Note: When you specify attributes and characteristics on
CTRACE DEFINE, these features do not change. When you specify options
and status through the TRACE CT operator command or in a parmlib member,
you can change these features dynamically.
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.
Figure 3. Structure of
Multiple Traces for an Application
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:
- 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.
- 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.
- 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.
- APPLABC defines
FUNCTION7 in the same way as FUNCTION5.
- 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).
- 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.
Figure 4. Setting up Multiple Traces with
CTRACE
DEFINE
Using the component trace external writer: To define
your application to component trace to support an external writer,
issue CTRACE DEFINE with the WTR=YES and WTRMODE parameters. The WTR=YES
parameter indicates the application supports having its trace buffers
written to trace data sets on DASD or tape. The WTRMODE parameter
specifies the type of storage your application is using for its trace
buffers. The WTRMODE values are PAGEABLE, DREF, or FIXED.
Note: IBM recommends
you keep your trace buffers in pageable storage, so you do not deplete
your system's central storage. However, if your application cannot
accept page faults, you should use either disabled reference (DREF)
or fixed storage.