This chapter briefly describes the architecture of ObjectStore and provides an overview of management tasks. For an introduction to object-oriented database management, including concepts such as persistence, see the first several chapters of the C++ API User Guide.

The following topics are discussed in this chapter:

• What Is ObjectStore?
• What Is an ObjectStore Database?
• What Kinds of Databases Are There?
• How ObjectStore Controls Storage
• Managing Processes
• Description of the Server Transaction Log
• Managing Computer Resources
• Managing Memory
• Managing the Rawfs
• What You Need to Know About the API
• Managing Databases
• Overview of the Backup/Restore Facility
• Backup Strategies
• The Dump/Load Subsystem
• Managing Users
• Modifying Network Port Settings
• How a Client Locates the Server for a Database
• Managing ObjectStore on Multiple Platforms
• Callback Messages Background
• ClearCase Virtual File System (MVFS)
• Troubleshooting

• Describe, store, and query complex data used in sophisticated computer applications, as well as data traditionally managed by relational database applications, such as MIS programs
• Persistently store data independently of the data type
• Access data in the same format in which it exists in the application
• Create and modify objects instead of tables, columns, rows, and tuples using the ObjectStore C++, Java, or ActiveX interfaces

Clusters

Clusters can be normal or huge. If an allocation is less than or equal to 64 KB, it is stored in a normal cluster, which can contain any number of normal allocations, up to a maximum size of 2 GB. If an allocation is greater than 64 KB, ObjectStore creates a huge cluster containing just that one allocation.

Segments

• The schema segment, which holds schema information about the objects stored in the database and the database roots. The schema segment is not directly accessible by the user application.
• The default segment, which stores entities you create with persistent new.

The default segment and any additional segments always have a default cluster. ObjectStore normally allocates storage from this cluster. You can create additional clusters using the
os_database::create_cluster() method.

What Kinds of Databases Are There?

File Databases

Rawfs Databases

A rawfs can contain directories, subdirectories, and databases, just as the native file system can. It can include links, but each link must be to another ObjectStore rawfs. The ObjectStore Server manages everything in the rawfs. Everything in the rawfs is invisible to the operating system. ObjectStore provides utilities and os_dbutil class methods for operating on databases and directories in a rawfs. An ObjectStore Server can manage one rawfs, which consists of one or more Server partitions.

Rawfs partitions

• Raw disk space set aside by the operating system, if the operating system supports this. This is referred to as a raw partition. Raw partitions have a fixed size.

• A file allocated in the operating system's file system. This is referred to as a file partition. File partitions can be expandable or of fixed size.

When you create a rawfs database, you specify a pathname. The Server determines where in the rawfs to store your database. Thus, the logical directory structure might not map directly to the physical placement of the databases in the partitions. For example, two rawfs databases in different ObjectStore directories might be stored in the same partition.

Rawfs database
name format

hostname::/database_pathname 

hostess::/accounts/payable/JUNE
hostess::/accounts/payable/june

How Do Objects Get into a Database?

See the C++ API Reference for information about these functions.

How ObjectStore Controls Storage

What Does the Server Do?

• Storage and retrieval of persistent data
• Arbitration of concurrent access by multiple client applications
• Recovery of databases to a transaction-consistent state if any process aborts or any host crashes, or in the event of network failure

Rawfs management

Typically, a Server must be running before any ObjectStore application can access databases on the host. (A locator file allows access to databases residing on a host that is not running a Server. See Chapter 5, Using Locator Files to Set Up Server-Remote Databases, for further information.)

An application can use databases that are stored on different hosts and managed by different Servers. A Server can serve clients on any number of hosts.

Multiple Servers on a host

A network can have a number of Servers.

What Does the Client Application Do?

• Maps persistent database objects to virtual addresses
• Allocates and deallocates storage for persistent objects
• Maintains the cache of recently used pages and the lock status of those pages
• Handles page faults on addresses that refer to persistent objects

• The Server on that host
• Any other Server on any other host in the network

To change the default size of the client cache, use the OS_CACHE_SIZE environment variable. See OS_CACHE_SIZE.

When a client application needs an object stored in a database it dereferences a pointer (or object reference in Java). If the page that holds the object is already in physical memory or if the page is in the cache with the appropriate permission, access is immediate.

If the page that holds the object is not in physical memory, is not in the cache, or is in the cache but with inappropriate permission, the application takes a page fault. This causes the client to request the page from the Server, put it in the cache, and resume executing the program.

UNIX

Windows

What Does the Cache Manager Do?

A Cache Manager starts automatically when an ObjectStore application starts, if a Cache Manager is not already running on the host. Each host that runs an ObjectStore application must have one Cache Manager. A single Cache Manager can handle callback messages for any number of client applications running on that host.

If you are running clients from two different major releases of ObjectStore, there are two Cache Managers - one for each release. Unlike running different Servers on one host, you need not configure ports.

The name of the Cache Manager executable is oscmgr6.

On UNIX, the oscminit6 executable starts oscmgr6. Typically, you never need to invoke oscminit6.

Callbacks

The Cache Manager is involved in the following situations:

• When a client requests permission to read or modify a page and another client has permission to modify that page
• When a client requests permission to modify a page and other clients have permission to read that page

The Server cannot send callback messages directly to the client because the client might not be listening; the client might be busy running the application. The Cache Manager determines whether the read or write permission can be released or whether the client requesting permission must wait.

If you are running an ObjectStore application that uses a database that nobody else is using, there are no callback messages for that database.

