FAQ OS/2 API Trace
Enabler/ Customizer/
Summarizer
Frequently Asked Questions
Q: In as simple terms as possible, how does tracing with OS/2 API Trace
really work?
A: In short, OS/2 API Trace intercepts the OS/2 API calls an application
makes, allowing it to log tracing information both before and after
calling the intended OS/2 API. How this is done is really quite
simple, albeit a little lengthy to describe in "simple" terms.
Every time an executable file makes a call to a procedure external to
itself, such as an OS/2 API, a fixup record is generated by the program
linker that tells the operating system which procedure is required when
the file is loaded at run-time. This fixup record includes information
such as what dynamic link library (DLL) contains the procedure and
which procedure it is, identified by either name or ordinal. Instead
of storing the name of each procedure's DLL within the actual fixup
record, the DLL names are instead stored together in a separate place
within the executable file, the import module name table, and an index
into this table is stored within the fixup record. This is done to
save space, in that a DLL's name is stored once per executable file
instead of once per fixup record.
When tracing is enabled for one of the supported DLLs, OS/2 API Trace
simply goes into the executable file's import module name table and
overwrites the name of the OS/2 DLL being enabled, such as "DOSCALLS",
with the name of the corresponding trace DLL, such as "T_DOS___". When
the executable file is loaded, the program loader redirects all API
calls intended for the OS/2 DLL to the exact same ordinals within the
trace DLL instead because the trace DLL's name now resides within the
import module name table. Each trace DLL mirrors its corresponding
OS/2 DLL ordinal for ordinal. If the ordinal within the OS/2 DLL
represents a published API, the trace DLL contains a matching trace API
(with identical parameter list) that logs API entry information, calls
the OS/2 API, and logs API exit information. If the ordinal within the
OS/2 DLL represents an unpublished (private) API, the trace DLL passes
the call directly to the OS/2 DLL through use of a forwarder entry.
When tracing is disabled for one of the supported DLLs, OS/2 API Trace
simply undoes what was done during enablement. That is, it goes into
the executable file's import module name table and overwrites the name
of the trace DLL being disabled, such as "T_DOS___", with the name of
the corresponding OS/2 DLL, such as "DOSCALLS". When complete, the
executable file is restored to its original state and all OS/2 API
calls go directly to the OS/2 DLL.
Q: How easy is it for a non-technical person to trace an application with
OS/2 API Trace?
A: It is really quite easy to trace an application with OS/2 API Trace as
long as one doesn't get overwhelmed by the number of options the
utility provides. Keep in mind that OS/2 API Trace provides three
unique functions: trace enablement/disablement, trace customization,
and trace summarization. Trace enablement/disablement turns on/off
tracing of an application, trace customization sets the types of trace
information generated by the application, and trace summarization
totals the APIs in the trace information generated by the application.
As an example, follow the simple scenario below to trace an executable
present on every OS/2 system, CMD.EXE.
Begin by opening an OS/2 window or full screen session and entering the
following commands:
md \cmdtrace
cd \cmdtrace
copy x:\os2\cmd.exe
where x is the drive on which OS/2 is installed. These commands create
a temporary copy of CMD.EXE to work on so as not to interfere with the
original copy in the \OS2 directory. A temporary copy is not really
necessary, but will avoid duplicate trace files being created in the
event that some other process uses CMD.EXE while running this scenario.
Start the tracing process by customizing OS/2 API Trace so as to get as
much trace information as possible:
os2trace -b all -d all -f all -g all -i on -l 3 -t on -w all
After the program banner, the utility displays the former options as
well as these new options. OS/2 API Trace remembers the states of
these customization options and uses them for all future traces until
they are changed by some subsequent customization commands.
Continue the tracing process by trace-enabling CMD.EXE:
os2trace -on -all cmd.exe
After the program banner, the utility displays which DLLs were and were
not enabled for tracing. Note that in this case CMD.EXE only imports
APIs from DOSCALLS.
At this point, CMD is ready to be traced. Go ahead and execute it by
entering the following command:
cmd
Enter as few or as many commands in this new command shell as desired;
when complete, terminate the shell by entering the following command:
exit
Complete the tracing process by trace-disabling CMD.EXE so that any
future invocations of CMD.EXE do not produce additional tracing
information which overwrites CMD.TRC:
os2trace -off -all cmd.exe
After the program banner, the utility displays which DLLs were and were
not disabled for tracing.
NOTE: The TRACE-IT batch file incorporates all of the above OS2TRACE
commands and invokes the executable, so the following works just as
well:
trace-it cmd
Now go ahead and edit CMD.TRC, which contains entry and exit
information for every API used by CMD.EXE while it was executing. For
instance, note how every keystroke is read in by Kbd16CharIn and
echoed to the display by Vio16WrtTTY, using the editor's find/search
capabilities to locate these APIs within the trace information file.
Optionally extend the tracing process by summarizing the APIs used by
CMD.EXE:
os2trace -s cmd.trc
After the program banner, the utility displays an alphabetical list of
the APIs used and how many times each was invoked successfully and
unsuccessfully.
Finish by entering the following commands:
del cmd.*
cd \
rd \cmdtrace
to remove the temporary files and directory.
Q: Why won't OS/2 API Trace enable tracing of a DLL that has an API
imported by name?
A: The program linker will not allow an executable file to export a
procedure that physically resides within the file AND import a
procedure with the same name from another executable file. Because
the trace DLLs import a majority of the OS/2 APIs they trace and
because they are unable to export procedures with the same names, all
trace APIs must be named differently from the OS/2 APIs they trace. If
an executable file imports an OS/2 API by name and the DLL containing
the API were enabled for tracing, a procedure-not-found error would be
generated by the program loader when attempting to load the file
because the OS/2 API name does not (and cannot) exist within the trace
DLL. To avoid this scenario altogether, OS/2 API Trace will not enable
tracing of a DLL referenced by an executable file through an
import-by-name fixup record.
Q: Why does the date and time stamp of an executable file change when
tracing is enabled or disabled?
A: An executable file's date and time stamp changes whenever a supported
DLL is enabled or disabled for tracing because the file's import module
name table is updated and the changes written to disk. Nothing else
within the executable file is affected by OS/2 API Trace.
Q: Can DLLs be traced through OS/2 API Trace?
A: Yes, OS/2 API Trace will work on any segmented (16-bit, NE format) or
linear (32-bit, LX format) executable file, such as .EXE files and .DLL
files. Any trace information generated by a DLL, however, cannot be
stored in a trace information file named after the .DLL file because
DLLs can be shared by more than one process. As a result, all trace
information generated by a DLL is stored in a trace information file
named after the .EXE file. For example, if A.EXE imports from B.DLL
and B.DLL is trace-enabled, the trace information from B.DLL is logged
to A.TRC when A.EXE is executed.
There is no limit to the number of DLLs that can be traced at once, but
trace information from all DLLs is logged to a single trace information
file named after the .EXE file that directly or indirectly loaded the
DLLs.
Q: Can 16-bit APIs be traced with OS/2 API Trace?
A: Yes, all the 16-bit APIs present in the Base subsystem (Dos, Kbd, Mou,
and Vio APIs) and Presentation Manager subsystem (Dev, Drg, Gpi, Pic,
Prf, Prt, Spl, and Win APIs) are supported as of version 2.40.34. See
OS2TRACE.API for a table containing all supported APIs.
Q: Can APIs loaded by the application at run-time through Dos16GetProcAddr
or Dos32QueryProcAddr be traced with OS/2 API Trace?
A: Yes, OS2TRACE's -I option and PMOS2TRC's "API interception" item on
the
"Customize" submenu enable interception and tracing of these APIs, also
known as dynamically loaded APIs. This functionality is available as
of version 2.40.36.
Q: What needs to be done to trace all APIs of a specific type, such as Dos
APIs or Win APIs?
A: Use the following table to determine which DLL or DLLs to enable for
tracing in order to trace all APIs of a specific API type:
Note that some DLLs contain more than one API type, such as HELPMGR and
PMSPL, so there may be some overlap of API types involved when enabling
one of these DLLs for tracing.
Q: Where are all those APIs in the trace information file coming from that
aren't part of the application's source code?
A: The C run-time. Remember that OS/2 API Trace intercepts every OS/2 API
call made by an application being traced, and the C run-time requires
OS/2 APIs to function properly under OS/2. For instance, the run-time
needs DosWrite in order to implement fprintf.
Q: Can network APIs be traced with OS/2 API Trace?
A: No, OS/2 API Trace only covers APIs included in the basic operating
system, which includes the Base, Presentation Manager, and Workplace
Shell subsystems. Operating system extensions such as Multimedia,
TCP/IP, and Network are not supported. See OS2TRACE.API for a table
containing all supported APIs.
Q: Are there any special steps should be taken to trace an application
over a long period of time, such as hours or even days?
A: Outside of a minimal performance impact, OS/2 API Trace does not hinder
the functionality of any APIs being traced, so no unusual steps are
required to trace an application over a long period of time. However,
a couple of customization options are provided that may be beneficial
when tracing over large periods of time.
The first such option is time stamping, which is specified through the
-T option (OS2TRACE) or Customization menu (PMOS2TRC). When time
stamping is enabled, all API entries and exits are marked with the time
they occurred accurate to a hundredth of a second. Time stamping can
be quite useful to record when exactly APIs were called while logging
several hours of trace information.
The second option is file wrapping, which is specified through the -F
option (OS2TRACE) or Customization menu (PMOS2TRC). When file wrapping
is enabled, only a certain amount of trace information is logged before
the trace information file is overwritten starting from the beginning.
File wrapping can be quite useful to set an initial limit to the trace
information file size, because, depending on the level of trace
information requested and the number of APIs being traced, OS/2 API
Trace can generate megabytes upon megabytes of information rather
quickly.
Q: It is documented that OS/2 API Trace can trace APIs from the latest
version of OS/2. Does this mean that it cannot work on earlier
versions of OS/2 because the latest APIs were not yet present on them?
A: OS/2 API Trace will work on ALL versions of 32-bit OS/2, or OS/2 2.x.
This is possible because the trace DLLs dynamically load all APIs added
to OS/2 after version 2.00 through use of the DosQueryProcAddr API.
Only APIs supported by OS/2 2.00 are actually imported by the trace
DLLs.
Q: Will OS/2 API Trace work on 16-bit versions of OS/2?
A: No, all executable files that comprise OS/2 API Trace are of the linear
(32-bit, LX) executable file format, which is unknown to all versions
of 16-bit OS/2, or OS/2 1.x. The 16-bit APIs that OS/2 API Trace
supports can only be traced under OS/2 2.x.
Q: When under disk space constraints, can only the trace DLLs needed be
placed on the system where the tracing will take place?
A: Yes, the only trace DLLs that are required in order for tracing to take
place are T_COMMON.DLL and whatever trace DLLs have been enabled for
tracing. The only exception to this rule is that if DOSCALLS has been
enabled for tracing, T_KBD___.DLL, T_M.DLL, T_MOU___.DLL, T_N.DLL,
T_PIP___.DLL, T_QUE___.DLL, T_SES_.DLL, and T_VIO___.DLL are all
required in addition to T_DOS___.DLL because T_DOS___ imports trace
APIs from these other trace DLLs. The following table shows all of the
supported OS/2 DLLs and their corresponding trace DLLs:
Q: Can only the files needed be replaced when updating to a later version
of OS/2 API Trace?
A: It is not recommended, as OS/2 API Trace may (and usually will) change
internally from release to release. Make sure that all the files that
comprise OS/2 API Trace have the same date and time stamps before
attempting to use the utility.
The sizes and date and time stamps of all the files that comprise the
latest release, Version 2.40.55, are shown in the following table:
Q: Why do some 16-bit applications trap or behave differently when being
traced?
A: Traps and/or different behavior when tracing 16-bit applications is
usually a sign of stack overwriting and/or stack overflow. The problem
stems from the fact that stacks for all 16-bit threads must be provided
by the programmer, which often leads to stacks that are surrounded by
data variables and/or stacks that do not have the recommended amount of
space available (4KB) when calling into an OS/2 API. This problem does
not usually occur in the case of 32-bit threads because the programmer
need only provide a stack size, resulting in a separate object for the
stack being allocated by the operating system. Regardless, tracing
does require additional stack space over and above what is required
normally, as shown in the following table:
API | Additional Stack Space Requirement (in bytes)
-------+---------------------------------------------------------------
16-bit | 122 + ( 2 * sizeof( parameters ) )
32-bit | sizeof( parameters )
This slight overhead can easily lead to traps or different behavior.
If these symptoms occur when tracing your own application, increase the
stack size for all of your threads and try again.
Q: What is summarization good for?
A: Summarizing a trace information file produces an alphabetical listing
of all the APIs called by an application and how many times each API
was successfully and unsuccessfully called. This information can be
quite useful in determining where erroneous API calls can be removed
or repaired and where performance enhancements can be made.
Q: Why are there so many failures logged when tracing certain APIs, such
as WinDefWindowProc, when the application clearly works?
A: Some Presentation Manager APIs return identical values with different
meanings based solely on the input parameters. This is most evident in
APIs dealing with messages, where some messages will return zero to
indicate success while others will return zero to indicate failure.
Instead of going through rather lengthy logic to determine whether a
return value indicates success or failure for this small group of APIs,
OS/2 API Trace assumes that zero indicates failure and non-zero
indicates success.
NOTE: As of version 2.40.45, OS/2 API Trace considers the following
APIs' return codes to be indeterminate (neither successful nor
unsuccessful):