Dynamic Probe Class Library Programming Guide

Chapter 6. Connecting to or starting the target application processes

In order for your analysis tool to be able to dynamically insert probes into a target application process, it must have established a communication connection to that process. This "communication connection" is achieved though a socket connection from the analysis tool to the DPCL communication daemon, and shared-memory communication between the DPCL communication daemon and the target application process. There are two ways an analysis tool may establish such a connection to a process -- either by calling a DPCL function to explicitly connect to the process, or by calling a DPCL function to actually create the process (which will implicitly establish the necessary connection). This chapter describes how an analysis tool can:

• if the target application is already running, establish a connection to each process in the target application. The analysis tool must establish a connection to a target application process if it is to later dynamically insert probes into that process. The first section of this chapter (Connecting to the target application) discusses the procedures for connecting to a serial application, a parallel (non-POE) application, and a POE application.
• create one or more target application processes if the target application is not already running. When an analysis tool creates a process, the DPCL system also establishes the connection necessary for inserting probes into the process. The second section of this chapter (Starting the target application) discusses the procedure for starting a serial application, a parallel (non-POE) application, and a POE application.

Connecting to the target application

Before an analysis tool can install and execute probes within a target application process, it must first establish a connection to that process. Connecting to a target application process on a particular host machine creates two DPCL daemon processes on that host -- a DPCL superdaemon process, and a DPCL communication daemon process.

The DPCL superdaemon creates the DPCL communication daemon and is responsible for ensuring that only one communication daemon per user exists on the remote host. Although the DPCL superdaemon establishes the initial connection to the target application process, it passes this connection to the DPCL communication daemon. It is then the DPCL communication daemon that handles the communication between the analysis tool and the target application process. It is also the DPCL communication daemon that performs much of the actual work requested, via DPCL function calls, by the analysis tool. For more information on the DPCL daemon processes, refer to What are the DPCL daemons?.

The procedure for connecting to the target application differs depending on whether you are connecting to a serial application, a parallel (non-POE) application, or a parallel POE application.

If the target application is:	The analysis tool connects to it by:
A serial application	creating a Process object that identifies the target application process, and calling the Process::bconnect or Process::connect function. For complete instructions, refer to Connecting to a serial application. For sample code, refer to Example: Connecting to a serial application.
A parallel application (non-POE)	Creating Process objects that identify the target application processes, grouping the Process class objects under an Application object, and calling the Application::connect or Application::bconnect function. For complete instructions, refer to Connecting to a non-POE parallel application. For sample code, refer to Example: Connecting to a non-POE parallel application.
A POE Application	Creating an empty PoeAppl object, initializing the PoeAppl object to contain Process objects representing the POE target application processes, and calling the Application::connect or Application::bconnect function. (The PoeAppl class is derived from the Application class, so these functions are available to the PoeAppl object.) For complete instructions, refer to Connecting to a POE application. For sample code, refer to Example: Connecting to a POE application.

Connecting to a serial application

To connect to a serial application, the analysis tool must:

1. instantiate a Process object that Identifies the target application process, and
2. call the Process::bconnect or Process::connect function.

The following steps describe these tasks in greater detail. For sample code, see Example: Connecting to a serial application.

Step 1: Instantiate a Process object that identifies the target application process

In order to connect to the target application process, the analysis tool must instantiate a Process object that represents the process. To do this, the analysis tool must:

1. Identify the host and process ID of the target application process, and
2. using this information, instantiate the Process object

The following substeps describe these tasks in greater detail.

Step 1a: Identify the host and process ID of the target application process

In order to instantiate a Process object that represents the target application process, the analysis tool must have some way of identifying the host running this process and the process ID on that host. The analysis tool could accomplish this in a number of ways; it could, for example, prompt the user to supply this information to standard input, or it could read a configuration file that contains the information.

Step 1b: Instantiate a Process object for the target application process

In order to connect to the target application process, the analysis tool must instantiate a Process object that represents the process. The Process class is defined in the header file Process.h. To assign the host name and process ID to a Process object, you can use a non-default constructor, a non-default constructor with a copy constructor, or the default constructor with an assignment operator. Say the target application process is currently executing on a host machine whose IP host name is "myhost.xyz.edu", and the process ID is 12345.

Table 17. Instantiating a Process object

To instantiate a Process class object, the analysis tool can:	For example:
Use a default constructor and an assignment operator to assign values to the Process object.	Process p; p = Process("myhost.xyz.edu", 12345);
Use a non-default constructor to directly assign values to the Process object.	Process p("myhost.xyz.edu", 12345);
Use a non-default constructor and a copy constructor to assign values to the Process object.	Process p = Process("myhost.xyz.edu", 12345);

When you assign a host name and process ID to a Process object (as shown in the preceding table), the Process object is in an unconnected state. In other words, it is just an object allocated by the analysis tool process; it does not yet have a connection to the particular process indicated by its host and process ID values. In fact, the DPCL system does not at this point even know if the Process object's host and process ID values are valid. This unconnected state is represented by the enumeration constant PRC_unconnected of the Process class' ConnectState enumeration type. The analysis tool can query a Process object's state by calling the Process::query_state function.

For more information on the Process class constructor, refer to the DPCL Class Reference

Step 2: Connect to the target application process

Once the analysis tool has a Process object that represents the target application, it can connect to it using either the blocking function Process::bconnect, or the asynchronous function Process::connect.

Table 18. Connecting to a target application process

