3D PLM PPR Hub Open Gateway

Product Modeler

Fetching a Product's Predefined Properties

Using the CATIPrdProperties Interface

Use Case

Abstract

This article presents the CAAPstPrdProperties use case which illustrates how to retrieve a product's predefined properties.

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

What You Will Learn With This Use Case

Using the CATIPrdProperties interface, the predefined properties of a product and its component can be retrieved. How to access the user defined properties is covered in Retrieving a Product's Properties (see reference [3]).

[Top]

The CAAPstPrdProperties Use Case

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

[Top]

What Does CAAPstPrdProperties Do

The goal of CAAPstPrdProperties is to demonstrate the CATIPrdProperties interface. It performs the following steps:

Loads a Product document
Displays the properties of the Root Product and its components

Below is the Product document that will be loaded in the use case. It can be found in

InstallRoot/CAAProductStructure.edu/CNext/resources/graphic/CAAPstPrdProperties_Prod.CATProduct

The CAAPstPrdProperties_Prod product consists of 2 parts: CAAPstPrdProperties_Part.1 and CAAPstPrdProperties_Part.2. Each component properties can be displayed using the contextual menu Properties. For example, CAAPstPrdProperties_Prod properties:

The code in the use case will traverse the product structure and displays each component properties producing the output below with the CAAPstPrdProperties_Prod.CATProduct.

The first section corresponding to the CAAPstPrdProperties_Prod, matches exactly the properties displayed in the Properties dialog above.

Properties of CAAPstPrdProperties_Prod:
     Nomenclature: CAAPstPrdProperties_Prod Nomenclature
         Revision: CAAPstPrdProperties_Prod Revision
           Source: Made
       Definition: CAAPstPrdProperties_Prod Definition
   Reference Desc: CAAPstPrdProperties_Prod Reference Description
   Instance Desc.: 

Properties of CAAPstPrdProperties_Part (CAAPstPrdProperties_Part.1):
     Nomenclature: CAAPstPrdProperties_Part Nomenclature
         Revision: CAAPstPrdProperties_Part Revision
           Source: Bought
       Definition: CAAPstPrdProperties_Part Definition
   Reference Desc: CAAPstPrdProperties_Part Reference Description
   Instance Desc.: CAAPstPrdProperties_Part.1 Instance Description

Properties of CAAPstPrdProperties_Part (CAAPstPrdProperties_Part.2):
     Nomenclature: CAAPstPrdProperties_Part Nomenclature
         Revision: CAAPstPrdProperties_Part Revision
           Source: Bought
       Definition: CAAPstPrdProperties_Part Definition
   Reference Desc: CAAPstPrdProperties_Part Reference Description
   Instance Desc.: CAAPstPrdProperties_Part.2 Instance Description

[Top]

How to Launch CAAPstPrdProperties

To launch CAAPstPrdProperties:

Set the current directory to InstallRoot/CAAProductStructure.edu
Set up the build time environment and build the CAAPstPrdProperties.m module (see reference [2])
Execute the following command:

mkrun -c "CAAPstPrdProperties input.CATProduct"

input.CATProduct - the path to the supplied document whose path is InstallRoot/CAAProductStructure.edu/CNext/resources/graphic/CAAPstPrdProperties_Prod.CATProduct

[Top]

Where to Find the CAAPstPrdProperties Code

CAAPstPrdProperties code is located in the CAAPstPrdProperties.m module of the CAAProductStructure.edu framework.

[Top]

Step-by-Step

There are six logical steps in CAAPstPrdProperties:

Loading a Product Document
Retrieving the Document's Root Product
Displaying the Properties of the Root Product
Displaying the Properties of the Root Product's Components
Closing the Session
Displaying a Component Properties

We will now detail each of those sections:

[Top]

Loading a Product Document

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 when the program exits. Once the session is created, a Product document can be loaded with CATDocumentServices::Open.

	CATSession *pSession = NULL;
	rc = ::Create_Session("CAA_PrdProp_Session", pSession);
...
	//----------------------------------------------------------------------
	// Opening an existing document with full path specified 
	//----------------------------------------------------------------------
	CATDocument *pDoc = NULL;
	rc = CATDocumentServices::Open(argv[1], pDoc);
...

[Top]

Retrieving the Document's Root Product

In order to work with a product structure within the Product document, it is 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.

        //----------------------------------------------------------------------
        // Search for the document's root product
        //----------------------------------------------------------------------
        CATIDocRoots* piDocRootsOnDoc = NULL;
        rc = pDoc->QueryInterface(IID_CATIDocRoots,
                                  (void**) &piDocRootsOnDoc);
...
        CATListValCATBaseUnknown_var* pRootProducts = 
                piDocRootsOnDoc->GiveDocRoots();
        CATIProduct_var spRootProduct = NULL_var;

        if (NULL != pRootProducts && pRootProducts->Size() > 0) { 
                spRootProduct = (*pRootProducts)[1];
...
        } else {
                cout << "Root product could not be obtained." << endl;
                return 5;
        }

[Top]

Displaying the Properties of the Root Product