For information about ownership and locks, see Callback Messages Background.

Commseg

UNIX

Windows

The operating system determines the location of the commseg in shared memory. The commseg is not a file; it is a region of virtual memory. The illustration that follows shows one possible configuration of ObjectStore processes.

Managing Processes

• Server (osserver)
• Client (application)
• Cache Manager (oscmgr6)

• Start-up
• Shutdown
• Obtain process status information

ObjectStore uses network connections to communicate among Server, client, and Cache Manager processes. The kind of network connection used depends on your platform. Typically, you need not modify network connections. However, if you do need to make changes, see Modifying Network Port Settings.

Starting ObjectStore Processes

When you start a Server, the Server checks for values of Server parameters you might have changed from the default and uses the modified values. If you have not modified any Server parameters, ObjectStore uses the default parameters.

The Server then makes its service available. A client can use the network connection available on its platform to connect to the Server. ObjectStore uses default network connections. To modify these connections, see Modifying Network Port Settings.

There are many Server parameters you can set to determine the behavior of the Server. Chapter 2, Server Parameters, describes each parameter. When you modify a parameter, you must shut down and restart the Server for the parameter to take effect.

Client

Cache Manager

Windows NT

Stopping ObjectStore Processes

• Before you reboot or halt the host
• After you modify Server parameters
• To resize the transaction log (see Log File Size)
• To add a partition to the rawfs

1. Use the ossvrstat utility to determine whether clients are using the Server.
   
   Along with other information, this utility displays client names, if they have been set. To identify clients easily, encourage developers to use the objectstore class, set_client_name method. See ossvrstat: Displaying Server and Client Information.

2. Notify clients to end their connections with the Server.
   
   
3. Use the ossvrclntkill utility to end the Server's connection with any dangling clients.
   
   Dangling clients are clients still attached to the Server, even though they no longer exist. This can happen when a client is halted abnormally rather than being stopped in the usual manner. See ossvrclntkill: Disconnecting a Client Thread on a Server.

4. Use the ossvrshtd utility to shut down the Server. See ossvrshtd: Shutting Down the Server.
   
   

Client

If necessary, you can use the ossvrclntkill utility to sever the connection between a client and the Server. This disconnects the client. See ossvrclntkill: Disconnecting a Client Thread on a Server for details.

Cache Manager

Obtaining Process Status Information

ObjectStore daemons seldom send messages to these files except under certain unusual error conditions. In these cases, this information can be helpful in understanding and resolving an error. When you report to Object Design a problem that might involve one of these daemons, find such a file if it exists and provide the contents.

Status commands

• The amount of data the Server sent to clients
• The amount of modified data clients sent to the Server
• The number of committed transactions the Server knows about
• The number of times the Server chose a deadlock victim
• The number of times a message from a client to the Server had to wait to use a message buffer
• The amount of data in the log

Use the oscmstat utility to obtain information about the Cache Manager, client cache files, and commseg files. See oscmstat: Displaying Cache Manager Status.

Debugging Cache Manager

oscmgr6 0 debug-level 

Pinging

Monitoring the Server

To run the Server in debug mode, you must shut down and restart the Server with the debug option. See Chapter 7, Managing ObjectStore on UNIX, or Chapter 8, Managing ObjectStore on Windows, for specific details for your platform. When you no longer need the debug output, shut down the Server and restart it without the debug option.

Debug mode slows down the Server but does not affect clients. Use debug mode only when you are experiencing a problem.

If you want to turn debug mode on without shutting down the Server, you can use the ossvrdebug command to set the debug trace level for the Server. To enable server debugging, type ossvrdebug -d debug-level where debug-level is an integer from 0 to 9. To disable server debugging, type ossvrdebug -d 0. See ossvrdebug: Setting a Server Debug Trace Level for more information.

Description of the Server Transaction Log

Log file

Location

When the log is in the rawfs, it is not visible to you. Its size is limited by the size of the rawfs. The log can span partitions.

When the log is in the native file system, its size is limited by the file partition size. You should place the log file where it can never be deleted by users accidentally. Deleting the log file can cause database corruption.

Transactions, commits, and the log

If your transaction aborts, the log entries are discarded. When your transaction commits, your program waits until the log information is safely on disk.

Propagation

Sector

Log File Size

When you run the ossvrstat utility, Current log size, in the list of Server parameters, displays the current size of the log. Usually, the log grows to a size that accommodates your application and then stops growing. There usually is no reason to monitor log size or to worry about its allocation. However, if an unusual event causes the log to grow too large, there are ways to make it smaller.

If there is nothing in the log when you start the Server, the Server resets the size of the log data segment and log record segments to the sizes set by the Log Data Segment Initial Size and Log Record Segment Initial Size Server parameters. For log files in the rawfs, this means the space is free for other databases. For log files in the native file system, this reallocates internal log file space; the log file size does not change.

Shrinking the
log file

1. Set the Log Data Segment Initial Size and Log Record Segment Initial Size Server parameters to the values you want. If necessary, ensure that the correct value is specified for the Log File Server parameter.
   
   
2. Ensure that no clients are using the Server.
   
   
3. Run ossvrshtd to shut down the Server.
   
   The Server clears the log before it actually shuts down.

4. If you are reallocating a log in the rawfs, skip to step 5. If you are reallocating a log in the native file system, run the Server executable with the -ReallocateLog option.
   
   This does not actually start the Server; it only reallocates the log. Enter

         osserver -ReallocateLog 
   

