Building ObjectStore C++ Applications

Chapter 6 Working with ObjectStore/Single

ObjectStore/Single is a form of the ObjectStore client tailored for single-user, nonnetworked use. The functional capability of an ObjectStore/Single application operating on file databases is virtually identical to that of a full ObjectStore client. Databases created with one kind of client are completely compatible with the other. However, full ObjectStore and ObjectStore/Single are not intended to run together.

As a stand-alone version of ObjectStore, ObjectStore/Single includes the Server and Cache Manager functionality as part of the same library as the ObjectStore client, rather than as separate processes. Also, ObjectStore/Single does not support rawfs file systems.

By using dynamic library load paths, you can decide at execution time whether an application should be a full ObjectStore or an ObjectStore/Single application. This allows you to develop applications using full ObjectStore but package the application using ObjectStore/Single as a replacement. This replacement eases integration of embedded applications.

ObjectStore/Single Features

Each invocation of an ObjectStore/Single application requires a Server log file. Applications for UNIX platforms also require a cache file. ObjectStore/Single applications normally supply these files automatically.

Platform	Library Load Path
UNIX	$OS_ROOTDIR/libsngl/:$OS_ROOTDIR/lib
Windows	%OS_ROOTDIR%\binsngl

Application Development Sequence

You can use two environment variables for proof of concept when you want to convert a full ObjectStore application to an ObjectStore/Single application. These environment variables are strictly for development purposes and are not supported if included in your final application. See Additional Considerations for a discussion of the issues involved in using these environment variables.

The two environment variables are

OS_CACHE_FILE
OS_LOG_FILE

OS_CACHE_FILE

The OS_CACHE_FILE environment variable can be used early in development, instead of the entry point objectstore::set_cache_file(), to specify the cache file for an ObjectStore/Single application execution. The entry point takes precedence over the environment variable. Use of the environment variable in the final application is not supported and is potentially troublesome to your customers. If you use neither the environment variable nor objectstore::set_cache_file(), ObjectStore/Single applications supply a default file named objectstore_6_cache in the current working directory.

OS_LOG_FILE

The OS_LOG_FILE environment variable can be used early in development, instead of the entry point objectstore::set_log_file() to specify the Server log file for an ObjectStore/Single application execution. The entry point takes precedence over the environment variable. Use of the environment variable in the final application is not supported and is potentially troublesome to your customers. If you use neither the environment variable nor objectstore::set_log_file(), ObjectStore/Single applications supply a default file named tplog.odi in the current working directory of the program.

The user must take responsibility for ensuring that the Server log information is propagated when moving a database from a full ObjectStore environment to ObjectStore/Single, or the reverse.

Server Log Propagation

This section discusses log propagation in both ObjectStore/Single and full ObjectStore.

ObjectStore/Single provides transaction consistency for databases just as full ObjectStore does. Both ObjectStore/Single and full ObjectStore use a Server log as a tool to provide transaction consistency. See Description of the Server Transaction Log in Chapter 1 of Managing ObjectStore for additional information about Server logs.

In this discussion, the term Server refers to both the separate osserver process of full ObjectStore and the functionally equivalent part of ObjectStore/Single contained in the client library. The term is meaningful for ObjectStore/Single because while ObjectStore/Single does not have or need a separate-process Server, the requisite work is done in a part of the client library internals known as the embedded Server.

Server Log Functions

You must be aware of several important aspects of Server logs.

Commit compared to propagation

A log might contain data that has been committed but not yet written to one or more databases. Logically, the log information is part of the databases, so it must be propagated, that is, written into the actual databases, before those databases can be used for more work. Users of full ObjectStore might have encountered this issue when trying to copy file databases with an operating system command such as cp rather than oscopy.

Databases are marked internally when there is unpropagated data in the log file, so that if an ObjectStore application tries to use that database with a log different from the one holding the not-yet-propagated data, an error is reported. The significance of this information is that you must be careful not to delete a log that has unpropagated information in it.

Server log size

Server logs can grow large fairly quickly. As a general rule, a log's size is proportional to the amount of data that has been modified in the largest transaction since that log was created. The Server cannot shrink its log. The log size is generally not a problem for full ObjectStore because there is only one log file per osserver process. However, in ObjectStore/Single, because each execution of an ObjectStore/Single process must have its own log, the log size can quickly become a disk space management problem. Thus you must be conscientious about finding and propagating (and thereby removing) old log files.

Log File Guidelines

The following ObjectStore behaviors help you deal with logs:

By default ObjectStore/Single forces the log to be propagated immediately when a transaction commits. The result of this is that the period of time when there is committed data in the log is usually quite short. This behavior can be overridden as described in OS_DISABLE_PROPAGATE_ON_COMMIT, following.
During start-up, both ObjectStore/Single and full ObjectStore's osserver process propagate data in the log before doing any other work.
During shutdown (either during a normal process exit or when objectstore::shutdown is called), ObjectStore/Single attempts to propagate any remaining data in the log and remove the log. Full ObjectStore's osserver process similarly propagates the log but does not delete it when ossvrshtd is executed.
The utility osprop propagates data from the log files named in the command invocation. Following successful propagation, the log files are removed automatically.
The other utilities that provide meaningful information as ObjectStore/Single tools (ossize and osverifydb) all accept a log file explicitly named on the command line. If a log file is specified and is writable, propagation of the log occurs automatically before the indicated operation is carried out.

OS_DISABLE_PROPAGATE_ON_COMMIT

The environment variable OS_DISABLE_PROPAGATE_ON_COMMIT controls when ObjectStore propagates committed data from the transaction log to a database. By default this environment variable is false and data is propagated to a database when a top-level transaction commits. If this environment variable is set to true, the data is propagated when a database is closed and when an application ends normally. If an application ends prematurely, some of the data mightnot have been propagated to the database. This data is propagated the next time the ObjectStore is initialized or on a call to progagate_log().

For some applications, setting this environment variable to true can improve performance because data is written to the database less frequently. However, it increases the risk of data loss, which can happen if an application ends prematurely and the transaction log is deleted before the data is propagated to the database.

Applications can override this environment variable by using . For more information, see objectstore::get_propagate_on_commit() and objectstore::set_propagate_on_commit()in ObjectStore C++ API Reference.

When to Intervene

An ObjectStore/Single application (or any of the ObjectStore/Single utilities) tries to ensure that all the data in its Server log is propagated and that the log is removed before the application exits.

Important note

The absence of a log after the program ends is both normal and a guarantee that all committed data is physically in the affected databases.

Conversely, the presence of a log after the program ends is an indication that the databases should be considered to be in an inconsistent state. When this happens, run the osprop utility on that Server log immediately.

Also keep in mind that any time an ObjectStore/Single application or utility is initialized with an existing Server log, ObjectStore conducts propagation automatically. The osprop<

Chapter 6

Working with ObjectStore/Single

ObjectStore/Single Utilities

OS_CACHE_FILE

OS_DISABLE_PROPAGATE_ON_COMMIT