[Next] [Previous] [Top] [Contents] [Index]
Aprobe
This guide is intended to be read by technical staff who have a desire to understand and use Aprobe. Users of Aprobe should be able to write programs in C or Java and run them at the command line.
The motivation and applications for Aprobe are given in separate documents available from OC Systems.
For information on installation and system requirements, see Installation Notes shipped with your software, or as described in the README file on the CD.
First time users should read Chapter 2, "Aprobe Basics", then do the on-line examples described in "Aprobe By Example".
After you've completed these examples, you should understand the basic steps of compiling, running and formatting probes for native (C, C++, or Ada) programs.
If you intend to use Aprobe primarily for native programs, then proceed to Chapter 3, "Writing APC Probes" and look over the rest of this book to get a more complete idea of what Aprobe can do. After that, simply use it as a reference when developing probes.
If you intend to use Aprobe primarily for Java programs, then work through the examples in Chapter 5, "Writing Java Probes", try some on your own application, and contact OC Systems if you have questions.
Aprobe is a sophisticated software tool that supports patching of executables and their supporting libraries. With Aprobe, you can write additions to your executable program and add them in a straightforward manner directly into the executable program just as it starts execution. These additions are called probes.
For compiled applications (C, C++, and Ada), probes are written using the C programming language. They are portions of C code which can be added into the executable under the control of Aprobe without having to recompile any of the original source code. The full ANSI C language is supported, so probes have the full power of both C and the C libraries at their disposal.
For Java applications, probes are also written in Java, as extensions of classes in the package com.ocsystems.aprobe. Because Java probes execute at a "higher" level, and are "straight Java" the are described in their entirety in Chapter 5, "Writing Java Probes".
In addition to being able to add compiled C code into the executable, Aprobe also provides many useful utility routines which allow the probes to do such things as automatically log and format data in a non-invasive manner and to obtain stack tracebacks. Aprobe also provides a preprocessor that makes it easy to reference all of the data and functions within the executable program being patched.
Aprobe allows you to add code (probes) to the executable:
without requiring access to the source code,
without relinking the application, and
without modifying the executable program file.
Aprobe also works on DLLs (Dynamically Linked Libraries) and on third party software for which you may not have source code.
Aprobe comes with some probes which you can use immediately (see "Predefined Probes"). However, the ability to write your own probes in C will prove to be even more valuable than these predefined probes.
Aprobe is best understood by using it on a few examples. Start with the Demo Workspace by selecting Open the Demo Workspace under Initial Options in the Welcome to Aprobe screen. If you're using Aprobe as part of a RootCause installation, you see this by opening Start->Programs->RootCause->Aprobe. If you have any problems with this, please contact OC Systems right away.
The next step is the Example WorkSpaces near the bottom of the File menu. Choose File->Example Workspaces->Simple->Ex01_Subprogram_Probes, and go from there. These step-by-step, C-based examples are designed to illustrate the basics of Aprobe, and you should be able to go through all of them in less than an hour.
From there, try the more advanced features which are discussed in this user's guide and illustrated under Example Workspaces->Advanced. They should help you to apply Aprobe to your own application programs.
Aprobe for Windows 2000 and NT includes a window-based graphical interface that generally eliminates the need to enter commands at the MS-DOS command prompt (which is often described in this manual). You can start this graphical interface right from the Aprobe installation process. After that, use the Start menu: Start->Programs->Aprobe (or Start->Programs->RootCause->Aprobe) provides a menu of actions related to Aprobe. The first one is just Aprobe, which starts the Aprobe window. The Help menu in the Aprobe window describes how to use this visual environment, and gives access to the HTML version of this user's guide as well as other documentation available only on-line.
This user's guide focuses on the development of probes themselves rather than the use of the tools, and refers primarily to the command-line method of invoking Aprobe which is consistent with the Unix platforms on which Aprobe is also available.
You can use this command-line method by selecting Aprobe Command Prompt from the Start->Programs->Aprobe menu, or choosing Command Prompt under the Run menu in the Aprobe window.
All of the examples discussed above in "Aprobe By Example" can be run from the command-line as well. You can point your HTML browser at Aprobe\Examples\Readme.htm and follow from there as you work at the command prompt.