Creating an Externally Derived StartUp

3D PLM PPR Hub Open Gateway	Feature Modeler	Creating an Externally Derived StartUp Using StartUps existing in other catalogs to create new ones
Use Case

Abstract

This article discusses the CAAOsmExtDerivedSU use case. This use case explains how to create a new StartUp deriving from an existing one found in another catalog.

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

What You Will Learn With This Use Case

This use case is intended to help you understand how to create a new StartUp based on an already existing one found in an external catalog. This can be useful when you want to create user data in a structured standard-type document. You will learn how to:

Create a new catalog using the CreateCatalog global function
Open an existing catalog using the OpenPrereqCatalog method of CATICatalog.
Create a new StartUp in the new catalog deriving from a StartUp existing in the loaded catalog using CreateSUInCatalog of CATICatalog
Add new attributes to the StartUp using the AddAttribute method of CATISpecObject
Create a new feature by instantiating the StartUp using the Instanciate method of CATISpecObject
Saving the new catalog using the SaveCatalog global function

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 CAAOsmExtDerivedSU Use Case

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

[Top]

What Does CAAOsmExtDerivedSU Do

The goal of CAAOsmExtDerivedSU is to illustrate creating new features based on StartUps deriving from other already defined external StartUps. To exemplify this, it uses the "CAAOsmNovel" 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 "CAAOsmNovel" StartUp has the feature type "CAAOsmNovel" and the client identification "CAAOsmClientId".

A new StartUp called "CAAOsmHistoricalNovel" and deriving from "CAAOsmNovel" is created in a new catalog. To this new StartUp, a few new attributes are added. This StartUp will, therefore, have all of the attributes of "CAAOsmNovel" plus its own particular ones. Here is an image of the new catalog's contents once the "CAAOsmHistoricalNovel" StartUp has been created:
Fig.2 CAAOsmExtDerivedSU.CATfct Catalog Contents

Note that the "CAAOsmHistoricalNovel" StartUp has the feature type "CAAOsmHistNovel" and the client identification "CAAOsmClientId2".

An instantiation of the "CAAOsmHistoricalNovel" StartUp is done and saved in a newly Part document.

[Top]

How to Launch CAAOsmExtDerivedSU

To launch CAAOsmExtDerivedSU, you will need to set up the build time environment, then compile CAAOsmExtDerivedSU along with its prerequisites, set up the run time environment, and then execute the sample as follows:

mkrun -c "CAAOsmExtDerivedSU NewCatalogName CAAOsmCatalogSU.CATfct DocumentStorageName.CATPart"

This step is fully described in the referenced article [3]. Following are the arguments passed when launching the use case:

NewCatalogName - is the entire pathname of the directory under which the new catalog is to be stored.
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 CAAOsmExtDerivedSU Code

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

Windows	`InstallRootDirectory\CAAObjectSpecsModeler.edu\CAAOsmExtDerivedSU.m`
Unix	`InstallRootDirectory/CAAObjectSpecsModeler.edu/CAAOsmExtDerivedSU.m`

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

[Top]

Step-by-Step

There are eight logical steps in CAAOsmExtDerivedSU:

Creating a New Catalog
Loading an Existing Catalog
Creating a New Document
Creating a New Externally Derived StartUp
Adding New Attributes to the StartUp
Creating a New Feature by Instantiating the StartUp
Saving the Catalog
Epilog

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

[Top]

Creating a New Catalog

CATICatalog *piCatalog = NULL;
CATUnicodeString newStgName = argv[1];

rc = ::CreateCatalog(&newStgName, 
                     &piCatalog);
if (NULL == piCatalog) 
{
   cout << "ERROR in creating Catalog" << endl << flush;
   return 2;
}
else cout << "Catalog created OK" << endl << flush;

A new catalog is simply created using the CreateCatalog global function. This function takes as input the entire pathname of the catalog to be created, in this case passed to the use case in the first argument. It returns a CATICatalog pointer to the new catalog that has been created.

Catalogs have the suffix .CATfct by default. In other words, when creating a catalog, you need not specify this suffix in the catalog name, but if you do, another one will not be added.

