Adding Components to a Product Structure

3D PLM PPR Hub Open Gateway	Product Modeler	Adding Components to a Product Structure Importing new and existing components
Use Case

Abstract

This article discusses the CAAPstAddComponent use case. This use case explains how to add new and existing components to a product structure.

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

What You Will Learn With This Use Case

This use case is intended to help you understand how to program adding new parts and products to a product structure. But before we get 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 CAAPstAddComponent Use Case

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

[Top]

What Does CAAPstAddComponent Do

The goal of CAAPstAddComponent is to add new and existing components to a product structure. It creates a new CATProduct document and adds three types of components to the root product in order to develop the product structure: an existing part, a new part and a new product.

In the CATIA image above, the initial CATProduct document has a root product called "Product1". We imported the existing CATPart document called "ImpSample" and instantiated it as "ImpSample.1". We also added a new CATPart document "CAAPstPart" that is instantiated as "CAAPstPart.1" and a new CATProduct document "CAAPstProduct" that is instantiated as "CAAPstProduct.1". These new CATPart and CATProduct documents are created in place and are saved along with the CATProduct document they have been instantiated in.

[Top]

How to Launch CAAPstAddComponent

To launch CAAPstAddComponent, you will need to set up the build time environment, then compile CAAPstAddComponent 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 "CAAPstAddComponent input.CATPart PartName ProductName pathNewPart pathNewProduct output.CATProduct"

input.CATPart - the path to the existing external CATPart that will be imported. You may reference the supplied CATPart document called "CAAPstImport.CATPart" 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.
PartName - the part number to give to the new part that will be created and imported
ProductName - the part number to give to the new product that will be created and imported
pathNewPart - the path where the newly-created part with name PartName will be saved
pathNewProduct - the path where the newly-created product with name ProductName will be saved
output.CATProduct - the path of the CATProduct document containing the new product structure.

[Top]

Where to Find the CAAPstAddComponent Code

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

Windows	`InstallRootDirectory/CAAProductStructure.edu/CAAPstAddComponent.m`
Unix	`InstallRootDirectory\CAAProductStructure.edu\CAAPstAddComponent.m`

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

[Top]

Step-by-Step

There are six logical steps in CAAPstAddComponent:

Creating a New CATProduct Document and an Initial Product Structure
Adding an Existing "Part" Component to the Product Structure
Adding a New "Part" Component to the Product Structure
Adding a New "Product" Component to the Product Structure
Saving the New CATPart and CATProduct Documents
Saving the Product Structure in a CATProduct Document and Closing the Session

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

[Top]

Creating a New CATProduct Document and Initial Product Structure

Create session
HRESULT rc = 0; ... 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.
Create CATProduct document
CATDocument *pDoc = NULL; rc = CATDocumentServices::New("Product", pDoc); if ( FAILED(rc) || (NULL==pDoc) ) return 2;
Now that we have a current session, we can create the CATProduct document. This is done using the New method of CATDocumentServices with type "Product" as input parameter. Note that "Product" is not the extension of the document (which is "CATProduct"), but rather its type, a name which appears in the list of document types available seen in the File/New menu of an interactive session.

Retrieve root product

CATIDocRoots *piDocRootsOnDoc = NULL;
rc = pDoc->QueryInterface(IID_CATIDocRoots,
		        (void**) &piDocRootsOnDoc);
if ( FAILED(rc) ) return 3;
	
CATListValCATBaseUnknown_var *pRootProducts =
   piDocRootsOnDoc->GiveDocRoots();

CATIProduct_var spRootProduct = NULL_var;
if (pRootProducts)
   if (pRootProducts->Size())
   {
      spRootProduct = (*pRootProducts)[1];
      delete pRootProducts;
      pRootProducts = NULL;
  }

piDocRootsOnDoc->Release();
piDocRootsOnDoc=NULL;
// Get CATIProduct handle on the root product.
CATIProduct *piProductOnRoot = NULL;
rc = spRootProduct->QueryInterface(IID_CATIProduct,
		                 (void**) &piProductOnRoot);

In order to initiate a new product structure within the CATProduct document, it is now necessary to access the root product. This is done using the GiveDocRoots method of CATIDocRoots which returns a list of all of the roots within the document, the first one being the root product we are looking for. From this root product, we get a CATIProduct handle which will be needed later in order to add new components.

[Top]

Adding an Existing "Part" Component to the Product Structure

Load an existing CATPart document

CATDocument *pDocPart = NULL;
CATIProduct *piInstanceProd = NULL;
// load the given CATPart
rc = CATDocumentServices::Open(argv[1],
		             pDocPart);
if ( FAILED(rc) || (NULL==pDocPart) ) return 4;

In order to add an existing "Part" component to the product structure, the corresponding CATPart document must be loaded into the session. This is done with the Open method of CATDocumentServices.

