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 ObjectStore 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
• Planning Your Configuration
• 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
• Troubleshooting
• Using Virtual File Systems

• With the ObjectStore C++ interface, create and modify C++ objects (as well as C structs) instead of tables, columns, rows, and tuples
• Access data in the same format in which it exists in the application
• 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

Segments

Default segment

Segment location

Number of pages
in a segment

Page size

What Kinds of Databases Are There?

File Databases

Rawfs Databases

A rawfs can contain directories, subdirectories, and databases, just like the native file system. 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?

• os_database::create()
• os_database::lookup()
• os_database::open()

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 of the processes aborts or any host crashes, or in the event of network failure

Rawfs management

Usually, 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

• Already in physical memory or the cache, the application just accesses it.
• Not in physical memory and not in the cache, or
  • In the cache but not yet accessed
  • In the cache but previously accessed with different permissions (for example, read-only instead of update)

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

Any number of clients can run on a particular host. These clients can contact

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

Windows and OS/2

See also

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 do not need to configure ports.

The name of the Cache Manager executable is oscmgr4.

On UNIX, the oscminit executable starts oscmgr4. Normally, you never need to invoke oscminit.

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 if 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

You can use the following environment variables to modify the default attributes of the commseg. See OS_COMMSEG_RESERVED_SIZE for details.

OS_COMMSEG_RESERVED_SIZE	Maximum size of the commseg
OS_COMMSEG_SIZE	Size of the commseg
OS_COMMSEG_START	Starting address of the commseg (rarely specified; ObjectStore usually determines this)

UNIX

Windows and OS/2

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 the ObjectStore processes specific to Windows and OS/2.

Managing Processes

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

• 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. Normally, you do not need to 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 if 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 that are 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.

Meters

• How much data the Server sent to clients
• How much modified data clients sent to the Server
• How many committed transactions the Server knows about
• How many times the Server chose a deadlock victim
• How many times a message from a client to the Server had to wait to use a message buffer
• How much data is 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

oscmgr4 0 debug-level 

Pinging

Monitoring the Server

To enable the ossvrdebug command, type ossvrdebug -d 5. To disable the command type ossvrdebug -d 0.

You can also run the Server in debug mode to obtain information about exactly what is happening. ObjectStore displays messages about process communication that show where the problems are, if there are any.

To run the Server in debug mode, you must shut down and restart the Server with the debug option. See the chapter supporting your platform for specific details. 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.

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 accidentally deleted by users. 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.

Log File Terms

Log record segment

Log record buffer

When choosing the log record buffer size, you should consider both the cost of formatting data into a log record and the cost of a separate write operation.

Log data segment

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 is usually no reason to monitor log size or 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: Never use -ReallocateLog if the Server is in an inconsistent state. Call the ObjectStore Support group for assistance.

Managing Computer Resources

CPUs

Memory

Disk space
and network

It is impossible to predict how much disk space you need for a client application because it is dependent on the application. However, here 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 and OS/2, the cache is in virtual memory and the commseg is in shared memory. Both are in locations that the operating system determines. 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 is typically 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.

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 some other 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?

Under immediate assignment, the total amount of address space needed by a segment is reserved the first time any page within that segment is used in the transaction. This address space must be large enough to contain the segment itself, as well as the portions of other segments that are referred to by pointers within the segment.

Under deferred assignment, space is reserved as each page of the segment is used in the transaction, and the amount of space reserved by each page is the minimum required to correctly relocate the page into virtual memory.

The default behavior of ObjectStore in Release 5 is to use deferred assignment, since doing so prevents address space from being wasted. However, under certain circumstances, ObjectStore can detect that the pages in a segment can be brought into virtual memory without any pointer relocation. In order to ensure that the proper amount of address space is reserved without doing pointer relocation, ObjectStore uses immediate assignment for such a segment, provided that doing so does not increase the address space consumption in the transaction above half of OS_AS_SIZE.

There are several environment variables that can be used to change this behavior. See the sections on OS_IMMEDIATE_THRESH, OS_MAX_IMMEDIATE_RANGES, and OS_FORCE_DEFERRED_ASSIGNMENT for more information.

Also note that databases created prior to Release 5 or with OS_FORCE_STANDARD_PRM_FORMAT on can only use immediate assignment until they are upgraded using the osupgprm utility.

Normally, ObjectStore removes the assignments of persistent space at top-level transaction commit or abort. This allows the next top-level transaction to start with an empty persistent storage region.

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, unless the number of pages exceeds the cache size
• Keeps in the cache 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. See ObjectStore Advanced C++ API User Guide, Using ObjectStore References, for further information.

