osdump: Dumping Databases

Syntax

osdump [options] [-emit] pathname ...


pathname ...

One or more pathnames, separated by spaces, specifying the database or databases to be dumped or (if -emit is supplied) specifying the database or databases for the loader source that is to be emitted.

• Dumps to an ASCII file the contents of a database or group of databases.
• Generates the source files for a loader executable capable of creating, given the ASCII as input, an equivalent database or group of databases. osdump also produces a makefile for your platform that allows you to build the loader executable with a single make or nmake command.

• First, without -emit, to dump the ASCII representation of the databases
• Second, with -emit, to generate the source for a loader tailored to the databases

The schema for the dumped databases is stored in a remote schema database associated with the dump.

See also osload: Loading Databases.

Default compared to customized dump and load

To determine when to customize, see When Is Customization Required?. To learn how to customize, see Chapter 7, Dump/Load Facility, in the Advanced C++ API User Guide.

Generated ASCII files

• filename.dmp for each dumped database, filename.db
• db_table.dmp, which records information about the dumped databases (you can change the name of this file with the -tab option)

Generated source and makefiles

• ldrdef00.h: Contains structs to hold loaded data before class construction.
• ldrhdr.h: A stub file to which you add lines to #include user headers.
• ldrldr00.h: Declarations of the classes needed for loading each of the classes in the dumped databases.
• ldrldr00.cpp: Implementation of the classes needed for loading each of the classes in the databases.
• ldrsch00.cpp: Contains OS_MARK_SCHEMA_TYPE() calls for each class in the databases.
• ldrmai00.cpp: The main() file for osload.
• makefile.unx or makefile.w32: The build file for UNIX or Windows, respectively. The version of the produced makefile depends on the platform on which you run osdump.

To build the loader from these files, use the makefile produced by osdump. On UNIX, use the make utility and makefile.unx. On Windows, use nmake and makefile.w32.

Considerations

• Dumping and loading a large database with segments or collections comparable in size to the available address space may not be possible.
• Indexes for collections are always put into the same segment as the collection even if the original index was in a different segment.
• User-defined constructors for non-specialized classes will not be executed during the load.
• If you plan to load a database on a platform with a different architecture from the architecture of the original database, you should neutralize the database and emit the loader on the platform with the target architecture.

In general, two databases are equivalent if every object in one database has a corresponding, equivalent object in the other database. Two objects are equivalent if

• The fundamental values they contain, directly or indirectly, are the same.
• The pointers or references they contain refer to corresponding objects (that is, if an object in a dumped database points to o, the corresponding object in the loaded database points to the object that corresponds to o).

Two objects, o1 and o2, are equivalent (according to map()) if and only if all the following are true:

