Managing Public Features and Attributes

3D PLM PPR Hub Open Gateway	Feature Modeler	Managing Public Features and Attributes Creating and updating the public specs (.CATSpecs) file
Use Case

Abstract

This article discusses the CAAOsmPublicSpecsFile use case. This use case explains how to define public features and attributes by adding new entries to the corresponding .CATSpecs file.

What You Will Learn With This Use Case
The CAAOsmPublicSpecsFile 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 define public features and attributes.

A "public" feature is a feature that is accessible in Read or Read/Write mode through exposed CAA API. A public feature may decide to allow some or all of its attributes to be accessed as well. These are then also said to be "public" attributes. Among the public features, some may be declared as being "derivable", i.e., a new feature deriving from this one can be created either using a provided factory or the specs builder. The .CATSpecs file contains an entry for each public feature, the list of the public attributes of each and a flag indicating whether or not it is a derivable feature. As of V5R8, the .CATSpecs file can be created and/or updated through the basic software provided with the Feature Modeler. However, for all features and attributes existing before V5R8 that are considered to be "public", a corresponding .CATSpecs file must be expressly created and/or updated in order for the new Feature Modeler software to be able to list public attributes or to allow the creation of a derived StartUp by the specs builder.

A .CATSpecs file corresponding to a .CATfct file must exist whenever the latter contains "public" features. The .CATSpecs file has the same name as the .CATfct file and is stored at the same location. In fact, the storage of the .CATSpecs file is performed automatically by the same global function that saves the .CATfct file (SaveCatalog).

This use case illustrates the update of the .CATSpecs file using a batch program. This is a procedure you will have to initially go through if you already have any "public" features.

[Top]

The CAAOsmPublicSpecsFile Use Case

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

[Top]

What Does CAAOsmPublicSpecsFile Do

The goal of CAAOsmPublicSpecsFile is to illustrate updating the .CATSpecs file corresponding to the existing CAAOsmCatalogSU.CATfct catalog created by the CAAOsmCatalogSU use case. Executing the CAAOsmCatalogSU use case is, therefore, a pre-requisite to the execution of this use case. The CAAOsmCatalogSU.CATfct contains the following StartUps that will be used here:
Fig.1 CAAOsmCatalogSU.CATfct

The initial creation of the CAAOsmCatalogSU.CATSpecs was done by the CAAOsmCatalogSU use case. This use case updates the file in three stages. In the first part, the file is updated with several of the StartUps already defined in the CAAOsmCatalogSU.CATfct catalog. Here is what the CAAOsmCatalogSU.CATSpecs file looks like at this stage:
Fig.2 Initial contents of CAAOsmCatalogSU.CATSpecs
<?xml version='1.0' encoding='ISO-8859-1' ?>


<CATSpecs>

...

<StartUp Type = "CAAOsmBook" Derivable = "TRUE">

<PublicAttribute Name = "Title"/>

<PublicAttribute Name = "BookPublisher"/>

</StartUp>

<StartUp Type = "CAAOsmNovel" Derivable = "FALSE">

<PublicAttribute Name = "Author"/>

</StartUp>

<StartUp Type = "CAAOsmDictionary" Derivable = "FALSE">

<PublicAttribute Name = "Language"/>

</StartUp>

</CATSpecs>

Fig.2 Initial contents of CAAOsmCatalogSU.CATSpecs
<?xml version='1.0' encoding='ISO-8859-1' ?> <!--Important: use only CAA API to modify this file!--> <CATSpecs> ... <StartUp Type = "CAAOsmBook" Derivable = "TRUE"> <PublicAttribute Name = "Title"/> <PublicAttribute Name = "BookPublisher"/> </StartUp> <StartUp Type = "CAAOsmNovel" Derivable = "FALSE"> <PublicAttribute Name = "Author"/> </StartUp> <StartUp Type = "CAAOsmDictionary" Derivable = "FALSE"> <PublicAttribute Name = "Language"/> </StartUp> </CATSpecs>

In the second stage, a new public, derivable StartUp and attribute are added in the CAAOsmCatalogSU.CATfct catalog which automatically updates the .CATSpecs file as seen below. Note that the StartUp's attribute has not been added to the file.

Fig.3 Contents of CAAOsmCatalogSU.CATSpecs with added public, derivable StartUp
<?xml version='1.0' encoding='ISO-8859-1' ?> <!--Important: use only CAA API to modify this file!--> <CATSpecs> ... <StartUp Type = "CAAOsmBiography" Derivable = "TRUE"> </StartUp> </CATSpecs>

