3D PLM PPR Hub Open Gateway

What You Will Learn With This Use Case

This use case is intended to show you how to browse a product structure. Through this use case, you will also learn some important concepts about the Product Structure model. Basically, you will see how to:

• Load an existing CATProduct document
• Retrieve the root product of the CATProduct document
• Retrieve each child of the product structure beginning with the root product

Before getting to the use case itself, it is important to get an understanding of the Product Structure model by reading the referenced article [1].

[Top]

The CAAPstBrowse Use Case

CAAPstBrowse is a use case of the CAAProductStructure.edu framework that illustrates the ProductStructure framework capabilities.

[Top]

What Does CAAPstBrowse Do

The goal of CAAPstBrowse is to navigate within an existing product structure and to retrieve the number and names of the children of a product. The existing product structure is found under the pathname of the document passed as an argument to this program.

Above is a CATIA image of a product structure we will use as an example to navigate through. Under the root product, "Product1", there are two product instances of external CATPart documents, called "ImpSample.1" and "CAAPstPart.1" and a product instance of an external CATProduct document, called "CAAPstProduct.1".

[Top]

How to Launch CAAPstBrowse?

To launch CAAPstBrowse, you will need to set up the build time environment, then compile CAABrowse 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 "CAAPstBrowse input.CATProduct"

• input.CATPart - the path to the existing external CATProduct that will be browsed. You may reference the supplied CATProduct document called "CAAPstBrowset.CATProduct" found in :

  Unix	InstallRootDirectory/CAAProductStructure.edu/CNEXT/resources/graphic
  Windows	InstallRootDirectory\CAAProductStructure.edu\CNEXT\resources\graphic

  where InstallRootDirectory is the root directory of your CAA V5 installation.

[Top]

Where to Find the CAAPstBrowse Code?

CAAPstBrowse code is located in the CAAPstBrowse.m use case module of the CAAProductStructure.edu framework:

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

[Top]

Step-by-Step

There are six logical steps in CAAPstBrowse:

1. Loading an Existing CATProduct Document
2. Retrieving the Root Product of the CATProduct Document
3. Finding the Number of Direct Children of the Root Product
4. Getting the Number of All of the Children of the Root Product
5. Getting Each Child's Root Product Reference and Instance Names
6. Closing the Session.

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

[Top]

Loading an Existing CATProduct Document

HRESULT rc = 0;
...
CATSession* pSession = NULL;
rc = ::Create_Session("CAA2_Sample_Session",
		             pSession);

The first thing that must be done in a batch environment is to create a new session. Use the Create_Session global function. It is important not to forget to delete the session at the end of your batch program.

CATDocument* pDoc = NULL;
rc = CATDocumentServices::Open(argv[1],
	                      pDoc);
if ( FAILED(rc) || (NULL==pDoc)) return 2;

Once the current session has been created, the CATProduct document can be loaded into the session using the Open method of CATDocumentServices. The input parameter representing the pathname of the document to be loaded is taken from the first argument passed to this program. As output, we receive a CATDocument pointer to the document loaded into the session.

[Top]

Retrieving the Root Product of the CATProduct Document

CATIDocRoots* piDocRootsOnDoc = NULL;
rc = pDoc->QueryInterface(IID_CATIDocRoots,
                          (void**) &piDocRootsOnDoc);
if ( FAILED(rc) ) return 3;
	
// get the root product which is the first element of root elements
CATListValCATBaseUnknown_var* pRootProducts = 
   piDocRootsOnDoc->GiveDocRoots();
CATIProduct_var spRootProduct = NULL_var;
	
if (pRootProducts->Size())
{  
   spRootProduct = (*pRootProducts)[1];
   delete pRootProducts;
   pRootProducts = NULL;
}
piDocRootsOnDoc->Release();
	
// Get CATIProduct handle on the root product.
CATIProduct *piProductOnRoot = NULL;
rc = spRootProduct->QueryInterface(IID_CATIProduct,
                                   (void**) &piProductOnRoot);
