ObjectStore Building C++ Interface 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. Users must be prepared to specify the cache and Server log files at each execution of an ObjectStore/Single application.

ObjectStore/Single API

The following functions in the class objectstore can be used in creating ObjectStore/Single applications:

ObjectStore/Single Utilities

The following ObjectStore utilities can be used with ObjectStore/Single. ObjectStore Management describes each utility in detail.

Dynamic Library Load Path

The tools run as full ObjectStore or ObjectStore/Single applications, depending on the kind of client and database utilities libraries found when the user's dynamic library load path is resolved at execution time.

For ObjectStore/Single, specify the following:

Platform Library Load Path
UNIX

$OS_ROOTDIR/libsngl/:$OS_ROOTDIR/lib

Windows

%OS_ROOTDIR%\binsngl

OS/2

%OS_ROOTDIR%\libsngl

Application Development Sequence

You should first develop your applications and schema using distributed ObjectStore, and then run your applications with the ObjectStore/Single libraries for final testing and delivery.

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.

OS_LOG_FILE

The OS_LOG_FILE environment variable can be used early in development instead of the new 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.

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 ObjectStore Management 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 that is 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, and 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 oscp.

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 rule of thumb, 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 not generally a problem for full ObjectStore since 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:

ObjectStore/Single always 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.
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 automatically removed.
The other utilities that provide meaningful information as ObjectStore/Single tools (oscp, 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.

When to Intervene

An ObjectStore/Single application (or any of the ObjectStore/Single utilities) will try to ensure that all the data in its Server log is propagated and the log removed before it 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 bear in mind that any time an ObjectStore/Single application or utility is initialized with an existing Server log, ObjectStore automatically conducts propagation. The osprop utility is the simplest possible ObjectStore/Single application - it starts, does propagation, and then shuts down.

Cautions to observe

Note the following considerations:

It is the responsibility of the application to keep track of Server logs. Databases do not contain any record of where an associated log is located.
Databases that have not been propagated should not be moved.
When the Server does log propagation, it silently discards data associated with databases not found.

Full ObjectStore osserver Role

The most reliable way to ensure that data has been propagated into a database last used by an osserver process is to shut down the Server using ossvrshtd. As a practical matter, though, the osserver process normally propagates data into a database when no client process has the database open.

Other than by shutting down the osserver process, it is not easy for users to know if log information has been completely propagated into a database.

However, the Server will hold a database open with a write file lock if unpropagated data lies in the log, so UNIX system tools such as ofiles or lsof can be used to infer the Server log state.

Remote Access

ObjectStore/Single allows remote access to databases through NFS. The pathname lookup algorithm differs from full ObjectStore in that it does not consider remote mount points when expanding paths, so all paths appear to be local.

The different pathname lookup behavior between ObjectStore/Single and full ObjectStore could be a concern for those who

Use cross-database pointers and cross-database references
Operate on databases via NFS mounts
Want to interoperate between full ObjectStore and ObjectStore/Single

Accessing Server Logs and Cache Files Through NFS

It is acceptable, though not recommended, for an ObjectStore/Single application to use a Server log that is reached through NFS.

Attempting to use a cache file through NFS is not supported and might generate run-time errors (for example, a failure in mmap), depending on the host platform.

Packaging ObjectStore/Single Applications

This section provides a checklist of the requirements for packaging ObjectStore/Single applications for UNIX and Windows platforms.

Cache and Server Log Files

ObjectStore/Single makes the application completely responsible for identification of each program's cache and Server log file. This burden is not trivial. Every instance of a program run must have a unique cache and Server log. (Note that cache files are required for UNIX applications only.) You must be sure that

Old cache files do not accumulate.
Server logs with unpropagated data (due to application crashes) are propagated and not inadvertently removed.

Additional Considerations

The ObjectStore/Single environment variables (OS_LOG_FILE and OS_CACHE_FILE) should only be used early in development when you are prepared for things to go wrong. They are not safe for production, and they can create interoperability problems. Nonetheless, they can be useful to you very early in the process of moving a project from full ObjectStore to ObjectStore/Single.

Picking cache and log file names for an application should not be done statically. The names chosen must be in the context of whatever other ObjectStore/Single applications happen to be running at the same time on the host. Name collisions must be avoided. All of these concerns are the application's responsibility.

This issue is more complicated than the cache manager's job in managing the commseg and cache file pools for networked ObjectStore, since there are the additional factors of user permissions and Server log file persistence. To summarize, your application should address the following issues when selecting a cache and log file.

Cache File Considerations

Specifying a location with sufficient disk space
Picking a unique name (for example, tmpnam or tempnam)
Deciding whether to immediately delete cache files after a program run or create a pool so that they can be reused

In case of an application crash, or if cache files are being pooled, you need to specify a mechanism for cleanup (the work done by oscmrf for full ObjectStore).

Server Log File Considerations

Specifying a location with sufficient disk space
Deciding where to put a backup of the log file
Determining how the log file name should be communicated to an external agent in case recovery is needed
Specifying how to manage recovery when the log file remains after the application exits
Devising a mechanism to safeguard the log file until recovery is accomplished

What Should You Tell Your Customers?

What is enough disk space and what is going to be backed up are the points that need to be communicated clearly to the application. The end-user site must determine where there is enough disk space and what should be backed up. If you do not consider the other items, at a minimum, your application should be installed in a space that allows all cache and log files to be generated in a subdirectory of the product installation or in another directory on the same disk.

Be sure to communicate this to your customers prior to your application installation.

Contact Object Design if you have recommendations about how the current cache file and Server log API could be enhanced to ease this requirement.

Packaging an ObjectStore/Single Application

If you choose to package the ObjectStore/Single components with your own libraries, you must include the ObjectStore/Single libraries from libsngl (both libos and libosdbu), plus whatever additional libraries from lib are useful to your application (such as liboscol, libosmop, and so on). Do not include lib/libos or lib/libosdbu.

Also include the ObjectStore utilities.

On Windows NT, all the ObjectStore/Single components are installed in the \binsngl directory. Choose which DLLs and ObjectStore utilities your application requires and add them to your packaging procedure.

Packaging with a VAR Product

When ObjectStore/Single is packaged with a VAR's product, the only other installation issues are related to the items presented in the discussion in Additional Considerations.

[previous] [next]

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

Updated: 03/26/98 20:02:08