This chapter provides instructions for using the schema generator to generate application, component, library, and compilation schemas.

Caution

The topics discussed in this chapter are

• Overview of Schema Generation
• Generating an Application or Component Schema
• Generating a Library Schema
• Generating a Compilation Schema
• Hiding Code from the Schema Generator
• Unsupported Types
• Restricting Use of Template Classes and Collections
• Correcting Schema-Related Errors
• Handling Pragma Statements in Source Code
• Utilities for Working with Schemas
• Comparison of ossg Command Lines
• Comparison of Kinds of Schemas
• Deploying Products with Protected Databases
• Using Rogue Wave with Solaris Sun C++
• ossg Troubleshooting Tips

• Application schemas
• Component schemas
• Library schemas
• Compilation schemas
• Database schemas

ObjectStore stores each application, component, library, and compilation schema in its own ObjectStore database. ObjectStore stores database schemas in the associated database or in a separate database that you specify.

Each schema database must be accessible to an ObjectStore Server.

Application Schemas

• Classes the application stores in or reads from persistent memory
• Classes that a library that your application links with stores in or reads from persistent memory

• Determine the layout of objects being transferred between the database and the application
• Validate the database schema to ensure that the application schema matches the database schema

Component Schemas

The rules for generating component schemas are identical to those for generating application schema, with these differences:

• Multiple component schema can be in effect at the same time in a single program.
• Batch schema installation is not supported. You must use incremental schema installation with component schema.

It is particularly important that a library schema contain definitions of persistently allocated types that users of the library do not have access to.

In addition to the library schemas you create, ObjectStore provides library schemas for its libraries that use persistent data. If you link your application with an ObjectStore library that has a library schema, you must specify that library schema when you generate the application schema. See Specifying ObjectStore Library Schemas.

Compilation Schemas

Database Schemas

Normally, ObjectStore stores a database schema in segment 0 of the database. (In each database, segment 0 is a special segment that is reserved for ObjectStore use.)

You can, however, specify an alternative database to contain the database schema. You do this when you create the database. The database whose schema is stored in another database is referred to as a remote schema database. The database that contains the schema belonging to the remote schema database is referred to as the schema database. The schema for a remote schema database resides in segment 0 of the schema database.

An application augments a database schema through batch (the default) or incremental schema installation.

With batch schema installation, the first time an application accesses a database, each class in the application's schema that can be persistently allocated is added to the database's schema (if it is not already present in the database schema). Subsequent execution of the application does not install schema in that database unless the application's schema changes (as evidenced by a change in the internally stored date of the application schema database).

With incremental schema installation, a class is added to a database's schema only when the first instance of that class is allocated in the database. You can specify incremental schema installation for a particular database in your source code.

The following table is a simple comparison of batch and incremental schema installation:

Batch Schema Installation	Incremental Schema Installation
Schema is larger.	Schema is smaller.
Administrative work is done at the beginning.	Administrative work is done in steps; there is potential for concurrency conflict because each incremental schema installation modifies some pages and so uses some write locks.

Keeping Database Schemas and Application Schemas Compatible

• Its data members must have identical definitions and ordering in each schema.
• Both class definitions must either define at least one virtual function, or virtual functions must be absent from both definitions.

Multiple Component Schemas

If two program schemata that are loaded into the same complete program schema define types with the same name, the type definitions must be identical.

This is only checked for types that appear in the schema of a database that is in use. An error will show up as a schema validation error.

When a new type is installed into a database schema, it will be validated against all program schemata and a schema validation error will be signaled if there are multiple inconsistent definitions.

Schemas Are Platform Specific

Consider that an application schema corresponds to an executable, a component schema corresponds to a DLL, a library schema corresponds to a library, and a compilation schema corresponds to an object file. Just as executables, libraries, and object files are platform specific, so are their accompanying schema databases.

Generating an Application or Component Schema

Output

