Description

The EXPRESS compiler parses and checks information models defined in the EXPRESS language, then generates output that you can use with your programs.

An EXPRESS information model contains data structure definitions along with matching rules and constraints. The compiler can do extensive parse and type checking on such a model, and can produce:

• C++ class code for building programs around these structures.
• Java class code for building programs around these structures, using the EXPRESS to Java Converter.
• A data dictionary, in the ROSE data format, that application programs use to read and write STEP Part 21 files. These files are named after the schemas as <schemaname>.rose.
• EXPRESS parse information for the SDAI EXPRESS interpreter and AP conformance checking tool. These files are in the ROSE format, and are named after the schema with the _EXPX extension, as <schemaname>_EXPX.rose
• HTML and other formatted text from the EXPRESS definitions, using the EXPRESS to HTML Converter.

The EXPRESS compiler can also compile "short-form" schemas and link them against libraries of resource schemas, such as the STEP 40-series schemas.

Command Line

expfront [options] expfile1 [expfile2 ...]

express2cxx [options] expfile1 [expfile2 ...]

The express2cxx wrapper calls expfront with the -rose -classes options.

If more than one EXPRESS file is given, the tool parses them as if all files were concatenated into a single file. If a filename has no extension, the tool appends .exp The compiler recognizes the following options.

-help

Print the list of available options.

Options that control the error checking and warnings:

-level <level>

Set the level of checking, where level is one of 0, 1, 2, 3, 3+ or 3++. Refer to Schema Checking for details. Default level is 3++.

-local

Suppress errors and warnings due to schemas that are not available for checking.

-[no|very]strict

Control the strictness of schema checking. Strict checking is the default. Use -nostrict to produce fewer warnings. Refer to Schema Checking for details.

The -nostrict option will report only EXPRESS errors; no warnings will be reported. The -strict option excludes warnings that are excessively pedantic. The -verystrict option reports all warnings and errors.

-suppress

Suppress errors and warnings on precompiled schemas.

Options that control the writing of compiled schema data and the loading of precompiled schema data:

-noload

Prevents loading of precompiled schemas.

-nopath

Prevents loading of precompiled schemas from the runtime support directories. Only precompiled schemas found in the current directory will be loaded.

-write[all|none]

The -writeall option forces writing of precompiled data for all schemas. The -writenone option prevents any precompiled data from being written.

-[no]write <schema>

Forces writing of precompiled data for given schema. The -nowrite option inhibits writing of precompiled data for given schema.

Options that control the generated classes and of compiled schema data and the loading of precompiled schema data:

-c

Parse and resolve the EXPRESS schemas. No classes or ROSE data structure definitions are generated. This is the default behavior for the expfront tool. Equivalent to -noclasses -norose

-[no]classes

Generate / Do not generate C++ classes for the EXPRESS definitions. Default is to generate (-classes).

-[no]rose

Generate / Do not generate ROSE data dictionary. The files are named after the original EXPRESS schemas <schema-name>.rose. Default is to generate (-rose).

-forcerose

Generate a ROSE data dictionary even if one already exists.

The following options customize various aspects of the generated output. They are used in conjunction with the generate options above.

-aggfiles / -aggwithbase

Specify where the generated code for aggregates is placed. The default is -aggwithbase, which puts an aggregate into the same .h and .cxx files as its base type. The -aggfiles option puts each aggregate in a separate file.

-attcheck [local|global|none]

Specify how to check for conflicts with attribute names. The default is local, which checks for attributes that have the same name as their type. The global style checks for attribute names that conflict with any type in the schema. The none style disables all checks.

If a conflict is found, the compiler will prepend att_ to the attribute name in any generated code.

-cext <ext>

Specify a different body file extension for the generated class files. The default extension is .cxx. See -hext for changing the header file extension.

-[no]derived

Generate / Do not generate methods for derived attributes in C++ classes. The tool can generate access functions for derived attributes that do not contain function calls. As implemented, this may produce an invalid reference when one derived attribute depends upon another that was too complex to be generated. Default is not to generate (-noderived).

-entity <name>

Only generate C++ code for the given definition. This option assumes that you have previously generated code for any other referenced classes. It can be specified multiple times.

-hext <ext>

Specify a different header file extension for the generated class files. The default extension is .h. See -cext for changing the body file extension.

-[no]inverse

Generate / Do not generate methods for inverse attributes in C++ classes. The default behavior is not to generate such methods (-noinverse).

-namestyle [rose|sdai|fullsdai]

Name convention for generated C++ classes. The rose keyword selects the ROSE naming conventions; sdai selects SDAI C++ names without schema prefix; fullsdai selects full SDAI C++ names prefixed with schemas. The default is rose.

-o <dir>

