3D PLM PPR Hub Open Gateway

Product Modeler

Adding Existing External Components Function

Importing an existing external component
Use Case

Abstract

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

What You Will Learn With This Function

This function is intended to help you program importing an existing 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 AddExternalComponent Function

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

[Top]

What Does AddExternalComponent Do

The goal of AddExternalComponent is to add an existing component to a product structure. Here are its input and output parameters:

INPUT:

OUTPUT:

[Top]

How to Launch AddExternalComponent

AddExternalComponent is a global function that is called from the CAAPstAddComponent [2] and CAAPstMovable [3] use cases. It is not an independently executable sample itself.

[Top]

Where to Find the AddExternalComponent Code

AddExternalComponent 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 two logical steps in AddExternalComponent:

  1. Retrieving the Root Product of the Component to be Imported (if any)
  2. Adding the Existing Component to the Product Structure

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

[Top]

Retrieving the Root Product of the Component to be Imported

HRESULT rc = E_FAIL;
	
if ( NULL != iDocument)
{
   // Get RootProduct of the document to import.
   CATIDocRoots *piDocRootsOnDoc = NULL;
   rc = iDocument->QueryInterface(IID_CATIDocRoots,
			          (void**) &piDocRootsOnDoc);
   if ( FAILED(rc) )
   {
      cout << "** QI on CATIDocRoots failed " << endl<< flush;
      return rc;
   }
		
   CATListValCATBaseUnknown_var *pRootProducts = 
	piDocRootsOnDoc->GiveDocRoots();
   CATIProduct_var spRootProduct = NULL_var;
   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;
      }
			
   piDocRootsOnDoc->Release();
   piDocRootsOnDoc=NULL;

If the pointer to the document to be imported is valid, we first get a CATIDocRoots handle on it in order to retrieve its root product using the GiveDocRoots method. The root product of the document is the first element in the list returned by this method. Note that if the document to be imported is neither a CATPart nor a CATProduct document, it will not have a root product.

[Top]

Adding the Existing Component to the Product Structure

  1. Adding a CATPart or CATProduct document 
    if (NULL_var != spRootProduct)
{
   // We have the root product from which one
   // will be agregated in "this"
   spProduct = iThisProd->AddProduct (spRootProduct);
}

    If a root product was actually retrieved from the document to be imported, we simply execute the AddProduct method of CATIProduct in order to create a new product instance of the imported document under the root product of the importing CATProduct document..

  2. Adding a V4 model 
    else
{
   CATUnicodeString docName = iDocument-> StorageName();
   iThisProd->AddShapeRepresentation(CATUnicodeString("model"),
				     docName);
   return 3;
}

    If the document to be imported is a V4 model, we use the AddShapeRepresentation method of CATIProduct in order to import this model into the product structure under the root product. We pass as input the string "model" and the entire storage path name of the document that we retrieve using the StorageName method of CATDocument. Then, we simply exit the function.

  3. Returning a product instance of the imported component 
    rc = spProduct->QueryInterface(IID_CATIProduct, 
			       (void**) &*oNewProduct);

    If we have actually imported a document having a root product, we retrieve the CATIProduct instance of this root product to return to the calling program.

[Top]

In Short

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

[Top]

References

[1] The Product Structure Model
[2] Adding Components to a Product Structure
[3] Positioning Products in a Product Structure

History

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

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