• Application schema database. The schema generator creates the application schema and stores it in an ObjectStore database.
• Intermediate schema source file. This file records the location of the application schema database along with the names of the application's virtual function dispatch tables, the names of discriminant functions, and the definitions for any get_os_typespec() member functions.

When you use ossg on Windows platforms, the schema generator creates the application schema object file directly.

Following is an illustration of the application schema generation process, extending to just before the link step.

Invoking ossg to Generate an Application Schema

ossg [ neutralizer_options] [ additional_app_options] [{-assf 

 app_schema_source_file | -asof  app_schema_object_file.obj}] 

-asdb  app_schema_db schema_source_file [ lib_schema_db1 ...  lib_
schema_dbn]-cd  class_definition_file 

ossg [ neutralizer_options] [ additional_options] -lsdb  lib_schema_db 
schema_source_file

ossg [ neutralizer_options] [ additional_options] -csdb  comp_schema_db 
schema_source_file

 neutralizer_options: [-arch setn...] [{-padm | -padc}] [-ostyp] 

[-nout file_name][{-showd | -showw}] [-nor] [-sopt]

 additional_app_options: [{ -mrlcp | -mrscp }] [-rtdp]

[-no_weak_symbols] [ additional_options]

 additional_options: [-no_default_includes] [-mrscp] 
 additional_options: [-smf] [{-sfbp | -pfb}]

ossg [ compilation_options] [ neutralizer_options] [-cpp_fixup]
[-final_asdb  final_app_schema_db] 
[-E  schema_source_file]


 compilation_options

Specifies any options that would be passed to the compiler if you were compiling a schema source file instead of generating schema from it. You should include any preprocessor options such as include file paths and macro definitions, as well as compiler options that might affect object layout, such as packing options (for example, /Zp4 for Visual C++). Optional.

If you specify the /I, -I (uppercase I), /D, or -D option, do not include a space between the option and the argument. For example, on OS/2 the following is correct:

ossg /I$(OS_ROOTDIR)\include ...

On UNIX, do not specify the -o option on the ossg command line.

On Windows, do not specify /Tp on the ossg command line.

On OS/2, when you specify any option that takes an argument do not put a space between the option and the argument. 


 neutralizer_options 

Include any of the options in ossg Neutralization Options. These options allow you to neutralize a schema for a heterogeneous application. You can include them in any order. 

Optional. The default is that neutralization is not done.


-arch set n 

The schema that is generated or updated will be neutralized to be compatible with the architectures in the specified set. See ossg Neutralization Options for explanations of the set options.

Required when you are neutralizing schema. No default.


-cpp_fixup

Allows preprocessor output to contain spaces inside C++ tokens. Specify this option if your preprocessor inserts a space between consecutive characters that form C++ tokens. For example, if your preprocessor changes :: to : :, you can specify this option so that the schema generator allows the inserted space and correctly reads the preprocessor output.

You might generate an application schema from a compilation schema and library schemas. In this case, you do not need this option because there is no source code input to the schema generator, which means that the preprocessor is not involved.

Optional. The default is that ossg does not allow a space in a C++ token such as :: or .*.


-E  schema_source_file 

The -E option causes ossg to preprocess the input file and send the preprocessed output to standard output.

This option is useful for debugging ossg parsing problems, because it allows you to see the results of any preprocessing that might have occurred without generating the schema. It is also useful when you report ossg problems to Technical Support because it allows the problem to be reproduced by Object Design without the need to package all your application's include files.

When specifying the -E argument, you cannot specify schema databases on the same command line. Only the schema source file and preprocessor switches, such as macro definitions and include paths, should be specified.


-final_asdb  final_app_schema_db

Specifies a location for the application schema database that is different from the location you specify with the -asdb option. The schema generator writes the location you specify with the -final_asdb option into the application schema source file (application schema object file for Visual C++). Use this option when you cannot specify the desired location with the -asdb option. The -asdb option is still required and that is where the schema generator places the application schema.

