This chapter provides an overview of building an ObjectStore application. The basic steps are the same, regardless of the compiler or platform you use.

The topics presented in this chapter are

• General Instructions for Building Applications
• Flow Chart for Building Applications
• Third-Party Compilers You Can Use
• Third-Party Libraries and Applications
• Virtual File Systems
• ObjectStore Server and the Build Process
• ObjectStore/Single

1. Modify the source.
   
   Modify your application source code to make ObjectStore API calls. See the ObjectStore C++ API User Guide for information about using ObjectStore APIs. Note that you must modify your makefile to find ObjectStore header files. See ObjectStore Header Files.

2. Create the schema source file.
   
   The schema source file is a C++ file with a specified format used as input to the schema generator (ossg). The schema source file includes the files that define
   • Classes that have instances stored by the application in persistent memory.
   • Classes that have instances read by the application from persistent memory. You can include the type itself, or the base types of the class.
   • Classes that appear in library interface query strings or index paths.
     
     See Determining the Types in a Schema for details.

3. Generate schema with ossg.
   
   Modify your makefile to run the ObjectStore schema generator (ossg). The input for this step includes
   • Schema source file
   • ObjectStore library schemas The output from this step is the

   • Application schema database
   • Application schema source file If you are using Visual C++, the output is an object file referred to as the application schema object 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.

     See Chapter 3, Generating Schemas, for further information.

4. Compile the application schema source file.
   
   See Compiling, Linking, and Debugging Programs. Make sure your makefile enables you to compile the application schema source file. This creates the application schema object file.

   When you use Visual C++, the schema generator creates the object file directly. On all other platforms, you must compile the application schema source file yourself.

5. Link.
   
   Make sure your makefile is modified to link the following (to create the executable):
   • Application object files
   • Application schema object file
   • Application libraries
   • ObjectStore libraries
   • System libraries

Third-Party Compilers You Can Use

• AIX C Set ++
• Digital UNIX DEC C++
• HP-UX HP C++
• IBM VisualAge C++ for OS/2
• SGI CC and NCC C++
• Sun SPARCompiler C++
• Solaris 2 Intel ProCompiler C++
• Microsoft Visual C++ 32-bit

• If it exists, obtain the vendor's version of the library or application and header files that use the ObjectStore API.
• Obtain the source code for the library or application and modify its calls where appropriate.

When using a third-party library or application with an ObjectStore application, you must ensure that all persistent data is read/written inside a transaction.

Virtual File Systems

A virtual file system provides a user with a logical view of a file system. When you use a virtual file system, it appears as if all sources and executables reside in the current directory path, when only local modifications actually reside there. The purpose of a virtual file system is to hide the actual locations of files from users.

When you use ObjectStore with a virtual file system, you must specify pathnames that would work without the virtual file system. This is usually some kind of absolute pathname.

This requirement applies to any ObjectStore database stored under a virtual file system and includes any file that the Server must access. The Server must be able to access whatever pathname is provided. This can be a virtual file system pathname if the Server is running under a virtual file system.

You can run ObjectStore clients and utilities in directories where ObjectStore can find all files. However, the opening of a database is always performed by the Server. In a virtual file system, the Server cannot determine where a file actually resides unless you specify the true location.

You can run the Server under a virtual file system if there is only one view of the virtual file system and the view is shared by all users. It is not possible for the Server to recognize more than one view. In some virtual file systems, machines and users can have their own views.

You can maintain schema databases in a virtual file system because the schema generator embeds the absolute pathname of the schema in the database. However, when you generate schema databases you must specify pathnames that the Server can use.

Some virtual file systems, such as ClearCase, provide a way to return an absolute (nonvirtual) pathname for a given element in a virtual file system. This pathname can enable the ObjectStore Server to locate the element. It does mean the loss of the ability to use relative names (such as eng_1.ldb in the following example) as arguments to ObjectStore utilities.

Example

> pwd 

/home/clients/libschemas

> ls

test_1.ldb
eng_1.ldb 
qa_1.ldb

> ossize eng_1.ldb

ossize: The database was not found
<err-0025-0351>The database 
"/home/clients/libschemas/eng_1.ldb"
does not exist (err_database_not_found)

>

ObjectStore/Single

ObjectStore/Single includes the Server and Cache Manager functionality as part of the same library as the client application rather than as separate processes. Those who benefit from ObjectStore/Single are application developers who develop applications for a nonnetworked environment. Therefore it is most useful for applications that have no requirement for

• Concurrency
• Networked Server
• Rawfs support

If you use dynamic library load paths, you can decide at execution time whether an application should be an enterprise 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.

A summary comparison of full ObjectStore and ObjectStore/Single follows.

Full ObjectStore	ObjectStore/Single
Installation requires root permission.	Installation does not require root permission.
Server is a separate process.	Server functions are integrated in single library.
Cache Manager is a separate process.	Cache Manager functions are integrated in single library.
Supports rawfs.	Does not support rawfs.
UNIX platforms use OS_ROOTDIR/lib/libos and libosdbu shared libraries. Windows platforms use %OS_ROOTDIR%\bin DLLs. OS/2 uses %OS_ROOTDIR%\lib DLLs.	UNIX platforms use OS_ROOTDIR/libsngl/libos and libosdbu shared libraries. Windows platforms use %OS_ROOTDIR%\binsngl. OS/2 uses %OS_ROOTDIR%\libsngl DLLs.
Transaction log files are automatically created by Server during ObjectStore installation.	User must specify transaction log files at each invocation of an application.
Cache files are automatically created by Cache Manager process.	User must specify and clean up cache files.
osserver process automatically manages crash recovery and Server log propagation.	User must ensure that unpropagated data in Server logs (for example, following a crash) is applied to the database by either Restarting the application Running the osprop utility
Uses Server and Cache Manager parameter files.	Does not use Server and Cache Manager parameter files.

See Chapter 6, Working with ObjectStore/Single, for additional information about ObjectStore/Single.

Updated: 03/26/98 19:56:48