read_exchange_structure

read_exchange_structure program

Vincent Marchetti
email: vmarchetti@kshell.com
site: https://www.kshell.com

Introduction

read_exchange_structure is a command-line program which reads a text STEP Part 21 data exchange file. In the default (no command line arguments) the program reads from standard input and exits silently, with return code 0. Options for interesting output is selected by command line arguments and can be one of:

A collection of Prolog ground clauses
A set of Logtalk objects
A summary of the types of instances present in the Part 21 file.

The program returns with error code 1 if a syntax or semantic error is encountered reading either the Part 21 file or associated EXPRESS schema file. Other run-time errors result in error code 2. In either case, messages are written to standard error stream.

At run time the program reads the EXPRESS text file defining the schema which governs the data model exchanged in the Part 21 file. The schema file is specified either through a command line argument; or through a schema-catalog method. The schema-catalog method requires setting an environment variable and preparing an XML-format file specifying the locations of schema files.

This program is written in C++ and is compilable with the GCC 3.3 compiler. Source code and makefiles are included in this distribution. This program uses the open-source libxml2 (XML parser and toolkit) library and the Boost (C++ utilities) library, both of which must be installed prior to the configure-compile steps described below.

In a complete installation the program can be run from the command line; as an example

read_exchange_structure -p

reads an exchange structure from standard input stream and writes Prolog clauses to the standard output stream. The full set of command line options is described in Appendix B.

EXPRESS schema management

This program reads an EXPRESS schema file at run-time to allow interpretation of a STEP Part 21 exchange file. There are two ways in which the program may determine what schema file to read:

The command line option -s schema_file directs the program to read the specified EXPRESS schema file.
The program may determine the EXPRESS schema from the attribute values of the FILE_SCHEMA entity of the HEADER section of the exchange file. The program uses a configuration file to associate a file path with a schema identifier. This configuration file uses xml syntax as described in Appendix A. The location of this configuration file is determined by either of:
- A command line option -c configuration_file.
- The location of the configuration file may be specified by the environment variable EXPRESS_SCHEMA_CATALOG.

If the program exits with a syntax error it may be difficult to determine whether the error message refers to a syntax error encountered in the Part 21 exchange file or in the EXPRESS schema file. The command line option -v schema_file directs the program to read only the schema file and exit (silently) if no error is encountered; if the schema file passes this test it can be determined that subsequent error messages refer to the exchange file.

Compilation and installation

The top directory of this distribution contains the shell script file configure. Running this shell script, with the working directory set to the top directory of the distribution, will generate a Makefile. Compilation and installation is configured by setting the values of several environment variables as described below prior to running the configure script. Running the make utility with various targets will compile and optionally install the program and associated support files.

The read_exchange_structure program is compiled with the execution from the command line of the following commands (with the top directory of the distribution as the working directory):

./configure
make

After a successful compilation there will be a shell script read_exchange_structure.sh in the top directory which provides for a quick-start/test; running

./read_exchange_structure.sh exchange_file

will run the program reading an exchange file using the executable and EXPRESS schema in the distribution directories. The only schema provided in the distribution is for STEP AP 203. Note that the file locations are "hard-wired" in the read_exchange_structure.sh script, so it will cease working if files or directories are relocated.

The configured Makefile also provides two specific targets for installation; the install target combines both of these:

install_executable will install the program in the location specified (at configure time) by the environment variable EXEC_DIR or inferred by the PREFIX variable.
install_schema will install a configuration file and a EXPRESS schema file for STEP AP 203. The location will be determined by the environment variable EXPRESS_SCHEMA_CATALOG at configure time; if no value is set then a default location will be chosen and a required value for EXPRESS_SCHEMA_CATALOG will be reported. Running this make target will not modify or update pre-existing directories.

It is up to the user to set shell configuration files, etc. so that the appropriate value of EXPRESS_SCHEMA_CATALOG is set when the read_exchange_structure program is executed.

Environment variables controlling compilation and installation

Setting the required environment variables can be accomplished by setting these values (and exporting them) from the command shell; or directly on the command line unsing the env command line executabe. The variables which control compilation, linking, and installation are:

LIBXML2_CPPFLAGS: options which must be passed to the gcc (or compatible compiler) which may be needed to include headers for the GNOME XML libraries. A typical value for this is

export LIBXML2_CPPFLAGS=-I~/include/libxml2
LIBXML2_LDLIBS: options passed to the linker to force linking to the appropriate libraries or archives containg GNOME XML library program code. A typical value setting the ‘-l’ flag, and specifying several other libraries required by the XML libraries, is