5. Restart the Server. See the chapter discussing your operating system for details.
   
   

Warning

Managing Computer Resources

CPUs

Memory

Disk space
and network

It is impossible to predict the amount of disk space you need for a client application because it is dependent on the application. However, following are some ways that an ObjectStore application uses disk space:

• On UNIX systems, the default location for the cache and commseg files is /tmp/ostore. On Windows, the cache is in virtual memory and the commseg is in shared memory. The operating system determines both locations. If necessary, you can increase the amount of virtual address space by configuring a larger swap file.
• ObjectStore uses swap space for transient data when it cannot be mapped into physical memory during a transaction. See Managing Memory.

Managing Memory

What Is Address Space?

• Physical memory
• Backing store
  • Backing store for persistent data is the client cache.
  • Backing store for transient data is swap space.

• Persistent data that the application accesses in an ObjectStore transaction
• Transient data that is static or allocated in the stack or heap

Each client process has its own address space. Address space is distinct from virtual memory in that

• Address space includes all addresses that could be assigned. It does not matter whether the address is in use. It typically is larger than virtual memory.
• Virtual memory includes only addresses that currently contain application data, either in physical memory or in backing store on disk.

Kinds of addresses

• Persistent address space - This is a range of addresses that ObjectStore uses to store only persistent data.
• Transient address space - This includes all addresses in the address space except those designated for persistent data.

Each client also has its own transient address space. This space includes all addresses not part of the PSR.

Locations for data

• Physical memory
• Backing store
  • Client cache for persistent data
  • Swap space for transient data

When a page of data needs to be brought into physical memory, the operating system often needs to make room by removing another page. When the operating system removes a page from physical memory, it places the page on disk in the appropriate backing store.

If the page contains persistent data, the operating system pages it to the client cache. Each client has its own cache.

If the page contains transient data, the operating system pages it to swap space. Swap space is a disk file or disk partition that is shared by all applications running on the host.

Virtual memory

Illustration of Address Space

The following figure shows address space. The persistent storage region is near the middle of the address space. The stack allocates transient data starting at one end of the range of addresses. The heap allocates transient data starting at the other end of the range of addresses. The stack and the heap can allocate space until they reach the persistent storage region.

What Is the Relationship Between a Transaction and Address Space?

Normally, after a top-level transaction commit or abort, the assignments of persistent space are made available for reuse.

However, if the application is using retain_persistent_addresses(), ObjectStore does not release persistent address space until the program calls release_persistent_addresses().

Transaction commit

• Sends a copy of each modified page back to the Server
• Keeps a copy of each modified page in the cache in case the page is needed in the next transaction
• Keeps in the cache those pages already in the cache but not modified

• Throws away modified pages because they are no longer valid
• Keeps in the cache pages already in the cache but not modified, in case they are needed in the next transaction

• Keeping transactions short.
• Using ObjectStore references rather than pointers. ObjectStore reserves address space for objects that are pointed to, even if the transaction does not touch these objects but it need not reserve address space for objects referred to by references until they are dereferenced. See Advanced C++ API User Guide for further information.

Persistent address space

Physical memory

Client cache

Swap space

• Prohibits other processes from starting
• Aborts the process that required additional swap space

How Can You Control These Resources?

The environment variables OS_AS_START and OS_AS_SIZE control the amount of persistent address space. Each application can use the default values or specify its own settings. See OS_AS_SIZE.

Physical memory

Client cache

Swap space

Increasing the size of the client cache or adding swap space provides more potential virtual memory for the client's data.

How Much Memory Is Needed?

Difference Between Assigning and Mapping an Address

When ObjectStore assigns an address to a page, it has determined where to put the page if the client needs it. The data on the page is not available to the client. Assigning an address reserves the address so that it cannot be assigned to another page. ObjectStore assigns address space in units of 64 KB, regardless of the page size on the platform. Assigning an address consumes address space but not physical memory or swap space.

When ObjectStore maps a page to an address, it means that the page is available to the client. The client can now use the data on that page. Mapping occurs one page at a time and consumes virtual memory (physical memory and, perhaps, swap space).

Summary of the Kinds of Memory an ObjectStore Application Uses

• Physical memory is the real memory (RAM) available on the machine. All applications running on the machine share the real memory.
• Virtual memory contains the application's data. Each application has its own virtual memory.
• Persistent memory is that in which you can store an application's persistent data. Each application has its own persistent memory.

Managing the Rawfs

Advantages

• Allows for large databases because databases can span partitions. Information in a single database is not limited to the maximum size of a file, which on some operating systems is limited to 2 or 4 GB. (Large usually refers to multigigabyte databases, but it also depends on the amount of disk space available.)
• Allows applications to use ObjectStore in such a way that ObjectStore is invisible to end users.
• Simplifies management because all databases are in a single location.

• Transaction log is hidden so accidental deletion cannot occur.
• Content of the rawfs is accessible only through ObjectStore. The rawfs is not visible to the operating system.
• Database contents are protected at the segment level.

• Has a fixed size. You must explicitly add a partition to increase the size. While file partitions in a rawfs can be expandable in size, the performance for file partitions is sometimes not as good as it is for raw partitions.
• Cannot be accessed with operating system commands, so you lose the flexibility offered by those commands.
• Might be difficult to back up because of its size.

