Dynamic Probe Class Library

Dynamic Probe Class Library Programming Guide


Chapter 5. Initializing the analysis tool to use the DPCL system

All DPCL analysis tools must, in order to use the DPCL system, perform the same initialization tasks. These tasks are the same whether the analysis tool is instrumenting a serial or parallel program. To initialize itself to use the DPCL system, the analysis tool must include the DPCL header files and initialize the DPCL system.

The following steps describe these three tasks in more detail. For sample code, see Example: Initializing the analysis tool to use the DPCL system.


Step 1: Include DPCL header file(s)

In order to have access to the functionality of the DPCL system, your analysis tool code must include the header file for each class, function, or function group that it will use. Your analysis tool can either include the header file dpcl.h (which includes all of the DPCL header files), or else it can include the individual header files that define just the classes, functions, or data types that it needs. To include all of the DPCL header files, use the preprocessor directive:

#include <dpcl.h>

 

If your analysis tool is a fairly simple application that does not use all the DPCL classes, you might, in order to minimize the size of your executable, want it to include only the header files for the classes, functions, and data types that it uses. The following table summarizes these individual header files. For more information on any of the classes or functions defined in these header files, refer to the DPCL Class Reference.


Table 16. DPCL header files
This Header File: Explanation:
AisGlobal.h Defines the global variables Ais_msg_handle and Ais_send. These global variables are used by probes when sending messages back to the analysis tool.
AisHandler.h Contains the function prototypes (and a supporting data type definition) for the AisHandler function group. The functions in this function group are designed to enable the analysis tool to monitor signals and file descriptors through the DPCL system.
AisInit.h Contains the function prototype for the Ais_initialize function. This function initializes the DPCL system.
AisMainLoop.h Contains the function prototype for the Ais_Main_Loop and Ais_end_main_loop functions. The Ais_Main_Loop function puts execution in an endless event loop that enables the analysis tool to interface asynchronously with the DPCL system. The Ais_end_main_loop function breaks execution out of this event loop.
AisStatus.h Defines the AisStatus class and contains the function prototypes (and supporting data type and constant definitions) for all functions in the class. Objects of the AisStatus class store status and severity codes returned by certain DPCL functions.
Application.h Defines the Application class and contains the function prototypes for all functions in the class. Objects of this class represent related processes (Process class objects). Specifically, the target application can use objects of this class to represent a set of tasks in a parallel program.
dpclExt.h Contains a prototype of the Ais_send function; used only with probe modules.
GenCallBack.h Defines the GenCallBack data types for callback parameters.
InstPoint.h Defines the InstPoint class and contains the function prototypes (and supporting data type and constant definitions) for all functions in the class. Objects of this class represent instrumentation points in target application processes (where the analysis tool can install point probes).
LogSystem.h Contains the function prototypes (and supporting data type and constant definitions) for the LogSystem function group. These functions enable the analysis tool to generate a diagnostic log.
Phase.h Defines the Phase class and contains the function prototypes for all functions in the class. Objects of this class represent phase probes.
PoeAppl.h Defines the PoeAppl class and contains the function prototypes for all functions in the class. Objects of this class (which is derived from the Application class) represent POE application processes. The PoeAppl class contains prototypes for convenience functions specific to manipulating POE applications (like starting a POE application in a stopped state, reading a POE configuration file, and supplying standard input text to the POE application).
ProbeExp.h Defines the ProbeExp class and contains the function prototypes (and supporting data type and constant definitions) for all functions in the class. Objects of this class represent probe expressions to be executed within one or more target application processes.
ProbeHandle.h Defines the ProbeHandle class and contains the function prototypes for all functions in the class. Objects of this class represent probe handles (references to probes that the analysis tool has installed in target application processes).
ProbeModule.h Defines the ProbeModule class and contains the function prototypes for all functions in the class. Objects of this class represent probe modules to be loaded into one or more target application processes.
ProbeType.h Defines the ProbeType class and contains the function prototypes (and supporting data type and constant definitions) for all functions in the class. Objects of this class represent a variable type (of a variable defined in a target application process or a probe).
Process.h Defines the Process class and contains the function prototypes for all functions in the class. Objects of this class represent a target application process.
SourceObj.h Defines the SourceObj class and contains the function prototypes (and supporting data type and constant definitions) for all functions in the class. Objects of this class represent part of the source code structure associated with a particular target application process.


Step 2: Initialize the DPCL system

All analysis tools built on the DPCL must initialize the DPCL system by calling the Ais_initialize function.

Ais_initialize();

The prototype for this function is contained in the header file AisInit.h.

Calling the Ais_initialize function enables the DPCL system to respond to unexpected system events such as a DPCL daemon exiting, or a target application process terminating. When such unexpected events occur, the DPCL system calls the appropriate system callback routine -- either a default one provided by the DPCL system that simply prints out an error message, or one that you supply as part of the analysis tool code.

For general information about DPCL callbacks, refer to What are DPCL callbacks?. For information on overriding the default system callback routines with your own system callback routines, refer to Chapter 16, Overriding default system callbacks.


Example: Initializing the analysis tool to use the DPCL system

The following example code:

#include <dpcl.h>

 

 

main() 

{

    Ais_initialize();

  

     .

     .    // Program Code Here

     .

 

}


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]