20.1 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.
20.2 Source Code
The ROSE utility is an application developed using the ROSE Class Library. The source code for a simplified version of this utility is distributed with ST-Developer in the directory $ROSE/demos/rose .
We distribute the source code for the ROSE utility to show how you can do similar things with your own STEP applications. Permission to use, copy, modify and distribute the source code in the directory $ROSE/demos/rose is granted, provided that the copyright notices appear in all copies and in supporting documentation.
20.3 Using a "Where" Clause
Several of the ROSE file utilities let you select objects that match constraints. The constraints are specified within a "where clause." For example, you could display all Points on the positive Y axis using the following:
% rose cat -where "domain=`Point' and x=0 and y>0" tutorial1
The syntax for the where clause is:
<where-clause> = <expr>
<expr> =
| <term>
| <term> `AND' <expr>
| <term> `OR' <expr>
<term> =
| `(' <expr> `)'
| <operand> <rel-op> <operand>
<rel-op> = `<' | `>' | `=' | `<>' | `>=' | `<='
<operand> =
| <EXPRESS string>
| <integer>
| <REAL number>
| <attr> <recursive-attr-spec>
<attr> =
| `THIS' | `DOMAIN' | `DESIGN' | `SCHEMA'
| <an attribute of the object being tested>
<recursive-attr-spec>
| `.' <attr> <recursive-attr-spec>
| `->' <attr> <recursive-attr-spec>
| `[' <integer> `]' <recursive-attr-spec>
| `[' <EXPRESS string> `]' <recursive-attr-spec>
| nil.
Examples
To select all Points whose X coordinate is less than or equal to 0.0:
-where "domain=`Point' and x<=0.0"
To select all instances of objects whose entity definition is in the "topology" schema:
-where "this.schema = `topology'"
In this example, the keyword "this" was optional. The same query could have also been written as:
-where "schema=`topology'"
To select all Polygons if the X coordinate of the first vertex is not equal to 0:
-where "domain=`Polygon' and this.vertices[0].x <> 0.0"
To select all objects in which the label is "A little Picture":
-where "label=`A little Picture'"
20.4 rose cat
rose cat [options] <design>...
-where <where-clause>- Specify constraints that must be met. The objects that meet the constraint will be displayed. Refer to Using a "Where" Clause for additional information.
-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>)
)
20.5 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"
See Also
20.6 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 . These schemas are distributed with ST-Developer in the directory $ROSE/express/part42 .
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
20.7 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> .
-where <where-clause>- Constraint that must be met. Delete the objects that meet the constraint. Refer to Using a "Where" Clause for more on where clauses.
-v- Verbose mode.
Use this tool to delete objects from a design. The -where option lets you selectively delete objects, and the -i option prompts you before deleting each object.
Examples
The following example deletes all Points in the design tutorial1, whose X coordinate is 0.0
% rose delete -where "domain=Point AND x=0.0" tutorial1
The following example deletes all instances of objects from the topology schema
% rose delete -where "domain.schema=`topology'" mbb.rose
The following example deletes all Lines and Circles.
% rose delete -where "domain=Line OR domain=Circle" tutorial1
20.8 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 .
20.9 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
20.10 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.
20.11 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.
-where <where-clause>- Constraint that must be met. Names will be assigned only to object that meet the constraint. Refer to Using a "Where" Clause for more information.
-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 the stepedit tool and within programs written using ST-Developer.
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
The following creates an index entry for each Person in the employee_db design if the Person's first name is `Joe':
% rose index -on Person.last_name -where "first_name=`Joe'" employee_db
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. The following finds all Polygons and asks the user to assign a name to each Polygon:
% rose index -i -where "domain=`Polygon'" my_design
20.12 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
20.13 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.
20.14 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
20.15 rose paths
rose paths
Use this command to display the run-time configuration of your ST-Developer installation. This utility displays the search path that all ST-Developer based applications will utilize 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\9.0
Complete search path [ROSE.path()]:
.
.\schemas
C:\steptools_8.0\system_db\schemas
20.16 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.
20.17 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.
See Also
20.18 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> .