To connect to a single target application process (Process object):	Do this:
Using the blocking function bconnect	sts = P.bconnect(); check_status("P.bconnect()", sts); printf(" %s: connected to pid:%d\n", toolname, P.get_pid());
Using the asynchronous function connect	AisStatus sts = p->connect(connect_cb, GCBTagType(0)); check_status("p->connect(connect_cb, GCBTagType(0))", sts); // // callback to be called after the connect completes // void connect_cb(GCBSysType sys, GCBTagType tag, GCBObjType obj, GCBMsgType msg) { // code within callback routine // can check the status of the // operation and respond to its // completion by, for example, // continuing with other work }

By using the Process::connect or Process::bconnect function, the analysis tool creates a connection to the Process indicated by the Process object's host and process ID values. When the DPCL system has established a connection between the analysis tool and a target application process, the analysis tool can instrument it with probes. This connected state is represented by the enumeration constant PRC_connected of the Process class' ConnectState enumeration type. The analysis tool can query a Process object's state by calling the Process::query_state function.

For more information on the Process::bconnect and Process::connect functions, refer to their UNIX man pages, or their entries in the DPCL Class Reference.

Example: Connecting to a serial application

The following example code:

• has the user identify the host name and process ID of the target application thorough command-line arguments.
• instantiates a Process object for the target application process using the host name and process ID supplied by the user.
• calls the bconnect function to create a DPCL daemon connection to the process represented by the Process object.

main(int argc, char *argv[]) 

{

    Process 	P(argv[1], atoi(argv[2]));

 

    Ais_initialize();

  

    printf("Connecting to process %s on node %s\n", argv[2], argv[1]); 

 

    AisStatus sts = P.bconnect();  

 

    printf ("connect status  = %d\n", (int)sts);

    if ( (int)sts != 0) printf("%s\n", sts.status_name());

.

.

.

 

Connecting to a parallel application

The procedure for connecting to a parallel application differs depending on whether or not the application is designed to run in the Parallel Operating Environment.

If the target application is:	The analysis tool connects to it by:
A parallel application (non-POE)	instantiating Process objects that identify the target application processes grouping the Process class objects under an Application object, and calling the Application::connect or Application::bconnect function. For complete instructions, refer to Connecting to a non-POE parallel application. For sample code, refer to Example: Connecting to a non-POE parallel application.
A POE application	Creating an empty PoeAppl object, initializing the PoeAppl object to contain Process objects representing the POE target application processes, and calling the Application::connect or Application::bconnect function. (The PoeAppl class is derived from the Application class, so these functions are available to the PoeAppl object.) For complete instructions, refer to Connecting to a POE application. For sample code, refer to Example: Connecting to a POE application.

Connecting to a non-POE parallel application

To connect to a non-POE parallel application, the analysis tool must:

1. instantiate Process objects that identify the target application processes,
2. group the Process objects under an Application object, and
3. call the Application::connect or Application::bconnect function.

The following steps describe these tasks in greater detail. For sample code, see Example: Connecting to a non-POE parallel application.

Step 1: Instantiate Process objects that identify the target application processes

In order to connect to the target application processes in the parallel application, the analysis tool must instantiate Process objects that represent the processes. Later, the analysis tool will organize these Process objects under an Application object so that it may treat all the processes as if they were a single unit. To instantiate Process objects to represent the processes, the analysis tool must:

1. Identify the host and process ID of each target application process, and
2. instantiate a Process object for each process in the target application.

The following substeps describe these tasks in more detail.

Step 1a: Identify the host and process ID of each process in the target application

In order to instantiate Process objects that represent the target application processes, the analysis tool must have some way of identifying the host running, and the process ID for, each target application process. The analysis tool could accomplish this in a number of ways; it could, for example, prompt the user to supply this information to standard input, or it could read a configuration file that contains this information.

Step 1b: Instantiate a Process object for each process in the target application

In order to connect to the processes in the target application, the analysis tool must instantiate Process objects that represent the processes. The Process class is defined in the header file Process.h. To assign the host name and process ID to a Process object, the analysis tool can use a non-default constructor, a non-default constructor with a copy constructor, or the default constructor with an assignment operator. Say one of the target application processes is currently executing on a host machine whose IP host name is "myhost.xyz.edu", and the process ID is 12345.

Table 19. Instantiating Process objects for multiple target application processes

To instantiate a Process class object, the analysis tool can:	For example:
Use a default constructor and an assignment operator to assign values to the Process object.	Process p[128]; p = Process("myhost.xyz.edu", 12345);
Use a non-default constructor to directly assign values to the Process object.	Process p[0]("myhost.xyz.edu", 12345);
Use a non-default constructor and a copy constructor to assign values to the Process object.	Process p[0] = Process("myhost.xyz.edu", 12345);

When you assign a host name and process ID to a Process object (as shown in the preceding table), the Process object is in an unconnected state. In other words, it is just an object allocated by the analysis tool process; it does not yet have a connection to the particular process indicated by its host and process ID values. In fact, the DPCL system does not at this point even know if the Process object's host and process ID values are valid. This unconnected state is represented by the enumeration constant PRC_unconnected of the Process class' ConnectState enumeration type. The analysis tool can query a Process object's state by calling the Process::query_state function.

For more information on the Process class constructor, refer to the DPCL Class Reference.

Step 2: Group Process objects under an Application object

By grouping a set of Process objects under an Application object, the analysis tool is able to treat the set of Process objects as a single unit. In other words, it need only make a single call to an Application class member function to act upon all Process objects managed by that Application object. In this case, we are grouping all of the parallel target application's Process objects under the Application object. Note, however, that an Application object can be any grouping of Process objects that the analysis tool needs to manipulate as a single unit.

To group a set of Process objects under an Application object, the analysis tool must:

1. Instantiate an Application object, and
2. add the Process objects to the Application object.

The following substeps describe these tasks in greater detail.

Step 2a: Instantiate an Application object

In order to manipulate different processes in a parallel application, the analysis tool must group them into an Application object. The Application class is defined in the header file Application.h.

Table 20. Instantiating an Application object (for connecting to multiple processes)

To instantiate a Application class object, the analysis tool can:	For example:
Use a default constructor:	Application app1;
Use a copy constructor:	Application app2 = app1;

For more information on the Application class constructor, refer to the DPCL Class Reference.

Step 2b: Add the Process objects to the Application object

The preceding step (Step 2a: Instantiate an Application object) showed how the analysis tool can use the Application class constructor to instantiate an empty Application object. In order to use this object to manipulate a set of processes as a single unit, the analysis tool now needs to add the Process objects to the Application object. It does this using the Application::add_process function. This function takes, as a parameter, the Process object to be added to the Application object. For example, the following line of code adds the Process object p to the Application object app1.

for (i=0; i<128; i++){

 

     app1.add_process(p[i]);

 

}

For more information on the Application::add_processs function >Applicnlica, mand inputsr theyentries in the DPCss< Class Reference.

Step 2: Connect to the target application processes

ample,s prompt the ue user identify the host name and procobject fod seltiple target application pr.uments.
• instan add the Process objes that repres of the target application prprocess using the host name and procr more inforess ID singnplied by the user.
• instant that an Application ructoode a set of Process oesponhe user.
• calls the Application::connect function to c to the a DPCL daemon conConnect to the target application pr.object.

for (i=0np; ++its[]) 





    p repring te ho: ") = a



thes(ng te ho)", sts);

    p repriPID: ") = a



thes(pidstrint)sts);
diffid8];gv[1]pidstrint)sts);dd the PP(ng te ho,ffidint)sts);A->  app1.add_p&Pint)sts}ork

 work
