Introduction

• Set up the run time environment 

  mkCreateRuntimeView mkrun -c "cmd"

[Top]

Getting started

The osm modeling language in short

Osm modeling language is an easy and compact way to define a feature data structure.

The following use case is based on #CAAOsmCatalogSU use case[2].

In this article we use an executable: the CATfctEditorAssistant to compile .CATfct file

$ CATfctEditorAssistant -h
usage: CATfctEditorAssistant -client-id id [-generate-osm|-upgrade-catalog|-new-catalog] files...
where:
generate osm file according to feat file
 -client-id id set your client id to set catalog ownership
 -generate-osm xxx.CATfct xxx.osm
upgrading a feat file by adding xxx.osm
 -upgrade-catalog xxx.CATfct xxx.osm
create a catalog file and is xxx.osm
 -new-catalog xxx.CATfct xxx.osm

Lets start by creating an empty catalog and an empty osm file using CATfctEditorAssistant

$ CATfctEditorAssistant -client-id MyUserId -new-catalog CAAOsmCatalogSU.CATfct CAAOsmCatalogSU.osm

Once it is created, you have to move the CAAosmCatalogSU.CATfct from the current directory to the run-time directory:

You can do this using the mkCreateRuntimeView command.

To modify this empty catalog you are going to upgrade it with a osm file.

Here is an example of one of the simplest catalog you can define.
We create one startup CATOsmBook.

 /*
 * The bookshop catalog
 */
document `CAAOsmCatalogSU.CATfct` 
{
        container RootCont #root 
 {
        feature CATOsmBook #startup 
 {
        string Title  
        specobject BookPublisher
 }
 }
}

