3D PLM PPR Hub Open Gateway

What You Will Learn With This Use Case

This use case is intended to help you understand the basics of working with features. Its main intent is to explain how to create new features from StartUps or from existing features by instantiation and how to work with simple feature attributes. Through this use case, you will also learn some important aspects recommended when programming with features. Specifically, you will learn how to:

• Load an existing catalog containing StartUps
• Create new features by instantiating StartUps
• Valuate feature attributes
• Add new attributes to features
• Create new features by instantiating existing features

Before getting to the use case itself, it is important to get an understanding of what a feature object is and how it is created [1].

[Top]

The CAAOsmSimpleAttr Use Case

CAAOsmSimpleAttr is a use case of the CAAObjectSpecsModeler.edu framework that illustrates CATIA ObjectSpecsModeler framework capabilities.

[Top]

What Does CAAOsmSimpleAttr Do

The goal of CAAOsmSimpleAttr is to illustrate the basics of working with features. It uses the catalog defined in the CAAOsmCatalogSU use case [2] which contains StartUps based on the "book" example. This article describes how a new feature, "CAAOsmNovel1" is instantiated from the "CAAOsmNovel" StartUp, how its attributes are valuated, how new attributes are added to it and how it itself is instantiated to create another new feature.

Fig.1

A "CAAOsmNovel" has two attributes inherited from its "supertype" ("CAAOsmBook") which are "Title" and "BookPublisher". It has two other attributes of its own which are "Author" and "NovelChapter". Since this article deals with simple attributes, only "Title" and "Author" will be valuated. The CAAOsmReferencedAttr [3] and CAAOsmAggregatedAttr [4] use cases will show you how to work with referenced and aggregated attributes respectively.

[Top]

How to Launch CAAOsmSimpleAttr

To launch CAAOsmSimpleAttr, you will need to set up the build time environment, then compile CAAOsmSimpleAttr along with its prerequisites, set up the run time environment, and then execute the sample. 

mkrun -c "CAAOsmSimpleAttr CAAOsmCatalogSU.CATfct CatalogStoragePathNameOut"

This is fully described in the referenced article [5]. When launching the use case, you must pass the following arguments:

• CAAOsmCatalogSU.CATfct - is the name of the catalog without the storage path and with the .CATfct extension. The catalog must be found under the current workspace "os"/resources/graphic file directory. Normally, it should be stored in the CAAObjectSpecsModeler.edu/CNext/resources/graphic file directory. Then, the "Update Runtime View" command creates the proper run-time environment. 
• DocumentStorageName.CATPart - the entire pathname, name and extension (.CATPart) under which the new document is to be stored.

[Top]

Where to Find the CAAOsmSimpleAttr Code

CAAOsmSimpleAttr code is located in the CAAOsmSimpleAttr.m use case module of the CAAObjectSpecsModeler.edu framework:

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

[Top]

Step-by-Step

There are eight logical steps in CAAOsmSimpleAttr:

1. Prolog
2. Loading the Catalog
3. Retrieving a StartUp and its Attributes
4. Creating a Feature by Instantiating a StartUp
5. Valuating the Attributes of a Feature
6. Adding New Attributes to a Feature
7. Creating a Feature by Instantiating an Existing Feature
8. Epilog

We will now comment each of those sections by looking at the code.

[Top]

Prolog

See the referenced article [6] for a detailed description of the steps to go through when creating a new document.

In this use case, we create a new "Part" document: CATDocument *pDoc, and retrieve its root container: CATIContainer *piRootContainer.

[Top]

Loading the Catalog

Loading the catalog means opening the catalog document and getting a CATICatalog handle that will be needed in order to retrieve StartUps from the catalog.

CATUnicodeString stgName = argv[1];
CATICatalog *piCatalog;
CATUnicodeString clientId("CAAOsmClientId");
rc = ::AccessCatalog (&stgName,
                      &clientId,
	              piRootContainer,
		      &piCatalog); 
	
if (SUCCEEDED(rc)) cout << "Catalog accessed OK" << endl << flush;
else
{
   cout << "ERROR on AccessCatalog" << endl << flush;
   piRootContainer -> Release();
   return 5;
}

To open a catalog, use the AccessCatalog global function that takes the following arguments:

• stgName - the name of the catalog without the storage path and with the .CATfct extension. The catalog must be found under the "WS" + "OS" + resources + graphic directory.
• clientId - the client id defined on the catalog at the time of its creation.
• piRootContainer - a CATIContainer pointer to the container in which StartUps from the catalog will be instantiated.
• piCatalog - a CATICatalog pointer to the StartUps catalog that has been opened.

[Top]

Retrieving a StartUp and its Attributes

1. Retrieve "CAAOsmNovel" StartUp

   CATBaseUnknown *pNovelSU = NULL; CATUnicodeString novelSUType("CAAOsmNovel"); rc = piCatalogOnContainer -> RetrieveSU(&pNovelSU, &novelSUType, "CATISpecObject"); if (NULL != pNovelSU) cout << "CAAOsmNovel StartUp retrieved OK" << endl << flush; else { (Process ERROR: Release pointers and return.) } // Get a CATISpecObject handle on the CAAOsmNovel StartUp CATISpecObject *piNovelSU = (CATISpecObject*) pNovelSU;

   A StartUp is retrieved from the catalog using the CATICatalog::RetrieveSU method. This method returns a CATBaseUnknown pointer in pNovelSU which is directly cast into a CATISpecObject pointer (piNovelSU). The CATBaseUnknown pNovelSU pointer must be released when no longer needed.

