Managing StartUp Catalogs

Technical Article

Abstract

Applications create feature objects by instantiating feature startups stored in catalogs. This article explains the process of how these catalogs are created and updated.

Foreword

It is assumed that you are already familiar with the concepts of the Feature Modeler [1], the OSM language [2] and the StartUp catalogs [3]. The focus of this article is on how the StartUp catalogs are created and updated using a command-line tool called CATfctEditorAssistant.

Each catalog managing step corresponds to one of CATfctEditorAssistant:

The CATfctEditorAssistant Command

The syntax of the CATfctEditorAssistant command is:

CATfctEditorAssistant options catfct_path osm_path
CATfctEditorAssistant Description Required Exclusive
Option
options -client-id id the client ID yes  
-new-catalog to create a new catalog   yes
-upgrade-catalog to upgrade an existing catalog   yes
-generate-osm to generate the OSM from and existing catalog   yes
arguments catfct_path the path to the catalog or .CAfct file yes  
osm_path the path to the OSM file yes  

We will now describe the functionality of each option.

Creating a New Empty Catalog

Every catalog becomes created this way: as an empty catalog with the -new-catalog option. This option does not convert an OSM to a catalog, it creates an empty catalog and the corresponding OSM file.

Both the catfct_path and osm_path arguments specify output arguments.

CATfctEditorAssistant -client-id id -new-catalog catfct_path osm_path

The -client-id option is required because the newly created empty catalog will be assigned a client id.

The OSM file only contains two statements describing the catalog with its empty root container:

/**
 * Copyright Dassault Systemes 2006
 * .osm file skeleton 
 */ 
document `MyCatalog.CATfct` {
  container RootCont #root {
    // insert here your startups
  }
}

Do not forget to move the newly created catalog in the run-time view so that it can be updated subsequently.

Updating a Catalog

The -upgrade-catalog option takes an existing catalog and an input OSM to output a new updated catalog.

The catfct_path argument designates both an input catalog and the path to the new updated one. During the input phase of the update, CATfctEditorAssistant will access the catalog using its name only (just like any application code accessing catalogs). The catalog to be updated must therefore be in the run-time view: OS_directory/resources/graphic. In the output phase however, the catalog is created at the location specified.

The osm_path argument is the path to the input OSM. This OSM must at least describe the existing catalog (which can be obtained with the -generate-osm option) and additional modifications. Not all types of modification are allowed because of the compatibility of previously created features. As these features were instantiated from the catalog, their StartUp or attributes must not be deleted for example.

CATfctEditorAssistant -client-id id -upgrade-catalog catfct_path osm_path

Again the -client-id option is necessary to upgrade the catalog.

Notes:

Retrieving the OSM of a Catalog

The -generate-osm option takes an existing catalog and outputs its description in OSM. This option can be used to verify the contents of a catalog or prior to modify it.

The catfct_path argument specifies an existing catalog in the run-time view: OS_directory/resources/graphic. Only the name will be kept for the lookup.

The osm_path argument specifies the location of the output OSM file.

CATfctEditorAssistant -client-id id -generate-osm catfct_path osm_path

Note: every identifier will have suffixes of the form #number . These are internal identification tags that help speeding up feature lookup and should be left as is.

Again the -client-id option is necessary to generation the OSM equivalent of a catalog.

Localizing a Catalog

When a feature is displayed on screen, its identifier is used unless this identifier is given a localized name thanks to an associated CATNls file. This file must have the same name as the catalog's appended with NLS. For example the CATNls file associated to the MyCatalog.CATfct catalog would be MyCatalogNLS.CATNls. This file should be created in the CNext/resources/msgcatalog directory of the workspace.

Such a CATNls file contains associations of the form feature_identifier="localized name";

In Short

In this article, we have detailed the process of how StartUp catalogs are maintained and the CATfctEditorAssistant tool that is used. The most important thing is the catalog update pattern:

  1. create an empty catalog
  2. modify the OSM
  3. upgrade the catalog
  4. generate the OSM and back to step 2.

References

[1] Feature Modeler Concepts
[2] Modeling Feature StartUps
[3] Understanding Feature StatUp Catalogs

History

Version: 1 [Aug 2007] Document created