3D PLM PPR Hub Open Gateway

What You Will Learn With This Use Case

As you may remember, StartUps are always created in catalogs. Catalogs are identified by unique client id's in order to protect them from unwanted access. Only the owner of a catalog has the ability to open the catalog and access the StartUps contained in it. Therefore, if you want to derive a new StartUp from a StartUp existing in a catalog that you do not own, you must either use a factory provided by the catalog owner which is useful when you do not know the name of the catalog or of the deriving StartUp, or you can use the generic factory provided by the feature modeler. This use case illustrates the usage of the generic factory. See the "Deriving New StartUps Using Provided Factories" use case [1] for a detailed explanation of creating and using a specific factory provided by the catalog owner.

 In order to use the feature modeler's generic factory, however, it is assumed that the StartUp you are trying to derive from has been declared "public" and "derivable" in the .CATSpecs file corresponding to the catalog containing it. This declaration must have been made by the catalog owner. See the "Managing Public Features and Attributes" use case [2] for a detailed explanation of how to create and update the .CATSpecs file. You will find  documentation on all Dassault Systemes public and derivable StartUps under the Quick Reference section for each modeler.

Before getting to the use case itself, you should have a good understanding of the feature modeler. [3].

[Top]

The CAAOsmGenericDerivedSUFactory Use Case

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

[Top]

What Does CAAOsmGenericDerivedSUFactory Do

The goal of CAAOsmGenericDerivedSUFactory is to illustrate using the generic StartUp factory called CATOsmSUFactory provided by the feature modeler. It uses the StartUp with type "CAAOsmAdd" found in the catalog created in the CAAOsmCatalogSU use case [4]. Here is an image of the "CAAOsmAdd" StartUp's data structure in this catalog:

Fig.1 CAAOsmCatalogSU.CATfct Catalog - "CAAOsmAdd" StartUp

In the CAAOsmCatalogSU use case, the "CAAOsmAdd" StartUp was declared in the CAAOsmCatalogSU.CATSpecs declarative file as being "public" and "derivable". Its derivation is, therefore, authorized. In this use case, a new StartUp called "CAAOsmNewAdd" derived from "CAAOsmAdd" is created in a new catalog by using the CATOsmSUFactory global function. Here is an image of the new StartUp in the new catalog:

Fig.2 CAAOsmGenericFactory.CATfct Catalog - "CAAOsmNewAdd" StartUp

Note that the new StartUp has inherited all of the attributes of its parent and that it has added one of its own attributes ("Third"). The new StartUp was also specified as being "public" and "derivable". A corresponding .CATSpecs file containing an entry for this new StartUp was, therefore, automatically created as well. Here is an image of this declarative file:

Fig.3 CAAOsmGenericFactory.CATSpecs - "CAAOsmNewAdd" StartUp

[Top]

How to Launch CAAOsmGenericDerivedSUFactory

To launch CAAOsmGenericDerivedSUFactory, you will need to set up the build time environment, then compile CAAOsmGenericDerivedSUFactory along with its prerequisites, set up the run time environment, and then execute the sample. This is fully described in the referenced article [5]. To launch the use case, execute the following command:

mkrun -c "CAAOsmMainGenericFactory NewCatalogStoragePathName NewDocumentStoragePathName"

• NewCatalogStoragePathName - the entire storage pathname, name and extension (.CATfct) of the new catalog created. This is the catalog that will contain the new, derived StartUp.
• NewDocumentStoragePathName - the entire storage pathname, name and extension (.CATProduct) of the new document created. This is the document in which the new, derived StartUp will be instantiated.

[Top]

Where to Find the CAAOsmGenericDerivedSUFactory Code

The main CAAOsmGenericDerivedSUFactory code is located in the CAAOsmMainGenericFactory.m module of the CAAObjectSpecsModeler.edu framework. It contains a unique source file named CAAOsmMainGenericFactory.cpp. This main calls one global function, CAAOsmCreateGenericDerivedSU, contained in the CAAOsmCreateGenericDerivedSU.cpp source file of the CAAOsmCreateSUByGenericFactory.m module: 