Destination directory for generated files. The directory is created if needed. If the directory exists, files will be moved to <dir>.bak. The default directory is classes.

-prefix <str>

A name prefix for the generated C++ definitions. This will be prepended to all class and file names. A prefix can also be specified in a workingset file.

-schema <name>

Only generate C++ code for the given schema. This option assumes that you already have generated code for any other referenced classes. It can be specified multiple times.

-[no]virtual

Generate / Do Not Generate virtual base declarations in C++ classes. For code with no multiple inheritance, the -novirtual option will avoid the use of virtual base classes. Note, inappropriate use of this option can cause undefined behavior. Default is all superclasses virtual (-virtual).

-ws / -workingset <namefile>

Provide a control file with details about what to generate from the EXPRESS schemas. See Customizing Output with a Working Set File for more information.

Options for the shortform to longform converter

-shtolo

Enable the short to long form converter.

-shortform <name>

The name of the schema to be converted to longform. The default value is the first schema in the first file.

-lfoutfile <file>

The output file for the generated longform schema. The default file is <schemaname>_longform.exp

Options that control other useful behavior:

-extension <ext>

Use input files ending with <ext> instead of .exp.

-force

Forces the compiler to complete all passes, despite any errors.

-ignorefile <file>

Specify a file containing a list of types and entities that should be ignored.

Windows Control Panel

The EXPRESS Compiler Windows control panel is shown below. Run this by selecting EXPRESS Compiler from the Start Menu. The following sections describe the fields and setting on this control panel and show how to perform various tasks with the compiler.

How the Compiler Works

The EXPRESS compiler reads a text file containing EXPRESS definitions, parses the definitions, and checks them for consistency. If multiple files are given, the tool behaves as if all files were concatenated together into a single file.

At the top of the EXPRESS Compiler control panel is a text field for one or more schema files that you would like to compile. You can open the file dialog using Ctrl+O or the [...] button to the right. You can also drag and drop files from the Windows Explorer.

The checkboxes in the Compiler Output area control what sorts of things the compiler will generate from the EXPRESS definitions. Next to each checkbox is a button that brings up a dialog with additional options for that type of output.

The compiler always parses EXPRESS definitions, and checks them for consistency. From the command line, simply specify the EXPRESS file. No other arguments are required.

    % expfront schema.exp

You can specify various options to vary the intensity of the checking and reporting. These are described in greater detail in Schema Checking.

When C++ Classes is checked (as it is by default), or -classes is given on the command line, the compiler will write a C++ class definition for each entity, select, aggregate or enumeration in the EXPRESS file. By default the files are written to a subdirectory called classes under the working directory. See Generate C++ Classes for more information.

When Data Dictionary is checked or -rose is given on the command line, a file of compiled data structure definitions is generated for each schema. This data dictionary is used by application programs. Each file is put in the working directory and is named after the schema, <schema>.rose.

The compiler can also write parse information used by the SDAI EXPRESS interpreter and AP conformance checking tools to validate rules and functions. These are named after the schema with the _EXPX suffix: <schema>_EXPX.rose. These files are written into the working directory. See Generate Data Dictionary and Precompiled Schemas for more information.

When Short to Longform is checked or -shtolo is given on the command line, the compiler will expand a shortform schema (which references other schemas) into a longform schema (which is self-contained). See Shortform to Longform Converter for more information.

For more control over the generated output, you can specify a control file in the Use working set field. On the command line, you would use the -ws option. These files let you select subsets of definitions or other settings. See Customizing Output with a Working Set File for details.

The Load EXPX options are used with short form schemas. The compiler can resolve references by searching through precompiled definitions. See Short Forms and Libraries of Precompiled Schemas for details.

The Work in directory field controls where any generated files will be written. If you leave this blank, output will be put in the same directory as the first EXPRESS input file. When calling the compiler from the command line, all outputs are written to the current directory.

Schema Checking

The EXPRESS compiler parses EXPRESS definitions and performs extensive schema checking. The options described below vary the intensity of the checking and reporting. In the control panel, click on the Check EXPRESS options button to bring up a dialog with the options for parsing and resolving EXPRESS definitions..

The compiler can check usage of the EXPRESS built-in functions TYPEOF(), USEDIN(), and ROLESOF(). Since parameters of these functions are often string literals, typographic and formatting errors are common. These flaws in the string literals are reported as warnings rather than errors by the compiler

Use the Checking level field or -level option to control the amount of checking performed by expfront. By default the compiler does all checking (3++). The compiler supports the following, and each level includes all checking done in lower levels.

-level 0

Syntax Checking -- Verifies that the input conforms to EXPRESS language syntax. A few other types of errors will be detected, such as declaring an identifier more than once in a given scope.

-level 1

