OS/2 Trace Tools

How to use the TraceCtl package 2022-08-28 SHL The TraceCtl package includes a script (TraceCtl.cmd) that implements an interface to the OS/2 Trace Facility. This script is designed to make it easier to configure the Trace Facility to capture the trace data needed to analyze an issue. The script is generic. The tracepoints and settings needed to capture specific data are defined in a configuration file. The configuration file name is passed on the TraceCtl command line. If you do not supply a configuration file name and the command line TraceCtl will look for a file named tracectl.cfg. You need to have a working OS/2 trace setup to use the TraceCtl script. If you don't have a working OS/2 trace setup, see: http://www.warpcave.com/os2diags/IBM-OS2-Trace.ref. for a cookbook setup guide. IBM-OS2-Trace.ref explains how to get the OS/2 Trace Facility ready to use on your system. It also includes a sample script for those that want to write their own scripts. The sample script is exactly that - a sample. It is unlikely to capture data relevant to your particular problem. Once you have the trace facility working, place TraceCtl.cmd and the trace configuration file in a convenient directory. This will often be the application home directory. If you are working on an application startup problem, shut down the application before running TraceCtl. Run TraceCtl from the command line supplying the name of the trace configuration file. TraceCtl will initialize the Trace Facility, enable the selected tracepoints and display a menu that provides one-key access to the most used trace functions. If your application is not running, start it now. Perform whatever actions are needed to trigger the problem you are analyzing. Switch to the Trace Formatter window and request File -> Recapture from the menu. The Trace Formatter will read the captured trace data from memory and display it in the formatter window. The formatted trace data display is in reverse time order, so you usually need to read the window from the bottom up. The trace buffer is fixed size and new data overwrites old data. Request the recapture as soon as possible after the problem occurs or you may lose the data you need to see. When the issue requires you to capture a large amount of data, you can configure a larger buffer. To write the formatted data to a file, use File -> Save Formatted menu option. When you are done with the trace, switch back to the TraceCtl session window and enter q to shut down TraceCtl and the Trace Facility. TraceCtl will turn off all tracepoints and reset the Trace Facility to a disabled state. If you are not a developer, you will usually be supplied with a pre-configured configuration file, but for the curious and those that need to know , here is an overview of the configuration file layout. A configuration file typically contains a combination of configuration commands, comments and blank lines. Comment lines begin with a semicolon (i.e. ;). Blank lines are ignored. Each configuration command must be on a single line. Command are of the form: keyword = value Command keywords and values are case-insensitive. Some commands take yes/no values. Yes/no values such as Y, Yes, 1, N, No and 0 are accepted. The configuration command keywords and their value styles are: keyword value style default ------- ----------- ------- CMD = trace command none OPTIONS = trace options none DIEONERROR = yes/no yes EXE = executable name none FINDPID = yes/no no PID = hex or decimal PID none All configuration commands are optional, although a typical configuration file will have an EXE command and one or more CMD commands. A simple example would be: exe = trace cmd = trace on os2krnlr(fs) The CMD keyword defines a trace command. Typically, the command value will be a trace command to set specific tracepoints, as shown in the example. The command value is passed to the shell for execution, so the command can be any valid shell command. To define multiple trace commands, provide multiple CMD configuration commands. The commands will be executed in the order they appear in the configuration file. The OPTIONS keyword allows the default values for buffer size, mode and optional data to be overridden. The mode and optional data values can be overridden with the CMD configuration command, but the trace facility does not report accurate return codes when the working with the buffer size and this will cause the CMD configuration commands to fail because only zero return codes are expected. The OPTIONS configuration command avoids this by providing special handling the spurious return codes. For example options /b:1024 will initialize the buffer size to 1MB. options /d:tsc can be used to include the timestamp in the trace data, but cmd trace off /d:all cmd trace on /d:tsc is better because it is less sensitive to the existing optional data settings. The DIEONERROR configuration command defines how certain errors are handled. If the command value is set to no, TraceCtl will continue if an executable or PID can not be found or if a CMD command fails. The default action is to quit. The EXE configuration command value specifies an executable to be traced. TraceCtl will search the PATH for the executable and will report if the executable can not be found. To trace multiple EXEs, supply multiple EXE commands. If there are no EXE or PID commands, all executables will be traced. The FINDPID configuration command controls PID lookup. If the command value is yes, TraceCtl looks up the PID for the executable(s) named by the EXE command(s). If the executable is not running, TraceCtl will report the error and quit. The default action is to bypass PID lookup. The PID configuration command specifies the process ID of a process to be traced. TraceCtl will search the process list and report the name of the executable corresponding to the PID. If the search fails, TraceCtl will report the error and quit. To trace multiple PIDs, supply multiple PID commands. The PID command may not be used with the EXE command unless PID lookup is enabled with the FINDPID command. If the hex PID contains only decimal digits, prefix it with 0x to avoid ambiguity. Prerequisites ============ The TraceCtl script requires that the O/2 Trace Facility be installed and that the installed TDF and TFF files match the booted kernel and the applications to be traced. The TraceCtl script requires RexxUtil.dll. This should be available on any installed OS/2 system. The TraceCtl script requires the RxUtilEx.dll. This should be available on any ArcaOS or eComStation system. If you need to install a copy check https://trac.netlabs.org/rexxlibs/ for a recent version of Alex Taylor's REXX Utility Functions - Extended Package. WARNING ======= As of 2004-09-08, it is known that krnlrfs tracepoints 281 and 282, which are in the QUE group, will trap with kernels between 14.93c and 14.100c. This may not be a complete list. This means, do not specify: trace on krnlrfs or trace on krnlfs(que) Specify explicit tracepoints or groups that do not include the above trace points and group. For example: trace on krnlrfs(fs) is OK. Good luck, Steven