if ( FAILED(rc) ) return 3;

In order to begin navigating through the product structure contained in the current document, we need to retrieve the root product using the GiveDocRoots method found in the CATIDocRoots interface implemented by the CATProduct document. This method returns all the roots of the document, the first being the root product we are looking for. From this root product, we can get a CATIProduct handle which will be needed later in order to browse the product structure.

[Top]

Finding the Number of Direct Children of the Root Product

int nbOfDirectChidren = piProductOnRoot -> GetChildrenCount() ;
cout << " Number of direct children under the root = " << nbOfDirectChidren << endl << flush;

Now that we have the root product in the form of a CATIProduct handle, we use the GetChildrenCount method in order to find the number of direct children under the root product. Using the product structure example shown previously, the trace should return: 3.

[Top]

Getting All of the Children of the Root Product

CATListValCATBaseUnknown_var*   ListChildren =
   piProductOnRoot->GetAllChildren();
piProductOnRoot -> Release();
if(NULL != ListChildren)
{
   int numberOfChildren = ListChildren->Size();
   cout << " Number of all children under the root = " << numberOfChildren << endl << flush;

Using the CATIProduct handle to the root product, we use the GetAllChildren method in order to get a list of all of the children of the root product. Again, based on the previous product structure example, the trace should return: 3.

[Top]

Getting Each Child's Root Product Reference and Instance Names

   CATIProduct_var spChild = NULL_var;
   for (int i=1;i<=numberOfChildren;i++)
   {
      spChild = (*ListChildren)[i];
      CATUnicodeString partNumber = spChild -> GetPartNumber();
      CATUnicodeString instanceName (" ");
      rc = spChild -> GetPrdInstanceName ( instanceName ) ;
      if  ( FAILED(rc) ) return 4;

      cout << " child number : " << i << endl << flush;
      cout << " has as part number : " << partNumber.CastToCharPtr() << endl << flush;
      cout << " and as instanceName : " << instanceName.CastToCharPtr() << endl << endl << flush;
   }
   delete ListChildren;
   ListChildren=NULL;
}

Each product in the structure has two names associated with it: the name of the product reference, in other words, the name of the root product of the document (CATPart or CATProduct) from which it has been imported, and the name of the product instance. For example, two instances of the same product will have the same product reference name (or "Part Number") but particular product instance names. Use the GetPartNumber method to get the product reference name for a child and GetPrdInstanceName to get its particular product instance name. Both are found in the CATIProduct interface. Above is the loop we coded to scan through all of the children and retrieve their names. Still based on our previous example of a product structure, the traces should come out thus:

Child number:  1  has as part number:  ImpSample   and as instanceName:  ImpSample.1
Child number:  2  has as part number:  CAAPstPart  and as instanceName:  CAAPstPart.1
Child number:  3  has as part number:  CAAPstProduct and as instanceName:  CAAPstProduct.1

[Top]

Closing the Session

1. Remove the CATProduct document from the session

   // remove opened document rc = CATDocumentServices::Remove (*pDoc); if (!SUCCEEDED(rc)) return 5;

   It is good practice to remove any opened documents before exiting the session.

2. Delete the session

   rc = ::Delete_Session("CAA2_Sample_Session");

   Do not forget to delete the session before exiting using the Delete_Session global function.

[Top]

In Short

This use case has demonstrated how to navigate within an existing product structure by retrieving the names of each child of the structure beginning with the root product. Specifically, it has illustrated:

• Loading an existing CATProduct document using the Open method of CATDocumentServices
• Retrieving the root product of the document using the GiveDocRoots method of CATIDocRoots
• Finding the number of direct children of a rood product using the GetChildrenCout of CATIProduct
• Getting all the children of a root product using the GetAllChildren method of CATIProduct
• Getting each child's reference name using the GetPartNumber method of CATIProduct
• Getting each child's instance name using the GetPrdInstanceName method of CATIProduct.

[Top]

References

History

Copyright © 2000, Dassault Systèmes. All rights reserved.