Persistent address space

Physical memory

Client cache

Swap space

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

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.

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.

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 where 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 the size of a disk. (Large usually refers to multigigabyte databases, but it also depends on how much disk space you have.)
• Allows applications to use ObjectStore in such a way that ObjectStore is invisible to end users.
• Simplifies management because all databases are in one location.

• Provides greater security because the
  • Transaction log is hidden so there is no chance for accidental deletion.
  • 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 not as good as 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.

1. Rawfs database stored in a raw partition
   
   
2. File database
   
   
3. Rawfs database stored in a file partition
   
   

Utilities for Managing the Rawfs

• 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 the chapter in this book discussing your platform. In that chapter are specific instructions for 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 your environment variables (OS_ROOTDIR and OS_DIRMAN_HOST) reflect 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. Modify the PartitionN Server parameter specifications to reflect your new 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 oscp, if you used it when saving the database) to restore any needed databases.
   
   

Mixing Network Protocols

For example, an OS/2 client running APPC and a UNIX client running TCP/IP can access the same Server.

However, be sure to avoid configurations that do not allow Servers to communicate with each other, as described in the next section.

All Servers in a Transaction Must Be Able to Communicate

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.

Running an Application from a CDROM

You should validate the schemas before you place an application and/or database on a CDROM. In other words, run the application on the database in question (in update mode) and then put the application and/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.

See additional schema validation discussions in the ObjectStore C++ API User Guide, in Chapter 2, Persistence.

What You Need to Know About the API

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
• All databases that databaseA points to or references

Schema databases

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 there are no bad pointers or dangling references. 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 correctly established.
   
   
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.

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 also 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/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 ObjectStore Building C++ Interface 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 and 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

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, then 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:

Sunday:	Backup level 0
Wednesday:	Backup level 1
Mon. Tues. Thurs. Fri. Sat.:	Backup level 2

For example, if you need to restore the databases on Friday morning, then you must restore the backup images from Sunday, Wednesday, and Thursday. It is advisable to save the previous level 0 backup in another spot 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 which databases have been backed up, and when they were backed up. The osbackup utility uses this information to determine which segments within a database have been modified since the last backup at a lower level. The utility then backs up only modified segments. The incremental record file is comparable to the archive record file for osarchiv.

• The -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 segment level, meaning that a segment 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 segments in all specified databases.
• The -f flag specifies the location of the backup image.

Archive Logging

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 megabytes. 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:

YYMMDDHH.ext, where,

YY =	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. Shorter intervals between snapshots have the effect of keeping the archive more up to date and keeping the amount of data that needs to be archived smaller. (Can this add to the recovery process?) However, since 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 where 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 -C 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 automatically taken. You can take a snapshot at any time that osarchiv is active by issuing the x command. Note that the x command can only be used when running osarchiv interactively.
• The -C flag enables the interactive command-loop feature. This feature is disabled by default.

See osarchiv: Logging Transactions Between Backups for further information about the options for this utility.

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 how 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\97080719.aaa 
      archive_img\97080719.aab 
      archive_img\97080720.aac 
      archive_img\97080720.aad 
      archive_img\97080720.aae 
      archive_img\97080720.aaf 

-F archive_list.txt -D 7/8/97 -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 in Chapter 4, Utilities for more detailed information about using the dump/load facility. For advanced topics related to customization, see Chapter 8, Dump/Load Facility in the ObjectStore 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

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.

UNIX

Windows and OS/2

Defaults for Port Settings

All Servers in all ObjectStore versions have the same port number. The default port settings are in the following table.

Process	IP Port Number	TLI_LOCAL Pathname	UNIX Pathname
Server to R4 Cache Manager	51034	os_callback_v4	/tmp/ostore/os_callback_v4
R4 client to R4 Cache Manager	51044	osccom4	/tmp/ostore/osccom4
Client to Server	51025	objectstore_server_comm	/tmp/ostore/objectstore_server_comm
Notification	51049	objectstore_notification	/tmp/ostore/objectstore_notification

Modifying Port Settings

On UNIX, Windows, and OS/2, 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 and OS/2	%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 next 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.




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 Release 4, specify 4. For compatibility, ObjectStore Release 5 also requires 4 as the version number in all cases except for server client. This service requires a 1.


port

Specifies a port identifier as described in the next table.

Example

TCP/IP:server client:1:54432

UNIX domain example

