Browsing a Process Document

3D PLM PPR Hub Open Gateway	Process Modeler	Browsing a Process Document Retrieving items attached to activities
Use Case

Abstract

This article accompanies the CAADmiBrowse use case. This use case explains how to browse a process document and retrieve items associated to activities.

What You Will Learn With This Use Case
The CAADmiBrowse Use Case
Step-by-Step
In Short
References

What You Will Learn With This Use Case

This use case is intended to help you browse an existing process document. Specifically, you will learn how to:

Get the number and list of activities of a given type
Get the number and list of items attached to the activity
Retrieve the name and type of a given item

[Top]

The CAADmiBrowse Use Case

CAADmiBrowse is a use case of the CAADMAPSInterfaces.edu framework that illustrates CATIA DMAPSInterfaces framework capabilities.

[Top]

What Does CAADmiBrowse Do?

The goal of CAADmiBrowse is to illustrate browsing a process document containing activities and items associated to activities. See the CAADmiGenerProcess use case [1] for a detailed description of how such a process document is created. This use case uses:

GetNumberOfChild and GetChild of CATISPPChildManagement in order to get the number and list of activities under the root activity of the process document
GetNumberOfItems and GetItems of CATISPPItemMgt in order to get the number and list of items associated to a given activity
GetLabel and GetType of CATISPPItem in order to get the name and type of a given item.

[Top]

How to Launch CAADmiBrowse?

To launch CAADmiBrowse, you will need to set up the build time environment, then compile CAADmiBrowse along with its prerequisites, set up the run time environment, and then execute the sample. This is fully described in the referenced article [2].

To launch the use case, execute the following command:

mkrun -c "CAADmiBrowse Process.CATProcess ActivityType"

Process.CATProcess - path name of an existing process document (note that the associated .act document has to be in the same directory as the document to be browsed). You may reference the supplied .CATProcess document called "CAADmiTestProcess.CATProcess" found in:
```
InstallRootDirectory\OS\resources\graphic
```
where InstallRootDirectory is the root directory of your CAA V5 installation, and OS is a directory the name of which depends on the operating system. Refer to [2] to get the list of the currently supported operating systems and their associated directory names.
ActivityType - the kind of activity that we want to filter our browse operation on. This activity type must exist in the associated .act activities library document. For example, you may enter "CAADmiAssembly" as an activity type.

[Top]

Where to Find CAADmiBrowse Code?

CAADmiBrowse code is located in the CAADmiBrowse.m use case module of the CAADMAPSInterfaces.edu framework:

Windows	`InstallRootDirectory/CAADMAPSInterfaces.edu/CAADmiBrowse.m`
Unix	`InstallRootDirectory\CAADMAPSInterfaces.edu\CAADmiBrowse.m`

where InstallRootDirectory is the root directory of your CAA V5 installation. It is made of a unique source file named CAADmiBrowse.cpp.

[Top]

Step-by-Step

There are six logical steps in CAADmiBrowse:

Loading a Process Document
Retrieving the Root Activity
Retrieving the Number and List of Activities under the Root Activity
Retrieving the Number and List of Items Associated to an Activity
Retrieving the Name and Type of an Item
Ending the Session

We will now comment each of these sections by looking at the code.

[Top]

Loading a Process Document

Create the session
HRESULT rc = E_FAIL; ... CATSession* pSession = NULL; rc = ::Create_Session("CAA2_Sample_Session", pSession);
Generally, the first thing that is necessary in a batch program is the creation of a new session. This is done using the Create_Session global function. It is important not to forget to delete the session at the end of your batch program.

Load the process document

CATDocument* pProcessDoc = NULL;
rc = CATDocumentServices::Open(argv[1],pProcessDoc);
if ( FAILED(rc) || (NULL==pProcessDoc)) return 2;
cout << endl << "CAAPpbBrowse.m:	process document opened : "
	<< argv[1] << endl << flush;

Now that we have a current session, we load a process document using the CATDocumentServices::Open method, to which we pass the entire pathname of the process document in the first argument. The name of the process document is itself a first argument passed to this program.

[Top]

Retrieving the Root Activity

CATInit *piInitOnDoc = NULL;
rc = pProcessDoc -> QueryInterface(IID_CATInit,
                                   (void**) &piInitOnDoc);
if (FAILED(rc) ) return 5;
CATISPPProcessContainer *piProcessCont = (CATISPPProcessContainer* )
        pInitOnDoc -> GetRootContainer("CATISPPProcessContainer");
if ( NULL == piProcessCont ) return 3;
piInitOnDoc -> Release();
piInitOnDoc = NULL;
    
CATLISTV(CATBaseUnknown_var) *pProcessList = 
        piProcessCont->GetAllProcess();
piProcessCont -> Release();
piProcessCont = NULL;
if ((NULL == pProcessList) || ((*pProcessList).Size() < 1))
{ 
   cout << "** ERROR empty list of process " << endl;
   if ((*pProcessList).Size() > 0) delete pProcessList;
   return 4;
}
cout << " number of processes in the document : "<< (*pProcessList).Size()
	<< endl << flush;

// root activity is the first of the list of processes.
CATISPPActivityRoot_var spActivityRoot = (*pProcessList)[1];
delete pProcessList;