CAAOsmMainGenericFactory.m (CAAOsmMainGenericFactory.cpp) -----> CAAOsmCreateSUByGenericFactory.m (CAAOsmCreateGenericDerivedSU.cpp) 

Here is the installation path, depending on the operating system:

where InstallRootDirectory is the root directory of your CAA V5 installation.

[Top]

Step-by-Step

There are seven logical steps in CAAOsmGenericDerivedSUFactory:

1. Create a New Product Document
2. Create the Catalog for the New Derived StartUp
3. Use the Generic StartUp Factory to Create the New Derived StartUp
4. Add a New Attribute to the StartUp
5. Instantiate the StartUp in the Part Document
6. Save the New Catalog
7. Epilog

We will now comment each of those sections by looking at the code. The code commented in all of the following sections is found in the CAAOsmCreateGenericDerivedSU global function.

[Top]

Create a New Product Document

CATDocument *pDoc = NULL;
rc = CATDocumentServices::New("Product",
                              pDoc);

//Process return code error.
...	

A new Product document is created using the New method of CATDocumentServices. This is the document that will contain an instance of the new derived StartUp "CAAOsmNewAdd" created with the CATOsmSUFactory generic factory.

[Top]

Create a Catalog for the New Derived StartUp

1. Create the catalog.

CATICatalog *piCatalog = NULL;
CATUnicodeString catalogStorage = pCatStorageName;
rc = ::CreateCatalog(&catalogStorage, 
                     &piCatalog);

//Process return code error. 
...   

A new catalog is created using the CreateCatalog global function. This function takes two arguments:

• catalogStorage - the CATUnicodeString storage pathname, name and .CATfct extension where the catalog will be stored. In this case, the value of catalogStorage comes from pCatStorageName which is passed in as an argument to the function.
• piCatalog - the returned CATICatalog pointer to the new catalog created.

2. Assign a client identifier to the catalog.

CATUnicodeString clientId("CAAOsmNewClientId");
rc = piCatalog -> SetClientId(&clientId);

//Process return code error. 
...

The catalog is uniquely identified using the SetClientId method of CATICatalog. This identification is necessary in order to access the catalog later on. This identifier should remain unique to this particular catalog.

[Top]

Use the Generic StartUp Factory to Create the New Derived StartUp

CATUnicodeString newSUType("CAAOsmNewAdd");
CATISpecObject *piNewAddSU = NULL;
CATUnicodeString superType("CAAOsmAdd");
CATUnicodeString catalog("CAAOsmCatalogSU");
CATBoolean publicSU = TRUE;
CATBoolean derivableSU = TRUE;
	
rc = ::CATOsmSUFactory (&piNewAddSU,
                        &newSUType,
		        piCatalog,
                        &superType,
			&catalog,
			publicSU,
			derivableSU);

//Process return code error. 
...

The new derived StartUp is created using the CATOsmSUFactory generic factory. This factory takes the following arguments:

• piNewAddSU - the new StartUp created in the specified catalog
• newSUType - the late type of the new StartUp that is to be created
• piCatalog - the CATICatalog pointer to the client's catalog that will contain the new StartUp
• superType - the late type of the deriving StartUp -

The derived StartUp can be a StartUp created just before the current one - See the cpp file for an example: Just after the CAAOsmNewAdd StartUp creation, the CAAOsmNewAdd_deriv StartUp deriving from CAAOsmNewAdd has been created.