UNIX:server client:1:/tmp/.ostore/objectstore_server_comm
UNIX:cache manager client:4:/tmp/.ostore/objectstore_client_cache
UNIX:cache manager server:4:/tmp/.ostore/objectstore_server_
cache

Different versions

To set up two Servers on the same host, you only need to change 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

On non-System V Release 4 systems, such as AIX, Digital UNIX, and HP-UX, specify a combination of UNIX and TCP/IP statements in the ports file. The UNIX domain or local ports have names in the file system's name space.

Windows

OS/2

If you do not specify port settings correctly, and you try to start a second Server or Cache Manager, the operation fails with the following error:

<err-0001-0144>There is a server for the service <sss> already running 
on net <nnn>.

This all happens automatically and transparently, so there is no relevant API. However, as with all network connections, you might want to control what network port 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	51049
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 which Server to communicate with.

When Accessing a Rawfs Database

• The rawfs host name appears in the pathname of the rawfs database.
• The environment variable OS_DIRMAN_HOST is set to the name of the rawfs host.

Managing ObjectStore on Multiple Platforms

Using Multiple File Systems

Translating Pathnames

Suppose you have a UNIX Server and some Windows NT and OS/2 clients.

Native pathnames

Server-relative pathnames

Callback Messages Background

Note: The terms ownership, encached page, and permit all represent the same concept - a client has permission to read or modify the page.

Read/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. 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 it previously read the page 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, then your client does not need to 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 Locking in Chapter 3, Transactions, of the ObjectStore C++ API User Guide.

Troubleshooting

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

Server Initialization Failed

Server initialization failed
Trouble accessing ObjectStore file system.
Exception message: <maint-0018-0006>
File access permission denied

• Check the content of the Server output file.

  OS/2	OSSERVER.TXT
  UNIX	/tmp/ostore/oss_out
  Windows	%OS_ROOTDIR%\OSSERVER.TXT

• Ensure that you are starting the Server with the correct permissions. For example, on UNIX you must be root.
• On UNIX and OS/2, you can try to restart the Server in debug mode.
• Consider what the Server needs to do when it starts up. See What Does the Server Do?

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 in OSSERVER.TXT.
• 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.

Miscellaneous ObjectStore Error

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.

  OS/2	OSCMGR4.TXT
  UNIX	/tmp/osc4_out
  Windows	OSCMGR4.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 oscminit executable.

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

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

• Use the osverifydb (see osverifydb: Verifying Pointers and References in a Database) and ossize (see ossize: Displaying Database Size) 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 K pages tries to access a database created on a machine that uses 4 K 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.

• Check that a current application schema database exists. It might be missing.
• Use the ossetasp utility (see ossetasp: Patching Executable with Application Schema Pathname) to check that the executable has the correct location of the application schema database. The executable might have the wrong location.

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.

No Handler for Exception - Invalid Address

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

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

Unsupported Server Protocol

Attempt to use unsupported server protocol.
<err-0001-0006> Server elvis does not support version 4.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.

AIX - Available Space But Database Does Not Grow

No handler for exception:
The server is out of disk space for the database or logfile
set_segment_size call to server (host "rexx")

rexx:phawkins(678)> df .:

Filesystem	Total KB free	%used	iused	%iused	Mounted on
/dev/lv00	2002944	411296	79%	5439	1% h/rexx/2

rexx:phawkins(679)> ls -l mydb
-rw-rw-r--   1 phawkins sys      1073082368 Sep 26 17:26 mydb

To change the limit, change the file /etc/security/limits and add -1 for the root fsize limit. For example:

default:
      fsize = 2097151
      core = 2048
      cpu = -1
      data = 262144
      rss = 65536
      stack = 65536
root:
      fsize = -1
daemon:
bin:
sys:
adm:
uucp:
guest:

• Hardware platform
• Operating system and release number
• ObjectStore release number
• Severity of the problem
• Description of the problem
• Information found in the Server and/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

Opening databases

Pathnames you
can use

This requirement applies to any ObjectStore database stored under a virtual file system and includes any object 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.

Running Server under virtual file system

Schema databases

Some virtual file systems 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 leaf names (such as eng_1.libschema in the following example) as arguments to ObjectStore utilities.

Sample error message

> pwd 

/home/clients/libschemas

> ls

test_1.libschema
eng_1.libschema 
qa_1.libschema 

> ossize eng_1.libschema

ossize: The database was not found
<err-0025-0351>The database 

"/home/clients/libschemas/eng_1.libschema"
does not exist (err_database_not_found)

Updated: 03/26/98 20:13:22