The Aprobe Workspace

Each workspace is represented on disk by an Aprobe workspace file, with a suffix of .apw. Each workspace is for probing a single executable program. When you create a workspace, you designate the path to the executable.

Starting With a New Workspace

You create a new Workspace with the New File dialog. You get to this from the "New..." entry on the Aprobe main window. Also, when you start Aprobe, you are presented with a dialog that offers you the choice: "Start with a New Workspace". Selecting this will take you to the New File dialog as well.

In the New File dialog, select "Workspace" from the the New File Type pane on the left side. Then give the full pathname to the application's executable file under "Executable:" in the right-hand column. This will provide a default Workspace Name as well.

For purposes of this example, let's say the executable is C:\Hello.exe. Click Ok to create the new Workspace (which would be called "Hello" in our example).

You should now see the root of the Workspace tree in the left window, with a nifty "a" icon, and a label for the workspace name and the associated executable in parentheses.

Now you're ready to probe the executable.

Parts of the Aprobe Workspace

• pulldown menus across the top. When we refer to Workspace->Application Settings... we mean "(left) click on the Workspace menu item at the top, then (left) click on the Application Settings... item in that pulldown menu".
• the Workspace tree is the window on the left. This lists the files related to the Aprobe operations that can be done.
• various temporary windows, such as APC source to be edited, or output from the aprobe or formatting operations.

There are a number of items in the workspace tree, each of which has a popup menu associated with it (shown by right-clicking on the item's icon).

Workspace root (executable)

The workspace tree always has exactly one root at the top. This shows both the name of the workspace and the name of the executable to be probed in that workspace. The popup menu associated with the workspace root contains most of the operations you'll want to perform, including the Workspace Application Settings....

UALs

There are zero or more UALs. These are the compiled .dll files for a probe. Those UALs that have a checkmark next to them will be included when the application is run under Aprobe. The Settings... item in the UAL popup menu allows you to pass parameters to that UAL when it is run, as well as specifying other options to the apc command.

APC files

Under each UAL there may be zero or more APC files. These are the "source code" for the probes in that UAL. Click on these to edit the APC file.

APD files

There may be zero or r more APD files (e.g., hello-0.apd), which are the data files produced by running the application with Aprobe for post-runtime formatting. The popup menu for the APD file contains the Format operation. Note you must do a Refresh on the Workspace to ensure that all APD files are visible.

File->Example Workspaces

Changing Application Settings

Use this to define the settings used when running your application under Aprobe. These correspond to the options and parameters on the aprobe command line. See Appendix A of the Aprobe User's Guide for a complete description of the aprobe command.

Working Directory

the directory in which the executable is to be run. If this is left blank, the workspace directory is used.

Application Arguments

the options and arguments to be passed on the application command-line when invoked

APD Filename

the basename of the APD file produced by aprobe. This defaults to the basename of the executable. Corresponds to the aprobe -d option.

Format Immediately

when checked, log statement output is formatted and displayed at run time. Corresponds to the aprobe -if option.

Verbose

display banner and warning information. Corresponds to aprobe -v option.

Number of files

Number of APD files over which output is to be distributed. Corresponds to the aprobe -n option.

Log file size

Maximum size of each APD file. Corresponds to the aprobe -s option. If left at 0, the default value is used.

Additional settings

other options on the aprobe command line. The following options may be entered here:

-q stacksize=<bytes>            : aprobe data stack size
-q heapsize=<bytes>             : aprobe heap size
-o[[fname][![fname][![fname]]]] : Redirect stdin, stdout, stderr to a 
                                  file or to this process

-sym symbol_search_path         : debug info search path
-dll DLL name to load           : DLL to load during initialization

Changing User Action Library Settings

This dialog specifies options used when building a UAL (.dll file containing probes), as well as options passed to the UAL when it is invoked by Aprobe at runtime.

UAL Build Options

The Build Options are the settings used when building a UAL from one or more APC and C files in your Workspace. These correspond to the options and parameters to the apc command. The corresponding option is shown in parentheses after the label. See Appendix A of the Aprobe User's Guide for a complete description of the apc command.

Verbose (-v)

when checked, shows all commands being run.

Keep Temporary Files (-C)

when checked, intermediate C files are saved for debugging purposes.

Compiler Defines (-D)

Specifies #define variables referenced by your APC file or files that it includes. Multiple comma-separated items may be specified of the form Name[=Definition]. For example:

 __MSDOS__,DEBUG=OFF 

Include Directories (-I)

Specifies directories to be searched for include files not found in the local directory, the normal C compiler include directories, or Aprobe\include. Multiple comma-separated path names may be specified.

Additional Options, Libraries, Object Files

Other options and object files that are to be passed on the apc command line when it is invoked. The following options may be entered here:

[ object_files  ] [ libraries ][-e name] 
[-linker options ] [-compiler options ]
object_files      : .OBJ or .LIB file names to be linked with the UAL
-e name           : Name of API entry point to export.
-compiler options : Flags passed to the compiler. 
                    All the flags must be in a quoted string.
-linker options   : Flags to be passed  to the target linker.  
                    All options must be in a quoted string.

Use Executable debug (-x)

when checked, specifies an executable file which is read to obtain symbol and debug information referenced from the APC file. Use this if you want your function names and data objects to be resolved at Build time instead of Run time.

If you want to use a different executable from the one for this workspace (or if there isn't yet an executable in the workspace) you can pick the executable to use in the corresponding text field.

UAL Runtime Settings

Include at Runtime

when checked, adds this UAL to the command line. This corresponds to the aprobe -u option.

UAL Parameters

enter the parameters to be passed to this UAL when it is invoked by Aprobe at runtime. This corresponds to the aprobe -p option.

Predefined Probes

This menu allows you to quickly select a predefined probe to run, specify its parameters, and go, without disturbing the workspace tree. This is especially useful for running info.dll within the workspace to get a list of symbols to probe (like the apinfo command).

If you want to add a predefined probe UAL to the workspace tree, you need to:

1. Select Add UAL... from the workspace root popop menu.
2. In the Workspace Files: section, clear the Create source file check-box (since there's no source file present for the predefined probes).
3. Click the [...] button to the right of the User Action Library text box.
4. Click "Up Folder" until the current folder is Aprobe.
5. Go into the ual_lib folder.
6. Select and Open the predefined probe you want.

More...

[Back to Top]