3D PLM PPR Hub Open Gateway

What You Will Learn With This Use Case

This use case is intended to help you understand how to integrate new features in an applicative container within a structured standard-type document such as a Part or Product document.

In order to create user data in a structured standard-type document, it is recommended that you use the feature modeler. Two different cases are possible:

1. Creating a feature whose StartUp derives from a pre-defined CAA V5 StartUp (in other words, the instantiating StartUp has a pre-defined "supertype"). In this case, the feature is instantiated in the same container as the one used by the CAA V5 application.
2. Creating a feature whose StartUp is strictly user-defined. In this case, the feature can be instantiated in a special user-defined applicative container.

In the first case, the following steps are necessary:

• Creating a ".CATfct" catalog using the CreateCatalog method of CATCatalogFactoryServices, as shown in the CAAOsmCatalogSU use case [1]
• Using the CATICatalog pointer acquired from the creation of the catalog, execute the OpenPrereqCatalog method in order to open the catalog containing the deriving StartUp.
• Creating a new StartUp using the CreateStartUpInCatalog method of CATICatalog, passing in the "supertype" parameter the type of the deriving StartUp found in the existing catalog.
• Creating a new feature from this StartUp using the Instanciate method of CATISpecObject.

In the second case, the following steps are necessary:

• Creating a user-defined applicative container within a structured standard-type document using the CATCreateApplicativeContainer global function
• Retrieving a StartUp from an existing catalog using the RetrieveSU method of CATICatalog
• Instantiating the StartUp to create a new feature within the applicative container using the Instanciate method of CATISpecObject
• Retrieving the applicative container using the CATGetApplicativeContainer global function in order to list its members using the ListMembers method of CATIClientContainer.

This use case illustrates the second case only.

Before getting to the use case itself, you should have a good understanding of what a feature object is and how it is created [2].

[Top]

The CAAOsmAppliCont Use Case

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

[Top]

What Does CAAOsmAppliCont Do

The goal of CAAOsmAppliCont is to illustrate working with user-defined features within a user-defined applicative container. It uses the "CAAOsmAdd" StartUp defined in the catalog created by the CAAOsmCatalogSU use case [1]. Here is an image of the contents of this catalog:

Fig.1: CAAOsmCatalogSU.CATfct Catalog Contents

Note that the "CAAOsmAdd" StartUp has the feature type "CAAOsmAdd" and the client identification "CAAOsmClientId".

This use case also creates a new user-defined applicative container in which a new feature, instantiated from the "CAAOsmAdd" StartUp, will be stored. Here is an image of the contents of the new applicative container:

Fig.2: CAAOsmAppliCont.CATPart New CATFeatCont Applicative Container Contents

Note that in this example, the applicative container has a late type of CATFeatCont.

[Top]

How to Launch CAAOsmAppliCont

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

mkrun -c "CAAOsmAppliCont CAAOsmCatalogSU.CATfct DocumentStorageName.CATPart"

This is fully described in the referenced article [3]. 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 CAAOsmAppliCont Code

CAAOsmAppliCont code is located in the CAAOsmAppliCont.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 CAAOsmAppliCont.cpp.

[Top]

Step-by-Step

There are ten logical steps in CAAOsmAppliCont:

1. Prolog
2. Creating a New Applicative Container
3. Loading the Catalog
4. Retrieving a StartUp from the Catalog
5. Creating a Feature by Instantiating the StartUp
6. Saving and Removing the Document from the Session
7. Loading the Document into the Session Again
8. Retrieving the Applicative Container
9. Listing the Contents of the Applicative Container
10. Epilog

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

[Top]

Prolog

See the referenced article [4] 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]

Creating a New Applicative Container

CATIdent idAppliCont = "CATFeatCont";
CATUnicodeString appliContIdentifier("CAAOsmAppliCont");
CATBaseUnknown *pApplicativeContainer = NULL;
rc = ::CATCreateApplicativeContainer(&pApplicativeContainer,   // appli cont created
                                     pDoc,                     // document  
				     idAppliCont,              // type of appli cont
				     IID_CATIContainer,        // interface type of appli cont
				     "",                       // supertype of appli cont 
				     appliContIdentifier);     // name of appli cont
...
CATIContainer *piApplicativeContainer = (CATIContainer*) pApplicativeContainer;

