ROSE File Tools

Overview

The ROSE file utility is a command line tool that can perform various services. The following syntax is used to invoke the commands of the ROSE utility:

    % rose <command> <options>

The utility accepts the following commands. A complete description of each can be found in the following sections.

cat: Display the contents of design files.
conflict: Find update conflicts between designs.
create: Create new objects.
delete: Delete objects.
diff: Compare two designs.
format: Change file formats. Can also merge data sets.
help: Print information about tool options.
index: Name objects.
ls: List design files in the search path.
migrate: Migrate data files to a new schema.
mutate: Mutate objects to a new data type.
paths: Display the run-time environment.
reference: Check the validity of inter-file references.
sed: Update a design using output of the diff tool.
set: Set the values of attributes in objects.

rose cat

rose cat [options] <design>...

-v: Verbose mode.

This tool to print the contents of a file to standard output. The data is printed in the ROSE text working format. If you specify multiple files, this utility prints each one with separators indicating where one design ends and another begins.

Examples

The following command displays the contents of a STEP data file named "tutorial1"

    %rose cat tutorial1

    ROSE_OIDS {
        (0 = 0x00807110537000028A2C14F0000622B0400000000)
    }
    ROSE_DESIGN (RoseDesign
        name: "tutorial1"
        root: $
        keyword_table: $
        name_table: $
        schema : <"picture">
    )

    STEP_OBJECTS (
        (<0-7> Circle
            radius: 1.5
            center: (<0-1> Point
                x: 2.5
                y: 4))
        (<0-6> Text
            label: "A Little Picture"
            center: (<0-2> Point
                x:5
                y:0))
        (<0-5> Point
            x:0
            y:0)
        (<0-4> Circle
            radius: 1.5
            center: <0-5>)
        (<0-3> Line
            enda: (<0-0> Point
                x: 1
                y: 0)
            endb: <0-1>)
    )

rose conflict

rose conflict [-v] <design>|<diffName> <diffName>

-v: Print each conflict as it is detected.

The conflict tool finds and displays update conflicts between a design and a diff file, or between two diff files. The types of conflicts that the tool searches for are strictly of a syntactic nature -- multiple updates to the same field, updates on a deleted object and so forth.

In the example below, two delta files, T1 and T2, each try to change the label and color attributes of a "ColorText" object in the file "original.rose". The conflict tool can be used to detect this.

    % rose conflict original T1 T2
    0 conflicts between original and T1
    0 conflicts between original and T2
    2 conflicts between T1 and T2

Using the -v option, you can make the tool display each conflict that is detected.

    % rose conflict -v backup T1 T2
    Modify conflict in:
    (<0-6> ColorText
        color: "blue"
        label: "A Little Picture"
        center: <0-2>)

    T1                        T2
    color="yellow"            color="red"
    label="Jack's Picture"    label="Jill's Picture"

rose create

rose create [options] <schema-name>...

-all: Creates one object of every domain in the specified schemas. This is the default behavior.
-domain <domain-name>: Create objects of the specified domain. This overrides the -all behavior.
-o <output-name>: Redirects output to <output-name>.
-r: Recursive mode. For each domain, recursively visits each attribute. If it is an object attribute, this option causes the attribute to be filled with an object of the appropriate type.
-style <style>: Where <style> is either c++ or generic_c++. If this option is specified, the tool generates a C++ program that can be used to create objects.; The c++ style program uses the C++ class definitions produced by the express2c++ tool. The generic_c++ style program uses classes and methods predefined in the ROSE class library.
-v: Verbose mode.

Use this tool to create new objects or to generate C++ code for creating new objects. The -domain option, if specified, determines the data type of the newly created object.

The argument <schema-name> specifies the names of compiled (.rose) schemas to be used for finding data types. You can use the -all option to request creation of an object of every type found in the specified schemas.

This tool is primarily used to quickly produce a data set or a C++ program for testing purposes. The generated objects should be structurally correct, but may not meet all of the constraints specified in the EXPRESS schema.

