If you are upgrading from an earlier release of ObjectStore to Release 6.0, you must perform the following steps:

1. If you have not already done so, upgrade to the latest Service Pack of ObjectStore Release 5.1. You must be at Release 5.1 to perform the remaining steps in this procedure. For information about upgrading from pre-5.1 to Release 5.1, see the ObjectStore 5.1 Release Notes.
   
   
2. Edit the source code of your application to remove or replace all incompatibile features of the ObjectStore API, and recompile under Release 6.0. For more information about performing this step, see Migrating Application Source Code.
   
   
3. Use the ObjectStore dump/load facility to migrate a 5.1 database to Release 6.0. See Migrating a 5.1 Database to Release 6.0 for how to use the ObjectStore dump/load facility to perform this step.
   
   

Migrating Application Source Code

• Features of the API that must be removed or replaced in a 5.1 application because they are not supported in Release 6.0. Attempting to compile an application under Release 6.0 that has any of these features will result in compile-time errors. For a simple list of all classes and methods that have been removed from the ObjectStore API for Release 6.0, see the main index entry "removed APIs" in the Index.
• Changed features of the API that can affect the run-time behavior of your program. The compiler cannot always detect these features, but their presence in an application can result in either run-time exceptions or unexpected behavior.

Removing and Replacing Incompatible APIs

The following list of incompatible features is not exhaustive, but concentrates on those that are most likely to occur in user applications:

• The C library interface to ObjectStore is not supported in Release 6.0. All applications written in C must be rewritten to use the C++ API.
• The os_object_cluster class has been removed and replaced by the class os_cluster. For an overview of the role of clusters in the architecture of Release 6.0 of ObjectStore, see Clusters. For reference information about the new os_cluster class, see os_cluster.
• The os_database_reference class and a number of member functions of os_database and os_segment that provided support for cross-database pointers have been removed. Support for cross-database pointers is now provided by the affiliation API. For more information, see Affiliation and Cross-Database Pointers.
• The segment-locking API has been removed. This API includes get_lock_whole_segment() and set_lock_whole_segment(), which were defined for the classes os_database and os_segment. These methods have been replaced by the get_lock_option() and set_lock_option() methods, which are defined by objectstore, os_database, os_segment, and os_cluster. For more information, see the descriptions of the new methods in Chapter 3, Changes to the API.
• The os_segment::get_default_segment_size() and os_segment::set_default_segment_size(), and os_segment::set_size() methods have been removed. In previous releases, these methods allowed you to presize segments. ObjectStore no longer supports presizing segments.
• The os_database::get_default_null_illegal_pointers() and os_segment::set_default_null_illegal_pointers() methods have been removed. For information about support for illegal pointer detection in , see C++ API User Guide, "Pointers and Persistent Memory" in Chapter 3.
• Access hooks are not supported in Release 6.0. In previous releases, this support was provided by the os_database::set_access_hooks() method, which has been removed from the API.
• You cannot use operator delete to destroy a persistent root. You must use os_database_root::destroy() instead. However, you can use operator delete to delete transient os_database_root objects.
• The os_database::decache() method has been removed from the API. Internal cleanup is now performed when you use operator delete to remove an os_database object. For other ways to manage os_database objects, see os_database::release_pointer() and os_database::retain_pointer().
• The os_transaction::abort_only enumerator has been removed from the API. If you want an abort-only transaction, you can nest an update transaction inside a read-only transaction, as described in Abort-Only Transactions.
• The objectstore::discriminant_swap_bytes() method, which provided support for persistent unions, has been removed. For information about persistent unions, see Support for Persistent Unions.
• The os_pvar class has been removed. Use os_Reference instead, or create an instance of os_database_root in one transaction and use it in another. (In Release 6.0, os_database_root objects are not persistent, making it possible to use them across transaction boundaries.)

Changes to the collections API

• Previous to Release 6.0, the default behavior for new collections was to signal an exception if you tried to pick from an empty collection. In Release 6.0, a pick from an empty collection always returns null. (os_collection::pick_from_empty_returns_null is supported for backward compatibility, but has no effect.)
• Safe cursors are not supported in Release 6.0. Consider using update-insensitive cursors instead.
• os_index_path::destroy() and os_coll_query::destroy() have been removed from the API. Use the delete operator to delete the object.
• os_rDictionary has been removed. The introduction of soft pointers in Release 6.0 eliminates the need for reference-based collections; see Soft Pointers.
• The os_rep class has been removed. How you replace it depends on the reason for you are using it:
  • If you used os_rep because you wanted a reference-based collection, removing os_rep from your code will have no impact. All Release 6.0 collections use soft pointers, which eliminates the need for reference-based collections.
  • If you used os_rep because you wanted an index-only collection, consider using os_Dictionary, which will result in a better implementation.
