Dynamic Trace Customiser (TRCUST) - Reference
OS/2 provides a mechanism by which developers may dynamically apply tracepoints
in their module at run time. This method eliminates all overhead of tracing
when tracing is disabled. It also allows the developer to add tracepoints
without modifying source code. This reduces the possibility that adding
a tracepoint will induce errors into one's code. OS/2 needs a binary file,
for each module being dynamically traced, which defines the tracepoints
for the module.
Note:
Information given here refers to the following versions of the system tracing
tools except where explicitly noted:
TRCUST 3.06 or higher
TRACE 2.4 or higher
TRACEFMT 2.4 or higher
TRSPOOL 4.2 or higher
TRACEGET with OS/2 Warp V3.0 FP35, OS/2 Warp V4.0 FP10 or OS/2 Warp E-Server
or higher
DTRACE 4.3 or higher
TRSPOOL 4.1 or higher
TFFLST 1.1 or higher
TDFLST 1.7 or higher
DEBDEL 1.0 or higher
MAKETSF 1.2 or higher
MAPTSF 1.7 or higher
Note:
There are certain restrictions on the use of dynamic trace which should
be noted. These are:
- Dynamic tracepoints may be applies to any non-VDM
protect-mode module. However, in order to apply tracepoint to non-DLL modules
a version of the trace command shipped with OS/2 Warp V3.0 fix pack 32,
OS/2 Warp V4.0 fix pack 1 or OS/2 Warp E-Server is required.
- Dynamic tracepoints may be applied to routines
that run at interrupt time only after fix pack 35 for OS/2 Warp V3.0, fix
pack 1 of OS/2 Warp V4.0 or OS/2 Warp E-Server.
- A dynamic tracepoint cannot be applied to a module
running under the Kernel Debugger that has a Breakpoint in place at the
same location as the trace point.
The Trace Customizer (TRCUST) converts tracepoint definitions from a trace
source file (TSF) into dynamic tracepoints for the trace definition file
(TDF), and into formatting rules in the trace format file (TFF).
TRCUST provides a high-level access to Dynamic Trace, particularly suitable
for use by developers. The associated DTRACE
tool provides a very low-level interface to Dynamic Trace, which is
suitable for attacking complex problems. Full details of the Dynmaic Trace
facility may be found in The Dynamic
Trace Facility And The DTRACE Tool.
Definitions
TSF
An ASCII file created by a developer which
defines all dynamic tracepoints for a given module. TRCUST allows just one
major code to be associated with a TSF.
.TDF
A
binary file, created by TRCUST, using the .TSF file as input. This
file defines all tracepoints in the module in a manner acceptable to OS/2.
This is used by the Trace Utility, TRACE.
.TFF
A
binary file also created by TRCUST using the .TSF file. This file
defines how all tracepoints will be formatted. This is used by the Trace
Formatter, TRACEFMT.
major code
A
byte value used to identify the module being traced. TRCUST allows at most
only one major code per TSF.
minor code
A
word value used to uniquely identify each tracepoint.
GROUP
A value used to identify this tracepoint with tracepoints
of the same category. Examples are MEM for memory management and PM for
Presentation Manager. For an example of uses of groups, see the online help
for the TRACE command.
TYPE
A
value used to associate a subset of dynamic trace events within a module.
Examples are PRE for pre-invocation, POST for post-invocation and API for
API calls within a module. For an explanation and examples of uses of types,
see the online help for the trace command.
[Back: Trace Event Parameters]
[Next: Overview]