In the third stage, we declare the "CAAOsmBiography" StartUp's attribute as being public by adding it to the CAAOsmCatalogSU.CATSpecs file:

Fig.4 Contents of CAAOsmCatalogSU.CATSpecs with added public attribute
<?xml version='1.0' encoding='ISO-8859-1' ?> <!--Important: use only CAA API to modify this file!--> <CATSpecs> ... <StartUp Type = "CAAOsmBiography" Derivable = "TRUE"> <PublicAttribute Name = "PersonageName"/> </StartUp> </CATSpecs>

Each of the above update of the .CATSpecs file causes the storage of the file in a temporary directory. In order to permanently store the .CATSpecs file, the SaveCatalog function must be executed. This function saves the current catalog and any current .CATSpecs file found in the temporary directory in the same, permanent directory specified by the user.

[Top]

How to Launch CAAOsmPublicSpecsFile

To launch CAAOsmPublicSpecsFile, you will need to set up the build time environment, then compile CAAOsmMainSpecsFile.m along with its prerequisites, set up the run time environment, and then execute the use case. This is fully described in the referenced article [1]. To launch the use case, you must do the following:

mkrun -c "CAAOsmMainSpecsFile CAAOsmCatalogSU.CATfct CatalogStoragePathNameOut"

where:

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.
CatalogStoragePathNameOut - the storage pathname of the same .CATfct catalog. This is also the storage directory of the .CATSpecs file.

[Top]

Where to Find the CAAOsmPublicSpecsFile Code

The CAAOsmPublicSpecsFile code is located in the CAAOsmMainSpecsFile.m module of the CAAObjectSpecsModeler.edu framework. This module contains a unique source file, CAAOsmMainSpecsFile.cpp. Here is the installation path, depending on the operating system:

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

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

[Top]

Step-by-Step

There are five logical steps in CAAOsmPublicSpecsFile:

Loading the StartUp Catalog
Creating or Updating the Public Specs File
Creating a New StartUp
Adding New Public Attributes to the Public Specs File
Saving the Public Specs File

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

[Top]

Loading the StartUp Catalog

Before working with the .CATSpecs file, it is necessary to load the corresponding catalog into the current session:

CATUnicodeString stgName = argv[1];
CATICatalog *piCatalog = NULL;
CATUnicodeString clientId("CAAOsmClientId");
rc = ::UpgradeCatalog (&stgName,
                       &piCatalog,
	               &clientId); 

if (SUCCEEDED(rc)) cout << "Catalog accessed OK" << endl << flush;
else
{
   cout << "ERROR on UpgradeCatalog" << endl << flush;
   return 2;
}

The StartUp Catalog is loaded using the UpgradeCatalog global function. This function needs the entire storage pathname of the catalog. The catalog is protected from unauthorized Read/Write access by the clientId argument which is mandatory. The function then returns a CATICatalog pointer to the catalog.

[Top]

Creating or Updating the Public Specs File

HRESULT retCode = E_FAIL;
int numSpecs = 3;
PublicSpec *pSpecs = new PublicSpec[numSpecs];

pSpecs[0].pAttrNames = new CATUnicodeString[2];
pSpecs[0].type = "CAAOsmBook";
pSpecs[0].derivable = TRUE;
pSpecs[0].pAttrNames[0] = "Title";
pSpecs[0].pAttrNames[1] = "BookPublisher";
pSpecs[0].attrNumber = 2;

pSpecs[1].pAttrNames = new CATUnicodeString[1];
pSpecs[1].type = "CAAOsmNovel";
pSpecs[1].derivable = FALSE;
pSpecs[1].pAttrNames[0] = "Author";
pSpecs[1].attrNumber = 1;

pSpecs[2].pAttrNames = new CATUnicodeString[1];
pSpecs[2].type = "CAAOsmDictionary";
pSpecs[2].derivable = FALSE;
pSpecs[2].pAttrNames[0] = "Language";
pSpecs[2].attrNumber = 1;
    
retCode = ::CATCreatePublicSpecsInFile(&piCatalog, pSpecs, numSpecs);
if (retCode == S_OK) cout << "Public Specs created OK." << endl << flush;
else
{ 
   cout << "ERROR in CAAOsmMainSpecsFile" << endl << flush;
   return 3;
}
	
delete [] pSpecs[0].pAttrNames;
delete [] pSpecs[1].pAttrNames;
delete [] pSpecs[2].pAttrNames;
delete [] pSpecs;

