ROSE Library Reference
RoseInterface

Overview

The RoseInterface class manages the memory workspace, including designs in memory, database search paths, EXPRESS data dictionary, and C++ type information. There is only one instance of the RoseInterface class called ROSE. This static instance is defined by the ROSE library and is declared by standard include files.

    extern RoseInterface ROSE;    /* only instance of interface object */

All RoseDesign instances are registered with the interface object upon creation. The interface object can designate one as the default or "current" design. This is where all objects created using the pnew operator are placed. Applications which use multiple designs can specify a particular design to functions by passing a pointer to the design or, in most cases, by passing the name of the design. See Current Design for more details.

beginTraversal()

void beginTraversal(); 

The beginTraversal() and endTraversal() functions and RoseObject::visit() and RoseObject::wasVisited() functions allow algorithms to traverse objects in a design and identify which objects have already been visited. This is useful in algorithms that need to detect circularity and/or avoid unnecessary search.

The beginTraversal() and endTraversal() functions put RoseInterface object into a traversal state where data objects can be marked as visited. Calls to beginTraversal() and endTraversal() cannot be nested. An appliction must end one traversal before starting a new one. Objects remain marked until endTraversal() is called. The isTraversing() function can be used to detect if a traversal is in progress. Marking Objects During Traversal describes how to traverse and mark objects in greater detail.

Example

The following example uses a RoseCursor to traverse an entire design object and perform some operation on objects. Object marking is used to insure that each object is only considered once. The body of the loop can mark other objects and the wasVisited() test will prevent the loop from operating on them again.

    RoseDesign * design;
    RoseCursor objs;
    RoseObject * obj;
     
    ROSE.beginTraversal();
    objs.traverse (design);
    while (obj = objs.next()) {
        if (!obj-> wasVisited()) {    /* test for mark */
            /* do something and maybe visit other objects */
            obj-> visit();         /* mark */
        }
    }
    ROSE.endTraversal();

See Also

Marking Objects During Traversal; RoseInterface::endTraversal(); RoseInterface::isTraversing(); RoseObject::unvisit(); RoseObject::visit(); RoseObject::wasVisited()

clearWorkspace()

void clearWorkspace();

The clearWorkspace() function deletes all of the design objects currently in memory. If any design has not been saved, its contents are lost. Schema designs are not removed by this function.

Example

    ROSE.clearWorkspace();

cvt<type>to<type>()

RoseBoolean cvtOIDtoSTR(
	RoseOID oid,
	char * str  /* str is char[43] */
	);

RoseBoolean cvtSTRtoOID(
	const char * str,  /* str is char[43] */
	RoseOID &oid
	);

The cvtOIDtoSTR() and cvtSTRtoOID() functions convert between a run-time "short" object identifier (RoseOID) and a string representing the corresponding full identifier. Full object identifiers are 160bits long, but for efficiency, they are represented as 32bit abbreviations in memory. This abbreviated id is what the RoseOID typedef is used for.

These abbreviations can change from one program execution to another, just as memory addresses do. For this reason, passing the abbreviated identifier between executing processes will not work. Applications that need to communicate identifiers via RPC or some other mechanism should use these functions to expand a 32bit RoseOID into string representations of the full 160bit object identifier before exchanging them.

The string parameter used by the functions is a 42 character hex string of the form "0x123ABC ... 123". The calling routine should allocate a buffer of size 43 characters for the string. These functions return a boolean value indicating whether the conversion was successful.

See Also

ROSE Universal Object Identifiers (OIDS)

design()

RoseDesign * design();

The design() function the current design object. This "current" design object is where all objects created using the pnew operator are placed, and is also the default target of most RoseInterface functions.

Example

We can reproduce the behavior of many RoseInterface functions by using the design() function to call an equivalent RoseDesign function on the current design.

    ROSE.display();              /* print current design */
    ROSE.design()-> display();   /* print current design */
     
    ROSE.saveDesign();           /* save current design */
    ROSE.design()-> save();      /* save current design */
     
    ROSE.setFormat("step");         /* set file format of current design */
    ROSE.design()->format("step");  /* set file format of current design */