This option is useful when you plan to store the application schema database as a derived object in a ClearCase versioned object base (VOB). The schema generator cannot place the application schema database directly in a ClearCase VOB. If you specify the -final_asdb option with the desired location, you avoid the need to run the ossetasp utility, which patches an executable so that it looks for its application schema in a database that you specify. 

You can also use this option to specify a relative path.

After you run ossg with the -final_asdb option, remember to move the application schema to the database you specify with -final_asdb.

You must specify an absolute pathname with -final_asdb.

Optional. The default is that the schema generator writes the pathname that you specify for -asdb in the application schema source file (object file for Visual C++).


-mrlcp or -make_reachable_library_classes_persistent

Causes every class in the application schema that is reachable from a persistently marked class to be persistently allocatable and accessible. 

This option is supplied for compatibility purposes only. The use of the -mrlcp option is discouraged. Specify
-mrscp instead.

When you specify this option, you cannot neutralize the schema for use with a heterogeneous application. If you are building a heterogeneous application, you must either mark every persistent class in the schema source file or specify the -mrscp option.

If you do not mark any types in the schema source file and you specify -mrlcp when you run ossg, then the application schema does not include any types. You must mark at least one type for there to be any reachable types.

Optional. The default is that only marked classes are persistently allocatable and accessible.

See also Determining the Types in a Schema.


-mrscp or -make_reachable_source_
classes_persistent

Causes every class that is both


Defined in the schema source file 



Reachable from a persistently marked class


to be persistently allocatable and accessible. 

The difference between -mrscp and -mrlcp is that when you specify -mrscp, it applies to the schema when ossg is translating from source to schema. This allows the schema generator to recognize which types you plan to allocate persistently. The -mrlcp option applies to the application schema after the merging of constituent schemas.

The benefit of specifying the -mrscp option is that it allows you to perform a persistent new for a type that you did not explicitly mark in the schema source file. The drawback is greater execution time and executable size overhead. 

If you do not mark any types in the schema source file and you specify -mrscp when you run ossg, then the application schema does not include any types. You must mark at least one type for there to be any reachable types.

Optional. The default is that only marked classes are persistently allocatable and accessible.

See also Determining the Types in a Schema.


-no_default_includes or 
-I-

When you specify this option, ossg does not automatically specify any include directories to the C++ preprocessor. However, the preprocessor can have default include directories built in. If there are any directories that are built into the preprocessor, ossg does check these built-in directories. Typically, the preprocessor uses built-in include paths to find standard include files such as stdio.h.

When you specify this option, you must explicitly specify directories that contain included files. 

For example, on some UNIX systems, when you do not specify this option, the C++ preprocessor looks for include files in the /usr/include directory. 

Note that if you want the schema generator to pass the ObjectStore include directory to the preprocessor as a directory for finding included files, you must always specify it. For example:

UNIX: -I$OS_ROOTDIR/include

Windows and OS/2: -I%OS_ROOTDIR%\include 

The -I- option is the letter I as in Include. Specifying -I- is the same as specifying -no_default_includes.

Optional. The default is that the preprocessor checks default directories for included files. 


-nor

A neutralizer option that prevents the schema generator from instructing you to reorganize your code as part of neutralization. This is useful for minimizing changes outside your header file, working with unfamiliar classes, or simply padding formats.

See ossg Neutralization Options for more information.


-neutral_info_output  filename or
-nout  filename 

A neutralizer option that indicates the name of the file to which neutralization instructions are directed. 

Optional. Default is that the schema generator sends output to stderr.


-no_weak_symbols

Default. Notifies you of missing vftbls and discriminants, allowing you to check whether a referenced vtbl or discriminant function symbol is undefined. 

If you specify -rtdp maximal -no_weak_symbols, the linker outputs messages about what is missing. You can use this information to determine which additional classes you need to mark. These missing symbols are only a hint about what you might consider marking. They might also be the result of a link line error.

Specify the option -weak_symbols to suppress this behavior.


-pad_maximal or -padm |
-pad_consistent or -padc 

Neutralizer options that indicate the type of padding requested. See ossg Neutralization Options for additional information.

