This book contains detailed information about each Dynamic Probe Class Library (DPCL) function. It is intended for programmers who are using DPCL to build parallel tools. The function descriptions in this book are arranged alphabetically and include programming information such as example coding, parameters, return values, and callbacks.
This book is a companion volume to the DPCL Programming Guide. While not as detailed as this book, the Programming Guide provides an overview of the tasks a programmer can perform using DPCL and describes the DPCL classes and functions related to each task.
This book is intended for C++ application developers working in a UNIX environment. You should, therefore, understand the C++ programming language and the UNIX operating system before reading this book. Furthermore, if you plan to use DPCL to instrument parallel programs, you should understand parallel programming concepts, and if you plan to run these programs in the IBM Parallel Environment for AIX (PE), you should also understand PE and the Parallel Operating Environment (POE) component of PE.
The functions described in this book are arranged in chapters by the C++ programming class to which they belong. Within each chapter, the functions are arranged alphabetically.
This book contains the following information:
This book uses the following typographic conventions:
| Convention | Usage |
|---|---|
| bold | Bold words or characters represent system elements that you must use literally, such as: command names, file names, flag names, path names, PE component names (pedb, for example), and subroutines. |
| italic | Italicized words or characters represent variable values that
you must supply.
Italics are also used for book titles and for general emphasis in text. |
| constant width | Examples and information that the system displays appear in constant-width typeface. |
In addition to the highlighting conventions, this manual often uses the C++ scope resolution operator (::) when referring to DPCL functions. It does this for the following two reasons:
The book you are reading now provides detailed reference information on
each of the DPCL classes and functions. For a general overview of the
DPCL classes, refer to this book's companion volume, the DPCL
Programming Guide. All of the reference information in this book
is also provided as UNIX man pages and can be accessed by using the UNIX
man command, as described in the following table.
Table 1. Accessing UNIX man pages for DPCL classes and functions
| To access the UNIX man page for: | ENTER: |
|---|---|
| a general overview of the DPCL classes: | man dpcl |
| a DPCL class: | man class-name
Where class-name is the name of the DPCL class. For example, to access the man page for the Process class:
|
| a DPCL function: | man function-name
Where function-name is the name of the DPCL function. Since different DPCL classes often have functions of the same name, note that the man page may contain multiple function descriptions. For example, for information on the Process::connect function, you would:
Also note that many of the DPCL classes have overloaded operator functions. |
For many users, the easiest way to learn DPCL will be by running and
examining actual working DPCL applications (called "DPCL analysis
tools") to see how they use DPCL functions to insert probes into another
running application (called a "DPCL target application").
For this reason, a set of sample applications was copied to the directory
/usr/lpp/ppe.dpcl/samples/ when you installed DPCL.
The following table summarizes the sample applications located in
subdirectories under /usr/lpp/ppe.dpcl/samples; the
order in which the sample directories are listed in this table indicates the
recommended order in which you should try the examples. Each of the
subdirectories in the following table contains a README file that provides
additional information about the program. These subdirectories also
contain makefiles for the sample target applications and analysis
tools. Refer to DPCL Programming Guide for more information on running
DPCL programs.
Table 2. Accessing DPCL sample applications
| This subdirectory of /usr/lpp/ppe.dpcl/samples/: | Contains: |
|---|---|
| hello | a "hello world" program in which a target application is instrumented to send a "hello world" string back to the analysis tool. |
| listmod | an analysis tool that displays all of the instrumentation points (locations where probes can be inserted) in the target application. |
| mpitrace | an analysis tool that finds all MPI function call sites within the target application, and inserts probes before and after the calls. These installed probes will generate messages indicating when execution of the target application has reached the points before and after the calls. |
| testcov | an analysis tool that periodically prints the number of times each function within the target application has been called. |
| diag | an analysis tool that periodically prints the values of global variables within the target application that have changed. |
| dynamic | an analysis tool that prints the value of a specified global variable when execution reaches a particular location within the target application's code. |
| profiler | an analysis tool that provides, for a given function within the target application, both the individual and accumulated values for elapsed usage and time. |
| probe_module | an analysis tool similar to the one in the subdirectory dynamic, except that it loads a probe module (a compiled object file containing one or more functions written in C) into the target application. |
| chaotic | an analysis tool that demonstrates how to install a probe at a function entry point within the target application to keep track of how many times the function is called. |
| stencil | function call count, probe module, and tracing examples. Although similar to some other sample applications, these examples accomplish the same tasks in different ways. |
The following terms are trademarks of the International Business Machines Corporation in the United States or other countries or both:
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
Microsoft, Windows, Windows NT, BackOffice, MS-DOS, and the Windows logo are trademarks or registered trademarks of Microsoft Corporation in the United States, other countries, or both.
Pentium and Pentium II Xeon are trademarks or registered trademarks of Intel Corporation in the United States, other countries, or both.
Tivoli Enterprise Console is a trademark of Tivoli Systems Inc. in the United States, other countries, or both.
UNIX is a registered trademark in the United States, other countries, or both and is licensed exclusively through X/Open Company Limited.
Other company, product, and service names may be the trademarks or service marks of others.