See Also

Current Design; RoseInterface::useDesign()

endTraversal()

void endTraversal();

The beginTraversal() and endTraversal() functions put RoseInterface object into a traversal state where data objects can be marked as visited. An appliction must end one traversal by calling endTraversal() before starting a new one. Objects remain marked until endTraversal() is called. Consult RoseInterface::beginTraversal() for more information and an example.

errcode() / errcontext()

RoseErrorCode errcode();

RoseErrorContext * errcontext();

The errcode() function returns the numeric code for the last error seen, or zero if there was no error. The errcontext() function returns the context object that defines the error, or null if the error was a general one reported through error() or warning(). The error_reset() function can be used to clear the error status.

See Also

ROSE Library Predefined Errors; RoseErrorReporter::errcode() / errcontext()

error() / warning() / message()

void error(
	const char * fmat, ...
	);

void warning(
	const char * fmat, ...
	);

void message(
	const char * fmat, ...
	);

These functions are used internally to report general conditions that do not have a pre-defined code for the report() function. The functions take variable arguments and use the printf() conventions, but no trailing newline is required.

The message() function is used to report informational messages. If the quiet() flag is set to false, these messages are not printed, but warning() and error() messages will be.

Example

    RoseDesign * design;
     
    ROSE.message ("Design %s is happy", design-> name())
    ROSE.warning ("Design %s is not happy", design-> name())
    ROSE.error ("Design %s is extremely unhappy", design-> name())

See Also

Error Reporting; RoseErrorContext::<error_severity>()

error_reporter()

RoseErrorReporter * error_reporter();

void error_reporter(
	RoseErrorReporter * eo
	);

The ST-Developer libraries use an instance of the RoseErrorReporter class to handle error reporting and logging. This instance is specified by the error_reporter() functions. Advanced applications may install a special subclass of this object in order to report errors in a specialized way.

error_reset()

void error_reset();

The error_reset() function clears the error status. This is an alias of the RoseErrorReporter::reset() function.

findDesign()

RoseDesign * findDesign(
	const char * design_name
	);

The findDesign() function searches memory and secondary storage for a design matching a name. All filenames and paths are assumed to be UTF-8 encoded strings. The function first looks for a design with a matching name in memory, otherwise it will try to read the design from disk. If no match is found or if there were errors reading from disk, the routine will return null.

The preferred way to read a file is to specify a full pathname. The findDesign() function accepts full filenames with paths as well as unqualified design names. The directories searched by the findDesign() function are given by the path() function and can be specified using the $ROSE_DB environment variable.

The findDesign() function does not change the current design. Call the useDesign() function to set the current design.

NOTE - When searching for an unqualified name (no directory or extension) ROSE Working Form files take precedence STEP Part 21 files because they contain additional information, such as object identifiers, and names. If two files, data.rose and data.step, are in the same directory, the data.rose file will be chosen. The data.step file will only be chosen if it is ahead of the data.rose file in the search path.

Example

The following example reads a Part 21 file /usr/home/db/gizmo.step and returns a design object containing the data.

    RoseDesign * design;
    design = ROSE.findDesign("/usr/home/db/gizmo.step");

The following examples use the search path. The first one looks for a Part 21 file called gizmo.step. The second one searches for any design called "gizmo". If the design is not in memory, the function will first look in each search path directories for a file called gizmo.rose, and then for one called gizmo.step.

    RoseDesign * design;
    design = ROSE.findDesign("gizmo.step");
    design = ROSE.findDesign("gizmo");

See Also

Reading and Writing Design Objects; Database Search Paths; STEP Part 21 Exchange Files; ROSE Working Form Files

findDesignInWorkspace()

RoseDesign * findDesignInWorkspace(
	const char * design_name
	);

The findDesignInWorkspace() function will search the memory workspace for a design with a particular name. If the design is not in memory, the function will return null. Unlike the findDesign() function, this function does not search secondary storage.

Example

    RoseDesign * design;
    design = ROSE.findDesignInWorkspace("gizmo");
    if (!design)
        printf ("Could not find the gizmo design in memory\n");