Optional. Default is -padc.


-parse_function_bodies or -pfb

This option ensures that any types that are marked inside a function are parsed by ossg. If you do not explicitly use this option and you have any types marked inside functions, an error is reported. See ossg Troubleshooting Tips for further information.

Optional. The default is that the -sfbp option is set. 


-runtime_dispatch or -rtdp
{minimal | derived | full | maximal}

Specifies the classes for which the schema generator makes vftbls and discriminant functions available. 

minimal specifies marked classes, classes embedded in marked classes, and base classes of marked classes. 

derived specifies the minimal set plus classes that derive from marked classes and classes embedded in the derived classes. 

full specifies the derived set plus the transitive closure over base classes, derived classes, and classes that are the targets of pointers or references. The full specification does not include nested classes or enclosing classes unless they meet one of the previous criteria.

maximal specifies the full set plus nested types. In previous ObjectStore releases, this was the default. If your application used an earlier release of ObjectStore and you do not specify this option, you might need to mark classes that you did not previously mark.

See Example of Using the -runtime_dispatch Option.

Optional. The default is derived.


-show_difference or -showd |
-show_whole or -showw



Neutralizer options that indicate the description level of the schema neutralization instructions. Optional. Default is -show_whole.


-skip_function_body_parsing or
-sfbp

Optional. Specifies that code within function bodies is not parsed. By default this option is in effect. 


-schema_options  option_file or
-sopt

A neutralizer function that specifies a file in which you list compiler options being used on platforms other than the current platform. See Listing Nondefault Object Layout Compiler Options for further information.


-store_member_functions or -smf

Causes ossg to create an instance of os_member_function for each member function in each class in the schema source file. It then puts these instances in the list of class members, which includes member types and member variables. 

This is useful when you intend to use the MOP to inspect the member functions. If you are not planning to inspect member functions, you should not specify this option, because it wastes disk space.

This also means that additions and deletions of member functions are schema changes and affect validation.

When you generate an application schema, you might specify a library or compilation schema. If you want to capture the member functions from the library or compilation schema, you must have specified the -store_member_functions option when you generated the library or compilation schema. You must also specify the -store_member_functions option when you generate the application schema.

Optional. The default is that ossg generates a schema that includes member types and member variables, but not member functions. 


-weak_symbols
Suppresses notification about missing vftbls and discriminants. This option overrides the default behavior described at -no_weak_symbols.


-assf  app_schema_source_file or
-asof        app_schema_object_file.obj

Specifies the name of the application schema source file or application schema object file to be produced by ossg. For all compilers except Visual C++, the schema generator produces a source file that you must compile. When you use Visual C++, the schema generator directly produces the object file. 

Required. No default.


-asdb  app_schema_db.adb 

Specifies the name of the application schema database to be produced by ossg. If the schema database exists and is compatible with the type information in the input files, the database is not modified. 

This pathname must be local to a host running an ObjectStore Server.

The pathname should have the extension . If you want to specify an existing application schema database with ossg, the application schema must have .adb as its extension.

Required. No default.


 schema_source_file 

Specifies the C++ source file that designates all the types you want to include in the schema. It should include all classes that the application uses in a persistent context.

No default. Required except in two cases: 


When you generate an application schema from a compilation schema as described on page  56



If you specify one or more library schemas that contain all the persistent types that your application uses 



 lib_schema.ldb ...

Specifies the pathname of a library schema database. The name must end in .ldb. This can be an ObjectStore-provided library schema or a library schema that you created with ossg. 

The schema generator reads schema information from the library schema database specified and modifies the application schema database to include the library schema information. You can specify zero or more library schema databases.

Optional. The default is that library schemas are not included.

OS/2 Platforms Have an Additional ossg Option

The reason for this option is that the icc compiler does not make public a number of symbols that ObjectStore needs to link your persistent data to your program at run time. However, these symbols are available to any file that includes your class definitions. Consequently, the application schema source file produced by the schema generator must include the class definitions for all persistent classes your application might need. For example:

