OS/2 API Trace Introduction

by Dave Blaschke (October 25, 2010)

OS/2 API Trace allows you to trace the 16-bit and 32-bit OS/2 APIs used by any application running on any 32-bit version of OS/2 (2.0 or later) without requiring the application's source code or requiring the application to be recompiled/relinked. Simply enable the application for tracing and run it, and the OS/2 API calls (and optionally their parameters) made by the application are logged to a text file that is already formatted and in English. OS/2 API Trace also allows tracing to be customized, controlled, and summarized.

Want to learn more about OS/2 API Trace? Want to learn how to use OS/2 API Trace? Want to download OS/2 API Trace? Want to contact the author of OS/2 API Trace? Heard enough about OS/2 API Trace?

More About OS/2 API Trace

So you want to learn more about OS/2 API Trace. Choose as many of the following questions that suit your interest:

Who can use OS/2 API Trace? What is OS/2 API Trace? Where can you get OS/2 API Trace? When is OS/2 API Trace updated? Why should you use OS/2 API Trace? How does OS/2 API Trace work? Now you know more about OS/2 API Trace, back to introduction

Who can use OS/2 API Trace?

Anybody can use OS/2 API Trace, as the only requirement is a basic working knowledge of OS/2. Although OS/2 API Trace will benefit application developers and debuggers the most, it was designed so that even the beginner can utilize it to start comprehending how OS/2 APIs are used as the building blocks of applications running under OS/2.

As far as system requirements are concerned, anyone with a 32-bit version of OS/2 (OS/2 2.0 or later) and 2.08MB of available DASD can use OS/2 API Trace.

What is OS/2 API Trace?

OS/2 API Trace is a freeware application written by an IBM software engineer with extensive experience in OS/2 kernel and Presentation Manager development. Although originally designed to be a run-time utility that determined the actual API coverage of test programs, it has evolved into a comprehensive and robust tracing application that supports 1989 OS/2 APIs and consists of over 108,000 lines of C and assembly code. This evolution came about in part because the author was unhappy with the complexity of the system trace utility provided with OS/2 and its inherent limitations, especially with regards to dumping structures. OS/2 API Trace can trace 16-bit, 32-bit, and mixed 16/32-bit applications, multi-threaded applications, and applications comprised of an .EXE or .COM, one or more .DLLs, and an .EXE or .COM and one or more .DLLs.

The OS/2 API Trace package consists of several executable files, including a command line interface (OS2TRACE.EXE) and a graphical interface (PMOS2TRC.EXE) for enabling/customizing/summarizing tracing, a command line program (CHK4TRC.EXE) that checks for and reports the executable file(s) that are trace-enabled, a command line program (STRIPAPI.EXE) that strips API entries/exits from a trace information file, and many trace DLLs (T_*.DLL). The package also includes several text files that contain helping information such as how to use OS/2 API Trace, the list of OS/2 APIs that are supported, answers to frequently asked questions, and a source code example of a user hook DLL.

Where can you get OS/2 API Trace?

In addition to this DevCon site, OS/2 API Trace is available on several places over the internet, including but not limited to:

   Dave Blaschke's Website on Angelfire
   Hobbes OS/2 Archive
   OS/2 Shareware BBS Website (Subscription required)

Internal to IBM, OS/2 API Trace is available from this intranet site.

When is OS/2 API Trace updated?

OS/2 API Trace is updated whenever the need arises, and changes generally encompass bug fixes, enhancements, and user-requested additions. To make it easier to keep track of the updates, the revision portion of the version number is incremented whenever a change is made, while the major and minor portions of the version number reflect the major and minor version of OS/2 currently supported by OS/2 API Trace. A complete history of OS/2 API Trace changes can be found in the text file OS2TRACE.NWS.

While the author maintains OS/2 API Trace on his own personal time, most changes are turned around in five working days or less, although this is, of course, not a guarantee.

Why should you use OS/2 API Trace?

OS/2 API Trace best serves any of the following purposes:

Debugging

OS/2 API Trace is great for debugging applications which have OS/2 APIs that are failing or APIs that just don't seem to be behaving the way you think they should. It can save you the trouble of running the application under a debugger or inserting a bunch of printf calls to see what's going on. The trace information file generated by OS/2 API Trace contains all of the APIs' return codes and even denotes which passed and which failed. The file can optionally contain the parameters passed in to and out of the APIs as well so that you can make sure that you are indeed invoking the API correctly.

Reverse Engineering

Want to see how a working application accomplishes something using OS/2 APIs? OS/2 API Trace can capture every single API call an application makes, including those made by the C run-time, those made from within a DLL, or those called dynamically through DosLoadModule and DosQueryProcAddr. By analyzing the trace information file generated by OS/2 API Trace, you can easily follow the application's logic and even see how some of the more difficult tasks are accomplished using OS/2 APIs.

Analyzing Performance

OS/2 API Trace automatically logs the entry and exit times of those OS/2 APIs that are most apt to block, such as DosSleep and DosWaitEventSem. It also has the optional capability of time stamping all API entries and exits. By examining the trace information file generated by OS/2 API Trace, you can determine where an application spends most of its time executing and where it spends most of its time waiting, and subsequently where you could improve performance.

Analyzing API Coverage

OS/2 API Trace can summarize the trace information file it generates, producing an alphabetical list of each and every OS/2 API called by the application and how many times each passed, failed, or did not return. These statistics are great for reporting the API coverage of test applications.

Altering Execution

OS/2 API Trace supports a user-provided procedure, also known as a user hook, that is called under various circumstances such as API entry and exit. Through use of this functionality you can easily examine or even modify information passed to or returned from any API being traced. This makes the user hook a very powerful tool at your disposal.