• oschhost changes the host that a link in the rawfs points to.
• osdf shows the amount of used and available disk space for the rawfs on the specified Server.
• osln creates a symbolic link in the rawfs hierarchy.
• osmkdir creates a directory in the rawfs.
• osrmdir removes a directory from the rawfs.

osls oscar::/sax/charlie*


Wildcard
Description
*

Matches any string, including a null string.


?

Matches any single character.


[...]

Matches any one of the enclosed characters. A pair of characters separated by - matches any character lexically between the pair, inclusive. If the first character following the opening [ is a !, any character not enclosed is matched.


{...}

Matches any one of the enclosed sequences. For example, file.{cc,hh} matches file.cc and file.hh.

Reconfiguring the Rawfs

See Chapter 7, Managing ObjectStore on UNIX, or Chapter 8, Managing ObjectStore on Windows, for specific instructions about creating a rawfs and starting the Server on your platform. If you decide to reconfigure the rawfs, use that information with these general instructions.

Motivation

• Shrink the size of the rawfs to save space
• Remove a partition

Procedure

1. Confirm that you are on the machine you want to reinitialize and that the OS_ROOTDIR environment variables reflects this. You must be careful not to delete another rawfs accidentally.
   
   
2. Use the ossvrstat utility to confirm that no users are changing any databases in the rawfs. The rawfs databases are backed up for the last time during this procedure.
   
   
3. Use the ossvrchkpt utility to move everything in the log to the relevant databases.
   
   
4. Use the osbackup utility to back up the databases in your rawfs.
   
   
5. Use the ossvrshtd utility to shut down the Server.
   
   
6. On UNIX platforms, modify the PartitionN Server parameter specifications to reflect your new rawfs. On Windows platforms, use the ObjectStore setup.exe utility to modify the configuration of the rawfs.
   
   
7. Initialize the Server by specifying osserver -i. This wipes out the rawfs partitions and starts the Server.
   
   
8. Use the osrestore utility (or oscopy, if you used it when saving the database) to restore any necessary databases.
   
   

Capacity planning

Data organization

Indexes and contention

Managing Databases

Additional utilities for operating on databases are documented in Chapter 4, Utilities.

Pointers and references

• Points to other databases
• Is pointed to by other databases

• DatabaseA
• All databases that point to or reference databaseA and their data sets
• All databases that databaseA points to or references and their data sets

If you move all the databases of a dataset as a unit, no further action is usually required. For example, if there are references among the three databases

host:/usr/ed/db1
host:/usr/ed/dbs/db2
host:/usr/ed/dbs/db3

host:/usr/fred/db1
host:/usr/fred/dbs/db2
host:/usr/fred/dbs/db3

hostess:/usr/ed/db1
hostess:/usr/ed/dbs/db2
hostess:/usr/ed/dbs/db3

Schema databases

Your application's executable files may have references to schema databases. Use ossetasp to determine whether the pathname is embedded in the application and to update the pathname as required. Applications can use the set_application_schema_pathname method of the objectstore class to choose the location of the schema database at run time; if so, you must work with your developers to determine how best to keep schema database pathnames consistent. See also ossetasp: Patching Executable with Application Schema Pathname.

Operate on the set

Moving, renaming, and dumping databases

1. Run the osverifydb utility described in osverifydb: Verifying Pointers and References in a Database to confirm that no bad pointers or dangling references exist. This utility detects inconsistencies; it does not fix them.
   
   

1. Run the ossize utility described in ossize: Displaying Database Size to ensure that cross-database references are established correctly.
   
   
2. Perform steps 1 and 2 on all databases in the data set.
   
   
3. Run the ossvrchkpt utility described in ossvrchkpt: Moving Data Out of the Server Transaction Log to ensure that all data has been propagated from the log to the affected database.
   
   

• Encourage developers to design database hierarchies that can be moved easily.
• Keep all databases in a set in a single directory.

Databases and applications on CDROM

You should validate the schemas before you place an application or database on a CDROM. In other words, run the application on the database in question (in update mode), then put the application or database on the CDROM. This validates the schemas and sets the appropriate cache state in the databases. The result is improved performance because schema validation is not needed when the application opens the database on the CDROM.

For information about schema validation, see Chapter 9, Schemas, in the C++ API User Guide.

Overview of the Backup/Restore Facility

• osbackup and osarchiv

• osrestore and osrecovr

These utilities provide protection from catastrophic data loss due to hardware failure and can be used to transport databases from one location to another. Run the utilities in the following order:

1. Run the osbackup utility (described in osbackup: Backing Up Databases) according to a schedule that you determine.
   
   
2. Keep the osarchiv utility active. See osarchiv: Logging Transactions Between Backups.
   
   
3. Run the osrestore utility (described in osrestore: Restoring Databases from Backups) to recover data backed up by the osbackup utility.
   
   
4. Run the osrecovr utility (described in osrecovr: Restoring Databases from Archive Logs) to recover data from archive logs.
   
   

On-line backup and archive logging provide these features:

• Interdatabase transaction consistency. Databases are consistent both internally and across the entire set of databases being backed up.
• Distributed backup capability, allowing transaction-consistent backups of interdependent distributed databases. You can back up databases on different Servers in the same backup operation.
• Concurrent read and write access by ObjectStore applications to databases in the backup set. That is, on-line backup never obtains locks on data in the backup set, so standard ObjectStore transactions can proceed normally.
• Support for full and incremental backup.
• Platform-independent format of backup archives, allowing databases to be moved from a Server on one architecture to a Server on another architecture. (This does not affect whether or not the clients of a given architecture can access the database. See Building ObjectStore C++ Applications, Chapter 5, Building Applications for Use on Multiple Platforms.)
• Ability to generate a single archive log for distributed databases.
• Ability to perform batch transactions to reduce the amount of data that must be archived.

On-Line Restore and Recovery

On-line restore and recovery offer these features:

• You can always recover a committed transaction if archive logging was being performed for the database when the transaction was committed.
• You can recover databases back to a transaction-consistent state at a specific time by restoring backup images, then applying committed changes from the archive log.
• Recovery time is fast because the archive log stores modified data and not the set of operations that modified the data.
• You can recover modifications from backup images and from archive logs in the same operation.

Backup Strategies

• How large are your ObjectStore databases?
• How far back do you need to back up?
• How much downtime to perform backups can you tolerate, if any?
• How much time can you tolerate for recovery?

General Backup Practices

With osbackup, you can specify a backup level from 0 to 9. Files that have been modified since the last backup at a lower level are copied to the backup image. For example, suppose that you did a level 2 backup on Monday, followed by a level 4 backup on Tuesday. A subsequent level 3 backup on Wednesday would contain all files modified or added since the level 2 (Monday) backup.

After the backup is complete, the backup images can then be moved to tape and eventually be stored in a safe location. For determining the best backup strategy, it is important that production size databases be estimated. If the databases are not in the gigabyte range, it is better to perform a level 0 (full backup) every night, as opposed to doing additional incremental backups. The advantage is that, in the event of a failure, only a single backup image needs to be restored. The following is a sample backup strategy:

Sun.:	Backup level 0
Wed.:	Backup level 1
Mon. Tues. Thurs. Fri. Sat.:	Backup level 2

For example, if you need to restore the databases on Friday morning, you must restore the backup images from Sunday, Wednesday, and Thursday. It is advisable to save the previous level 0 backup in another location before starting the new level 0 backup.

osbackup command flags

osbackup -i bkup_rec.txt -l 0 -f full_bkup.img sample1.db sample2.db 
sample3.db 

• The -i flag specifies the incremental record file - a file that contains information about the databases that have been backed up and when they were backed up. The osbackup utility uses this information to determine those clusters within a database that have been modified since the last backup at a lower level. The utility then backs up only modified clusters. The incremental record file is comparable to the archive record file for osarchiv.

• The -l (lowercase l) flag specifies the level of the backup. You can specify an integer from 0 to 9. Files that have been modified since the last backup at a lower level are copied to the backup image. Backup is incremental at the cluster level, meaning that a cluster is only backed up if it has been modified since the last backup at a lower level. A level 0 backup (the default) backs up all clusters in all specified databases.
• The -f flag specifies the location of the backup image.

Archive Logging

Because the osarchiv process requires a backup image as initial input, the script responsible for this operation might choose to stop osarchiv and restart it each night after the osbackup process is completed successfully. Avoid updates in the window of time following the start of osbackup and the startup of osarchiv so osarchiv does not have to dump full clusters. You can move the archive file from disk to tape at this time if disk space is an issue.

osarchiv switches to the next archive file in the sequence when it encounters the maximum size allowed for an archive file. You can specify the maximum amount with the -s flag. The default maximum size is 2 MB. If osarchiv runs out of disk space for archive files, it notifies you and suspends activity until additional disk space is available.

The utility uses the following naming convention for archive files:

YYYYMMDDHH.ext, where

YYYY =	Year
MM =	Month
DD =	Day
HH =	Hour
ext =	Extension of the form aaa, aab, aac...

If you decrease the time between snapshots, you also decrease the number of transactions recorded in each snapshot. Using shorter intervals between snapshots has the effect of keeping the archive more up to date and keeping the amount of data that needs to be archived smaller at each interval. However, because each snapshot causes information to be written to the archive file, even if no data modifications are being recorded, frequent snapshots can consume space in the archive file unnecessarily. Longer intervals can reduce the amount of data being logged in cases in which the same data is modified by multiple transactions. In such cases, only the most recent copy of the committed data needs to be logged.

osarchiv command flags

osarchiv -a bkup_rec.txt -d archive_img -i 30 sample1.db sample2.db 
sample3.db 

• The -a flag specifies the pathname of the file that osarchiv uses to record the segment change IDs for the archive set. The osarchiv utility updates this file each time it successfully records committed changes to the archive set. This activity is known as taking a snapshot. The osarchiv archive record file is equivalent to the incremental record file for osbackup. It is usually the same file.
• The -d flag specifies the directory in which to create the archive log files. You cannot perform archive logging directly to a tape device.
• The -i flag specifies an integer that osarchiv uses as the interval between snapshots. By default, this interval is in seconds, but you can append m, h, or d to indicate minutes, hours, or days. For example, -i 60 and -i 1m both specify an interval of one minute. When interval is not 0, osarchiv takes a snapshot immediately after being initiated and then every interval n seconds (or minutes, hours, or days) thereafter. When you do not specify an interval, it defaults to 0, which means that snapshots are not taken automatically.

Special Considerations for Large Databases

Using a file system backup and the ObjectStore archiver

1. Freeze your applications (or shut them down).
   
   
2. Perform a Server checkpoint.
   
   
3. Wait for the archiver to take its snapshot.
   
   
4. Shut down the archiver.
   
   
5. Shut down the Server.
   
   
6. Run the File system backup.
   
   
7. Restart the Server.
   
   
8. Restart the archiver.
   
   
9. Resume or restart your applications.
   
   

The next paragraphs describe the way osrestore and osrecovr work.

Recovery Options

Using both osrestore and osrecovr

osrestore -f full_bkup.img 

• The -f flag specifies the location of the backup image. The osrestore utility prompts you for incremental backup images you might want to apply after this (you use this option if you have incremental backup images resulting from an incremental backup procedure).

      osrecovr -F archive_list.txt 

• The -F flag specifies the location of a file containing the names of all the archive images. For example, archive_list.txt might contain

      C:\name\user>type archive_list.txt 
      archive_img\1999020719.aaa 
      archive_img\1999020719.aab 
      archive_img\1999020720.aac 
      archive_img\1999020720.aad 
      archive_img\1999020720.aae 
      archive_img\1999020720.aaf 

-F archive_list.txt -D 2/8/1999 -r 19:59:45 

Using system backup and osrecovr

The Dump/Load Subsystem

The ObjectStore dump/load facility allows you to

• Dump to an ASCII file the contents of a database or group of databases.
• Generate a loader executable capable of creating, given the ASCII as input, an equivalent database or group of databases.

See osdump: Dumping Databases and osload: Loading Databases for more detailed information about using the dump/load facility. For advanced topics related to customization, see Chapter 7, Dump/Load Facility, in the Advanced C++ API User Guide.

Managing Users

• Those who run ObjectStore applications
• Those who develop ObjectStore applications

Running applications

• Client, Server, and Cache Manager executables.
• Application schema database.
• One or more databases for storage of application data. The data can already exist or can be created by the application.

You can set OS_ROOTDIR on each host that runs an ObjectStore Server or application. Alternatively, you can set OS_ROOTDIR in each user's environment.

OS_ROOTDIR allows you to change the location of the ObjectStore installation and allows users to switch to a different version of ObjectStore.

Application schema database

You can use the ossetasp utility to change the pathname of an application schema database for a particular executable.

Alternatively, an application can specify its application schema database pathname when it runs by calling objectstore::set_application_schema_path().

Sharing schemas

Developing applications

Modifying Network Port Settings

Communication Methods Background

• The local transport layer allows communication between processes on the same host.
• The remote network allows the local host to communicate with remote hosts. In Release 5.1 and above, this is always TCP/IP.

UNIX

Windows

Defaults for Port Settings

connect.server_client
accept.server_client
connrel.server_client
connreg.server_client
exception.server_client.

The default port settings are in the following tables.

Process	IP Port Number	TLI_LOCAL Pathname	UNIX Pathname
Server to R6 Cache Manager	51031	os_callback_v6	/tmp/ostore/os_callback_v6
R6 client to R6 Cache Manager	51041	osccom6	/tmp/ostore/osccom6
Client to Server	51025	objectstore_server_comm	/tmp/ostore/objectstore_server_comm
Notification	51050	objectstore_notification	/tmp/ostore/objectstore_notification

Modifying Port Settings

On UNIX and Windows, you can also set the variable OS_PORT_FILE to the name of a file you create.

Platform	Ports File
UNIX	$OS_ROOTDIR/etc/ports
Windows	%OS_ROOTDIR%\ETC\PORTS

Ports File Format

net:service:version:port 


net 

Specifies the network type. It must be one of the values that appear in the Network column in the following table. Possible values vary according to the platform. 


service 

Specifies one of the following network services:




cache manager client is the service the client uses to find the Cache Manager. This is only meaningful when net is a local network. (The port the Cache Manager listens on for clients is always accessed by local clients.)




cache manager server is the service the Server uses to find a Cache Manager.




cache manager notification is the service the Server uses for notification purposes among clients.




server client is the service a client uses to find the Server.


version 

Specifies the software version for the Cache Manager client or the Cache Manager Server. For Releases 4 and 5, specify 4. For ObjectStore Release 6, specify 6 as the version number in all cases except server client. This service requires a 1.


port 

Specifies a port identifier as described in the following table.

Examples

TCP/IP:server client:1:54432
NSharedMemory:server client:1:new_server
UNIX:server client:1:/tmp/.ostore/objectstore_server_comm
UNIX:cache manager client:6:/tmp/.ostore/objectstore_client_cache
UNIX:cache manager server:6:/tmp/.ostore/objectstore_server_
cache

Different versions

To set up two Servers on the same host, you need to change only the server client ports for one of the Servers. The Cache Manager ports are already different in different major versions of ObjectStore.

All Servers that a client can communicate with must have the same network port number. This means that if you run two Servers on one host, any single client can access one of those Servers but not the other. It also means that if a client accesses Servers on more than one host, you must change the Server port settings on all affected hosts.

UNIX notes

Windows

When Your Application Uses Notification

This all happens automatically and transparently, so there is no relevant API. However, as with all network connections, you might want to control the network port that is used by the connection. You can use the ports file in the usual way to control the use of network ports. The relevant information follows:

Name of service	cache manager notification
Default IP port number	51050
Default UNIX local socket file name	/tmp/ostore/objectstore_notification

How a Client Locates the Server for a Database

When Accessing a File Database

If the client cannot find a Server that is local to the disk, it signals an error unless there is a locator file.

A locator file allows a client to access Server-remote databases. Server-remote databases are stored on disks that are not local to an ObjectStore Server. See Chapter 5, Using Locator Files to Set Up Server-Remote Databases.

If there is a locator file, the client checks it to determine the Server to communicate with.

When Accessing a Rawfs Database

Managing ObjectStore on Multiple Platforms

Using Multiple File Systems

Translating Pathnames

Suppose you have a UNIX Server along with some Windows NT clients.

Native pathnames

Server-relative pathnames

Callback Messages Background

Note

Read or write ownership

A Server grants read ownership to as many clients as request it. If one client requests write ownership, that client must wait if there are current transactions that are reading that page, or if there is a current transaction that is modifying that page.

Many clients can have read ownership at the same time, but only one client at a time can have write ownership. When a client has write ownership, no clients can have read ownership.

Clients can release ownership in the following situations:

• The result of a callback message to the Cache Manager is that the client can release ownership.
• The client terminates its connection with the Server.

Ownership and locks

When a client has ownership, it can place a lock on a page without communicating with the Server.

A client can have read ownership without a read lock if the client read the page previously but is not reading the page in the current transaction. The same is true for write ownership and locks.

Lazy release

The lazy release is an optimization. If no other client needs the page that your client has ownership of, that client need not request ownership from the Server for that page for as long as the client is active.

Callbacks

The Cache Manager is involved in the following situations:

• When a client requests read or write ownership for a page and another client already has write ownership for that page
• When a client requests write ownership for a page and other clients have read or write ownership for that page

If the client with ownership

• Has a lock on the page because it is in a transaction, the second client waits.
• Does not have a lock on the page, perhaps because it is between transactions, the second client receives ownership.

API for lock management

For more information about ownership and locks, see Chapter 2, Advanced Transactions, in the Advanced C++ API User Guide.

ClearCase Virtual File System (MVFS)

Troubleshooting

• Try to define what the problem is
• Determine the ObjectStore resource that is affected
• Obtain more information

Where to begin?

• To isolate the problem, review the Installation Guide for your platform. Ensure that you are running a supported version of the operating system and have installed all required patches.
• If the problem is that the Server or cache manager is crashing or not responding, see Debugging the ObjectStore Server or Debugging the Cache Manager.
• If you suspect problems with a database, use osverifydb to verify the content of the database. It is good practice to run osverifydb occasionally to confirm that your database is not corrupt. By maintaining a history of osverifydb results, you can identify when corruption appears.
• If it is a problem with your client application, see Debugging ObjectStore Client Applications.

• Ensure that you are starting the Server with the correct permissions. For example, on UNIX you must be root.
• Consider what the Server needs to do when it starts up. See What Does the Server Do?.

osserver -F -d 5

osserver -con -d 5

You can confirm that the Server has started successfully by using the ossvrstat command.

If the Server starts successfully and you want to turn on debugging output just before a test run, you can use the ossvrdebug utility with a command such as

ossvrdebug server host name debug level

This command turns on debug output from the named server and ossvrdebug 0 turns it off. The higher the debug level, the more verbose the output and the more Server performance is affected. The levels are

Level 0	Turns ossvrdebug off
Level 1	Reports client connect or disconnect
Level 2	Reports messages received
Levels 3-8	Provide expanded message information
Level 9	Provides full message information

Server Initialization Failed

Server initialization failed. (orecvery.cc line 2787)
Unknown record type 127528668 at line 1266304
Failed to start ObjectStore server

• Check the content of the Server output file. For the name of the file on your platform, see the table on page 60.
• If there is a parameters file, check its content for the name of the log file.
• If the log is not in the rawfs, confirm its existence in the location specified in the parameters file.
• Try to start the Server in debug mode.

While running a client application you might receive this message:

Sample trace file reading

Mon Jan 25 15:01:12 1999 DEBUG 48416 [03] client #41
 (flurry.odi.com/9325/(unknown)): upgrade_locks2 CLIENT MESSAGE 
315
 RECEIVED
Mon Jan 25 15:01:12 1999 DEBUG 48417 [04] client #41
  (flurry.odi.com/9325/(unknown)): upgrade_locks2(able to abort, wait
  forever for lock)
Mon Jan 25 15:01:12 1999 DEBUG 48418 [05] client #41
  (flurry.odi.com/9325/(unknown)): upgrade_locks2 implicit
  start_transaction(read/write)
Mon Jan 25 15:01:12 1999 DEBUG 48419 [05] client #41
  (flurry.odi.com/9325/(unknown)): upgrade_locks2 write_locking(DB 
  handle 28, segment #42, 0, 16)

Mon Jan 25 15:01:12 1999 DEBUG 48420 [05] Callback Thread
  (flurry.odi.com) client #36: callback for write(pid=9175, DB handle 28,
  segment #42, 0, 16)
Mon Jan 25 15:01:12 1999 DEBUG 48421 [04] Callback Thread 
  (flurry.odi.com) client #36: callback for write(pid=9175, DB handle 28, 
  segment #42, 0, 16) -> POSITIVE

Mon Jan 25 15:01:12 1999 DEBUG 48422 [05] Callback Thread
  (flurry.odi.com) client #39: callback for write(pid=9318, DB handle 28, 
  segment #42, 0, 16)
Mon Jan 25 15:01:12 1999 DEBUG 48423 [04] Callback Thread
  (flurry.odi.com) client #39: callback for write(pid=9318, DB handle 28,
  segment #42, 0, 16) -> NEGATIVE

Additional notes

• POSITIVE means the lock was successfully called back, and NEGATIVE means it was unsuccessful in calling back the lock.
• DB handle 28 is assigned when the database is first opened by the client and is used to refer to the database in all subsequent messages about the database until it is closed by the client.
• Segment #42 is the name of a particular segment.
• 0,16 is a reference to the starting sector and the number of sectors. Sectors are 512 bytes. On this client platform, a page is 4 KB, so 0,16 means that the first two pages of this sector are locked.

On UNIX, verify the setuid root. If the cache manager fails to start, you can try starting it by hand with additional arguments to enable debugging output. On UNIX, as root, enter

oscmgr6 0 <debug level> 

oscmgr6 -con 0 <debug level>

You can confirm that the cache manager has started successfully by using the oscmstat command.

Debugging Cache Manager Autostart

Miscellaneous ObjectStore error
Reached end-of-file reading initial message from cache manager
(PID=0) (err_misc)
Segmentation Fault

• Check the contents of the Cache Manager output file to see if the Cache Manager is running.

  UNIX	/tmp/ostore/osc6_out
  Windows	OSCMGR6.TXT

• Check cache and commseg file locations and dates. You might have deleted these files but did not use the oscmrf utility.

• On UNIX, verify suid root permissions on the oscminit6 executable.

• On UNIX, verify permissions on the cache and commseg files.

Environment Variables Useful for Debugging

The following are environment variables useful for debugging ObjectStore Servers and Cache Managers. Most of these variables are enabled with a value of 1.

OS_DEBUG_NETWORK	Displays information about each network call.
OS_DEBUG_DYNAMIC_NET	Displays information about network initialization. Generates debug information regarding the server's decision about the network protocol (such as TCP/IP or NetBios) to use at start-up.
OS_DEF_EXCEPT_ACTION	Controls the outcome if an unhandled exception is signaled. Useful in debugging unhandled exceptions. You can specify the following values: abort - ObjectStore aborts the process. On UNIX, ObjectStore creates a core file, if you are running in a debugger. integer - Specify an integer greater than or equal to 1. Object Store exits from the program with that specified integer as the return value. kill - ObjectStore action varies by platform: On Windows NT: ExitProcess (0x006600); On UNIX: kill (getpid(), SIGKILL);
OS_DEF_BREAK_ACTION	Sets a hard-coded break point that allows you to obtain a stack trace before the unwinding of the stack.
OS_DEF_MESSAGE_ACTION	Determines the default message action for _ODI_message (used for unhandled TIX exceptions). You can set this variable to stderr or stdout to send the information there, or you can specify the name of a file to receive the information.

Debugging ObjectStore Client Applications

The following environment variables apply only to client applications.

OS_DEBUG_CMGR_STARTUP	Displays information about a client's attempt to autostart the Cache Manager. Set to any value to display useful dialog information. If running a client, it needs to invoke a Cache Manager.
OS_DEBUG_LOCATOR_FILE	Takes values 1, 2, or 3 to generate varying degrees of output from the locator file mechanism. The higher the value, the more comprehensive the reported information.
OS_TRACE_MISSING_VTBLS	Useful when you are debugging problems with missing vtbls. This environment variable helps determine those classes that need vtbls. Any nonempty value except 0 enables the debugging message. The higher the value, the more comprehensive the reported information.
OS_DEBUG_C0000005	Instructs ObjectStore to display a message box if a fault occurs and the ObjectStore exception handler sees it. The message explains the fault as an attempt to read location 0x1234 from EIP 0x10231023. This can be useful in tracking down access violations in your code.

No Handler for Exception

Database Error

No handler for exception:
ObjectStore internal error Database dbname has fraction length?
(err_internal)

• Use the osverifydb (see page 251) and ossize (see page 230) utilities to check all databases that the application accessed. Check both schema and production databases.
• Use a debugger to find the line of code causing the error.
• Confirm that the architecture page size matches the database page size. This error can be caused when an application running on a machine that uses 8 KB pages tries to access a database created on a machine that uses 4 KB pages.
• Rebuild the database, checking for corruption as it occurs.

No handler for exception:
Cannot open the application schema
<err-0025-0311> The application schema database db.asdb was not 
found
(err_cannot_open_application_schema)
While trying to open the application schema database.

• Verify that a current application schema database exists. It might be missing.
• Use the ossetasp utility (see page 212) to verify that the executable has the correct location of the application schema database.

The application schema database must be local to a Server. The only exception to this is when you use a locator file. See Chapter 5, Using Locator Files to Set Up Server-Remote Databases.

Invalid Address

No handler for exception
ObjectStore internal error
ObjectStore referenced invalid address 0x7fff0028(0)

• Execute the program in the debugger and determine the line of code that has a bad pointer.
• Obtain a back trace from a debugger. It might be that the program is using ObjectStore features incorrectly.

Unsupported Server Protocol

Attempt to use unsupported server protocol.
<err-0001-0006> Server elvis does not support version 5.0 clients.
(err_protocol_not_supported)

Cannot Commit

The exception occurs only when a two-phase commit has problems. A two-phase commit usually occurs only if multiple Servers are being written to in that transaction. If a client reads from ServerA in one transaction and writes to ServerB in the same transaction, it is not a two-phase commit and it is not necessary for ServerA and ServerB to be able to communicate across a common network.

Before You Call Object Design Support

• Hardware platform
• Operating system and release number
• ObjectStore release number
• Severity of the problem
• Description of the problem
• Information found in the Server or Cache Manager output file (if this is relevant)
• Server debug mode output if there is a problem with the Server
• Debugger output if there is a problem with an application

Updated: 03/11/99 11:18:14