RoseInterface Class

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 */

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() function is a deprecated alias for rose_mark_begin().

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.

ROSE.clearWorkspace();

cvtOIDtoSTR() / cvtSTRtoOID()

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 a ROSE Universal Object Identifier between a 32bit run-time abbreviated form (RoseOID) and a string representing the corresponding 160bits full identifier.

The abbreviated form 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.

design()

RoseDesign * design();

The design() function returns the current design. This is is the RoseDesign that will own all data objects created using the pnew operator. The useDesign() function changes this value.

endTraversal()

void endTraversal();

The endTraversal() function is a deprecated alias for rose_mark_end().

error() / warning() / message()

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

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

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

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())

error_reporter()

RoseErrorReporter * error_reporter();

The ST-Developer libraries use an instance of the RoseErrorReporter class to handle error reporting and logging. There is one instance which is returned by the error_reporter() function.

findDesign()

RoseDesign * findDesign(
	const char * filename
	);

The findDesign() function searches memory and secondary storage for a design matching a name. Filenames are assumed to be UTF-8 encoded strings. The function first looks for a design with a matching filename 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 input is a complete filename with a directory. The function will check the exact filename first. Then, if the filename does not have an extension, it will then check each known extension.

When given a name with no directory, the function will search each directory given in the path() list. If the name does not have an extension, the function will check each known extension first, then for the name without an extension.

When checking known extensions, the ROSE Working Form extension (.rose) is checked before STEP Part 21 extensions (.stp, .step). This is because they could contain additional information, such as object identifiers, and names which was not available in STEP files prior to P21e3.

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

RoseDesign * d = 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 gizmo.rose, gizmo.stp, gizmo.step, gizmo.p21, gizmo.ifc, and finally gizmo.

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

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.

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.

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.

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.

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

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.

    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.

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

isTraversing()

RoseBoolean isTraversing();

The isTraversing() function is a deprecated function that tests whether a traversal mark has been opened by checking whether rose_mark_current() returns a non-zero value.

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.

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 RoseDesign and makes it the default design. It is equivalent to creating a design with new followed by a call to useDesign().

Refer to the RoseDesign constructor for more discussion of the name and schema parameters.

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);

path()

ListOfString* 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.

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

ListOfString * 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);

pathDesignNames()

ListOfString* 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.

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

ListOfString * 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 changes the reporting thresholds for the ROSE library so that informational messages are no longer printed. Warnings and errors are always printed. This just sets the report_threshold() of the error reporter.

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.

ROSE.quiet (ROSE_TRUE);     /* prevent messages */
ROSE.quiet (ROSE_FALSE);    /* allow messages */

// same as ROSE.quiet(ROSE_TRUE);
ROSE.error_reporter()-> report_threshold (ROSE_STATUS_WARNING);

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.

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.

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. The version which takes a design name calls findDesign(), which may read the design from secondary storage.

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

usePath()

void usePath(
	const const char * new_path
	);

void usePath(
	ListOfString* 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(ListOfString*) 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().

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:

ListOfString * dirs = new ListOfString;
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);

userSchemaNames()

ListOfString * 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.

ListOfString * 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()

ListOfRoseDesign * 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.

ListOfRoseDesign * 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());
}

Overview

beginTraversal()

clearWorkspace()

cvtOIDtoSTR() / cvtSTRtoOID()

design()

endTraversal()

error() / warning() / message()

See Also

error_reporter()

findDesign()

See Also

findDesignInWorkspace()

findDomainInWorkspace()

findObjectInWorkspace()

isInPath()

See Also

isInWorkspace()

isSystemCreate()

isTraversing()

keystone()

newDesign()

See Also

path()

See Also

pathDesignNames()

quiet()

report()

saveWorkspace()

shutdown()

See Also

shutdown_everything()

See Also

useDesign()

See Also

usePath()

See Also

userSchemaNames()

workspaceDesigns()