1. define a document scope, named "catalog.CATfct".
• Identifiers containing special character has to be escaped by backquoting the identifier. You need to backquote if the identifier contains non alphanumerical character and does not begin with a letter, an underscore or the dollar sign ('a'-'z', 'A'-Z', '_' or '$').
• The language is case sensitive.
• The documents name is always the basename of the filename (you should not specify any path).
• Keep in mind that documents name is case sensitive on UNICES systems.
2. define a container scope, named and typed RootCont.
• The "#root" token means that the container is a root container. 
• For osm language all token beginning by a sharp symbol are facets that alter statement behavior. 
• Facet are always prefixed by a sharp '#' and can be combined, order is not important. 
• When a facet take a value, it is set by surrounding the value by a parenthesis. example #external_link_meta_data(`MyMetaData`).
3. define a feature scope, named and typed CATOsmBook. The "#startup" facet means that the feature is not an instance but a startup
• add a string attribute named Title on CATOsmBook.
  
• Instead of C++, the statement delimiter is the <CR> character but you can use semicolon ';' to put several statement on the same line.

Now compile !

$ CATfctEditorAssistant -client-id id -upgrade-catalog CAAOsmCatalogSU.osm CAAOsmCatalogSU.CATfct 

In current directory we have now a CAAOsmCatalogSU.CATfct file.
 Dont forget to move the new generated catalog from the current directory to the run-time directory.

The CATfctEditorAssistant compiler

1. The CATfctEditorAssistant compiler enables you to check that your osm source file is syntaxically correct.
   
2. It embed your source file in the catalog file.
3. It can generate the osm source of an existing catalog.

Catalogs contains the data definition of all feature and are very similar to dynamic linked library (DLL).
Like DLL are located thru the PATH environment, a catalog is located thru a V5 official environment variable CATGraphicPath.

Keep in mind that CATGraphicPath environment variable is used to search existing catalog. CATfctEditorAssistant tool always load the first catalog found in your CATGraphicPath. 

When specified the directory path is used to save at the specified directory. If unspecified it save in current directory.

CATfctEditorAssistant compiler usage

Here follow the three most usefull options to handle catalog files.

$ CATfctEditorAssistant -client-id id -generate-osm catalog.CATfct catalog.osm 
$ CATfctEditorAssistant -client-id id -upgrade-catalog catalog.CATfct catalog.osm 
$ CATfctEditorAssistant -client-id id -new-catalog catalog.osm catalog.CATfct 

1. Generate the osm source code from catalog file.
• The catalog must be located in CATGraphicPath.
2. Upgrade the catalog by applying osm file. You can :
   • create container
   • add new feature
   • update some part of feature definition
   • add new attribute
   • update attribute definition
   • set attribute value
   •   Document's name `catalog.CATfct` written in osm source file and command line argument basename must be the same.
3. Create a catalog from scratch.
   • This option can be used to create a new catalog.

/ BE CAREFULL WHEN USING THIS OPTION

read the next section

How to manage document and containers

How to create a new catalog and the root container

Before creating a new catalog, verify that you have a clear understanding of how you want to create your container structure.

after creation there is no way to remove a container.

Suppose that you want create a catalog named CAAOsmCatalogSU.CATfct with a root container named RootCont.

document `CAAOsmCatalogSU.CATfct`
{
 container RootCont #root  
 {
 }
}

1. Always define the root container.

An existing root container is requested to create the document

Run the CATfctEditorAssistant compiler :

$ CATfctEditorAssistant -client-id id -new-catalog CAAOsmCatalogSU.osm CAAOsmCatalogSU.CATfct 

1. Notice that you have to specify the full target path.
• This will overwrite your sourcefile and add some important data to your source code

The latest command produces a file that much more look like that :

document `CAAOsmCatalogSU.CATfct` {
 container RootCont #root {
 ...

How to create a new feature?

There are several ways to create features

document `CAAOsmCatalogSU.CATfct` 
{
 container RootCont #root
{
feature CATOsmBook #startup {} 
feature CATOsmNovel CATOsmBook #startup {} 
feature `Book.1` CATOsmBook {} 

1. Create CATOsmBook startup. Note the #startup facet. the late type is CATOsmBook.
2. This statement creates a sub startup of CATOsmBook named CATOsmNovel.
3. This creates an instance of CATOsmBook named Book.1 in the current container scope.

You may have to create instance to initialize your startup. Or if you have to define predefined reference feature.

After upgrading and re-generating the source code look like

document `CAAOsmCatalogSU.CATfct` {
 container RootCont #root { 
 feature CATOsmBook#1 #startup { 
}
feature CATOsmNovel#2 CATOsmBook#1 #startup {
 }
 feature `Book.1`#4 CATOsmBook#1 {
 }

1. The generator adds #nn tag after the declaration.

This insure stability of persistant tag. This tag is required for an efficient feature lookup.

/ THE TAG IS A REQUIREMENT FOR CATALOG COMPATIBILITY.-new-catalog

/ The tag is required when you want to create two instances with the same name.

How to define the instance reference or the startup super type ?

In previous section we have seen how to create a startup super class or reference in the same container. But suppose that we have to create the CATOsmDictionary startup in another catalog. We need also to create an instance of Book.1 and an instance of CATOsmBook :

document `AnotherSU.CATfct` {
 container RootCont #root {
 catalog_manager `CAAOsmCatalogSU.CATfct` 
feature CATOsmDictionary CATOsmBook@`CAAOsmCatalogSU.CATfct` #startup {} 
feature `Book.1` CATOsmBook@`CAAOsmCatalogSU.CATfct` {} 
feature `Book.2` `Book.1`@`CAAOsmCatalogSU.CATfct` {} 

1. This statement registers a catalog_manager.
• Keep in mind, that catalog_manager are local to container and is an hidden feature. It is located by scanning the container... So you better have to create this feature as soon as possible. When you create a new catalog introduce one of this statement just after the container declaration.
  Hint If you do not need a catalog insert catalog_manager `ObjectSpecsModeler.feat` This catalog is always loaded by FeatureModeler.
2. Create CATOsmDictionary as a startup using CATOsmBook startup in CAAOsmCatalogSU.CATfct.
3. Create a first instance named Book.1 using CATOsmBook startup in CAAOsmCatalogSU.CATfct.
4. Create Book.2 an instance of Book.1 of CAAOsmCatalogSU.CATfct.

 Note that there is two Book.1 instances one in CAAOsmCatalogSU and one in AnotherSU.
 

Notice that defining a reference and subclassing use the same syntactical construction, the #startup facet change the behavior.

Some way to reference an existing feature

Here follows several way to specify an existing feature.

 
MyFeature 
MyFeature@SubCont 
MyFeature@`Other.CATfct` 
MyFeature@SubCont@`Other.CATfct` 

1. locating by name
2. locating in the sub container SubCont in the same document
3. locating in the root container in another document
4. locating a sub container in another document

How to add an attribute on a startup?

Suppose that we want create a catalog to describe book content.

/*
* a naive book content modeling
*/
document `CATOsmBookContent.CATfct`
{
 container RootCont #root
 {
feature CATOsmBook #startup {
  component style #list // list of style  
 }
 feature CATOsmStyle #startup {
  string font_name  
  double font_size  
         boolean underline  ; int background; int foreground
 }

 feature CATOsmItem #startup {}
 feature CATOsmText CATOsmItem #startup {
  specobject style  
  string text
 }
 feature CATOsmImage CATOsmItem #startup {
 external image_link
 }
 }
}

Create an attribute typed as:

1. component list
2. string named font_name
3. double named font_size
4. boolean named underline and two int named background and foreground
5. specobject name private access

How to define quality ?