The PublicSpec structure is instantiated for the number of public specs to be written in the file. Then the structure is filled with each spec's data: the type of spec, its derivability and its attributes. The CATCreatePublicSpecsInFile global function creates the .CATSpecs file (if it does not already exist) corresponding to the catalog whose pointer is passed as an input argument. If the corresponding .CATSpecs file already exists in the runtime view, it is simply updated with the data contained in the PublicSpec structure.

Do not forget to delete all allocations.

[Top]

Creating a New StartUp

1. Create a New StartUp.

CATBaseUnknown *pBiogSU = NULL;
CATUnicodeString biogSUName("CAAOsmBiography");
CATUnicodeString biogSUType("CAAOsmBiography");
const CATUnicodeString *superType = NULL;
CATBoolean publicSpec = TRUE;
CATBoolean derivable = TRUE;
rc = piCatalog -> CreateSUInCatalog (&pBiogSU,
                                     &biogSUName,
	     	                   &biogSUType,
				 "CATISpecObject",
				 superType,
				 publicSpec,
				 derivable);
if (NULL == pBiogSU) 
{
   cout << "ERROR in creating CAAOsmBiography StartUp" << endl << flush;
   piCatalog -> Release();
   return 4;
}
else cout << "CAAOsmBiography StartUp created OK" << endl << flush;

// Get a CATISpecObject handle on the CAAOsmBiography StartUp

CATISpecObject *piBiogSU = (CATISpecObject*) pBiogSU;

The CreateSUInCatalog method of CATICatalog creates a new StartUp in the current catalog. If the StartUp is declared to be public through the "publicSpec" argument, then this method also causes an entry to be made in the .CATSpecs file corresponding to the current catalog. The .CATSpecs file will contain only the type of the new StartUp and its derivability. Note that the .CATSpecs file may not yet exist; in this case, it is created.

2. Add a new attribute to the StartUp.

CATUnicodeString personageName("PersonageName");
CATISpecAttribute *piPersName = piBiogSU -> AddAttribute(personageName,
                                                         tk_string);
if (NULL == piPersName)
{
   cout << "ERROR in adding PersonageName attribute" << endl << flush;
   return 5;
}
else
{
   cout << "PersonageName attribute added OK" << endl << flush;
   piPersName -> Release();
   piPersName = NULL;
}

pBiogSU -> Release();
pBiogSU = NULL;

A new attribute is added to the StartUp using the AddAttribute of the CATISpecObject interface.

Remember to release the pointer to the new StartUp retrieved from CreateSUInCatalog.

Adding New Public Attributes to the Public Specs File

CATUnicodeString specsType("CAAOsmBiography");
CATUnicodeString attributeName("PersonageName");

retCode = ::CATAddPublicAttributeToFile(&piCatalog, specsType, attributeName);

if (retCode == S_OK) cout << "Attribute PersonageName added OK." << endl << flush;
else
{ 
   cout << "ERROR in CAAOsmMainSpecsFile" << endl << flush;
   return 6;
}

Attributes added to StartUps in the catalog are not automatically added to the corresponding .CATSpecs file. It is, therefore, necessary to perform this operation yourself in case there are public attributes to be declared. This operation may also be necessary if at any time you decide that an existing "private" attribute is to become "public". To update the .CATSpecs file with a new attribute, use the CATAddPublicAttributeToFile global function, specifying the pointer to the corresponding catalog, the type of the StartUp to which the attribute belongs and the attribute name.

[Top]

Saving the Public Specs File

stgName = argv[2]; rc = ::SaveCatalog(&piCatalog, &stgName); piCatalog -> Release(); piCatalog = NULL; if (FAILED(rc)) { cout << "ERROR in saving catalog document" << endl << flush; return 7; } else cout << "Catalog saved OK" << endl << flush;

The .CATSpecs file is saved at the same time and in the same directory as the corresponding catalog file. Use the SaveCatalog global function to do this. Remember that the storage directory should indicate CNext + resources + graphic in order for the catalog and public specs file to be correctly referenced in the runtime view.

[Top]

In Short

A .CATSpecs always has a corresponding .CATfct file. It contains an entry for each StartUp declared as "public". The .CATSpecs file is created or updated automatically by Feature Modeler software. However, for all StartUps existing before V5R8, the .CATSpecs file must be generated by a batch program. Use the CATCreatePublicSpecsInFile global function to create and/or update the .CATSpecs file. Use the CATAddPublicAttributeToFile in order to declare a new public attribute for an already existing public StartUp.

[Top]

References

[1]	Building and Launching a CAA V5 Use Case
[Top]

History

Version: 1 [June 2001]	Document created
[Top]

3D PLM PPR Hub Open Gateway

Feature Modeler