• In your Release 6.0 makefiles, remove all references to .ldb files. In Release 6.0, schemas are loaded automatically.

Nested opens

To make your program run correctly, make the open modes consistent in the nested calls to open(). If you are changing the open mode to protect the database, consider making the transaction read-only.

The Release 6.0 semantics of close() are compatible with its 5.1 semantics. For more information, see Opening and Closing Databases. For descriptions of Release 6.0 versions of open() and close(), see os_database::open() and os_database::close().

Managing lifetimes of ObjectStore objects

• os_database
• os_database_root
• os_segment

For more information, see Managing ObjectStore Objects.

Dump/load facility

For detailed information about the dump/load facility, see osdump: Dumping Databases in Chapter 4 of Managing ObjectStore and Chapter 7, Dump/Load Facility of Advanced C++ API User Guide. For information about using the dump/load facility as a migration tool, see Migrating a 5.1 Database to Release 6.0.

Note

Changes that can Improve Performance and Functionality

The following are the most significant Release 6.0 features that you might want to use in your application:

• Sessions; see ObjectStore Sessions Facility
• Clustering; see Clusters
• Soft pointers; see Soft Pointers
• Relocation optimization; see Relocation Optimization. In previous releases your application may have included code to perform relocation optimization. In Release 6.0, you can eliminate this code because of the relocation optimization performed by ObjectStore.

The class of objects stored in notes.db is simple and requires only the steps outlined in this procedure to migrate to Release 6.0. If your database stores more complicated objects (for example, unions, hash tables, or other data structures that rely on actual addresses or offsets to locate data stored in the database), refer to the discussion of the dump/load facility in Chapter 7, Dump/Load Facility of Advanced C++ API User Guide. For a description of osdump, see osdump: Dumping Databases in Chapter 4 of Managing ObjectStore.

Following is the migration procedure:

1. Run the 5.1 version of osverifydb to ensure that the database has no errors.
   
   
2. Run the 5.1 version of osdump to dump your database to an ASCII file:
   
   

   osdump notes.db

3. Generate a Release 6.0 schema for your database by running ossg against your application's schema source file.
   
   

   Windows: ossg -asof schema.obj -asdb schema.adb /GX /MD /DWIN32 schema.cpp

   UNIX: ossg -assf dschema.cc -asdb dschema.adb schema.cc

4. Make a copy of the source file provided by ObjectStore for loading the 6.0 database that uses the schema for your application:
   
   

   Windows: copy $OS_ROOTDIR\etc\dumpload\dummy.cc
   create_db6.cpp

   UNIX: cp $OS_ROOTDIR/etc/dumpload/dummy.cc \
   create_db6.cc

5. Compile this C++ source file and the application schema source file output by ossg to produce the executable file that will generate the schema for the new Release 6.0 database:
   
   

   Windows: cl /Fecreate_db6.exe /nologo /GX /MD /DWIN32
   create_db6.cpp schema.obj %OS_ROOTDIR%\lib\ostore.lib

   UNIX: CC -o create_db6 create_db6.cc dschema.cc \
   -I$OS_ROOTDIR/include -los -loscol -losthr

6. Run the executable produced in the previous step, specifying the name of the new database as an argument:
   
   

   create_db6 database6.db

7. Generate source files for the loader by running the 6.0 version of osdump, specifying the -emit option and the name of the database you created in the previous step as arguments:
   
   

   osdump -emit database6.db

8. Make a copy of your application's header file, which contains the declarations of all the persistently stored classes, renaming the copy ldrhdr.h:
   
   

   Windows: copy note.hh ldrhdr.h .

   UNIX: cp note.hh ldrhdr.h .

   If your application has more than one header file that contains declarations of persistent classes, either copy them all to ldrhdr.h or use the include directive to include them.

9. Produce the executable osload by running make, specifying the name of the makefile generated in the previous step:
   
   

   Windows: nmake -f makefile.w32

   UNIX: make -f makefile.unx

10. Generate the Release 6.0 version of your database (in this example, notes.db) by running the executable (osload) generated in the previous step. In this example, osload is specified with the -cwd option so that 6.0 database written to the current working directory rather than to the directory in which the 5.1 database was originally created:
    
    

    osload -cwd db_table.dmp notes.dmp

Running Different Releases of ObjectStore

To help you manage different releases, we define the C preprocessor macro OS_MAJOR_RELEASE. This macro is an integer and is defined in the header file osreleas.hh. ObjectStore sets the value of OS_MAJOR_RELEASE to a value that represents the major release number. You can use this variable in C preprocessor directives to check for which release of ObjectStore is currently running and to determine whether the compiler should emit code that performs a Release 6.0 operation or a Release 5.1 operation, as in the following:

#if (OS_MAJOR_RELEASE == 6) 
      // do it the Release 6.0 way 
#else 
      // do it the 5.1 way 

Updated: 03/11/99 12:17:56