ossg -assf osschema.cpp -cd schmdefs.hh -asdb myschema.adb \
myschema $(OS_ROOTDIR)\lib\os_coll.ldb

@ filename 

When the schema generator encounters this option, it reads additional options and arguments from filename. Note that the command line passed to the compiler for preprocessing is the fully expanded command line, so those options that are passed to the compiler must still meet command-line length restrictions.

Be sure that you do not insert a space between @ and filename. You can specify this option on any platform.

On OS/2 and Windows NT, this is commonly used to avoid problems with the length of a command line in Microsoft's nmake program. The usual nmake syntax is

ossg  -other-args @<<
$(LONG_ARGS1)
$(LONG_ARGS2)
<<

Specifying Remote Library Schemas

How Long Does Schema Generation Take?

If You Omit a Required Library Schema

If the collections library schema is required, and you omit it, the linker typically displays a message indicating that there are missing get_os_typespec functions. If os_tinyarray::get_os_typespec() is among them, this probably indicates that you failed to include the collections library schema while building the application schema.

If the types in a library are not persistently used,

• It might not matter if the corresponding library schema is not specified when the application schema is generated. For example, there might be types that are persistent in some situations but not in others. Also, if there are get_os_typespec() functions, the library schema is required. Consequently, Object Design recommends that you always specify a library schema when you use a type in that library, whether or not the types are persistently used.
• The database schema might be larger than necessary when batch schema installation is used.

Here is a trivial application:

#include <ostore/ostore.hh>
#include <ostore/coll.hh>
main ()
{
      OS_ESTABLISH_FAULT_HANDLER
      objectstore::initialize();
      os_collection::initialize();
      OS_END_FAULT_HANDLER
return 0;
}

Schema source file

#include <ostore/ostore.hh>
#include <ostore/manschem.hh>

ossg -assf os_nullschm.cc -asdb nullschm.adb nullschema.cc

Running the ProCompiler

CC -pta -vdelx -mt -o test test.o os_nullschm.o -loscol -los -losthr

Undefined                       first referenced
 symbol                             in file
static _RH_ref<_RH_ref_slot_SHV>::get_os_typespec(void) 
...
...

Example of Using the -runtime_dispatch Option

class A {
public:
      class B { public: G* gp; };
      E* ep;
};
class C : public A { };
class D : public A { };
class E { };
class F : public D { public: E e; };
class G { public: E e; }
class H { };

Using the Same Application Schema for Multiple Applications

1. Generate the application schema that you want the applications to share.
   
   
2. Compile the application schema source file produced by the schema generator. (If you are using Visual C++, the compiler directly produces the application schema object file.)
   
   
3. Link the application schema object file into each application that you want to use this schema. When applications share an application schema object file, they consequently share the application schema.
   
   

Examples of Generating an Application Schema

ossg -assf myschema.cc -asdb myschema.adb schema_source.cc

ossg -mrscp -assf myassf.c -asdb my.adb mine.c my.ldb your.ldb 

Windows

ossg -asof jetsch.obj -asdb jetsch.adb jetsch.cc \ %OS_
ROOTDIR%\lib\os_coll.ldb

OS/2

ossg -assf paris.cc -asdb paris.adb paris_sch_source.cc\ 
-cd paris.hh %OS_ROOTDIR%\lib\oscmpct.ldb

Generating a Library Schema

You specify the library schema when you generate the application schema for applications that use the library. ObjectStore adds the types defined in the library schema to the application schema.

In addition to the library schemas you create, there are library schemas that ObjectStore provides. Specifying ObjectStore Library Schemas describes library schemas provided with ObjectStore.

Makefiles

• Specify the -lsdb option on the ossg command line. Do not specify the -asdb option.
• Do not specify the -assf or -asof option. Generating a library schema does not involve generating the application schema source (or object) file.

Invoking ossg to Generate a Library Schema

Using Multiple Schema Source Files to Create a Library Schema