• The #in, #out enable you too specify the quality of an attribute.

 The #in_external can also be set on external attribute to propagate update on pointed object.

How to modify an attribute?

You should never modify attribute definition.
Removing or modifiying an attribute type or quality can leads to data upward compatibility or memory capacity issues.
As an unset attribute cost nothing, the solution is to create a new attribute.

How to set a value?

You may have to set value after defining all feature.</br> You can do that by assigning the value to an attribute.
Values are always constants, and must be set after all feature creation
Here is an example of an attribute we want to set to 5

document `catalog.CATfct` {
 container RootCont #root {
 catalog_manager `ObjectSpecsModeler.feat`
  feature MyStartup#2 #startup { 
  double X 
 X = 5. 
 }
 }
}

1. The with construction is used for feature lookup.
• If it does not exist the with statement emit an error.
2. set X to 5. See How to format a value ?

How to format a value ?

 b'0fabced0-00-555555' delimited binary

[ 0xf, 0xab, 0xce, 0xd0, 0x00, 0x55, 0x55, 0x55 ]

[Top]

How to define an extension feature

An extension feature is an extension that inherit from FeatExt. FeatExt is a virtual type defined by the feature modeler.

document `CAAOsmCatalogSU.CATfct` 
{
 container RootCont #root
{
feature CAAOsmHistoricalNovel FeatExt@`ObjectSpecsModeler.feat` #startup {} 

What to do when something goes wrong?

Error format, source and severity

Here is a typical CATfctEditorAssistant error message

[E] OSM-CVT : created catalog is not the first in CATGraphicPath  : { doc='catalog .feat', found='...\intel_a\resources\graphic\.' }

 The error severity begin any message there is three level of severity : 
 

 This is the error source. It indicates which OSM components emites the error. 
 Most of the errors source from CATfctEditorAssistant are :
 

3. an human explaination of the error

4. some usefull data that help to understand the context

Omsfeat is a two pass compiler :

Compilation error

Now suppose that we have wrote the following catalog source:

 document `catalog.CATfct` 
 {
 catalog_manager `catalog.CATfct`
 container RootCont #root 
 {
 feature MyStartup #startup 
 {
 double X :
 }
 feature MyStartup2 MyStarup #starup
{
double y
 }
 }
 }

$ CATfctEditorAssistant -client-id id -create-feat ...\intel_a\resources\graphic\catalog.CATfct catalog.osm
[E] OSM-PAR: catalog.osm:3: parse error, unexpected `OSMKCatalogManager', expect
ing `OSMKContainer' or `OSMKEnd' or `OSMKMetaDataDef' near 'catalog_manager'
catalog_manager `catalog.CATfct` 
[E] OSM-PAR: catalog.osm: 1 error(s) found during parse

1. Compilation errors indicate the source filename and the line number where the errors are detected
2. Parse errors occur during the first pass.
• The most important data is the "near 'catalog_manager'" which tell where in the line the syntax error is. 
• The error also enumerate the token type the parser expected</br> Here it means that a OSMKCatalogManager token is unexpected (ie. catalog_manager keyword), the compiler expects a OSMKContainer (ie. container), a OSMKEnd (<CR> or ';') or an OSMKMetaDataDef.
3. It prints the current line. This feature is disable when the source file is not available
4. Summary of errors and warnings.

Ho, yes! the catalog_manager have to be in a container scope. corrected file :

 document `catalog.CATfct` 
 {
 container RootCont #root 
 {
 catalog_manager `catalog.CATfct`
 feature MyStartup #startup 
 {
 double X :
 }
 feature MyStartup2 MyStarup #starup
{
double y
 }
 }
 }

[E] OSM-PAR: catalog.osm:8: parse error, unexpected `$undefined.', expecting `OS
MKEnd' or `OSMKFacet' or `'='' near ':'
 double X :
[E] OSM-PAR: catalog.osm:10: invalid facet name
feature MyStartup2 MyStarup #starup
[E] OSM-PAR: catalog.osm: 2 error(s) found during parse

1. Here there is an extraneous ':'
2. Here startup is mistyped
3. Summary of errors and warnings.

Runtime errors

Run again CATfctEditorAssistant compiler.

[E] OSM-PAR: catalog.osm:10: cannot find reference : { feature='MyStartup2',
reference='MyStarup', container='RootCont', document='catalog.CATfct' }
feature MyStartup2 MyStarup #startup 
[E] OSM-PAR: catalog.osm: 1 error(s) found during evaluation
[W] OSM-PAR: catalog.osm: 1 warning(s) found during evaluation

Here, the error occurs at line 5, with catalog.CATfct in container RootCont in document catalog.CATfct.

1. The message tell you that the reference is not found. MyStarup is mistyped
2. note that now we have evaluation error not parse error!

References

History

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