The document's root container is retrieved using the GetRootContainer method of CATInit which is directly cast to a CATISPPProcessContainer handle. Using this handle, we can get a list of all the processes contained in the document using the GetAllProcess method. The root activity is the first process in the list and we retrieve it in a CATISPPActivityRoot handle.

[Top]

Retrieving the Number and List of Activities under the Root Activity

// handle on CATISPPChildManagement on the process. 
CATISPPChildManagement *piChildMgtOnActivity = NULL;
rc = spActivityRoot -> QueryInterface(IID_CATISPPChildManagement,
                                      (void**) &piChildMgtOnActivity);
if (FAILED(rc)) return 5;

// get activities children of type given in argument.
cout << " number of children under root activity : "<< 
piChildMgtOnActivity -> GetNumberOfChild() << endl << flush;
cout << " same, but filtered with given type: " << argv[2] <<" : " << 
      piChildMgtOnActivity -> GetNumberOfChild(argv[2]) << endl << flush;

CATListValCATBaseUnknown_var *pListChildren = 
      piChildMgtOnActivity->GetChild(argv[2]);
piChildMgtOnActivity->Release();

In order to get the number and list of activities under the root activity of the process document, we first need to get CATISPPChildManagement handle on the root. Using it, we can get the number of children using GetNumberOfChild to find out how many total activities there are and also how many activities of a given type there are. To filter on a given activity type, we simply pass to GetNumberOfChild the activity type defined in the second argument of the program.

Using the process document created in the CAADmiGenerProcess use case [1], if we pass "CAADmiPlace" as an activity type, our trace would read:

number of children under root activity : 5
same, but filtered with given type: CAADmiPlace: 2

Next, to actually retrieve a list of the activities of the process document, we use the GetChild method of CATISPPChildManagement. We can pass the activity type to this method as well, thereby retrieving only the activities of a given type.

[Top]

Retrieving the Number and List of Items Associated to an Activity

if ((NULL != pListChildren ) && ((*pListChildren).Size() != 0))
{
   CATBaseUnknown_var spAssemblyActivity = (*pListChildren)[1];
   delete pListChildren;
   pListChildren=NULL;

   // get list of items concerned by activity.
   CATISPPItemMgt *piItemMgtOnActivity = NULL;
   rc = spAssemblyActivity -> QueryInterface(IID_CATISPPItemMgt,
                                             (void**) &piItemMgtOnActivity);
   if (FAILED(rc)) return 5;

   cout << " number of items associated to root activity : "
         << piItemMgtOnActivity->GetNumberOfItems() << endl << flush;
   CATListValCATBaseUnknown_var *pItemsLists =
         piItemMgtOnActivity->GetItems();
   piItemMgtOnActivity->Release();
   piItemMgtOnActivity = NULL;
   if ((NULL == pItemsLists) || ((*pItemsLists).Size() == 0)) 
         return 6;
   ...

Now, if the list of children is not empty, we get the first activity and find the items associated to it. In order to do this, we need a CATISPPItemMgt handle which is used to get the number of items using the GetNumberOfItems method and to actually retrieve the items in a list using the GetItems methods. Still using the same example as above, our traces would now read:

number of items associated to root activity : 2

[Top]

Retrieving the Name and Type of an Item

   CATBaseUnknown_var spFirstItem = (*pItemsLists)[1];
   delete pItemsLists;
   pItemsLists = NULL;
		
   // Informations on items
   CATISPPItem *piItemOnItem = NULL;
   rc = spFirstItem -> QueryInterface(IID_CATISPPItem,
                                      (void**) &piItemOnItem);
   if (FAILED(rc)) return 5;
		
   CATUnicodeString LabelItem = piItemOnItem->GetLabel();
   
   piItemOnItem->Release();
   piItemOnItem=NULL;

}

Based on the first item in the list, we illustrate retrieving the name (label) and type of the item. To do this, we need a CATISPPItem handle on the first item in the list. Next, using the GetLabel method, we can get the name of the item, and using the GetType method, we get the type of the item.

[Top]

Ending the Session

// remove opened document
rc = CATDocumentServices::Remove (*pProcessDoc);
if (!SUCCEEDED(rc)) return 7;
	
// delete the session, removes the opened documents also.
// never forget to delete a creating session after usage.
	
rc = ::Delete_Session("CAA2_Sample_Session");

It is always a good idea to remove any opened document from the session before actually deleting the session itself and ending the program. Use the CATDocumentServices::Remove method to do this and delete the session using the Delete_Session global function.

[Top]

In Short

This use case has illustrated how to browse a process document. It retrieves all the processes of the document using the GetAllProcess method of CATISPPProcessContainer, then it retrieves activities using the GetChild method of CATISPPChildManagement and items using the GetItems method of CATISPPItemMgt for which it can also retrieve the name using the GetLabel method and type using the GetType method, both found in the CATISPPItem interface.

[Top]

References

[1]	Creating a New Process Document
[2]	Building and Launching a CAA V5 Use Case
[Top]

History

Version: 1 [Apr 2000]	Document created
[Top]

3D PLM PPR Hub Open Gateway

Process Modeler