findDomainInWorkspace()

RoseDomain * findDomainInWorkspace(
	const char * domain_name
	);

The findDomainInWorkspace() functions perform the findDomain() operation on all the schemas in memory. If there are multiple matches, the function returns the first domain that it finds. The function always starts the search with schemas of the current design. If no domain is found, the function returns null.

Example

    RoseDomain * pt_type = ROSE.findDomainInWorkspace ("cartesian_point");
    if (pt_type)
          printf ("Found cartesian_point domain\n");
    else  printf ("There is no cartesian_point domain in memory\n");

findObjectInWorkspace()

RoseObject * findObjectInWorkspace(
	const char * obj_name
	);

RoseObject * findObjectInWorkspace(
	RoseOID oid
	);

The findObjectInWorkspace() functions perform the findObject() operation on all the designs in memory. If there are multiple matches, the function returns the first one that it finds. The function always starts the search with the current design. If no object is found, the function returns null.

Example

    RoseObject * top = ROSE.findObjectInWorkspace ("top");
    if (top)
          printf ("Found top object\n");
    else  printf ("There is no top object in memory\n");

isInPath()

RoseBoolean isInPath(
	const char * design_name
	);

The isInPath() function is used by the findDesign() function to determine whether a design with a particular name is in the database search path. The database search path is specified using the $ROSE_DB environment variable. Use the findDesign() function to retrieve a pointer to the design.

When searching directories, the search functions use filename extension to distinguish designs from other files. When a filename ends in .step, .stp, .p21, or .pdes, it is considered to be a STEP Part 21 file. If a filename ends with .rose or .ros, it is a ROSE Working Form file.

Example

    if (ROSE.isInWorkspace ("gizmo"))
          printf ("Gizmo design is in the search path\n");
    else  printf ("Gizmo design is not in the search path\n");

See Also

Database Search Paths; RoseInterface::path(); RoseInterface::pathDesignNames()

isInWorkspace()

RoseBoolean isInWorkspace(
	const char * design_name
	);

The isInWorkspace() function indicates whether or not a design object with a given name is resident in memory. If the specified design object is in memory, isInWorkspace() returns true rather than a pointer to the design object. Use the findDesign() function to retrieve a pointer to the design.

Example

    if (ROSE.isInWorkspace ("gizmo"))
          printf ("Gizmo design is in memory\n");
    else  printf ("Gizmo design is not in memory\n");

isSystemCreate()

RoseBoolean isSystemCreate();

The isSystemCreate() function can be used within a constructor to determine the conditions under which the object is being created. There are two possibilities. If the object is created by the user (through new or pnew), the constructor may populate attributes by creating other objects. If the object is created by the system (through copy() or findDesign()), the the system functions may populate the attributes and the constructor should not attempt to do so.

Currently, the default constructor is used by the pnewInstance() and other system create functions. Future versions of the ROSE library may define a special constructor for this purpose.

Example

    SomeClass::SomeClass() {
        if (ROSE.isSystemCreate()) {
            /* just null out the attributes */
        }
        else {
            /* populate some attributes */
        }
    }

isTraversing()

RoseBoolean isTraversing();

The beginTraversal() and endTraversal() functions put RoseInterface object into a traversal state where data objects can be marked as visited. The isTraversing() function detects whether a traversal is in progress. Consult RoseInterface::beginTraversal() for more information and an example.

keystone()

RoseDesign * keystone();

The keystone() function returns a pointer to the ROSE "keystone" design. This design contains all the primitive domains as well as a number of other basic domains needed by all ROSE applications. This design is constructed in memory during the ROSE bootstrap process and can never be written to secondary storage.

Example

    RoseDesign * keystone = ROSE.keystone();
     
    printf ("The keystone design is called %s\n", keystone-> name());

newDesign()

RoseDesign * newDesign(
	const char * design_name,
	RoseDesign * schema = NULL
	);

RoseDesign * newDesign(
	const char * design_name,
	const char * schema_name
	);

