Adding New External Components Function

3D PLM PPR Hub Open Gateway	Product Modeler	Adding New External Components Function Importing a new external component
Use Case

Abstract

This article accompanies the AddNewExternalComponent function found in the CAAPstComponentServices utility program. It explains how to add a new external component to a product structure.

What You Will Learn With This Function
The AddNewExternalComponent Function
Step-by-Step
In Short
References

What You Will Learn With This Function

This function is intended to help you program importing a new external component into a product structure. But before we get to the function itself, it is important to get an understanding of the Product Structure model by reading the referenced article [1].

[Top]

The AddNewExternalComponent Function

AddNewExternalComponent is a global function called by the samples found in the CAAProductStructure.edu framework that illustrates ProductStructure framework capabilities.

[Top]

What Does AddNewExternalComponent Do

The goal of AddNewExternalComponent is to add a new existing component to a product structure. This document must first be created. It will be saved at the same time as the importing CATProduct document. Here are its input and output parameters:

INPUT:

CATIProduct *iThisProd - the importing CATProduct document's root product
CATUnicodeString iDocumentType - the type of document to be created ("Product" or "Part")
CATUnicodeString iPartNumber - the name of the document to be created

OUTPUT:

CATIProduct *oNewProduct - the product instance of the new imported document under iThisProd

[Top]

How to Launch AddNewExternalComponent

AddNewExternalComponent is a global function that is called from the CAAPstAddComponent [2] use case. It is not an independently executable sample itself.

[Top]

Where to Find the AddNewExternalComponent Code

AddNewExternalComponent code is located in the CAAPstComponentServices.m shared library of the CAAProductStructure.edu framework:

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

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

[Top]

Step-by-Step

There are three logical steps in AddNewExternalComponent:

Creating a New CATPart or CATProduct Document
Retrieving the Root Product of the New Document
Adding the New Document as a Product Instance of the Importing Product Structure

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

[Top]

Creating a New CATPart or CATProduct Document

HRESULT rc = E_FAIL;
*oNewProduct = NULL;
	
CATUnicodeString product = "Product";
CATUnicodeString part = "Part";

if ( (iDocumentType != product) &&  (iDocumentType != part) )
{
   cout << " ERROR in AddNewExternalComponent : document type : " << iDocumentType.CastToCharPtr() << " is not allowed "<< endl << flush;
   return rc;
}

CATDocument *pNewDoc = NULL;
rc = CATDocumentServices::New(iDocumentType,
		              pNewDoc );
if ( FAILED(rc) || (NULL==pNewDoc) )
{
   cout << "ERROR : document Creation Failed" << endl<< flush;
   return rc;
}

If the document type is valid, the actual document is created using the New method of CATDocumentServices. A CATDocument pointer to the new document is thus retrieved.

Retrieving the Root Product of the New Document

...
CATIDocRoots *piDocRootsOnNewDoc = NULL;
rc = pNewDoc->QueryInterface(IID_CATIDocRoots,
			     (void**) &piDocRootsOnNewDoc);
if ( SUCCEEDED( rc ) )
{			
   CATListValCATBaseUnknown_var *pRootProducts =
	piDocRootsOnNewDoc->GiveDocRoots(); 
   CATIProduct_var spRootProduct;
   if (NULL != pRootProducts)
      if (pRootProducts->Size())
      {  
         // the root product is first element of
         // the list of root elements.
         spRootProduct = (*pRootProducts)[1];
         delete pRootProducts;
         pRootProducts = NULL;
      }
	
   piDocRootsOnNewDoc->Release();
   piDocRootsOnNewDoc=NULL;

In order to get the root product of the new document, we first get a CATIDocRoots handle on it. Then, using the GiveDocRoots method, we get a list whose first element is the root product itself.

[Top]

Adding the New Document as a Product Instance of the Importing Product Structure

   if (NULL_var != spRootProduct)
   {
      // Set PartNumber to the created root
      // ATTENTION : be sure that the part number is single
      // in a document .
      spRootProduct -> SetPartNumber(iPartNumber);

      // We have the root product from which one
      // will be agregated in "this"
      CATIProduct_var spProduct;
      spProduct = iThisProd->AddProduct (spRootProduct);
      rc = spProduct->QueryInterface(IID_CATIProduct, 
                                     (void**) &*oNewProduct);

   }
}

...

Before actually adding the new component to the product structure, we attribute it a name passed to the program as the argument "iPartNumber". We use the SetPartNumber method of CATIProduct to do this. Next, we use the AddProduct method to add the root product of the new document under the root product of the initial importing product structure.

[Top]

In Short

This function has demonstrated how to import a new document into a product structure. Specifically, it has illustrated:

Creating a new CATPart or CATProduct document using the New method of CATDocumentServices
Retrieving the root product of the document using the GiveDocRoots method of CATIDocRoots
Adding the new document as a product instance of a product structure using the AddProduct method of CATIProduct.

[Top]

References

[1]	The Product Structure Model
[1]	Adding Components to a Product Structure
[Top]

History

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

3D PLM PPR Hub Open Gateway

Product Modeler