// Add a client identification to the catalog. This is a mandatory step. 
CATUnicodeString clientId("CAAOsmClientId2");
rc = piCatalog -> SetClientId(&clientId);
if (NULL == rc) cout << "ClientID setOK" << endl << flush;
else
{
   cout << "ERROR in setting ClientID" << endl << flush;
   piCatalog -> Release();
   return 3;
}

Once the catalog has been created, it is necessary to assign a client id to it. This is done using the SetClientId method of CATICatalog. This identification is necessary in order to open the catalog later on. The string defined by SetClientId is added on as a suffix to the name of each StartUp added to the catalog. This identifier should remain unique to this particular catalog in order to insure the uniqueness of the StartUp name in the case where more than one catalog were used at the same time. So, choose your identifier carefully, such that you will be able to distinguish your features from others.

[Top]

Loading an Existing Catalog

Loading a catalog means opening the catalog document in order to allow the access to the StartUps it contains.

CATUnicodeString oldStgName = argv[2];
clientId = "CAAOsmClientId2";
rc = piCatalog -> OpenPrereqCatalog (&oldStgName,
                                     &clientId);
		
if (SUCCEEDED(rc)) cout << "OpenPrereqCatalog OK" << endl << flush;
else
{
   cout << "ERROR on OpenPrereqCatalog" << endl << flush;
   piCatalog -> Release();
   return 4;
}

In order to open a catalog from which a new StartUp will be derived, use the OpenPrereqCatalog method of CATICatalog which takes the following arguments:

oldStgName - the name and .CATfct extension of the catalog being opened. 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.

[Top]

Creating a New Document

// We will work with a "CATPart" document. 

CATDocument *pDoc = NULL;
rc = CATDocumentServices::New("Part",
                              pDoc);
if (NULL != pDoc) cout << "New document created OK" << endl << flush;
else
{
    cout << "ERROR in creating New document" << endl << flush;
    piCatalog -> Release();
    return 2;
}

A new document is created simply by executing the New method of CATDocumentServices.

//----------------------------------------------
// Retrieve the root container of the document. 
//----------------------------------------------

CATInit *piInitOnDoc = NULL;
rc = pDoc -> QueryInterface(IID_CATInit,
                            (void**) &piInitOnDoc);
if (FAILED(rc)) 
{
    cout << "ERROR in QueryInterface on CATInit for doc" << endl << flush;
    piCatalog -> Release();
    return 3;
}
else cout << "QI on CATInit OK" << endl << flush;
	
CATIContainer *piRootContainer = NULL;
piRootContainer = (CATIContainer*) piInitOnDoc ->GetRootContainer(idCATIContainer);
piInitOnDoc -> Release();
if (NULL == piRootContainer)
{
    cout << "ERROR in GetRootContainer" << endl << flush;
    piCatalog -> Release();
    return 4;
}
else cout << "GetRootContainer OK" << endl << flush;

It is also necessary to retrieve the root container of the newly-created document because, in this case, it is the container we will use to create new features later on. The root container is retrieved using the GetRootContainer method of CATInit.

[Top]

Creating a New Externally Derived StartUp

CATBaseUnknown *pHistNovelSU = NULL;
CATUnicodeString histNovelName("CAAOsmHistNovel");
CATUnicodeString histNovelType("CAAOsmHistNovel");
CATUnicodeString novelType("CAAOsmNovel");
rc = piCatalog -> CreateSUInCatalog (&pHistNovelSU,
                                     &histNovelName,
                                     &histNovelType,
                                     "CATISpecObject",
                                     &novelType);
if (NULL == pHistNovelSU) 
{
    cout << "ERROR in creating CAAOsmHistNovel StartUp" << endl << flush;
    piRootContainer -> Release();
    piCatalog -> Release();
    return 8;
}
else cout << "CAAOsmHistNovel StartUp created OK" << endl << flush;

// Get a CATISpecObject handle on the CAAOsmHistNovel StartUp

CATISpecObject *piHistNovelSU = (CATISpecObject*) pHistNovelSU;

