3D PLM PPR Hub Open Gateway

Product Modeler

Retrieving a Product's Properties

Using the CATIAttributesDescription
and CATIInstance Interfaces

Use Case

Abstract

This article presents the CAAPstAllProperties use case which illustrates how to obtain information on the properties of a product.

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

What You Will Learn With This Use Case

Using the CATIAttributesDescription and CATIInstance interfaces, the properties of a product, including the user defined ones, can be queried and retrieved. This is different from the Retrieving a Product's Predefined Properties use case where only predefined properties are retrieved.

[Top]

The CAAPstAllProperties Use Case

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

[Top]

What Does CAAPstAllProperties Do

The goal of CAAPstAllProperties is to demonstrate the CATIAAttributesDescription and CATIInstance interfaces. It performs the following steps:

Loads a Product document
Displays all 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's 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's properties producing the output below with the CAAPstPrdProperties_Prod.CATProduct document.

Each line displays information on a property:

● Property Name

● Value Type

● Value

The first section corresponds to the CAAPstPrdProperties_Prod product:

Properties of CAAPstPrdProperties_Prod:
          PartNumber ( String): CAAPstPrdProperties_Prod
            Revision ( String): CAAPstPrdProperties_Prod Revision
          Definition ( String): CAAPstPrdProperties_Prod Definition
        Nomenclature ( String): CAAPstPrdProperties_Prod Nomenclature
      DescriptionRef ( String): CAAPstPrdProperties_Prod Reference Description
     DescriptionInst ( String): 
              Source ( Source): Made
    DefaultRepSource ( String): ** undefined **
                Name ( String): CAAPstPrdProperties_Prod
                  Id ( String): CAAPstPrdProperties_Prod
               Owner (Feature): 
     UserInfoComment ( String): ** undefined **
           NamedURLs (   List): ** undefined **
            String.1 ( String): CAA Product
           Integer.1 (Integer): 1

The following two sections show the properties of the constituting components: CAAPstPrdProperties_Part.1 and CAAPstProperties_Part.2:

Properties of CAAPstPrdProperties_Part:
          PartNumber ( String): CAAPstPrdProperties_Part
            Revision ( String): CAAPstPrdProperties_Part Revision
          Definition ( String): CAAPstPrdProperties_Part Definition
        Nomenclature ( String): CAAPstPrdProperties_Part Nomenclature
      DescriptionRef ( String): CAAPstPrdProperties_Part Reference Description
     DescriptionInst ( String): CAAPstPrdProperties_Part.1 Instance Description
              Source ( Source): Bought
    DefaultRepSource ( String): S:\R14\CAAPstPrdProperties_Part.CATPart
                Name ( String): CAAPstPrdProperties_Part.1
                  Id ( String): CAAPrdProperties_Part.1
               Owner (Feature): CAAPstPrdProperties_Prod
     UserInfoComment ( String): ** undefined **
           NamedURLs (   List): ** undefined **
            String.1 ( String): CAA Part
           Integer.2 (Integer): 2001

Properties of CAAPstPrdProperties_Part:
          PartNumber ( String): CAAPstPrdProperties_Part
            Revision ( String): CAAPstPrdProperties_Part Revision
          Definition ( String): CAAPstPrdProperties_Part Definition
        Nomenclature ( String): CAAPstPrdProperties_Part Nomenclature
      DescriptionRef ( String): CAAPstPrdProperties_Part Reference Description
     DescriptionInst ( String): CAAPstPrdProperties_Part.2 Instance Description
              Source ( Source): Bought
    DefaultRepSource ( String): S:\R14\CAAPstPrdProperties_Part.CATPart
                Name ( String): CAAPstPrdProperties_Part.2
                  Id ( String): CAAPstPrdProperties_Part.1
               Owner (Feature): CAAPstPrdProperties_Prod
     UserInfoComment ( String): ** undefined **
           NamedURLs (   List): ** undefined **
            String.1 ( String): CAA Part
           Integer.2 (Integer): 2001

[Top]

How to Launch CAAPstAllProperties

To launch CAAPstAllProperties:

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

mkrun -c "CAAPstAllProperties 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 CAAPstAllProperties Code

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

[Top]

Step-by-Step

There are six logical steps in CAAPstAllProperties:

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's 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 CATProduct document can be loaded with CATDocumentServices::OpenDocument.

	CATSession *pSession = NULL;
	rc = ::Create_Session("CAA_PrdProp_Session", pSession);
...
	//----------------------------------------------------------------------
	// Opening an existing document with full path specified 
	//----------------------------------------------------------------------
	CATDocument *pDoc = NULL;
	rc = CATDocumentServices::OpenDocument(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 PrintAllProperties 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
        //----------------------------------------------------------------------
        PrintAllProperties(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 PrintAllProperties 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
                //--------------------------------------------------------------
                PrintAllProperties(piChildProduct);
...
        }

[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's Properties

PrintAllProperties first retrieves information on the properties of a component with the CATIAttributesDescriptor interface: the List method returns a list of CATAttributeInfos describing each property.

void PrintAllProperties(CATIProduct *iInstanceProd)
{
	HRESULT rc;

	if (iInstanceProd == NULL) {
		cout << "InstanceProd is NULL!!" << endl;
		return;
	}
	CATIAttributesDescription *piAttrDesc = NULL;
	rc = iInstanceProd->QueryInterface(IID_CATIAttributesDescription,
                                            (void **) &piAttrDesc);
...
	CATIInstance *piInstance = NULL;
	rc = iInstanceProd->QueryInterface(IID_CATIInstance,
                                            (void **) &piInstance);
...
	// List all the properties and their types
	CATUnicodeString partNum = iInstanceProd->GetPartNumber();
	cout << endl << "Properties of " << partNum.ConvertToChar() << ":"
	     << endl;
	CATListValCATAttributeInfos attrInfoList;
	rc = piAttrDesc->List(&attrInfoList);
...

Of the CATAttributeInfos object obtained for each property, the Name member is then used to fetch the property value using the CATIInstance interface.

...
	if (FAILED(rc)) {
		cout << "Failed to List AttributesDescription" << endl;
	} else {
		int attrCount = attrInfoList.Size();
		for (int i = 1; i <= attrCount; i++) {
			CATAttributeInfos attrInfo = attrInfoList[i];
			const CATUnicodeString& propertyName = attrInfo.Name();
			const CATUnicodeString& valueType = attrInfo.Type()->Name();
			CATIValue *pValue = piInstance->GetValue(propertyName);
			CATUnicodeString valueString;
			if (pValue == NULL) {
				valueString = "** undefined **";
			} else {
				rc = pValue->AsString(valueString);
				if (FAILED(rc))
					valueString = "** failed to convert **";
			}
			cout.width(20); cout.setf(ios::right);
			cout << propertyName.ConvertToChar();
			cout << " (";
			cout.width(7); cout.setf(ios::right);
			cout << valueType.ConvertToChar() << "): ";
			cout << valueString.ConvertToChar() << 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 a component properties with CATIAttributesDescriptor and CATIInstance

[Top]

References

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

History

Version:1.1 [Aug 2004]	Document revised
Version: 1 [Feb 2004]	Document created
[Top]