2. Get CATISpecAttrAccess handle

   // Retrieve the attribute key to some of the CAAOsmNovel StartUp's attributes CATISpecAttrAccess *piSpecAttrAccessOnNovelSU = NULL; rc = piNovelSU -> QueryInterface(IID_CATISpecAttrAccess, (void**) &piSpecAttrAccessOnNovelSU); if (FAILED(rc)) { (Process ERROR: Release pointers and return.) }

   Once the StartUp has been retrieved, it is a good idea to immediately get the attribute keys that will be needed later on. These attribute keys remain globally available once they have been accessed. This means that valuating the attributes of any number instances of this StartUp will be more direct since there will be no need to access the attribute again before valuating it. In order to get the StartUp's attribute keys, we first get a CATISpecAttrAccess handle.

3. Get attribute keys

   CATISpecAttrKey *piKeyTitle = piSpecAttrAccessOnNovelSU -> GetAttrKey("Title"); if (NULL == piKeyTitle) { (Process ERROR: Release pointers and return.) } CATISpecAttrKey *piKeyAuthor = piSpecAttrAccessOnNovelSU -> GetAttrKey("Author"); if (NULL == piKeyAuthor) { (Process ERROR: Release pointers and return.) } piSpecAttrAccessOnNovelSU -> Release();

   Using CATISpecAttrAccess::GetAttrKey, we get a CATISpecAttrKey handle to each attribute that will be valuated.

[Top]

Creating a Feature by Instantiating a StartUp

CATISpecObject *piNovelInst1 = piNovelSU -> 
		Instanciate(CATUnicodeString("CAAOsmNovel1"),
		            piRootContainer);
pNovelSU -> Release();
if (NULL != piNovelInst1) cout << "CAAOsmNovel SU instance 1 created OK" << endl << flush;
else 
{
   (Process ERROR:  Release pointers and return.)
}

A new feature is created by instantiating a StartUp that has been retrieved from the catalog. This is done using the Instanciate method of CATISpecObject. This method needs to know the new feature's name and the container in which it will be created.

[Top]

Valuating the Attributes of a Feature

In order to valuate the attributes of the new feature instance "CAAOsmNovel1", we use the different "Set" methods found in the CATISpecAttrAccess interface. As you have seen above, the attribute keys have already been retrieved on the "CAAOsmNovel" StartUp. What we need to do now, is to use these keys in order to valuate the attributes of the feature instance.

CATISpecAttrAccess *piSpecAttrAccessOnNovelInst = NULL;
rc = piNovelInst1 -> QueryInterface(IID_CATISpecAttrAccess,
                                    (void**) &piSpecAttrAccessOnNovelInst);
if (FAILED(rc)) 
{
   (Process ERROR:  Release pointers and return.)
}

First of all, we get a CATISpecAttrAccess handle on the actual feature whose attributes we want to valuate.

piSpecAttrAccessOnNovelInst -> SetString(piKeyTitle,
		                       "The Three Musketeers");
piSpecAttrAccessOnNovelInst -> SetString(piKeyAuthor, 
                                         "Alexandre Dumas");
		
piKeyTitle -> Release();
piKeyAuthor -> Release();

Then, we use SetString to valuate the tk_string attributes.

Note that the pointers acquired from GetAttrKey must be released.

[Top]

Add New Attributes to a Feature

CATISpecAttribute *piVolumeNumber = piNovelInst1 ->
		AddAttribute(CATUnicodeString("Volume"),
		             tk_integer); 

if (NULL != piVolumeNumber)
        piVolumeNumber -> Release();

CATISpecAttrKey *piKeyVolume = piSpecAttrAccessOnNovelInst ->
		GetAttrKey("Volume");
if (NULL == piKeyVolume)
{
   (Process ERROR:  Release pointers and return.)
}

piSpecAttrAccessOnNovelInst -> SetInteger(piKeyVolume,
                                          1);
piKeyVolume -> Release();

CATISpecAttribute *piTranslator = piNovelInst1 -> 
		AddAttribute(CATUnicodeString("Translator"),
		             tk_string);
CATISpecAttrKey *piKeyTrans = piSpecAttrAccessOnNovelInst -> 
		GetAttrKey("Translator");

if (NULL != piTranslator)
	    piTranslator -> Release();

if (NULL == piKeyTrans)
{
   (Process ERROR:  Release pointers and return.)
}

piSpecAttrAccessOnNovelInst -> SetString(piKeyTrans,
                                         "John D. Smith");
piKeyTrans -> Release();

piSpecAttrAccessOnNovelInst -> Release();

To add new attributes to existing features, use the AddAttribute method of CATISpecObject and then proceed as before to valuate them.

[Top]

Creating a Feature by Instantiating an Existing Feature

piRootContainer -> Release();
piCatalogOnContainer -> Release();