Import the CATPart document under root
rc = ::AddExternalComponent(piProductOnRoot, pDocPart, &piInstanceProd); if ( FAILED(rc) ) return 5;
Now that we have the part in the session, in order to add it to our product structure as a component, we use the AddExternalComponent global function. See the referenced article [3] for a description of this function. We pass the following parameters to this function:
- piProductOnRoot - the root product of the importing CATProduct document
- pDocPart - the document to be imported
- piInstanceProd - the product instance of the imported document.

[Top]

Adding a New "Part" Component to the Product Structure

Import a new CATPart under root

CATIProduct *piInstanceProd2 = NULL;
CATUnicodeString partName (argv[2]);

// creates a new part document and imports it under the product
rc = ::AddNewExternalComponent(piProductOnRoot,
		             "Part",
			    partName,
		             &piInstanceProd2);
if ( FAILED(rc) ) return 6;

Adding a new external "Part" component to a product structure is performed when there is a need for creating and working with a new part. The actual CATPart document is created automatically at the same time as the new "Part" component is imported into the product structure. This is done by using the AddNewExternalComponent global function. See the referenced article [4] for a description of this function. We pass the following parameters to this function:

piProductOnRoot - the root product of the importing CATProduct document
"Part" - the type of document to create and import
partName - the name of the document to create and import
piInstanceProd2 - the product instance of the imported document.

Get CATDocument document pointer to the new CATPart.

CATDocument *pPartDoc2 = NULL;
CATUnicodeString partDocName = partName + ".CATPart";
rc = CATDocumentServices::GetDocumentInSession (partDocName,
                                                pPartDoc2);

A CATDocument pointer to the new CATPart will be needed later on in order to be save the document. We use the GetDocumentInSession method of CATDocumentServices in order to get this pointer.

[Top]

Adding a New "Product" Component to the Product Structure

Import a new CATProduct document under root

CATIProduct *piInstanceProd3 = NULL;
CATUnicodeString productName (argv[3]);
...
rc = ::AddNewExternalComponent(piProductOnRoot,
		             "Product",
		             productName,
		 	    &piInstanceProd3);
if ( FAILED(rc) ) return 6;
piProductOnRoot -> Release();
piProductOnRoot = NULL;

Adding a new external "Product" component to the product structure is done in exactly the same way as for a "Part" component. We use the same AddNewExternalComponent function (see the referenced article [4]) ass before.

Get CATProduct document pointer.

CATDocument *pProdDoc = NULL;
CATUnicodeString productDocName = productName + ".CATProduct";
rc = CATDocumentServices::GetDocumentInSession (productDocName ,
		                              pProdDoc);

if ( FAILED(rc) ) return 7;

piInstanceProd2 -> Release();
piInstanceProd2 = NULL;
piInstanceProd3 -> Release();
piInstanceProd3 = NULL;

We must also perform a GetDocumentInSession following the addition of this new component in order to get a CATDocument pointer to the CATProduct document just created, in view of saving it later on.

Do not forget to release the pointers to the product instances returned by AddNewExternalComponent!

[Top]

Saving the New CATPart and CATProduct Documents

CATUnicodeString partPath( argv[4]);
rc = CATDocumentServices::SaveAs(*pPartDoc2, 
		               partPath);
if ( FAILED(rc) ) return 8;

CATUnicodeString prodPath( argv[5]);
rc = CATDocumentServices::SaveAs(*pProdDoc, 
                                 prodPath );
if ( FAILED(rc) ) return 8;

Before exiting the session, it is necessary to save the new documents (CATPart and CATProduct). The pathnames used for the CATPart and CATProduct documents are passed to the use case program as fourth and fifth arguments respectively. We use the SaveAs method of CATDocumentServices to save these documents.

[Top]

Saving the Product Structure in a CATProduct Document and Closing the Session

Save the CATProduct document
rc = CATDocumentServices::SaveAs(*pDoc, argv[6]); if ( FAILED(rc) ) return 8;
We can now save our new CATProduct document containing a new product structure under the name specified in the sixth input argument to this use case program.
Remove the CATProduct document from the session
rc = CATDocumentServices::Remove (*pDocPart); if ( FAILED(rc) ) return 9;
It is good practice to remove any opened documents before exiting the session.
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 import new and existing components into a product structure. Specifically, it has illustrated:

Creating a new CATProduct document using the New method of CATDocumentServices
Retrieving the root product of the document using the GiveDocRoots method of CATIDocRoots
Loading an existing external component using the Open method of CATDocumentServices
Importing an existing external component using the AddExternalComponent global function
Importing a new external component using the AddNewExternalComponent global function
Retrieving a CATDocument pointer for a new external component using the GetDocumentInSession method of CATDocumentServices
Saving the new external component and the new product document using the SaveAs method of CATDocumentServices.

[Top]

References

[1]	The Product Structure Model
[2]	Building and Launching a CAA V5 Use Case
[3]	Adding Existing External Components Utility
[4]	Adding New External Components Utility
[Top]

History

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

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

3D PLM PPR Hub Open Gateway

Product Modeler