To create a new applicative container, we use the CATCreateApplicativeContainer global function. This function takes as arguments:

• pApplicativeContainer - the pointer that references the new applicative container that is to be created. Its type can be a CATBaseUnknown, a CATIContainer or a CATIClientContainer, depending on the value of the fourth parameter.
• pDoc - the CATDocument pointer to the current document in which the applicative container will be created
• idAppliCont - if the value of this argument is not "CATFeatCont", the fifth parameter, the supertype, must be "CATFeatCont". This argument is the late type of the container that will be created.
• IID_CATIContainer - the interface IID that this new applicative container will implement. If a CATIClientContainer handle were needed, this parameter would be: IID_CATIClientContainer.
• "" - this is the supertype of the applicative container. If left blank, the idAppliCont argument must be "CATFeatCont". Otherwise, this argument must be "CATFeatCont" itself.
• appliContIdentifier - the name of this new applicative container.

Note that the new applicative container created must be of late type "CATFeatCont" or be of a late type deriving from "CATFeatCont", as seen in the fifth argument "supertype".

If the applicative container is created in an interactive command you must had the following line after the CATCreateApplicativeContainer call:

rc = ::CATOmbPerformAfterContainerCreation( piApplicativeContainer );

This method declares the container to the undo/redo mechanism. This call is usefull only in interactive context, once the undo/redo process is only an interactive feature.

Note: Always in interactive context, for an applicative container implementing CATInit, the Init method must be called after the container creation, and the CATOmbPerformAfterContainerCreation method must be called after the initialization.  

[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,
		      piApplicativeContainer,
	              &piCatalog); 

if (SUCCEEDED(rc)) cout << "Catalog accessed OK" << endl << flush;
else
{
   cout << "ERROR on AccessCatalog" << endl << flush;
   pApplicativeContainer -> Release();
   return 6;
}

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.
• piApplicativeContainer - a CATIContainer pointer to the applicative 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 from the Catalog

CATBaseUnknown *pAddOpSU = NULL;
CATUnicodeString addOpSUType("CAAOsmAdd");
rc = piCatalogOnContainer -> RetrieveSU(&pAddOpSU, 
                                        &addOpSUType,
	                                "CATISpecObject");
piCatalogOnContainer -> Release();
piCatalogOnContainer = NULL;

if (NULL != pAddOpSU) cout << "CAAOsmAdd StartUp retrieved OK" << endl << flush;
else
{
   cout << "ERROR in retrieving CAAOsmAdd StartUp" << endl << flush;
   pApplicativeContainer -> Release();
   return 7;
}

// Get a CATISpecObject handle on the CAAOsmAdd StartUp

CATISpecObject *piAddOpSU = (CATISpecObject*) pAddOpSU;

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

[Top]

Creating a Feature by Instantiating the StartUp

CATISpecObject *piAddOpInst1 = piAddOpSU -> 
	Instanciate(CATUnicodeString("CAAOsmAdd1"),
	            pApplicativeContainer);
pAddOpSU -> Release();
pAddOpSU = NULL;

pApplicativeContainer -> Release();
pApplicativeContainer = NULL;

if (NULL != piAddOpInst1) cout << "CAAOsmAdd instance 1 created OK" << endl << flush;
else 
{
   cout << "ERROR in creating instance 1 of CAAOsmAdd SU" << endl << flush;
   return 8;
}

piAddOpInst1 -> Release();
piAddOpInst1 = NULL;

A new feature is created in the applicative container by instantiating the StartUp that was 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. Note that the CATBaseUnknown pAddOpSU pointer is released here since it will no longer be used.

[Top]

Saving and Removing the Document from the Session

rc = CATDocumentServices::SaveAs (*pDoc, argv[2]);
if (FAILED(rc))
{
   cout << "ERROR in saving document" << endl << flush;
   return 9;
}
		
rc = CATDocumentServices::Remove (*pDoc);
if (FAILED(rc)) 
{
   cout << "ERROR in removing document" << endl << flush;
   return 10;
}

We save the new document under the name passed as a second argument to this use case using the SaveAs method of CATDocumentServices. Then, we remove it from the session using the Remove static method of CATDocumentServices. Removing the document is necessary in this case since we want to re-load it later on.