The primitive attribute fields of objects are filled with arbitrary values. If the recursive option (-r) is specified, the object attribute fields are filled with an object of the appropriate type; otherwise, the object attribute fields are set to NULL.

Examples

The examples below use the STEP generic resource EXPRESS schema p42.exp.

To create an instance of every entity defined in the topology schema of Part 42, first compile p42.exp, then use the tool as follows:

    % express2c++ p42.exp
    % rose create -all topology_schema.rose

The tool can recursively populate the attributes of objects. The following statement will create instances from the geometry schema, because entities in the topology schema use definitions from the geometry schema:

    % rose create -all -r topology_schema.rose

To generate a class based C++ program for creating objects:

    % rose create -all -style c++ topology_schema.rose

rose delete

rose delete [options] <design>...

-i: Interactive mode. Ask whether to delete each object.
-n: No execution. Prints objects to be deleted, but do not actually delete them. If the -v option is specified, display the objects in ROSE working format; otherwise, just print the OID/name of the object.
-o <output-design>: Place deleted objects into <output-design>. The objects are moved to the <output-design>.
-v: Verbose mode.

Use this tool to delete objects from a design. The -i option prompts you before deleting each object.

rose diff

rose diff <design1> <design2> [<output_name>]

-v: Verbose mode.

Use the diff tool to create a file that describes differences between two designs. This file, when applied to <design2> with the sed tool, makes the two designs identical.

If you do not specify an output name, the differences will be stored in the file diff.rose.

rose format

rose format <new-format> [options] <design>...

-o <output-file>: Redirects output to <output-file>.
-r: Recursive. Merge a data set which is distributed over multiple designs. Specify an output file using the -o option.
-v: Verbose mode.

This tool to changes the format of a existing design or schema file. This operation reads the file, changes the output format using the RoseDesign::format() function, and saves it again. The value of <new-format> should be one of the following:

p21: The STEP Part 21 ASCII exchange file format defined in ISO 10303-21. Files are written as <design>.stp.
p28: The STEP Part 28 XML file format defined in ISO 10303-28. Files are written as <design>.p28 and are zip-compressed to reduce size.
p28-raw: The STEP Part 28 XML file format as above, but written without any compression. Files are written as <design>.xml.
step: An alias for the "p21" format described above.
binary: ROSE binary working form. Files are written as <design>.rose
rose: ROSE ASCII working form. Files are written as <design>.rose.
express: Convert a compiled ROSE data dictionary back into an EXPRESS text description. This option prints to standard output. Only structure is recovered, all constraints and rules are lost.

Examples

The following command converts the file format of the design "tutorial1" to STEP:

    % rose format step tutorial1

Convert the compiled schema "picture" to EXPRESS text:

    % rose format express -o picture.exp picture

To merge the data in files tutorial1.rose and tutorial2.rose. Place the merged data in the file merged_data.rose:

    % rose format standard -o merged_data tutorial1 tutorial2

Data in ROSE working form files can contain inter-file references. Use the -r option to recursively visit and merge these references. The example below creates the design file merged_data2.rose, which will contain copies of all objects in tutorial1 and all objects that are referenced by tutorial1:

    % rose format standard -r -o merged_data2 tutorial1

rose help

rose help [<command>]

Use this command to obtain descriptions of the various ROSE file tools. If the parameter <command> is not specified, a list of available commands is displayed on the screen.

rose index

rose index [options] <design>...

-i: Interactive. Ask the user to supply a name for each object.
-on [<domain>].attribute: Use the value of the specified attribute as the index name. A domain name can also be specified, to restrict the scope of the attribute.
-v: Verbose mode.

Use this command to create entries in a design's name table. A design file contains a dictionary that maps names to objects. Named objects can be found quickly and easily within programs written using STEP Tools software.

An object can have more than one name. Each name, however, can match only one object. If you assign the same name to many objects, only the last assignment is kept.

