Managing ObjectStore

ossevol: Evolving Schemas

 The ossevol utility modifies a database and its schema so that it matches a revised application schema. It handles many common cases of schema evolution. For more complicated evolutions, including the cases ruled out in this section, see Advanced C++ API User Guide, Chapter 8, Advanced Schema Evolution.

Use osbackup first

Running the ossevol utility changes the physical structure of your database. Consequently, you should back up your database before you run the ossevol utility.

Syntax

ossevol workdb new_schema.adb evolvedb.bak ... options 
workdb is the name of a scratch file that ossevol uses as a 
workspace; you can delete this file after ossevol has finished 
successfully. new_schema.adb is the revised and regenerated 
application schema database. evolvedb.bak is a copy of the 
database to be evolved, which ossevol modifies to become the 
evolved database.

Options
-task_list filename
Specifies that the ossevol utility should produce a task list and place it in the file specified by filename. Use "-" for stdout. When you specify this option, ObjectStore does not perform schema evolution.

The task list consists of pseudofunction definitions that indicate the way the migrated instances of each modified class would be initialized. This allows you to verify the results of a schema change before you migrate the data.

 
-classes_to_be_removed class-name(s)
Specifies the name of the classes to be removed.

 
-classes_to_be_recycled class-name(s)
Specifies the name of the classes whose storage space can be reused. By default, the storage associated with all classes is recycled.

 
-dll_schema pathname(s)
Specifies the pathnames of component schema databases to be used in addition to the new application schema. Use spaces between multiple pathnames.

 
-drop_obsolete_indexes { yes | no }
Specifies whether obsolete indexes encountered in the course of the evolution should be dropped. The default is no, meaning that they are not dropped.

 
-local_references_are_db_relative
Specifies that all local references are relative to the database in which they are encountered. The default is no.

 
-resolve_ambiguous_void_pointers
Resolves ambiguous void pointers to the outermost enclosing collocated object. The default is no.

 
-explanation_level n
A number from 1 to 3, primarily an internal debugging aid.

Description

 When you specify two or more classes for an option, separate the class names with a space.

Changes can include

You can use the ossevol utility to evolve the following changes:

Changes cannot include

 You cannot use the ossevol utility to evolve changes that include

Changes might include

 You might be able to use the ossevol utility to evolve the following changes. In each item, the information after the first sentence indicates reasons that the ossevol utility might not be able to perform the evolution.

Evolution not required

 These changes do not require schema evolution:

Except on Windows NT, the following two changes do not require schema evolution. On Windows NT, these two changes require schema evolution in some cases. You receive a schema validation message when you run the schema generator and schema evolution is required.

Transformer function required

 These changes require application-specific transformer functions:

Schema protection

 When developing an application, if you are running this utility on a protected schema database, ensure that the correct key is specified for the environment variables OS_SCHEMA_KEY_LOW and OS_SCHEMA_KEY_HIGH. If the correct key is not specified for these variables, the utility fails. ObjectStore signals

err_schema_key _CT_invalid_schema_key,
"<err-0025-0151> The schema is protected and the key provided did not 
match the one in the schema."
When deploying an application, if your end users need to use the ossevol utility on databases protected by a schema key, you must supply them with an application that uses the ObjectStore Schema Key API to set the correct schema key and then os_schema_evolution::evolve(). End users need not know anything about the key.

For more information about protecting database with schema keys, see Restricting Access with Schema Keys in C++ API User Guide.

API

For complete information about the schema evolution API, see os_schema_evolution in C++ API Reference and Chapter 8, Advanced Schema Evolution, in Advanced C++ API User Guide.



[previous] [next]

Copyright © 1999 Object Design, Inc. All rights reserved.

Updated: 03/11/99 11:19:07