ossg -lsdb foo.ldb s1.cc
ossg -lsdb foo.ldb s2.cc

If you modify a source file from which you created a library schema and run ossg again, the schema generator adds to the library schema. It does not overwrite the existing library schema. If you do not want to add to the existing library schema, you must remove the old schema or specify a name for a new library schema.

For example, if you modify s1.cc after you create foo.ldb and then you run ossg again, ossg adds to foo.ldb. It does not overwrite foo.ldb.

Example

ossg -lsdb part.ldb partschm.cc

If you specify neutralization arguments when you generate a library schema, you must specify the same neutralization arguments each time you run ossg to update that library schema.

If Not Creating a Library Schema

Generating a Compilation Schema

A compilation schema contains information about the classes in your application's source files that are read from or written to persistent memory. A compilation schema differs from an application schema in that the compilation schema does not include information about the classes used by libraries your application links with.

You can use ossg to explicitly generate a compilation schema before you generate the application schema.

A makefile that generates a compilation schema is almost the same as a makefile that generates an application schema. The major differences are that when you want to generate a compilation schema you

• Specify the -csdb option on the ossg command line. Do not specify the -asdb option.
• Do not specify the -assf or -asof option. Generating a compilation schema does not involve generating the application schema source (or object) file.

Why Generate a Compilation Schema?

• When building a very large application. You can split the schema source file into multiple files so that you need not regenerate the entire schema when one type description changes.
• When performing schema evolution. See ObjectStore C++ API User Guide, Chapter 8, Schema Evolution, Generating a Compilation Schema for additional information.

Example

ossg -csdb my.cdb myschema.cc

Using a Compilation Schema to Generate an Application Schema

ossg -assf engine_schema.cc -asdb engine.adb libmine.cdb 

ossg -asof engine_schema.obj -asdb engine.adb libmine.cdb 

Hiding Code from the Schema Generator

• When your source files include code that is
  • Compiler specific (not ANSI C++)
  • Not compilable by ossg; for example, code that has an error but the code is not pertinent to schema generation
• To speed up ossg

#ifndef _ODI_OSSG_
/* code you do not want the schema generator to see */
#endif

Unsupported Types

Limited Support for long long Data Type

On platforms that support long long, the schema generator recognizes this type in a source fed through it. On platforms that do not support long long, the schema generator signals an error when it encounters this type.

However, you cannot perform a persistent new for an object that includes the long long type. In other words, you cannot mark a type in the schema source file that includes a long long member. An error occurs during schema generation if you do.

Support for wchar_t Types

You can persistently store an object that has a wchar_t member type. However, code that requires implicit conversions or type promotions that involve wchar_t is not guaranteed to be recognized by the schema generator. You might need to conditionalize such code so that the schema generator ignores it.

You cannot neutralize a schema that includes the wchar_t type. The schema generator treats wchar_t types in the same manner as the architecture/compiler platform for which it is generating schema. Different platforms treat this type in different ways.

Schema evolution and queries of classes containing wchar_t types are not supported.

Restricting Use of Template Classes and Collections

• __NO_TEMPLATES__
• OS_NO_COLLECTION_TEMPLATES

The use of these macros does not affect your ability to define and use your own template classes. These macros hide only the definitions of ObjectStore templates.

__NO_TEMPLATES__

OS_NO_COLLECTION_TEMPLATES

It is not possible to allow the use of collections without allowing the use of template classes.

Caution

Correcting Schema-Related Errors

• Type mismatch errors
• Persistent allocation errors
• ossg run-time errors
• Metaschema mismatch errors

Similarly, you might get an exception when an application is run against a database, if the class definitions in the application schema are incompatible with class definitions already present in the database schema. When this happens, you might have to either change the application to match the database or evolve the schema database.

When an error occurs due to a type mismatch, the easiest way to get more information about the mismatch is to use the osexschm utility. See ObjectStore Management, Chapter 4, osexschm: Displaying Class Names in a Schema.

Persistent Allocation Errors