The newDesign() function creates a instance of a RoseDesign and makes it the default design. Every design must have a name. The names of designs must be unique in memory. The name will be used as the basis for the filename when the design is written to secondary storage. The new design will not contain any objects.

Every design must also have a one or more schemas. Schemas provide EXPRESS definitions for the objects within a design. When an application uses early-bound classes, each class knows it's schema, but when doing late-bound programming, the pnewInstance() and findDomain() functions must search through a list of schemas to find EXPRESS definitions.

The newDesign() function allow an application to specify one schema, either by name or by pointer. Additional schemas can be added with the addDesign() functions. An early-bound application does not need to explicitly set the schemas unless it will also be doing late-bound calls. If no schema is provided, the the schema of built in C++ classes will be assigned to the design.

Designs can be created with the new operator or the RoseInterface::newDesign() function. The new operator does not set the new design to be the default design.

Example

The example below shows two ways of creating a new design. The newDesign() function makes the new design the current design, while the new operator does not.

    RoseDesign * design;
     
    /* create and make current design */
    design = ROSE.newDesign ("gizmo","config_control_design");
     
    /* create and make current design */
    design = new RoseDesign ("gizmo","config_control_design");
    ROSE.useDesign (design);

See Also

Creating and Deleting Design Objects; RoseDesign Constructor

path()

List(String)* path();

The path() function returns the database search path used by the findDesign() function. This list of directories can be specified using the $ROSE_DB environment variable. In addition to the directories in this path, the findDesign() function will also search the ST-Developer schemas directory $ROSE/system_db/schemas.

It is a good idea to make the first directory in the search path the current directory. When the ROSE library saves a new design to secondary storage, it uses the first directory in this search path.

Example

The following example prints the search directories used by an application.

    List(String) * dirs;
    unsigned i, sz;
     
    dirs = ROSE.path();
    for (i=0, sz=dirs->size(); i<sz; i++) {
        printf ("Directory %s\n", dirs-> get(i));
    }
    printf ("Also the system_db/schemas directory\n");

See Also

Database Search Paths; RoseInterface::findDesign()

pathDesignNames()

List(String)* pathDesignNames(
	const char * dir = NULL
	);

The pathDesignNames() function returns the names of all designs the database search path used by the findDesign() function. If a directory is specified, the function returns a list of designs in that directory.

Example

The following example prints the names of all designs in the search directories.

    List(String) * designs;
    unsigned i, sz;
     
    designs = ROSE.pathDesignNames();
    for (i=0, sz=designs->size(); i<sz; i++) {
        printf ("Design %s\n", designs-> get(i));
    }

quiet()

RoseBoolean quiet();

void quiet(
	RoseBoolean quietFlag
	);

The quiet() flag determines whether or not the ROSE library displays the banner and issues messages when file I/O occurs. Setting the flag to true will prevent the banner and messages from being displayed. Setting it to false will print more informational messages. The default value is false. Since the library prints messages as soon as it is initialized, you must set this value before calling pnew or any other operations.

Example

    ROSE.quiet (ROSE_TRUE);     /* prevent messages */
    ROSE.quiet (ROSE_FALSE);    /* allow messages */
     
    if (ROSE.quiet())
        printf ("No messages will be printed\n");

report()

void report(
	RoseErrorCode, ...
	);

The report() function is used to report a predefined error or warning condition. This function is used internally to report conditions defined by the built-in error context. Applications can define their own error contexts and report to them.

saveWorkspace()

void saveWorkspace();

The saveWorkspace() function saves all of the design objects in memory. Each design will be written using the RoseDesign::save() function.

shutdown()

void shutdown();

The shutdown() function releases all of the persistent data in memory and restores the ROSE library to a pre-boot condition. You can start over and read things back in if you want to though.

See Also

RoseInterface::shutdown_everything()

shutdown_everything()

void shutdown_everything();

The shutdown_everything() function releases all of the persistent data in memory as well as any runtime C++ type information kept by the RoseType objects. Once this is done, there is no way to restart and you should not make any more calls to the ROSE library.

See Also

RoseInterface::shutdown()