Structure and Reference Checking -- Examine the inheritance and type structure, and resolve all identifiers to the definitions they reference. Verify that the inheritance and definition graphs of entities, defined types and selects are acyclic.

-level 2

Type Checking -- Check that the result of expressions satisfy the constraints of type compatibility and assignment compatibility.

-level 3

Simple Value Checking -- Verify simple constraints on the values in the EXPRESS schema, such as whether aggregate lower bounds are less than upper bounds. More sophisticated constraints are checked by the following levels.

-level 3+

Intermediate Value Checking -- Check parameters to the built-in functions USEDIN(), TYPEOF(), and ROLESOF() for proper string formatting, resolution to defined types, and type compatibility.

-level 3++

Advanced Value Checking -- Perform the most intensive value checking. For example, the compiler will attempt to evaluate string literals passed through multiple levels of function calls.

These levels correspond roughly to the levels of checking defined in the EXPRESS Language Reference Manual (ISO 10303-11). However, this does not mean that the compiler performs all of the checks required by the standard for a particular level.

The Report field or the -strict and -nostrict options control how results are reported. With strict checking (the default), the compiler warns when it cannot completely check an EXPRESS construct. The construct may not be in error, but the compiler is unable to determine this. For example, when checking string values passed to USEDIN(), the compiler will warn if the string is constructed by an expressions more complicated than it can compute at compile time, so they can be checked by hand. Use the -nostrict option to suppress these warnings.

If you know that your schema has problems, you can select the Force all passes check box to make the compiler continue beyond the point where it would normally stop. On the command line, this is controlled by the -force option.

If you are linking against precompiled schemas that have errors, you can select No errors or warnings for precompiled schemas or by the -suppress option to avoid excessive messages associated with the precompiled schemas.

If you are compiling a short form schema and some schemas are not present, you can select Ignore missing schemas to avoid excessive errors associated with the missing definitions. On the command line, this is controlled by the -local option.