<err-0025-0022> Persistent new requested for type "XXX", which has not 
been marked as a legitimate type for persistent new.
<err-0025-0021> Persistent new requested for type "XXX", which was not 
found in the application schema.

• The persistent allocation was done in a library and the library schema was not supplied to ossg.
• ossg was not used.
• ossg was used, but the type was not marked with a call to the OS_MARK_SCHEMA_TYPE macro.

ossg Run-Time Errors

When the schema generator builds a compilation schema, errors can occur because a class definition used in a persistent context in one file differs from the class definition of a class with the same name in another file. This situation normally causes a compile-time error.

For library and compilation schemas, you can determine how ossg handles type-mismatch errors during schema generation. Set the environment variable OS_COMP_SCHEMA_CHANGE_ACTION to one of the following values:

warn	Reports a warning. The new type definition replaces the previous definition in the compilation schema. Default.
silent	Not reported. The new type definition replaces the previous definition in the compilation schema.
error	Reports an error. The schema generation is eventually terminated, and the compilation schema remains unchanged.

Metaschema Mismatch Errors

Schema Neutralization Errors

Missing Virtual Function Table Pointer Problems

Handling Pragma Statements in Source Code

In particular, a #pragma statement that is nested in a class does not take effect until the start of the next nonnested class. For nonpersistent classes, this might not be a problem. For persistent classes, be sure that all #pragma statements that affect structure layout occur outside the class. Otherwise, the object layout defined by the compiler and the ObjectStore schema might be inconsistent.

Utilities for Working with Schemas

• osexschm lists the classes in an application, component, compilation, database, or library schema.
• osscheq compares schemas.
• ossetasp patches an executable to use a specified application or component schema database. This utility is described on page 75. OS/2 does not support this utility.
• ossetrsp sets the pathname of a remote schema database.
• ossevol updates a database schema to reflect modifications to your application or component schema.

Comparison of ossg Command Lines

ossg [ compilation_options] [ neutralizer_options] 
[-cpp_fixup] [-final_asdb  final_app_schema_db] 
[{-mrlcp | -mrscp}] [-no_default_includes] [-no_weak_symbols]
[-rtdp {minimal | derived | full | maximal}] 
[-store_member_functions]
[-use_cf20_name_mangling | -use_cf30_name_mangling]
{-assf  app_schema_source_file or -asof  app_schema_object_file.obj}
-asdb  app_schema_database schema_source_file 
[ lib_schema.ldb ...]
On OS/2, you must also specify

-cd  class_definition_file 

ossg [ compilation_options] [ neutralizer_options] [-cpp_fixup] [-mrscp]
[-no_default_includes] [-store_member_functions]
[-use_cf20_name_mangling | -use_cf30_name_mangling]
-lsdb  lib_schema.ldb  schema_source_file 

ossg [ compilation_options] [ neutralizer_options] [-cpp_fixup] [-mrscp]
[-no_default_includes] [-store_member_functions]
[-use_cf20_name_mangling | -use_cf30_name_mangling]
-csdb  comp_schema.cdb s chema_source_file 

After you generate a compilation schema, you can use the compilation schema to generate the application schema. In this scenario, the name of the compilation schema replaces the name of the schema source file in the ossg command syntax for generating an application schema. The syntax is

ossg {-assf  app_schema_source_file | -asof  app_schema_object_
file.obj}
-asdb  app_schema_database.adb  comp_schema.cdb

This convention is not observed in Release 5.1. The Release 5.1 convention is to use names without the initial dot. Again, this is a convention and not a requirement.

Comparison of Kinds of Schemas

