Using the ST-Developer C++ Libraries

Overview

ST-Developer ships with pre-built C++ class libraries for the common information models. You can start programming immediately, just by linking against the appropriate library. The easiest way to start is to use one of the sample programs we have provided for each library, then modify as needed.

If you prefer to start with a brand-new project, consult one of the guides below for the necessary settings:

The sections below describe some details to be aware of while writing your application. If we have not provided pre-built class library for the schema you are working with (or you want to change one of the preinstalled libraries) we have instructions for generating a class library from scratch.

Include Files

Your code must include the header file for the class definitions. There is a file [schema_name].h, but we also provide a header file called stp_schema.h for each of the STEP AP libraries.

Each AP library defines this file, so you can move code between different APs without changing the include definitions. The correct version of the stp_schema.h file will be found based on the compiler include path in your makefile/project settings.

#include <stp_schema.h>   /* for a STEP AP */

For non-STEP AP schemas (like CIS/2 and IFC), you must include the header file file with the schema name explicitly.

#include <[schema-name].h>   /* for a non-AP schemas */

#include <structural_frame_schema.h>   /* CIS/2 */
#include <ifc2x2_final.h>              /* IFC */

These header files also bring in the rose.h header file for the ROSE Programming Library. If you need read/write support for Part 28 XML files, you must also include the rose_p28.h header file as described below.

Class Naming Conventions

The generated classes for all of the STEP APs have the "stp_" prefix. So the class for the "product" EXPRESS definition is stp_product, the class for "cartesian_point" is stp_cartesian_point, and so on. This prefix makes it easier to identify the classes within your code and avoids symbol conflicts with other packages on names like "point" or "curve".

The IFC and CIS/2 class libraries are not STEP (although they have some similar definitions) so we do not give those classes a prefix. The class names are the same as the EXPRESS definition (possibly capitalized if it conflicts with a reserved word).

Complete lists of all classes for entities, complex entity combinations, aggregates, select types, and enumerations, can be found on the page for each schema.

Complex Entity Combinations

Complex entity combinations (sometimes called "AND/OR" instances) are instances with a set of types rather than a single type. This is just multiple inheritance, but the EXPRESS schema does not define an ENTITY for the combination. C++ does need a class for this combination, however, so we generate an extra class for it.

The AP libraries contain all of the combinations that you are likely to need. The name for a complex class is made by concatenating the supertypes in alphabetic order with "_and_". See the class list for your schema for a complete list of the extra complex classes available.

In the Part 21 files, complex instances are written differently. Each supertype is called out in a parenthesized list along with the attributes defined by the super. The example below shows some complex instances used for unit definitions in STEP.

/* SI Units and Conversion-based units, complex instances */
#14= ( 	LENGTH_UNIT()
	NAMED_UNIT(*)
	SI_UNIT(.MILLI.,.METRE.)  );

#15= (	NAMED_UNIT(*)
	PLANE_ANGLE_UNIT()
	SI_UNIT($,.RADIAN.) );

#16= (	CONVERSION_BASED_UNIT('degree',#18)
	NAMED_UNIT(#17)
	PLANE_ANGLE_UNIT() );

/* some normal instances */
#17= DIMENSIONAL_EXPONENTS (0.,0.,0.,0.,0.,0.,0.);
#18= MEASURE_WITH_UNIT (PLANE_ANGLE_MEASURE(0.01745329252),#15);

If you look at the EXPRESS for named_unit, you will see that it has two groups of subtypes, some to describe the purpose of the unit (length_unit, plane_angle_unit, area_unit, etc) and some to describe the definition of the unit (si_unit, conversion_based_unit). STEP usage requires us to make a complex instance by picking one from each of these groups.

The C++ classes used for the instances above (these also have the stp_ prefix):

#14 => stp_length_unit_and_si_unit
#15 => stp_plane_angle_unit_and_si_unit
#16 => stp_conversion_based_unit_and_plane_angle_unit

If you should ever use the EXPRESS compiler to generate your own C++ classes, you can provide the EXPRESS compiler with a workingset file that lists all of the extra class combinations. We have provided workingset files for each installed schema with the combinations you are likely to need.

Force Link in main()

You must call the stp_schema_force_load() function to force the linker to bring in all C++ classes. If you do not, some linkers will omit classes, and you will get "Best Fit" warning messages when reading STEP files as the ROSE library tries to find a C++ class to hold the instance data.

You only need to call this once, in your main() (or other always-present function).

#include <stp_schema.h>

int main(int argc, char* argv[])
{
    /* Force optimizing linkers to bring in all C++ classes */
    stp_schema_force_load();

    /* Rest of your application */
    . . .
}

For non-STEP AP schemas (like CIS/2 and IFC), this function is named after the schema and you must include a separate header file, also named after the schema.

#include <[schema-name]_ROSE_LOAD.h>   /* for a non-AP schemas */

#include <structural_frame_schema_ROSE_LOAD.h>   /* CIS/2 */
structural_frame_schema_force_load();

#include <ifc2x2_final_ROSE_LOAD.h>              /* IFC */
ifc2x2_final_force_load();

Part 28 XML Read/Write Support

If you need read/write support for Part 28 XML files, you must also include the rose_p28.h header file. ST-Developer applications can read and write STEP Part 28 Edition 2 XML exchange files (ISO 10303-28:2007). To enable this functionality, simply include the rose_p28.h header file then call rose_p28_init() at the start of your program to register the XML reader and writer. You must also link against the p28e2 library.

From then on, your application will automatically recognize STEP Part 28 XML files when reading. By default, new files are written as Part 21 but you can switch to Part 28 XML by calling RoseDesign::format() with "p28" or "p28-raw" strings.

RoseDesign * d;
d-> format ("p21");
d-> save()  // write as Part 21 text

d-> format ("p28");
d-> save()  // write compressed Part 28 XML

d-> format ("p28-raw");
d-> save()  // write raw Part 28 XML

The "p21" format is the default and specifies a STEP Part 21 ASCII file, and the file will be given the ".stp" extension if none is specified.

The "p28" format specifies XML with zip compression to reduce size, and the file will be given the ".p28" extension if none is specified. If you run unzip on the result, you will see a single file called iso_10303_28.xml , which contains the raw XML.

The "p28-raw" format specifies XML without any compression, and the file will be given the ".xml" extension if none is specified.