AisStatusA->us("p->connect(conneAint)s

    check_sA->us("p->connect(conneAiype(0))", sts);

 

//

// callback to be called after the connect completes
 es

//

void connect_cb(GCBSysType sys, GCBTagType tag, GCBObjType obj, GCBMsgTys[]) 
     // code within callback r    // can check the status     // operat]) 
 on and respond     // completion by, for ex    // continuing with other 

 work

 



Connecting to a POE application



To connecin the P llel

Operating Envi (l (non-POE) applicesses, the

analysis tool must:


nr to instantiate an empty PoeAppl object,

inealizing the PoeAppl object to contain Process

objects representing the POE target application processes, and

Application::connect or

Application::bconnect function. (The

PoeAppl class is derived from the Application class, so

these functions are available to the PoeAppl object.)

For more informatPOEnctions, refer in thet wiin the P rating Envi ftStep 1: Instantie  cation object



In order to connect to the g to a POE appl object, the analysis tonit. To

instaaing the PoeAppl object that represe g t target

appli Dss is defined in the heading the ication,lues to

th
PoeAppl class is derived from the Application daemonprovidtantddiApplasis tvenis Re
these funspecificconng t target

applrocessee, the following line  illustrnstancribes how an armatiysis tool ca
instaaing the PoeAppl rocess usior the default

consp1.

 app2 = app
 

The prelowing line  wor itbeunction to cmchiate an empty PoeAppl
object apps tool. For more infoit neable to the PoeAppcation class constructor, refer in the DPCss< Class Reference.

SII>
inealiziie  cationobjes that repres ng the POE target appl object






In order to connect ng the POE target application procbject, the armatiysis too evenI>
inealiziate an empty PoeAppl
sbes inti>defaulhat chon all Process objects representing the POE target applent the

procDo precois tooene avai from the analysis tt to

manip>StII>
inealiziie  cation obje,able to the PoeAppcationprovidtans tvenis Resss fu objectene avai from the analysis ,ocessewere a a DPCL functi,nit. To

instantiate Process oructoodt grouilable to the PoeApon

oTcribehavvenis Re
these fun">What n. (The

::nI> f daemo> oer the blocequivale c tantbnI>s fu t. Note, howeses, the analysis toot muste user identify tht name and ssStep 1a: Identify the host and process ID ng th havme and ication.

Step 1a: Identify the host and process ID ng th havme and icatect













nextllowing ng step (StII>
inealiziie  cation objechapter describes how an analysis tenI>
ineaan. (The

PoeAppl
sbes inti> aulhat chon all Process  and e is ree grouping all oo the processes ng the POE target appl valuesct. In order tobehavvenis Re
these funs intohat

 supply >
in applicat Note, howeses, the analysis tooe user ile code:

 using the hosng all ng thwh theng twcessnvokconnecse forese g t target

appl ( to be  ID ng th hav %s )he user.

 of tpoectStatorough ssnvoc information og th hactor,de ( to be  ID ng th havnd the ).object.

The analysis r itPOE supply this inforh this in a number oti>defau; it could, for exot yeprompt thser to supply this inforastorough slck 
{d-line argumenon.

For more informatPOEnctions, refer in thet wiin the P rating Envi ftStII>
inealiziie  cation objion

fer to Step 1: Instantie  cation objunction, the analysis tooldantiate an emptyhe PoeAppl  Neventis tenI>
ineantains (The

PoeAppl
sbes inti> aulhat chon all Process s ID on s that repres ng the POE target application pr
octions tooene avai fes, the

analysis tt to

manip>
inealizing the PoeAppl,lues toat the analysis tool n singl using eitn. (The

::nI> fd inputsrer the blocequivale c --alizing the ::bnI>s fuunctiT>.




2.tII>
iny grouie  cationobjeect to ciate a Process classsprocess


::nI> andhe ::bnI>
set of

Process s(d e is ree grres oo the processes to the g t target

appl)objects th(The

PoeAppl
s toot tcts,em deobjects tslent the

pr
trs,eas not at thilecessn n an

unconnected lid.

This unco anject's state is represented by the enumeration c tant

PRC_unconnectedProcess ass'

ConnectState enumchieation type. The analysis tool can  by the Process's anject's state by call  the

Process::query_stasss fuunction.

For more information on t

::nI> andhe ::bnI>DPCL Class Reference/CITE>.

Fos tooce a PonnellonApplication or

Application::bconneco/TT>, or the asyncn. This func> or

Application::conne.h.




3able 18. Connectts for mung the POE target application processes






















Do this:



Using the asynchronous functinI>


ie  A;ork
AisStatusA.nI>




Using the blocking functionI>


ie  A;ork
AisStatusA.bnI>
ined pid:%d\n", t) = a = app1;








To connellfferent processn target appli(t upon all Process

objects manao into an Application
object):

Do this:



Using the asynchronous function connect



AisStatusaatus("p->connect(conneaType(0));

    check_saatus("p->connect(conneaType(0))", sts);

 

 

//

// callback to be called after the connect completes

//

void connect_cb(GCBSysType sys, GCBTagType tag, GCBObjType obj, GCBMsgType msg)

{

 


     // code within callback 
{

 


     // can check the status
{

 


     // operation and respond
{

 


     // completion by, for e
{

 


     // continuing with oth er work

 

}






Using the blocking function bconnect








By using the Application::connect or

Application::bconnect f object, the analysis t tool chave a consconnect to the proce/TT> indicated ject's host and proes

ss ID ng all variynchon all Process objects managed to the

Application /TABLE6">

<. When the DPCL sysst have establ daemon conConnect cation proceate is represented Pd the Process ot tcts managediate an Applin oocees, the

analysis tool can insteveineset of proent it with pFbject fication

procsses this connected state is represented by the enumeration constant

PRC_connected of the Process class'

ConnectState enumeration type. The analysis tool can query a

Process object's state by calling the

Process::query_state function.

For more information on the Application::connect and

Application::bconnect functions, refer to theject t  man
pages, or their entries in the DPCL Class Reference.
5
Example: Connecting to a POE applicatect

The following example code:

LI>
instant tate an empty PoeApplhe user.

inests th(The

PoeAppl
 state by calling the
e ::bnI>
calls the Application::connect function to c to the
a DPCL daemon conConnect to the target application .object.



 A;ork
AisStatusA.bnI>
ined pid:%d\n", t) = a = a
    >To connellfect tohese ta ID ng trget

appl= a = a






pP>The procedusrthe
>By usihe POE target application (esechars

ocesmberng on wP>Whereusrthe
>Bying to a serial appl,sses in a pacation (non-serial appl,snstres in a pang trget

applronment.








If the target application is:

The analysisancse forcts to it by:





le 20. Instanti on the Processcationobjes that repres tion

pe user.

By using the Proon toconnect orhe Procon toconnect function to res tion

ocess= a
oppconnecteocesses, and

calling the Prse foconnect orhe Prose foconnect functse forrently formfu", entst and 
object.

For complete instructions, refer to Bying to a serial application.




A parallel application (non-POE)



I
instantiating Process sbjes that repres of the target

application prpe user.

B,cobject foto

a Process obje/TT> orhe Proon toconnect orhe Procon toconnect function to res tion

ocess= a
oppconnecteo
cesses

grouping the Process objects under an Application

object, and

By using the Applicse foconnect or

Applicase foconnect functse forrently formfu", entst and e 
object.

For complete instructions, refer to Bying to a non-POE parallel application.






le 20. Instantitiate an empty PoeAppl object,

calling the ::oon toconnect orhe ::bcon toconnect function to res ng trget

appl= aferent processe
oppconnecteocesses, and

calling the Applicse foconnect or

Applicase foconnect functse forrently formfu", entst and e 
nctioo

th
PoeAppl class is derived fuse the

ApplicationPoeAppl object.)

For complete instructions, refer to Bying to a POE application.



3


se foring to a serial appl,stject, the analysis tool must:



Instan on the Processcationobjes that represication

pes, and

Proon toconnect orhe Procon toconnect function to res tion

o
oppco tarorctsot mustrentlye avamplete instocesses, and

Prse foconnect orhe Prose foconnect functse forrently formfu", entst and 
object.



The following steps describe these tasks in greater >

Step 1: Instantid the Processication



on the Processe that co class member fsocedurks i
>Byin thejection

o
oppco rorctsot mustrentlye avamplete instocessocedusrthe
>Byaication

procesen">What unctioon toconnecessonctionon toconnesss fu o(bsteps ds dadsks in more dade, see SCon to rf the target applihe Prbje,a.edu", onctise foconnecessonctiose foconnect froce(bsteps ds dadsks in more dade, see 
instantiate a Processle unit. To

instantiate a Process object .

Procesl rocess usior the defon the Processe tass constt tool ci on the Procesl cess= a"pre-s toold"nnected Alost. Altho (The
e Process obnit. To

instd oocessctualo theition

oc>
s toos that repi it does is t tooldd lid.
pre-s tooldnnected state is represented by the enumdefault
n c tant

 of the Process class'

ConnectState enumeration type. The analysis tool can query a

Process object's state by calling the

Process::query_state function>

SCon to rf the target applihe Prbjion

In ordon to cof each target application presses, the

analysis tool must:



Identirentlye avasigned,a.edu", ofy thendinifor,igned ttes, and

Proon toconnect orhe Procon toconnect fcation.



The following substeps describe these tasks in more detail.

Step 1a: Identirentlye avasigneda.edu", ofy thendinifor,es tion

os toosulicatect

nextllowing nhapter describocess, the analysis tocp>Proon toconnect orhe Procon toconnect function to a tion

ooess= a the

partess("object. In order  using statusse /TT>s fu t. Note, hlues toat the analysis tooser to sutoabsoluto pathConnect rentlye av,z.edu", entfy the hosere whaddr

oog all ng tha host mace>What urentlye avas tooceaunon type. The analysis toPOE supply this inforh this in a number of

ways; it could, for example, prompt the user to supply this informacessndard input, or it could read a configuration file that contens this

information.

StCon to res he POE target application Prbject

















s, the analysis tocon to cof each target application os this usingocking functihe Proon toconnect orhe Procon toconne"objetddiApplhe uspecifythis usingocllffathConnect rentlye av,z.edu",  ng tha host mendiniforc>
s toosed,ayouis too also: e code:

ser to d-line arobjects that the analysis toopen Connect rentlye av,es, and

.




4.tCon ttanti he POE target application PrbjecB


By using the Proon toconnect orhe Procon toconnect function, the analysis toolsss= a theition

oace>Whrently forsyssbon b
oppco ror,es tion

'ot musloceentlye avamplete inst
object. I"s toold"nnecte

fact, the DPCL sysloceshave establ daemon conCojectene avsai from the analysis t. To
llffer desp thlues totion

prbjet, tprocssenected state is represented by the enumdefault
n c tant

 of the Process class'

ConnectState enumeration type. The analysis tool can query a

Process object's state by calling the

Process::query_state function.

For more information on the Proon toconnect orhe Procon toconnect functions, referlicnlica,  manslocobject se /TT>s fu t.pages, or their entries in the DPCL Class Reference.





By using the Proon toconnect orhe Procon toconnect f,pectbsteps ds dad", entst anhe precedi,is tooion to a tion

obu>
s too
opputsr ently foraepresicat mustrentlye avamplete instd lid.
ene avsai from the analysi    /tunit. To
llffer desp thr,es tion

o(ectbsteps ds dade, see Chaplled9,  Eently exefer desp the POE target application proces);

orunctse foe grres oo the .hPrse foconnect orhe Prose foconne.h.




5. erthe
>Byinhe POE target application PrbjecB






Do this:



Using the asynchronous functioon toconness








Using the blocking functionon toconness
















Byinhe POE target application es this using thehe Prse foconnect orhe Prose foconnect fs(se fosrrently formfu", entst and  (inifors too", nrot yebon b
oppco ror,es tion

'ot musloceentlye avamplete inst)on typry a

Procesnected stnow and e is represented by the enumeration c tant

PRC_connected
set of

Process ass'

ConnectState enumchieation type. The analysis tool can  by the Process's anject's state by call  the

Process::query_stasss formation.
3


pP>The procedusrthe
>By"-1">A parallel application (esechars

ocesmberng on wedut do>Usinallel appliwectbstignconnecned tta ID nn the P llel

Opmberating Environment.








Do this:



Using the asynchronous functise foconnect



AisStatusp-ise fo(se foconnee sys, GCB(0)onnect();

    check_sp-ise fo(se foconnee sys, GCB(0)oype(0))", sts);

 

 

//

// callback to be called aftse foronnect completes

//
se foconnect_cb(GCBSysType sys, GCBTagType tag, GCBObjType obj, GCBMsgType msg)

{

 


     // code within callback 
{

 


     // can check the status
{

 


     // operation and respond
{

 


     // completion by, for e
{

 


     // continuing with oth er work

 

}






Using the blocking functiose foconnect












If the target application is:

The analysisancse forcts to it by:



A parallel application (non-POE)



Con ttantiating Process sbjes that repres of the target

application prpe user.

B,cobject foto

a Process obje/TT> orhe Proon toconnect orhe Procon toconnect function to res tion

ocess= a
oppconnecteo
cesses

grouping the Process objects under an Application

object, and

By using the Applicse foconnect or

Applicase foconnect functse forrently formfu", entst and e 
object.

For complete instructions, refer to Bying to a non-POE parallel application.






Con ttantitiate an empty PoeAppl object,

calling the ::oon toconnect orhe ::bcon toconnect function to res ng trget

appl= aferent processe
oppconnecteocesses, and

calling the Applicse foconnect or

Applicase foconnect functse forrently formfu", entst and e 
nctioo

th
PoeAppl class is derived fuse the

ApplicationPoeAppl object.)

For complete instructions, refer to Bying to a POE application.


Bying to a non-POE parallel application




se foring to a non-POE parallel appl,stject, the analysis tool must:

Con to iating Process sbjes that repres of the target

application prpe user.

<,cobject foto

a Process obje/TT> orhe Proon toconnect orhe Procon toconnect function to res tion

o
oppco tarorctsot mustrentlye avamplete insto
cesses

Process objects under an Application

object, and

Applicse foconnect or

Applicase foconnect functse forrently formfu", entst and e 
object.

The following steps describe these tasks in greater >


Step 1: InstaPd the Process Prbject



on the Processe that co class member fsocedurks i
>Byijection

o
oppco rorctsot mustrentlye avamplete instprocesen">What /TT> oroon toconnecessonctionon toconne
these funcuctos in teps ds dadsks diffemore dade, see SCon to rf the target applicatiobject. In orot yetce a Ponns so

these fuication, the

analysis toot musteI>
instantiate a Processcobject fodProcessl1.

Process obocess usior the defon the Processe tass constt tool cs totion

r entra "pre-s toold" anject' valation ping the Process o">What mselveunion todication, ctualotion

r es t if toos that rep">Whnotd lid.
pre-s tooldnnected s and e is represented by the enumeration c tant


set of

Process ass'

ConnectState enumchieation type. The analysis tool can  by the Process's anject's state by call  the

Process::query_stasss formation.

SCon to rf the target applicatect

In ordon to he POE target application e presses, the

analysis tool must:



Identirentlye avarati(s)asigned,a.edu", ofy tha host (s)aendinifolues totion

r es toosed.ct, and

Process ocp>Proon toconnect orhe Procon toconnect f
object.

The following substeps describe these tasks in more detail.
6
Step 1a: Identirentlye avarati(s)asigneda.edu", ofy t(s)aendinifocs totion

r es toosulicatect6/A>


nextllowing nhapter describocess, the analysis tocp>Proon toconnect orhe Procon toconnect function to a tion

ooess= a the

partess("oE="-on to res he POE target application e presses, the

analysi    // lsis ton orot yect fodhon all Process  an(s tooldndade, see Step 1: InstaPd the Process Prbj)ssnvokct using eith> oroon toconnecoronctionon toconnesss fu"object. In order  using statusse /TT>s fu t. Note, hcation, the

analysis tooser to sutorelativosereabsoluto pathConnect rentlye av,z.edlues tofy the hosere whaddr

oog all ng tha host mace>What urentlye avas tooceaunon type. The analysis toPOE supply this inforh this in a number of

ways; it could, for example, prompt the user to supply this informanctse 
to standard input, or it could read a configuration file that contobnit. is

information.
6
StCon to res he POE target application esicatect6/A>
="-on to res he POE target application e pressrom the analysi    /s tonitot yect fodhon all Process  (s tooldndade, see Step 1: InstaPd the Process Prbj)ssnvokct using eith> oroon toconnecoronctionon toconnesss fu"objetddiApplhe uspecifythis us ocllffathConnect rentlye av, daemon",  ng tha host mendiniforc>
s toosed,ayou too also: e code:

ser to d-line arobjects that the analysis toopen Connect rentlye av,es, and

.




6.tCon ttantts for muhe POE target application processes


By using the Proon toconnect orhe Procon toconnect function, the analysis toolsss= a theition

oace>Whrently forsyssbon b
oppco ror,es tion

'ot musloceentlye avamplete inst
object. I"s toold"nnecte

fact, the DPCL sysloceshave establ daemon conCojectene avsai from the analysis t. To
llffer desp thlues totion

prbjet, tprocssenected state is represented by the enumdefault
n c tant

 of the Process class'

ConnectState enumeration type. The analysis tool can query a

Process object's state by calling the

Process::query_state function.

For more information on-Pmetersailable
 emptyhe Proon toconnect orhe Procon toconnect functions, referlicnlica,  manslocobject se /TT>s fu t.pages, or their entries in the DPCL Class Reference.

WhLI>
griuping all on-POE paof the target

appl'chon all Process objects using the Application

oNote

 Note, hcatatao into an Applicationis tobepe.an eLI>
grdProcess objects that the analysis tool nject to

manipesy were a singl
>
="LI>Process objects uuse the

Applicatios objepe. The analysis tool must:

Con to o into an Application,a.edes, and

Process obos using the Application


bject.

The following substeps describe these tasks in greater >

Step 1: Instanunate an Application object



In ort to

manidiflass totion

r entra on-POE parallel appl,stjeon, the

analysis tooLI>Application >Applicatipl clasft esuntries hNAME=uratiuse the

Appl.hconne.h.




7. le 20. Instantitiate an Application (cedusrthe
>Byts for muhe POE target application pr)ocesses






















Do this:



Using the asynchronous functioon toconness


id the PP;ork
te an AppliA", sts);E="-1">for (i=0NUM_PROCS; ++its[]) 


AisStatusP.oon to(ng te ho[i],ffroge ho[i],foon to_argv, eatp,
{

 stdou(conne(e sys, GCB) 0d loderrcon (CBGys, GCB) 0d
{

 oon to_onne(e sys, GCB) i)", sts

    check_sP.oon to(Type(0))", st A.  app1.add_p&Pint)s}, sts);

 

 

//

// callback to be called afteon to onnect completes

//

on to_onnect_cb(GCBSysType sys, GCBTagType tag, GCBObjType obj, GCBMsgType msg)


     // code  afteithin callback r    // can check the status     // operat]) 


 on and respond     // completion by, for ex    // continuing with other 

 

}






Using the blocking functionon toconness




 

//on to s havme gramsrmation specified ject's hooodt grouilaapp Ampletes

te an AppliA", sid the PP;orkts);E="-1">for (i=0NUM_PROCS; i++ts[]) 









For more information on the ApplProcesse tass consnctionsrmancties in the DPCL Class Reference.
6










preche precedi (fer to Step 1: Instanunate an Application obj)ish wed jeibocess, the analysis tool can use the

Applicatione tass consttoteI>
instantiate an emptyan Application object. In order ct. Icationobjject to

manipng tedProcess obos using the Application

 It dovsai i es this using the

Applic  app1.add_y_state fu lid.
t fcattake prcesy on-Pmeter,t gr/ng the Processallback  aldnilable
 emptyan Application oFn by, for ,t gr/
The follst mefisne of   ast gr/ng the Processaobject Application

ing tgpp1conne.h.

For more information on the Applic  app1.add_y_stasss functions, reond icnlica,  mand inputsr theyentries in the DPCss< Class Reference.
5






mptyhe Proon toconneca andhe Procon toconnect fution to a tion

o
oppco ronit.tsot mustrentlye avamplete instprociT  can objectI>SCon to rf the target applicatis toobeo
oppco untilnted e. The analysiexrgetitly(se foslues tmd lid.
ene avsai from the analysi    /tut. To
llffer desp thpe.actChaplled9,  Eently exefer desp the POE target application proces);

orunctse foe grresm.hApplicse foconneonApplicose foconne.h.




8. erthe
>Byts for muhe POE target application processes






instantiatehe Applicatipls objepe. The analysis tootion is:



e tass cons:ication



arget appliapp1 = app1;






e tass cons:ication



arget appliapp28];gpp1 = app1;
















ByinLI>Applicse foconnect or

Applicase foconnect fs(se fosrrently formfu", entst and e  (inifors tooot yebon b
oppco ror,es tion

'ot mustrentlye avnit. Tote inst)on typject'smfuct foto

a Processd stnow and e is represented by the enumeration c tant

PRC_connected
set of

Process ass'

ConnectState enumchieation type. The analysis tool can  by the Process's anject's state by call  the

Process::query_stasss formation.

For more information on the Applicse foconnect or

Applicase foconnect fsnctions, refer to theica,= a tan
pages, or their entries in the DPCL Class Reference/TABLE.

Bying to a POE application





se forinnn the P llel

Op rating Envi (n (narallel appl,stject, the armancysis tool must:

eI>
instantiate an empty PoeAppl object,

< alling the ::oon toconnect orhe ::bcon toconnect function to res ng trget

appl= aferent pro
oppco ror,esirot mustrentlye avamplete insts
object, and

Applicse foconnect or

Applicase foconnect functse forrently formfu", entst and e 
nctioo

th
PoeAppl class is derived fuse the

ApplicationPoeAppl object.)

For more informatPOEnctions, referlin theIBMnnn the P rating EnvilocobjeAIX: llel

operatiU
.

Step 1: Instantie  cation object



mptyh
PoeApplsyss class member fso(> oroon toconnecess
 emptybcon toconne)objects tooion to a>
instantiate 
PoeAppl
bjes that represicang trget

applr tioo

th
PoeAppl class is derived fuse the

Application frocespecific
bjeng trget

appls.cessee, the follst mefisne  illustra compljeiboo athe

analysis tool cLI>instantiate 
PoeAppl
s this usingor the >e tass consl1.

 gpp1 = app
 

inston, tiate 
PoeAppl
ng tgpp1conne. .

For more informalues to

th
PoeApple tass consnctions ncties in the DPCss< Class Referencemation.

SCon to ng the POE target application pricatect





mptyh
PoeApplst vidprotwoi  nvenis Recst pertir ebjeclocene avai from the analysis ,ocesse
ere a t fuLI><,cion to a> froce(ng the ::oon toconneca andhe ::bcon toconne) also:e code:

ion to ng the Process oboss that repct fodhng the POE target

application prp's hooodsns so

ng the Process obos us
 emptyhe PoeAppl
sbes ects that the analysis tot to

manioupmsasss= awere a singl
>bject. In order ctact, thsignedang tjobs,ayou s toobject>A pame gramsras opposconne= aw to a ones"objetddiApplhe ul dammrat-lst mireprface simipartbos us
 efamipiato theidammratxample,,ang tst vidprocis in a nu eating Envi varie av lues atayou too g tetoteIflus Rectus     // openu ng trIdpres rently formf= afergramsr/ code ngletiol ceating Envi varie av P    rol sufocs ingsrasmpljeiba host mresourcessctionlloc todicrIdpjeibI/OtianhrId be botwon b us
 ea host ms totiogramtianlaunchs derive( to be TT>hng th havnode) .edu", enton-POE paofsks. My thehng teating Envi varie av Palsorot yrmacesocinstd dammrat-lst mflagsCojectene avayou bos emporarily overrideu", enteating Envi varie av valu macenssnvok
>Byng trIdpyoury"-1">A pame gramBefP>Foyou too der ctact, thsignedaaang tst gram,ms totiogramts tooal couan ebn s tenctions nc/CITn theIBMnnn the P rating Envi objeAIX:icallel

operatiU
By"-1">A pame gramsrs thisng trgeearesp = a"Chaplled2: Eently exenn the P Pe grams"heBy usiocking functihe ::oon toconne,ct orhe ::bcon toconne objepe. The analysis specifies TT>hng th havnodederiveinifocs tong tst gramis toobeolaunchs 
object,st vidprothtoabsoluto pathConnect poocoB>trentlye avadammratoce(/usr/bin/poo). Youryat the analysis tooser to sutoabsoluto pathConnect
TABB>poocoB>tdammratxbecau
Byan MPItst gramn ebyt using specifythisBB>poocoB>tmpipp1.gmpipp1.gpoocoB>tmpipp1.gpoocoB>tdammratl
>
="    rol POE'staently foreating Envi,s us
 emptyhe ::oon toconneca andhe ::bcon toconne
these funclsorot y on-Pmetersaijeclocene avai from the analysis  s teng teating Envi varie av Pand dammratelst 
 eflags.cessee, the folye avamllustra coy usicatioe proceducon te bentferent processeng trget

applrh.




9.tCon ttantng the POE target application pricatecs






Do this:



Using the asynchronous functise foconnect








Using the blocking functiose foconnect


















By using the ::oon toconnect orhe ::bcon toconnect function, the analysis toolslues totion

r ,obu>
susrs

ocoupmsaor,es tion

'ot mustrentlye avnit. Tote inst
object. I"s toold"nnecte

fact, the DPCL sys eshave estadefaulmon con obos usication isoojectene avai from the analysis  . To
llffer denit. bos usmprbjet, tprocssenected state is represented by the enumdefault
n c tant

 of the Process class'

ConnectState enumeration type. The analysis tool can query a

Process object's state by calling the

Process::query_state function.

For more information on the ::oon toconneca andhe ::bcon toconne
these functions, refer to theica,= a tan
t.pages, or their entries in the DPCL Class Reference.





mptyh
::oon toconneca andhe ::bcon toconne
these funion to res ng the POE target

application pro
oppco ror,esirot mustrentlye avamplete insts

oppct fodm ror,esirot musloceentlye avamplete inst
objet, tprocssenected state is representedlocen the enumeration c tant

 of the Proceon

'chon a

ConnectState enumeration type. The armancysis tool canttypject'smfu gr/ng the Processa state by calling the

Process::query_state functionTes tion

e
oc tooldnsented mptyh
::oon toconneca andhe ::bcon toconne
these funf toos maijo
oppco untillues toat the analysiexrgetitly(se fos s tmd lid.
ene avsai from the armancysis   /tut. To
llffer desp thpe.act< iuping all ol the pro(ectbsteps ds dade, see Chaplled9,  Eently exefer desp the POE target application proces);

orunctse foe grresm./TABLEei Rectus 

th
PoeAppl class is derived fuse the

ApplicationFosys tce a Ponniuping alluse the

Application fcatithe

itplicse foconnect or

Applicose foconne.h.




Byng the POE target application pricatecs






Do this:



Using the asynchronous functioon toconness


ie  P;orkchar *poee hos= "/usr/bin/poo";orkchar *argvp[]s= {poee ho,trgee ho,tNULL};ork
AisStatusP.oon to(ng te ho, poee ho,trrgvp, eatp,
{

stdou(conne(e sys, GCB) 0d loderrconne(e sys, GCB) 0d
{

oon to_onne(e sys, GCB) &Pint)s

    check_sP.oon to(Type(0))", sts);

 

//

// callback to be called afteon to onnect completes
 es

//

on to_onnect_cb(GCBSysType sys, GCBTagType tag, GCBObjType obj, GCBMsgType msg)


     // code eithin callback r    // can check the status     // operat]) 


 on and respond     // completion by, for ex    // continuing with other 

 

}






Using the blocking functionon toconness


ie  P;orkchar *poee hos= "/usr/bin/poo";orkchar *argvp[]s= {poee ho,trgee ho,tNULL};ork
AisStatusP.boon to(ng te ho,ffoee ho,trrgvp, eatp,
{

stdou(conne(e sys, GCB) 0d loderrconne(e sys, GCB) 0int)s

    check_sP.boon to(Type(0))", s

    pntf( arget applisyssbon b" toold pid:%d\n", t) = ats);pp1;
















ByinLI>Applicse foconnect or

Applicase foconnect fs(se fosrrently formfu", entst and e  (inifors tooot yebon b
oppco ror,es tion

'ot mustrentlye avnit. Tote inst)on typject'smfuct foto

a Processd stnow and e is represented by the enumeration c tant

PRC_connected
set of

Process ass'

ConnectState enumchieation type. The analysis tool can  by the Process's anject's state by call  the

Process::query_stasss formation.

For more information on the Applicse foconnect or

Applicase foconnect fsnctions, refer to theica,= a tan
pages, or their entries in the DPCL Class Reference/TABLE.
RR>

[de, see Indexicati]coB>t0">

<




Do this:



Using the asynchronous functise foconnect



PRC_coneriveAte an AppliA pid:%d\n", t) = ats);

 

 

//

// callback to be called aftse foronnect completes

//
se foconnect_cb(GCBSysType sys, GCBTagType tag, GCBObjType obj, GCBMsgType msg)

{

 


     // code within callback 
{

 


     // can check the status
{

 


     // operation and respond
{

 


     // completion by, for e
{

 


     // continuing with oth er work

 

}






Using the blocking functiose foconnect