Examples

This uses the value of the "last_name" attribute as the index value. To create an index entry for any object that has a last_name attribute (regardless of the object's type):

    % rose index -on last_name employee_db

This uses the value of the "last_name" attribute as the name of the object.

rose ls

rose ls [options]

-l: Display files in long format, indicating the owner, date, permissions and size of each database file.
-v: Verbose mode.

Use this command to list, by directory, the design files in the search path. The following example shows the result of such a listing:

    % rose ls

    Total number of designs::  4

     In /usr/local/step_toolkit/system_db/schemas
            data_transfer_schema.rose
            ChangeProcessing.rose
            header_section_schema.rose
            express_parser.rose

rose migrate

rose migrate <design>...

-newschema <schema>: Specifies the name of the new schema. This option must be set if the data is in rose or STEP file format.
-v: Verbose mode.

Use this command to update a ROSE binary working form file to the most recent version of a schema. To use this effectively, you should understand the impact of modifying data types and the limits of this tool.

Compiled Data Types

The expfront tool generates compiled data definitions and places them into compiled ".rose" files. For example, given the following schema, stored in the file point_schema.exp:

    SCHEMA point_schema;
          ENTITY Point;
                x:REAL;
                y:REAL;
          END_ENTITY;
    END_SCHEMA;

By invoking the EXPRESS compiler,

    % expfront -rose point_schema

you generate a file called point_schema.rose. This file contains compiled type definitions. There are two ways to access the definitions in point_schema.rose:

By the entity name ("Point")
By the unique object identifier (OID) of the definition object ("#0x008071051700002A7827AF00004CC2040000000010A")

The STEP Part 21 file format and the ROSE ASCII working form use the first method, while the ROSE binary working form uses the second.

Compiling EXPRESS Schemas

When you recompile an EXPRESS schema, the compiler compares the definitions it had previously generated with the EXPRESS model. If the compiler detects a difference, it regenerates the type definition.

The old and new type definitions are both stored in the compiled schema, allowing applications to use data described by either definition. The new definition is accessible by name or by OID, while the older one is accessible only by OID. Applications and files that refer to types by name will always get the most recent version of the schema.

For example, suppose we added a 'Z' attribute to the Point Entity and recompiled the schema:

    ENTITY Point;
          x : REAL;
          y : REAL;
          z : REAL;
    END_ENTITY;

The point_schema.rose file will contain two definitions of Point. The "default" definition would be the most recently generated version.

The Migrate Tool

There are three basic formats for storing data:

STEP -- the STEP Part 21 physical exchange file format.

This format references data types by name. For example, a Point object might be represented as:

    #3 = POINT (2.3, 4.0);

Attribute values are listed in the order in which they appear in the EXPRESS specification. This means that STEP files are very sensitive to schema modifications.

For example, if we add a Z attribute to our EXPRESS Point definition, we might have trouble reading the above X-Y Point.

ROSE -- ROSE ASCII working form

This format references data types by name. For example, a Point object might be represented as:

    (<1-3> Point x:2.3 y:4.0)

The ROSE ASCII working format is more robust than Part 21, because it stores attribute name/value pairs. Adding new attributes, reordering attributes, and deleting attributes will not cause problems. Data in this format will be automatically upgraded to the newest EXPRESS definitions.

For example, we can the above X-Y Point, even after we add a Z attribute to the EXPRESS definition. In this example, the object would be read in as an X-Y-Z Point and a default value would be assigned to the Z attribute.

Standard -- ROSE binary working form.

The ROSE binary working form references data definitions by OID. When you modify and recompile a schema, the EXPRESS compiler will generate new type definitions, but will not delete old ones. Thus, binary files can contain data that uses old definitions. The individual objects are not automatically upgraded to the most recent definitions.

For example, suppose we had a data set containing X-Y Point objects. After extending and recompiling our EXPRESS schema to use X-Y-Z Points, We can still read and work with our old X-Y points, but any new Points will be created as X-Y-Z points.

Use the migrate tool to update our old data to the most recent schema definitions. The tool will scan a data set for objects with old definitions and 'migrate' them into the most recent definition. In our example, the tool would find all older X-Y Points, and convert them into X-Y-Z points. The new Z attribute would just contain a default value.

rose mutate

rose mutate <design> <old_type> <new_type>

-v: Verbose mode.

Use this tool to mutate every instance of <old_type> in the design <design> into an instance of <new_type>.

As the name implies, this operation changes the structure of objects. The values of attributes are preserved when possible. The operation is often used to modify objects when a schema is extended.

Examples

The following command reads the design "tutorial1" and converts every instance of "Line" into an instance of "ColorLine"

    % rose mutate tutorial1 Line ColorLine

rose paths

rose paths

Use this command to display the run-time configuration of your STEP Tools development installation. This utility displays the search path that all STEP Tools applications will use by default. It is possible, of course, for an application to change the path at run time. This tool is useful for determining from where various schema files are being loaded, especially when you have a compilicated setup.

    Search Path:         .;.\schemas
    System Schema Path:  C:\steptools_9.0\system_db\schemas
    Registry Key:        SOFTWARE\STEP Tools, Inc.\ST-Developer\17.0

    Complete search path [ROSE.path()]:
            .
            .\schemas
            C:\steptools_8.0\system_db\schemas

rose reference

rose reference [options] <design>...

-oids / -nooids: Check / Do Not Check the OID field of inter-file references. The default is to check (-oids).
-r: Recursively check referenced design objects.
-v: Verbose mode.

Use this command to check the inter-file references of a design. An inter-file (or external) reference is a pointer between an object in one design and an object in another design.

An inter-file reference contains two fields: the name of an external design and the OID of an object within the external design.

This tool can perform several levels of checking. If no options are used, the tool checks the design-name field by finding and loading each externally referenced design. Once an externally referenced design is loaded, the tool checks the validity of the OID field of each inter-file reference.

If the -nooids option is specified, the command only verifies that the design of each externally referenced object is in the search path. This checks the design name of inter-file references, but not the OID.

If you use the recursive option (-r), whenever one design references another, the referenced design is also checked for dangling external references. In other words, the tool calls itself recursively.

rose sed

rose sed <design> <diffName> [<outputName>]

-v: Verbose mode.

The sed tool updates the design using a "diff" file, which is generated by the diff tool. The diff file contains objects that describe how to update the objects within the design.

If you do not specify an output name, the original design will be overwritten.

The diff file may contain edit instructions which cannot be applied to the specified design. For example, the diff file may attempt to update an object which has been deleted from the design.

The sed tool applies as many edit operations as possible on the specified design. When the tool encounters an operation which cannot be applied, it skips the operation and moves on to the next.

Examples

Suppose we have two engineers working on different copies of the same design. If we want to merge the changes they have made, we can use the diff and sed tools. The following example computes the changes each engineer has made, and then applies those changes to the original design file. The files T1 and T2 store the changes made by each engineer.

    % rose diff eng_one original T1
    % rose diff eng_two original T2
    % cp original.rose backup.rose
    % rose sed original T1
    % rose sed original T2

This example assumes that there will be no conflicts between the two sets of changes. If we expect conflicts, we can use the rose conflict tool to detect them.

rose set

rose set <design> <domain> <attr> <value>

-v: Verbose mode.

Use the set command to change the value of attribute <attr> of every object of domain <domain> in the design <design> to <value>.

Overview

rose cat

Examples

rose conflict

See Also

rose create

Examples

rose delete

rose diff

rose format

Examples

rose help

rose index

Examples

rose ls

rose migrate

Compiled Data Types

Compiling EXPRESS Schemas

The Migrate Tool

rose mutate

Examples

rose paths

rose reference

rose sed

Examples

See Also

rose set