useDesign()

RoseDesign * useDesign(
	const char * design_name
	);

RoseDesign * useDesign(
	RoseDesign * design
	);

The useDesign() functions change the default design object. This "current" design object is where all objects created using the pnew operator are placed, and is also the default target of most RoseInterface functions. The version which takes a design name calls findDesign(), which may read the design from secondary storage.

Example

    ROSE.useDesign ("gizmo");                     /* equivalent */
    ROSE.useDesign (ROSE.findDesign ("gizmo"));   /* equivalent */

See Also

Current Design; RoseInterface::design()RoseInterface::findDesign()

usePath()

void usePath(
	const const char * new_path
	);

void usePath(
	List(String)* dirs
	);

The usePath() function sets the database search path used by the findDesign() function. It is a good idea to make the current directory the first directory in the search path. When the ROSE library saves a new design to secondary storage, it uses the first directory in the search path.

The usePath(const char*) version expects the directories in the path to be separated by the character appropriate for the platform (colons on UNIX, semicolons on Windows, and commas on VMS). The usePath(List(String)*) version replaces the actual list object.

The initial value for the path is usually taken from the $ROSE_DB environment variable, but can be changed with the rose_get/setenv search_path() functions. Once the library has been initialized, the path can be changed with the usePath() function.

The system schemas directory is normally appended to the search path. By default this is the ST-Developer schemas directory $ROSE/system_db/schemas, but the value can be changed with rose_get/setenv system_schema_path().

Example

The following example sets the search directories used by an application.

    ROSE.usePath (".:./schemas:/usr/home/db:/usr/home/db/schemas");

Using the second form of the function:

    List(String) * dirs = new List(String);
    dirs-> add (".");                   /* current directory */
    dirs-> add ("./schemas");           /* a relative schemas directory */
    dirs-> add ("/usr/home/db");        /* an absolute data directory */
    dirs-> add ("/usr/home/db/schemas"); /* an absolute schema directory */
    ROSE.usePath (dirs);

See Also

Database Search Paths; rose_get/setenv search_path(); rose_get/setenv system_schema_path(); RoseInterface::findDesign(); RoseInterface::path()

useShortNames()

RoseBoolean useShortNames();

void useShortNames(
	RoseBoolean yn
	); 

The useShortNames() functions get and set the preferences for using short names when writing STEP Part 21 files. As with reading short names, a schema equivalents file (<schema_name>.nam) must be present somewhere in your database search path. The short names will not be written if this file can not be found. The default is to always write long names.

Example

    ROSE.useShortNames (ROSE_TRUE);   /* short names if possible */ 
    ROSE.useShortNames (ROSE_FALSE);  /* always long names */

See Also

Short Names

userSchemaNames()

List(String) * userSchemaNames();

The userSchemaNames() function returns the names of schemas that are referenced by compiled-in C++ classes. This list does not contain system schemas such as the ROSE keystone.

Example

    List(String) * schemas;
    unsigned i, sz;
     
    schemas = ROSE.userSchemaNames();
    for (i=0, sz=schemas->size(); i<sz; i++) {
        printf ("Program uses %s schema\n", schemas-> get(i));
    }

workspaceDesigns()

List(RoseDesign) * workspaceDesigns();

The workspaceDesigns() function returns a list containing every design that has been read into the memory workspace. Do not attempt to change or free this list.

Example

    List(RoseDesign) * designs;
    unsigned i, sz;
     
    designs = ROSE.workspaceDesigns();
    for (i=0, sz=designs->size(); i<sz; i++) {
        printf ("Design %s is in memory\n", designs-> get(i)-> name());
    }

workspaceDesignNames()

List(String) * workspaceDesignNames();

The workspaceDesignNames() function returns a list containing the names of every design that has been read into the memory workspace. Do not attempt to change or free this list.

Example

    List(String) * designs;
    unsigned i, sz;
     
    designs = ROSE.workspaceDesignNames();
    for (i=0, sz=designs->size(); i<sz; i++) {
        printf ("Design %s is in memory\n", designs-> get(i));
    }