Finally, functions sometimes refer to types that are not included in a schema. For example, the AP203 valid_units function (originally from Part 41) references several types that were not included in AP203, such as luminous_intensity_measure. This results in warnings like the one shown below:

    "203.exp", line 5556: warning: Undefined entity or defined type `TIME_MEASURE' in TYPEOF.

These warnings can be suppressed by specifying a file containing the names of types which should be assumed to exist. Use the Ignore entities and tyles listed in text file field or the -ignorefile option to provide the name of the file. The contents of the AP203 ignore file are shown below:

    TIME_MEASURE
    ELECTRIC_CURRENT_MEASURE
    THERMODYNAMIC_TEMPERATURE_MEASURE
    AMOUNT_OF_SUBSTANCE_MEASURE
    LUMINOUS_INTENSITY_MEASURE
    RATIO_MEASURE
    SHELL_BASED_WIREFRAME_REPRESENTATION
    GEOMETRICALLY_BOUNDED_WIREFRAME_REPRESENTATION

Generate C++ Classes

The compiler can generate C++ for use in building programs around the entity, select, aggregate and enumeration definitions in a schema. In the control panel, check the C++ Classes box or use the -classes option. The C++ Classes Options button brings up additional controls for customizing the generated code.

The C++ source code is written to .cxx and .h files in a subdirectory called classes under the working directory. If this would overwrite an existing file, the existing file is moved to a backup directory classes.bak.

The compiler generates a master include file <schema>.h that brings in all definitions for that schema. It also generates a <schema>_ROSE_LOAD.h file containing ROSE_LOAD() calls for each type in the schema. This can be used to force linkers to bring in all of the object files for a schema.

On the command line, the simplest way to generate classes is as follows. Programs that use the classes also need the data dictionary files generated by the -rose option. You can omit this if the data dictionary files have been previously generated, such as with the pre-installed schemas in $ROSE/system_db/schemas.

    % expfront -classes -rose schema.exp 

If you have a control file for selecting certain definitions or forcing AND/OR classes to be generated, specify it under the Use working set field. See Customizing Output with a Working Set File for more details.

In the Class Options section of the options dialog, the Use name style control or -namestyle command line option control how EXPRESS definition names are turned into C++ symbols. The default is to use the rose naming style, which uses the name with the same case as it appears in the EXPRESS. These conventions are described with the ROSE Library.

The Check att names field and -attcheck option controls what happens when attributes and types use the same name. The default local style looks for attributes with the same name as their type. The global style checks attribute names for conflict with any type in the schema. The none style disables checking. If a conflict is found, the compiler will prepend att_ to the attribute name in any generated code.

The Add name prefix field or -prefix option prepend a string to the definition names. This can also be done within a workingset file.

The Avoid virtual superclasses and -novirtual option. This will minimize the use of virtual base classes, but is not recommended because of potential conflicts if you add AND/OR or other multiple inheritance classes later on.

The Use derived attributes and -derived option attempt to generate code for some derived attributes. Only simple expressions can be handled in this way.

The Use inverse attributes and -inverse option attempt to generate code for inverse attributes. Backpointers must be computed using the rose_compute_backpointers for the inverse attributes to work with acceptable performance, and it is up to the application programmer to make sure that they are current. Refer to the ROSE Library Reference Manual for more information.

In the File Options section of the options dialog, use the Write ROSE data dictionary for classes or -rose command line option to control the data dictionary files as described above. The Force new ROSE file even if one exists and -forcerose options will ignore any pre-installed data dictionaries and always write a new one.

Aggregates are normally put into the same .h and .cxx files as their base type. If you prefer separate source files for each aggregate, select Write aggregates to separate files or use the -aggfiles command line option.

By default, the generated classes are put in a subdirectory called classes. You can specify a different name in the Classes output folder field or use the -o option on the command line.

The generated C++ source files have a .cxx extension and the header files have a .h extension. If you prefer a different extension, you can specify it in the Header file extension field or the Body file extension field. On the command line, these are controlled by the -cext and -hext options.

The Generate specific definitions fields command the compiler to only produce C++ code for the given list of schemas or entities. This option assumes that you already have generated code for any other referenced classes. On the command line, this is controlled by the -schema and -entity options. You can specify them multiple times.

Generate Data Dictionary and Precompiled Schemas

The compiler can generate two types of schema dictionary information. Data dictionary files, <schema>.rose, are used by all application programs. The parse data files, <schema>_EXPX.rose, are used by the SDAI, AP conformance checker, and the compiler as described in Short Forms and Libraries of Precompiled Schemas.

In the control panel, check the Data Dictionary box and use the associated Options button to bring up the options dialog. On the command line, use the -rose option to generate <schema>.rose data dictionary files. The <schema>_EXPX.rose parse data files are written by default when the command line version of the compiler is used. To suppress them, use the -nowrite option:

    % expfront -rose schema.exp 

The Precompiled schemas options control which schemas should have precompiled parse information. The Write all schemas option and -writeall flag saves parse data for all input schemas. Use Except or the -nowrite command line option to suppress the writing of certain schemas.

The Write no schemas option and -writenone flag suppresses the writing of all parse data. Use Force or the -write command line option to selectively force the writing of certain schemas.

The Write ROSE data dictionary for classes or -rose command line option generates the data dictionary files. The Force new ROSE file even if one exists and -forcerose options will ignore any pre-installed data dictionaries and always write a new one.

Once you generate the data dictionary or precompiled parse data files you should consider copying them in to ST-Runtime installed schemas area so that other applications can find them.

Short Forms and Libraries of Precompiled Schemas

The compiler parses and resolves all of the EXPRESS definitions in the input files. If there are any unresolved schemas, the compiler will search for precompiled schema information to resolve those definitions. This allows, for example, the entire library of STEP Integrated Resources to be precompiled and automatically loaded whenever a STEP short-form AP is compiled.

This can be suppressed with the -noload option. The compiler searches for precompiled schemas in the ST-Runtime support directories. This behavior can be changed using the -nopath option.

Once all schemas have been either loaded or determined to be unavailable, the compiler checks the EXPRESS model as a whole. During this phase, the -suppress and -local options can control whether or not errors and warnings that are due to schemas that are either unavailable or that were precompiled and loaded are reported.

After checking is finished, precompiled parse data for each schema is written to a <schema-name>_EXPX.rose file. The files are always written to the current directory. Only schemas given as input files or precompiled schemas that changed (by being more completely resolved) are written. This behavior can be changed using the -writeall, -writenone, -write, or -nowrite options.

Customizing Output with a Working Set File

Working set files are small text file that give more information to the compiler about how you want your classes and other output generated. You can use these control files to generate a subset of definitions, change the naming of particular classes, or force the compiler to generate complex AND/OR classes or extra aggregates.

Tell the compiler to use a working set file with the -ws command line option or the Use working set field of the EXPRESS compiler control panel. Refer to the Working Set documentation in the ROSE Library manual for a full discussion of working file syntax, usage, and options.

Shortform to Longform Converter

When Short to Longform is checked on the control panel or -shtolo is given on the command line, the compiler will expand a shortform schema (which references other schemas) into a longform schema (which is self-contained). The associated options dialog controls aspects of the process. .

The Main schema option and the -shortform command line option give the name of the EXPRESS schema to be expanded. By default, the first schema in the first file will be expanded. Any remaining schemas are compiled and used to resolve REFERENCE FROM or USE FROM statements, superseding any separately-compiled schemas which may be available.

The Base filename option and the -lfoutfile command line option give the output filename for the longform schema. By default, the filename will be constructed from the schema as <schemaname>_longform.