[Top]

Loading the Document into the Session Again

rc = CATDocumentServices::Open(argv[2], 
		               pDoc);
if (SUCCEEDED(rc) && (NULL != pDoc)) cout << "Document opened OK" << endl << flush;
else
{
   cout << "ERROR in opening an existing document" << endl << flush;
   return 11;
}

We re-load the document found under the same storage pathname as the one used to save it. This is done in order to show the entire process of creating and retrieving applicative containers within documents. In order to re-load the document, we use the Open static method of CATDocumentServices which returns a CATDocument pointer to the document itself.

[Top]

Retrieving the Applicative Container

rc = ::CATGetApplicativeContainer (&pApplicativeContainer,   // appli cont retrieved
                                   pDoc,                     // document
                                   IID_CATIContainer,        // interface type of appli cont
                                   appliContIdentifier);     // name of appli cont to retrieve
if (SUCCEEDED(rc)) cout << "Applicative container retrieved OK" << endl << flush;
else
{
   cout << "ERROR in retrieving applicative container" << endl << flush;
   return 12;
}

We use the CATGetApplicativeContainer global function in order to retrieve the applicative container created previously. We pass the following arguments to this function:

• pApplicativeContainer - the pointer that references the applicative container that we want to retrieve. Its type can be a CATBaseUnknown, a CATIContainer or a CATIClientContainer, depending on the value of the fourth parameter.
• pDoc - the CATDocument pointer to the current document in which the applicative container is to be found
• IID_CATIContainer - the interface IID that the applicative container implements. If a CATIClientContainer handle were needed, this parameter would be: IID_CATIClientContainer.
• appliContIdentifier - the name given to the applicative container when it was created.

[Top]

Listing the Contents of the Applicative Container

CATIClientContainer *piClientOnAppliCont = NULL;
rc = pApplicativeContainer -> QueryInterface(IID_CATIClientContainer,
                                             (void**) &piClientOnAppliCont);

pApplicativeContainer -> Release();
pApplicativeContainer = NULL;

if (NULL == piClientOnAppliCont)
{
   cout << "ERROR in retrieving catalog pointer" << endl << flush;
   return 4;
}
	
CATListPtrCATBaseUnknown *pMemberList = new CATListPtrCATBaseUnknown();
rc = piClientOnAppliCont -> ListMembers(IID_CATISpecObject,   // filter on object type
                                        clientId,             // filter on client id of object
                                        &pMemberList);        // list of objects retrieved
piClientOnAppliCont -> Release();
piClientOnAppliCont = NULL;

if (SUCCEEDED(rc)) cout << "Member list retrieved OK" << endl << flush;
else
{
   cout << "ERROR in retrieving member list" << endl << flush;
   return 13;
}

cout << "Number of members in applicative container: " << pMemberList->Size() << endl << flush;

delete pMemberList;
pMemberList = NULL;

In order to retrieve the contents of an applicative container, we use the ListMembers method of CATIClientContainer. First, we need a CATIClientContainer handle on the applicative container itself. The ListMembers method takes the following arguments:

• IID_CATISpecObject - the interface IID that the objects to be retrieved within the applicative container implement
• clientID - the client identification defined on the catalog whose StartUps served to instantiate the features to be retrieved from the applicative container
• pMemberList - a CATListPtrCATBaseUnknown pointer that will reference the list of the members of the applicative container.

[Top]

Epilog

See the referenced article [4] for a detailed description of the steps to go through when saving the document.

Note that the catalog document does not need to be removed from the session.

[Top]

In Short

This use case has demonstrated how to create an applicative container within a structured standard-type document and how to instantiate new features within it. Specifically, it has illustrated:

• Creating a new applicative container using the CATCreateApplicativeContainer global function
• Loading a catalog using the AccessCatalog global function
• Retrieving a StartUp from the catalog using the RetrieveSU method of CATICatalog
• Creating a new feature in the applicative container by instantiating the StartUp using the Instanciate method of CATISpecObject
• Saving and removing the new document from the session using the SaveAs and Remove static methods of CATDocumentServices
• Retrieving the applicative container using the CATGetApplicativeContainer global function
• Listing the contents of the applicative container using the ListMembers method of CATIClientContainer

[Top]

References

History

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