The UDS Control trace facility (TRCCTL) lets you monitor performance and diagnose suspected problems as threads are executing in UDS. This facility has two parts: an interactive program called TRCCTL and a UDS Control component that reacts to TRCCTL commands. This section explains how to use the TRCCTL facility. UDS Control also provides performance monitoring through the TeamQuest Transaction
Performance Auditing System (TeamQuest TPAS) with UDSC-TPAS.
7.1.
Trace Control Functions
Of the two trace control functions, monitoring performance and diagnosing problems, you probably have more need for the first, which you can use to gather statistics on performance.
To monitor performance, you can use TRCCTL options to turn on the statistics- gathering component, and you can collect two types of information:
• Counters that give details on the execution path of one thread (local statistics)
• Counters that represent a current snapshot of global system information (global statistics)
To diagnose problems, you can trace suspected errors in the execution path of a specific user program. TRCCTL options allow you to turn a trace on or off, to specify which components to trace, and to choose a trace level. TRCCTL writes the results to a trace file. You can process all or part of the trace file, and print or display the output for analysis.
Monitoring Performance and Diagnosing Problems
7.2.
Calling the Trace Control Program (TRCCTL)
The trace control program, TRCCTL, is in an absolute file on the UDS Control release tape.
To execute TRCCTL and display the options menu , enter
@xqt appl-qual*abs$.trcctl
or
@xqt uds$$src*abs$.trcctl
If your system is configured with Security Option 3 Controlled Access Protection, you must have privileges to use the UTILITY UDS command before you can execute TRCCTL commands.
Your user-id must also have the proper security attributes to access the UDS Control ABS$ file. If Security Option 3 is configured on your system, the security attributes of your user-id must match the security attributes of the UDS secure subsystem to enable TRCCTL to function. This is necessary because TRCCTL accesses the UDS Control subsystem to turn trace on and off.
For more information about Security Option 3, see Section 9. For more information about setting up the necessary security attributes for your system, see the
Repository for ClearPath OS 2200 Programming Reference Manual.
7.3.
TRCCTL Options
When the TRCCTL program starts, it displays four options:
OPTIONS:
1 Turn on trace to create raw trace file. 2 Turn off trace.
3 Process and print raw trace file. 4 Stop.
Please choose a number:
TRCCTL can perform only one function at a time. If you select more than one option, press the XMIT key after choosing each option.
While trace is active, you can update the components being traced as well as the level of trace. Setting a level of trace to 0 for any component turns off that component.
The size of the trace file is important. If a trace produces too much data for the specified file size, the trace wraps around to the beginning of the trace file,
overwriting the early part of the trace. The trace continues in this circular manner until you turn it off.
Monitoring Performance and Diagnosing Problems
Option 1
Option 1 turns on the trace, taking one of four paths:
• If TRCCTL does not know the name of the application group you want to trace, it solicits the name.
• If the application group you want to trace is not active, the TRCCTL program ends immediately and you must restart it.
• If the application group is active but TRCCTL does not know the name of the file in which trace is active, it solicits the name of the trace file and its size. TRCCTL then catalogs the trace file and assigns it.
• If the application group is active and TRCCTL knows the name of the file in which trace is active, it displays the name of the trace file and a list of the components that are turned on and their levels.
TRCCTL now solicits the names of the components you want to trace. Component names are shown in Table 7–1. If you specify a UDS component (or ALL), you must also specify a trace level. Trace levels are described in Table 7–2. TRCCTL stops asking for component names when you transmit a blank line. The trace is then active and stays active until you enter option 2.
If you need to increase the size of the trace file, specify option 2 first (if this is your first TRCCTL execution). If you do not specify option 2 first, TRCCTL does not solicit you for the new file name and size.
Option 2
Option 2 ends the trace. To prevent you from accidentally turning off the trace of another user, TRCCTL displays the name of the active trace file. At this point, you can either turn off the active trace or return to the options menu, leaving the trace on.
Option 3
Option 3 lets you process all or part of the trace file to an output file that you can print or display. First, TRCCTL solicits the name of the trace file. You can specify any trace file, as long as it is still cataloged on the system. Next, TRCCTL solicits the name of your output file. If this file is not already cataloged, TRCCTL catalogs and assigns it.
Last, TRCCTL solicits any search constraints, which are described in Table 7–3. They determine how much of the trace file TRCCTL writes to the output file. For example, if you asked TRCCTL to trace four UDS components for option 1 but want only the trace information for the locking subsystem, you can specify this as a search constraint. In this case, the output file would contain only the trace information for the locking subsystem. Trace information for all components traced remains in the trace file.
If TRCCTL is terminated abnormally (for example, by @@X T) while printing the UDS trace file, the run printing the trace must terminate (@FIN) or it must direct the output to the file you designated (@BRKPT output-file).
Monitoring Performance and Diagnosing Problems
7.4.
Trace Components
Table 7–1 lists the components you can trace through TRCCTL.
Table 7–1. TRCCTL Trace Components
Component Definition
ALL All UDS components, statistics, and immediate I/O
CAM Cache manager
DMR Data Management Routine
This is the DMS online management routine that accesses and updates the DMS database. See “7.9 DMR Trace” for more information. IMM Immediate (not an actual component). Specifies that every trace action
during the trace causes an immediate I/O.
This option is recommended when using the trace facility to locate a problem. When collecting statistics, however, using this component is not recommended because of the high processing overhead.
IRU Integrated Recovery Utility
LINK TCS table linking
LSS Locking subsystem
PCI SFS
QAD Queuing and deadlock detection
RDM Relational data manager
RSA Relational Syntax Analyzer (requires a trace level of 3 or greater) Data entries contain selected RSA debug information important for coordinating UDS trace information. Information in the trace file is primarily represented as octal and does not include any formatted output.
See the Relational Database Server for Clear Path OS2200 SQL
Programming Reference Manual (7830 8160) for the DEBUG DUMP
statements required to enable the inclusion of debug information in the UDS trace file.
RSM Relational storage manager
SQL Database modification SQL statements
STAT Statistics (requires a trace level of 1 or greater)
STAT is not useful for tracing SFS threads because SFS does not currently accumulate statistics.
TCL Thread control
TCS Table control system