Once the Root Product is obtained, we need to query for its CATIProduct interface which is passed to the PrintPrdProperties function to display its properties.

        //----------------------------------------------------------------------
        // Get CATIProduct handle on the root product.
        //----------------------------------------------------------------------
        CATIProduct *piProductOnRoot = NULL;
        if (spRootProduct != NULL_var)
        rc = spRootProduct->QueryInterface(IID_CATIProduct,
                                           (void**) &piProductOnRoot);
...
        //----------------------------------------------------------------------
        //Print the properties of the root product
        //----------------------------------------------------------------------
        PrintPrdProperties(piProductOnRoot);

[Top]

Displaying the Properties of the Root Product's Components

Next, we get the Root Product's components using GetAllChildren. For each of these children, we query their CATIProduct interface and pass it to PrintPrdProperties to display their properties.

        //----------------------------------------------------------------------
        //Get the root product's children
        //----------------------------------------------------------------------
        CATListValCATBaseUnknown_var* childrenList = 
        piProductOnRoot->GetAllChildren();
        if (NULL == childrenList || childrenList->Size() <= 0) {
                cout << "Could not retrieve Root product's children." << endl;
                return 8;
        }
...
        CATIProduct_var spChild = NULL_var;
        int childrenCount = childrenList->Size();
        for (int i = 1; i <= childrenCount; i++) {
                spChild = (*childrenList)[i];

                //--------------------------------------------------------------
                // Get CATIProduct handle on the child product
                //--------------------------------------------------------------
                CATIProduct *piChildProduct = NULL;
                if (NULL_var != spChild) {
                        rc = spChild->QueryInterface(IID_CATIProduct,
                                                     (void**) &piChildProduct);
...
                }

                //--------------------------------------------------------------
                //Print the properties of the child part
                //--------------------------------------------------------------
                PrintPrdProperties(piChildProduct);
                if (NULL != piChildProduct) {
                        piChildProduct->Release();
                        piChildProduct = NULL;
                } 
        }        
        delete childrenList;
        childrenList = NULL;

[Top]

Closing the Session

Before terminating the use case, we need to remove the document from the session before closing it.

        //----------------------------------------------------------------------
        // Remove opened document from session
        //----------------------------------------------------------------------
        rc = CATDocumentServices::Remove (*pDoc);
...

        //----------------------------------------------------------------------
        //Delete the session 
        //----------------------------------------------------------------------
        rc = ::Delete_Session("CAA_PrdProp_Session");
...

[Top]

Displaying a Component Properties

The properties of a component are accessed through the CATIPrdProperties interface. PrintPrdProperties begins by displaying the component part number and then its instance name if applicable. Then each property is obtained with a corresponding method, namely:

GetNomenclature
GetRevision
GetSource
GetDefinition
GetDescriptionRef (Description of the Reference Product)
GetDescriptionInst (Description of the Instance)

void PrintPrdProperties(CATIProduct *iInstanceProd)
{
        HRESULT rc;
        CATUnicodeString oValue;

        if (NULL == iInstanceProd) return;

        oValue = iInstanceProd->GetPartNumber();
        cout << endl
             << "Properties of " << oValue.ConvertToChar();
        rc = iInstanceProd->IsReference();
        if (FAILED(rc)) {
                rc = iInstanceProd->GetPrdInstanceName(oValue);
                if (SUCCEEDED(rc))
                        cout << " (" << oValue.ConvertToChar() << ")";
        }
        cout << ":" << endl;

        CATIPrdProperties_var spPrdProps(iInstanceProd);
        if (NULL_var != spPrdProps) {
                spPrdProps->GetNomenclature(oValue);
                cout << " Nomenclature: " << oValue.ConvertToChar() << endl;

                spPrdProps->GetRevision(oValue);
                cout << " Revision: " << oValue.ConvertToChar() << endl;

                CatProductSource oSource;
                spPrdProps->GetSource(oSource);
                switch (oSource) {
                case catProductSourceUnknown:
                        oValue = "Unknown";
                        break;
                case catProductMade:
                        oValue = "Made";
                        break;
                case catProductBought:
                        oValue = "Bought";
                        break;
                default:
                        oValue = "Undefined";
                }
                cout << " Source: " << oValue.ConvertToChar() << endl;
 
                spPrdProps->GetDefinition(oValue);
                cout << " Definition: " << oValue.ConvertToChar() << endl;

                spPrdProps->GetDescriptionRef(oValue);
                cout << " Reference Desc: " << oValue.ConvertToChar() << endl;

                spPrdProps->GetDescriptionInst(oValue);
                cout << " Instance Desc.: " << oValue.ConvertToChar() << endl;
        } else {
                cout << "None" << endl;
        }
}

[Top]

In Short

This use case has demonstrated how to access to a component properties:

Loading a Product document with CATDocumentServices::Open
Retrieving the root product of the document with CATIDocRoots::GiveDocRoots
Traversing the components returned by CATIProduct::GetAllChildrenList on the root product
Accessing to a component properties with CATIPrdProperties

[Top]

References

[1]	The Product Structure Model
[2]	Building and Launching a CAA V5 Use Case
[3]	Retrieving a Product's Properties.
[Top]

History

Version: 2.1 [Aug 2004]	Document revised
Version: 2 [Feb 2004]	Reference added
Version: 1 [Sep 2003]	Document created
[Top]