export LIBXML_LDFLAGS=”-lxml2 -lz -lpthread -liconv -lm”
BOOST_CPPFLAGS: additional options to be passed to the C++ compiler to allow compiling with references to the Boost libraries. Typically these flags will specify the location of the Boost header files. This variable does not need to be defined if the Boost header files are installed in the standard compiler search path.
BOOST_LDLIBS: additional options to be passed to the linker to allow for linking with the Boost libraries. Typically these flags will specify the libraries to be dynamically linked as locations of the library files. If not defined, a reasonable guess is made for this variable, assuming the Boost libraries have been installed in a standard location.
EXEC_DIR: the location into which the read_exchange_structure program will be installed when the make command is run with target install. If not specified, this variable will be set to $PREFIX/bin if variable PREFIX is defined, or ~/bin otherwise.
SCHEMA_DIR: A location into which a folder express_schema will be copied. This folder will contain a schema_catalog file as well as EXPRESS schema files needed to read STEP files. The user will have to arrange having the environment variable EXPRESS_SCHEMA_CATALOG defined at the time the installed version of read_exchange_structure is executed. If not defined, an attempt will be made to deduce this variable from a defined EXPRESS_SCHEMA_CATALOG variable, or the choice $PREFIX/etc or ~/etc. In any case an existing directory located at $SCHEMA_DIR will not be overwritten or modified.

Some installations of the GNOME XML libraries include a shell script xml2-config which can automatically provide values for LIBXML2_CPPFLAGS and LIBXML2_LDLIBS. If these environment variables are not defined when configure is invoked, and if the xml2-config script is installed in the PATH of the environment, then the environment variable will be set using xml2-config.

Appendix A: schema-catalog

A schema-catalog file is used to locate an EXPRESS schema for a Part 21 file at run time, based on the schema identifiers in the Part 21 file's HEADER section. A schema-catalog file matches the schema identifier label with a file system path. The comparison between the schema identifier in the Part 21 file and the label in the schema-catalog is case-insensitive. The path in the schema-catalog will be resolved by the program relative to the location of the schema-catalog file. A typical installation will put the schema-catalog file and the schema files in the same directory; then the path data may simply be the base-name of the schema file.

Example of a schema-catalog file, including embedded DTD:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE schema_catalog [ <!ELEMENT schema_catalog (schema)*> <!ELEMENT schema (description? , identifier+)> <!ATTLIST schema path CDATA #REQUIRED> <!ATTLIST schema status CDATA #IMPLIED> <!ELEMENT description (#PCDATA)> <!ELEMENT identifier (label)> <!ELEMENT label (#PCDATA)> ]> <schema_catalog> <schema path="10303-203-aim-long.exp" status="IS"> <description> This is the ISO 10303:203 Am1 (2000) EXPRESS definition </description> <identifier><label>CONFIG_CONTROL_DESIGN</label></identifier> <identifier><label>AP203</label></identifier> </schema> </schema_catalog>

schema-catalog notes

The description element and the status attribute of the schema element are optional and are not used by the program.

The label element is buried inside an identifier element because future versions will allow for identifying a schema through its object identifier; the identifier element will then contain an object_identifier element instead of a label.

Appendix B: Command line options

-h | --help: display help information
-f | --file filename: reads input from the file filename rather than standard input
-o | --output filename: writes output to the file filename rather than standard output
-v | --verify_schema filename: reads the passed filename as an EXPRESS schema, used to verify that this file can be used by this program to control reading of Part 21 files. No Part 21 file is read; and any errors reported pertain to reading the EXPRESS schema file.
-l | --locate_schema label: invokes the schema-catalog method to determine the file path of the EXPRESS schema identified by the label argument. Writes the file path to standard output.
-p | --prolog: generate prolog output.
-g | --logtalk: generate logtalk output.
-e | --entity_sets: generates output summarizing instances by their entities.
-i | --ignore_entities entity: ignore instances containing the entity passed as argument. This option may be repeated, however its use even once is highly deprecated; it is an artifact from an early development of this software and will probably be removed in future releases.
-s | --schema filename: Use the passed filename as an EXPRESS schema to interpret the Part 21 file. This file will be used regardless of the schema identifiers specified in the Part 21 HEADER section.
-c | --catalog filename: Use the passed filename as a schema-catalog to locate schema files. Use of this option is an alternative to specifying the catalog file in the EXPRESS_SCHEMA_CATALOG environment variable. In either case, the location of the catalog file (its directory) is used to resolve relative locations specified in the catalog file for the schema files.
-x | --xml_message: report errors resulting from syntax/semantic errors in the schema or Part 21 files as xml-formatted strings