• o1 and o2 have the same type.
• If the type of o1 is fundamental, o1 and o2 have the same value.
• If o1 is a pointer or (C++) reference, map(the referent of o1) is the referent of o2.
• If o1 is an array, o1 and o2 have the same cardinality, and for every index-list, o1[index-list] is equivalent to o2[index-list].
• If the type of o1 is a non-ObjectStore class, for every member, m, of o1, o1.m is equivalent to o2.m.
• If o1 is an ObjectStore reference, map(the referent of o1) is the referent of o2.
• If o1 is an ObjectStore collection, o1 and o2 have the same cardinality, and for each element, e, of o1, e has the same count in o1 as map(e) does in o2.
• If o1 is an ordered ObjectStore collection, for each element, e, of o1, e has the same position in o1 as map(e) does in o2.
• If o1 is an ObjectStore index, o1 and o2 have the same path and index options, and map(the collection that o1 indexes) is the collection that o2 indexes.
• If o1 is an ObjectStore cursor, o1 and o2 have the same cursor options, and map(the element at which o1 is positioned) is the element at which o2 is positioned.
• If o1 is an ObjectStore database root, o1 and o2 have the same root name, and map(o1's associated entry-point object) is o2's associated entry-point object.
• If o1 is an ObjectStore index path, o1 and o2 represent the same paths.

A dumped object and its equivalent loaded object do not necessarily have the same location, that is, the same offsets in their segment. Among the implications of this are the following:

• Other objects might use different pseudoaddresses to refer to them.
• Their addresses might hash to different values; that is, for example, objectstore::get_pointer_numbers() might return different values for them.

The default dumper and loader also take into account the second implication for ObjectStore types including collections with hash-table representations. Because a dumped collection element hashes to a different value than the corresponding loaded element does, their hash-table slots are different. The facility, then, does not simply dump and load the array of slots based on fundamental values (which would result in using the same slot for the dumped and loaded objects).

Instead, it dumps the collection in terms of sequences of high-level API operations (that is, string representations of create and insert arguments) that the loader can use to recreate the collection with the appropriate membership.

The default dumper and loader do not take into account the second implication for non-ObjectStore classes. If you have your own classes that use hash-table representations, you must customize their dumping and loading. Any other location-dependent details of data structures (such as encoded offsets) also should be dealt with through customization.

See Chapter 7, Dump/Load Facility, in the Advanced C++ API User Guide.

Performance

Converting a Database

1. Dump the databases using the Release 5.1 version of osdump to create the database table file and the ASCII representations of the databases.
   
   

1. Generate a Release 6.0 schema that corresponds to the schema of the Release 5.1 database.
   
   

      ossg -asof schema.obj -asdb schema.adb /nologo /GX /MD \

      /DWIN32 schema.cc

      ossg -assf dschema.cc -asdb schema.adb \

      -I$OS_ROOTDIR/include schema.cc

1. Use the header and schema files to build a Release 6.0 application that simply creates an empty Release 6.0 database. The source code for a simple application to do this is
   $OS_ROOTDIR/etc/dummy.cc. Copy this to the working directory and compile. On Windows:
   
   

      cl /Fedummy.exe /nologo /GX /MD /DWIN32 dummy.cc \

      schema.obj %OS_ROOTDIR\lib\ostore.lib

      CC -o dummy dummy.cc dschema.cc -los -loscol -losthr

1. Run the application to create the empty database:
   
   

      dummy my_db.db

1. Generate the loader source files from the empty database using the Release 6.0 version of osdump.
   
   

      osdump -emit my_db.db

1. Build an osload executable from the loader source files. On Windows, use nmake and makefile.w32. On UNIX, use the make utility and makefile.unx.
   
   
2. Generate the Release 6.0 format database by running osload and specifying the database table file and the ASCII database representations you dumped in step 1.
   
   

      osload db_table.dmp filename.dmp

Default Dumper ASCII Format

For each dumped database, filename.db, filename.dmp has the format shown for database, in the following information:

database_table ::= 
      databases [ number_databases ] 
            { database_entry [ database_entry ]* } 
number_databases ::= 
      the integer number of dumped databases 
database_entry ::= 
      < 
            pathname 
            database_size 
            number_segments 
            odi_release 
            architecture (date) 
      > 
database ::= 
      database [database_index] pathname segments roots finalization

      fixups
pathname ::= 
      the pathname of the database being dumped 
database_size ::= 
      the size of the database in an integral number of bytes 
number_segments ::= 
      the integral number of segments contained in the database 
odi_release ::= 
      the ObjectStore release information 
architecture ::= 
      the host architecture set for the database 
date ::= 
      the date the database was last modified 
database_index ::= 
      the index of this database within the list of databases being 
      dumped (0-based) 
roots ::= 
      roots [ number_roots ] { root [ , root ]* } 
root ::= 
      name ( Type ) id 
segments ::= 
      segments [ segment ]* 
segment ::= 
      segment segment_number [segment_size] 
            (pathname) data 
segment_number ::= 
      integral segment number of this segment within its database 
data ::= 
      ( objects )* 
cluster ::= 
      cluster [cluster_size] { objects } 
objects ::= 
      object* 
object ::= 
      id ( type ) value 
id ::= 
      <database_index,segment_number,cluster_number,offset> 
offset ::= 
      integral value denoting the byte offset of an object 
            within its segment 
type ::= 
      integral | real | pointer | reference | array | class 
value ::= 
      character | integral | floating_point | pointer_value | reference | 
            collection | string | array_elements | class_members 
integral ::= 
      char | signed char | unsigned char | signed short | 
            unsigned short | int | unsigned int | signed long | 
                  unsigned long 
real ::= 
      float | double 
pointer ::= 
      type* 
reference ::= 
      type& 
array ::= 
      array type [ size ] 
class ::= 
      ( class | struct | union ) name 
character ::=
'      c' where c is any printable ascii character or escaped hex value
integral ::= 
      any non-floating-point decimal number 
floating_point ::= 
      any floating-point decimal number 
pointer_value ::= 
      id 
string ::= 
      "s" where s is any sequence of printable ascii characters or 

      escaped hex value with '"' escaped as "\"" and '\' escaped as "\\". 
array_elements ::= 
      { value [ , value ]* } 
class_members ::= 
      { value [ , value ]* } 

The special storage types cluster, segment, and database denote underlying ObjectStore storage structures. When a storage type appears, each object following is contained within that storage structure.

Other types denote C++ type constructs. Values appear as single values or as a bracketed comma-separated list of values. Base class instances and other embedded subobjects are flattened into a class_members list.

ObjectStore references or soft pointers, collections, cursors, indexes, and queries are instances of Object Store types that require special treatment. The following special dump formats are used for them:

reference ::= 
      id
collection ::=       
      simple_collection | dummy_cursor | cursor | cursor_with_index | 
                  cursor_with_range | collection_index | 
                        collection_element_load | collection_query 
simple_collection::= 
      [ behavior cardinality collection_type representation_enum ] 
behavior::= 
      integral 
cardinality::= 
      integral 
collection_type::= 
      string 
representation_enum::= 
      integral 
dummy_cursor::= 
      [ D ]
cursor::= 
      [ C options ]
collection_reference::= 
      reference 
safe_flag::= 
      integral 
cursor_with_index::= 
      [  C options
            { I path_name_length path_name element_name_length 
                  element_name } ]
path_name_length::= 
      integral 
path_name ::= 
      string 
element_name_length::= 
      integral 
element_name::= 
      string 
cursor_with_range::= 
      [  C collection_reference safe_flag 
            { R range_type key_type low_condition low_value H 
                  high_condition high_value } ]
range_type::= 
      integral 
key_type::= 
      integral 
low_condition::= 
      boolean 
low_value::= 
      integral 
high_condition::= 
      boolean 
high_value::= 
      integral 
boolean::= 
      0 | 1
collection_index::=  
      [ [{ path_name_length path_name element_type_length 
            element_type_name }]* ]
collection_element_load::= 
      [ [element_reference]* ]
element_reference::= 
      reference 
element_type_length::= 
      integral 
element_type_name::= 
      string 
collection_query::= 
      [ element_type_length element_type  < query_string_length 
            query_string > < file_name_length file_name > 
                  < line_number > ]
query_string_length::= 
      integral 
query_string::= 
      string 
file_name_length::=
      integral 
file_name::= 
      string 
line_number::= 
      integral 

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