• catalog - the name (without the .feat or .CATfct suffix of the catalog containing the deriving StartUp
• publicSU - TRUE if the new StartUp to be created is meant to be "public"; FALSE otherwise
• derivableSU - TRUE if the new StartUp to be created is meant to be "public" and other StartUps are allowed to derive from it; FALSE otherwise

[Top]

Add a New Attribute to the StartUp

CATUnicodeString third("Third");
CATISpecAttribute *piThird = piNewAddSU -> AddAttribute(third,
		                                        tk_integer);
//Process return code error. 
...   

Now that the StartUp has been created, it can be enriched with new attributes over and above those inherited from its parent StartUp. This is done using the AddAttribute method on the CATISpecObject pointer returned by the factory.

[Top]

Instantiate the StartUp in the Part Document

1. Create a new applicative container for the new feature object.

CATIdent idAppliCont = "CATFeatCont";
CATIdent iContSU = NULL;

CATUnicodeString appliContIdentifier("CAAOsmSUCont");
CATBaseUnknown *pApplicativeContainer = NULL;
rc = ::CATCreateApplicativeContainer(&pApplicativeContainer,   // appli cont created
                                     pDoc,                     // document  
                                     idAppliCont,              // type of appli cont
				     IID_CATIContainer,        // interface type of appli cont
				     iContSU,                  // supertype of appli cont 
				     appliContIdentifier);     // name of appli cont

//Process return code error. 
...	

In this use case, we want to create a new feature in an applicative container. Therefore, the applicative container must first be created using 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 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 type of the container that will be created.
• IID_CATIContainer - the interface IID that this new applicative container will implement. 
• iContSU - this is the supertype of the applicative container. If left blank, the idAppliCont argument must be "CATFeatCont". Otherwise, this argument must itself be "CATFeatCont".
• appliContIdentifier - the name of this new applicative container.

See the CAAOsmAppliCont [6] use case for a more detailed description of this service (CATCreateApplicativeContainer) in interactive context.

2. Instantiate the StartUp as a new feature object in the applicative container.

CATISpecObject *piNewAddInst1 = piNewAddSU -> Instanciate(CATUnicodeString("CAAOsmNewAdd1"),
		                                          pApplicativeContainer);
piNewAddSU -> Release();
piNewAddSU = NULL;

pApplicativeContainer -> Release();
pApplicativeContainer = NULL;

//Process return code error. 
...   

piNewAddInst1 -> Release();
piNewAddInst1 = NULL;

To create a new feature object in the applicative container by instantiating the StartUp created above, use the Instanciate method of CATISpecObject on the StartUp pointer returned by the factory. This method takes the following arguments:

• "CAAOsmNewAdd1" - the new name of the feature object. The StartUp type will remain the same for all the features instantiated from it.
• pApplicativeContainer - the pointer to the applicative container in which the new feature object will be created.

Don't forget to release all pointers that will no longer be used.

[Top]

Save the New Catalog

rc = ::SaveCatalog(&piCatalog,
		   &catalogStorage);
piCatalog -> Release();
piCatalog = NULL;

//Process return code error. 
...    

A catalog is saved using the SaveCatalog global function. This function takes the following arguments:

• piCatalog - the CATICatalog pointer to the catalog to be saved.

• catalogStorage - the CATUnicodeString pathname, name and .CATfct extension of the catalog to be saved.

Note that whenever the "publicSU" argument of the CATOsmSUFactory generic factory is set to TRUE, the new StartUp created is "public" and an entry in the corresponding .CATSpecs declarative file is automatically made. This declarative file is automatically saved at the same time as the catalog and in the same file directory.

[Top]

Epilog

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

Note that the opened catalog documents do not need to be removed from the session.

[Top]

In Short

A StartUp is declared as "public" and "derivable" if its owner has authorized others to derive new StartUps from it. In this case, a generic factory called CATOsmSUFactory provided by the feature modeler can be used to create the new, derived StartUp. Once the factory has been executed and the new StartUp created in the client's catalog, the client can work with the StartUp in order to enrich it by adding new attributes using the AddAttribute method of CATISpecObject, or by instantiating it in an applicative container of his working document using the Instanciate method of CATISpecObject.

[Top]

References

History

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