A new StartUp called "CAAOsmHistNovel" is created in the new catalog. It derives from the StartUp "CAAOsmNovel" of type "CAAOsmNovel" found in the existing catalog we just loaded. The new StartUp is created using the CreateSUInCatalog method of CATICatalog. This method takes as arguments:

CATBaseUnknown pointer to the new StartUp that will be created
CATUnicodeString name of the new StartUp
CATUnicodeString type of the new StartUp
Interface name
CATUnicodeString supertype of the new StartUp: this is the type of the StartUp found in the existing catalog from which this new StartUp will derive.

[Top]

Adding New Attributes to the StartUp

// Add "CAAOsmHistNovel" attributes

CATUnicodeString timePeriod("TimePeriod");
CATISpecAttribute *piTimePeriod = piHistNovelSU -> 
          AddAttribute(timePeriod,
                       tk_integer);
if (NULL == piTimePeriod) cout << "ERROR in adding Time Period attribute" << endl << flush;
else cout << "Time Period attribute added OK" << endl << flush;
	
piTimePeriod -> Release();

CATUnicodeString subject("Subject");
CATISpecAttribute *piSubject = piHistNovelSU ->
          AddAttribute(subject,
                       tk_string);
if (NULL == piSubject) cout << "ERROR in adding Subject attribute" << endl << flush;
else cout << "Subject attribute added OK" << endl << flush;
	
piSubject -> Release();

New attributes are added to the StartUp using the AddAttribute method of CATISpecObject. The new StartUp will possess these attributes as well as those it inherited from its "supertype", the StartUp "CAAOsmNovel" it is derived from.

[Top]

Creating a New Feature by Instantiating the StartUp

CATISpecObject *piHistNovelInst1 = piHistNovelSU ->
              Instanciate(CATUnicodeString("CAAOsmHistNovel1"),
                          piRootContainer);
pHistNovelSU -> Release();
if (NULL != piHistNovelInst1) cout << "CAAOsmHistNovel SU instance 1 created OK" << endl << flush;
else 
{
    cout << "ERROR in creating instance 1 of CAAOsmHistNovel SU" << endl << flush;
    piRootContainer -> Release();
    piCatalog -> Release();
    return 9;
}
piHistNovelInst1 -> Release();

To complete the example, a new feature is created from the StartUp by instantiation using the Instanciate method of CATISpecObject.

[Top]

Saving the Catalog

    rc = ::SaveCatalog(&piCatalog,
	               &newStgName); 

    if (FAILED(rc))
	{
	   cout << "ERROR in saving catalog document" << endl << flush;
	   return 10;
	}

In order to save the new catalog, use the SaveCatalog global function. We use here the same name as for the creation of the catalog. Because the AccessCatalog method systematically looks for the catalog in the "resources/graphic" directory under the current workspace, it is simpler to save it there directly. In order to save the catalog, use the SaveCatalog global function. Note that a Remove operation need not be performed on a catalog.

Epilog

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

[Top]

In Short

This use case has demonstrated how to create a new feature instantiated from a StartUp that has been derived from another StartUp existing in an external catalog. Specifically, it has illustrated:

Creating a new catalog using the CreateCatalog global function
Loading an existing catalog using the CATICatalog pointer of the new catalog to execute the OpenPrereqCatalog method
Creating a new document using the New method of CATDocumentServices
Creating a new StartUp in the new catalog deriving from an existing StartUp found in the loaded catalog, using the CreateSUInCatalog method of CATICatalog
Adding new attributes to the StartUp using the AddAttribute method of CATISpecObject
Creating a new feature by instantiating the new StartUp using the Instanciate method of CATISpecObject
Saving the Catalog using the SaveCatalog global function.

[Top]

References

[1]	Creating StartUps in Catalogs
[2]	Feature Modeler Conceptual Overview
[3]	Building and Launching a CAA V5 Use Case
[4]	Creating a New Document
[Top]

History

Version: 1 [Jan 2000]	Document created
Version: 2 [Nov 2000]	Document modified
[Top]

3D PLM PPR Hub Open Gateway

Feature Modeler