Kind of Schema	What Does It Contain?	How Is It Generated?	When Is It Used?
Application You specify a database in which to store it.	Definitions of classes the application stores in or reads from persistent memory, and classes persistently used by libraries the application links with.	Specify the -asdb option when invoking ossg. Naming convention recommended for an application schema: yourchoice.adb1	ObjectStore uses the application schema during run time to determine the layout of objects being transferred between the database and the application.
Component
Library You specify a database in which to store it.1	Definitions of types that the library stores or retrieves in a persistent context.	Specify the -lsdb option when invoking ossg. Naming convention required for a library schema: yourchoice.ldb	You can specify a library schema when you generate an application schema for an application that uses the corresponding library. ObjectStore adds the types defined in the library schema to the application schema.
Database ObjectStore stores it in the database itself or in a remote database if you specify one when you create the database.	Definitions of all C++ types that have ever been, or are expected to be, stored in the database.	ObjectStore creates a database schema from application schemas of the applications that access the database. An application augments a database schema through batch (the default) or incremental schema installation.	When an application accesses a database, ObjectStore checks to make sure that the definitions of classes that are in both the application schema and the database schema are the same.
Compilation You specify a database in which to store it.1	Definitions of classes the application stores in or reads from persistent memory. (It does not include classes used by libraries the application links with.)	Specify the -csdb option when invoking ossg. Explicitly creating a compilation schema is optional. Naming convention recommended for a compilation schema: yourchoice.cdb	If you explicitly create a compilation schema, you specify it to generate the application schema. ObjectStore always creates a compilation schema, and uses it to create the application schema.

Deploying Products with Protected Databases

When you deploy a product that generates a schema for a protected database, you must write an application that does the following:

1. Programmatically sets the environment variables OS_SCHEMA_KEY_LOW and OS_SCHEMA_KEY_HIGH to the correct schema key. See ObjectStore Management, OS_SCHEMA_KEY_LOW.
   
   
2. Spawns a child process that
   
   
   • Inherits the settings for the OS_SCHEMA_KEY_LOW and OS_SCHEMA_KEY_HIGH variables
   • Generates a schema for the protected database

Using Rogue Wave with Solaris Sun C++

ossg -csdb fiddle:/home/bow/aa.cdb -I$OS_ROOTDIR/include

a.cc"/opt/SUNWspro/SC3.0.1/include/CC/rw/tislist.h", line 216: Error: 
Trying to open encrypted file
 "/opt/SUNWspro/SC3.0.1/include/CC/rw/tislist.cc" while 
preprocessing."/opt/SUNWspro/SC3.0.1/include/CC/rw/tislist.h", line 
216: Error: Could not open include file "
rw/tislist.cc"."/opt/SUNWspro/SC3.0.1/include/CC/rw/tpslist.h", line 244: 
Error: Trying to open encrypted file
 "/opt/SUNWspro/SC3.0.1/include/CC/rw/tpslist.cc" while 
preprocessing."/opt/SUNWspro/SC3.0.1/include/CC/rw/tpslist.h", line 
244: Error: Could not open include file "
rw/tpslist.cc".

There are two work arounds for this:

• Buy a Rogue Wave source license.
• Modify the schema source file to avoid including the encrypted sources, which are not needed anyway. In the schema source file, include the following two lines before including any other header files:

      #include <rw/compiler.h>
      #undef RW_COMPILE_INSTANTIATE

ossg Troubleshooting Tips

Precompile

Member function declarations

• If a class has at least one virtual member function, ossg needs to see at least one virtual member function declaration so that it can install virtual function table (vtbl) information in the schema correctly.
• If there are discriminant functions (for unions) ossg must see them so they can be installed in the schema.
• If the -store_member_functions option of ossg is specified, the member functions must be visible to ossg.

Skip function body parsing

<warn-0038-0003>One or more types have been marked in a function 
body, but function bodies are not being parsed. These types will not be 
marked in the schema. Please move the marking of all types outside of 
function bodies (preferred) or specify -parse_function_bodies.

Modularize schema information

Swap space

What to send to Technical Support

• A copy of the problem code in the form of preprocessed source
• The error information
• Platform and release information

• Include all -D or /D options, all -I or /I (uppercase I) options, the schema source file, but no other options or schema specifications.
• Use the -E option and redirect the output to a file.

      ossg -E -D... -I... source.cc > source.ii

Updated: 03/26/98 19:57:53