This chapter provides information about managing ObjectStore on UNIX systems. For complete information, you should consult the first six chapters in this book along with this chapter.

The topics discussed in this chapter include

• Database and Executable Pathnames
• Setting Server Parameters
• Starting the Server
• Creating a Rawfs
• Setting Cache Manager Parameters
• Increasing the Size of the Cache
• Description of ObjectStore Directories
• Finding Files Containing ObjectStore Messages
• Using Tapes with the osbackup Utility
• ObjectStore Use of /tmp/ostore
• AIX Considerations

os_database::open("/usr3/fauntleroy/my_file_db")

ObjectStore treats links in the usual manner.

Automount pathnames are acceptable. If you are using automount, the pathname you specify cannot include the automount prefix, usually /tmp_mnt. Referring to the file with this prefix does not cause automount to keep it mounted and can cause the file to appear deleted.

Unless you set up a database to be a Server-remote database (see Chapter 5, Using Locator Files to Set Up Server-Remote Databases), you must store file databases on a host that is running an ObjectStore Server. ObjectStore determines which Server to use based on the NFS mountings of the client that creates the database.

Colons in file pathnames are interpreted as alphabetic characters if a slash character precedes the colon in the pathname. For example:

/usr1/moe/a:b	Specifies a file named a:b in the /usr1/moe directory, in the local host's name space.
bill:/usr2/dbs:abc	Specifies a file named dbs:abc in the /usr2 directory, on Server bill, in the Server's name space.
fifi/mimi:lulu	Specifies a file named mimi:lulu in the fifi directory, relative to the working directory, in the local host's name space.

File Name Expansion

You must insert a back slash (\) as an escape character immediately before a wildcard character. For example:

sax::/charlie\*.

osls -d /oshome/bin/osse*
osls -d /oshome/bin/osse\*

Executable Pathnames

$OS_ROOTDIR/bin/utility-name 

Where the input name is a file database name, the commands (except oscp and osmv) pass the name on to the corresponding system command. Those commands that modify an individual database file in any way (oschgrp, oschmod, oschown, osmv, and osrm) attempt to verify that the file being operated on is in fact a database, by calling os_database::lookup() on the path before operating on it. This verification is only done, however, if neither -f (force) nor -R (recursive) is specified. If the force or recursive flag is specified, the paths are simply passed to the shell without further checking. This means, for example, that

osrm /foo/bar

osrm -f /foo/bar

Note: ObjectStore utilities return a zero to indicate success and a nonzero value to indicate otherwise.

Setting Server Parameters

All Server parameters have default values. Object Design recommends that you use the default value for each parameter, which requires no action on your part. You can, however, modify Server parameters in two ways:

• You can use the osconfig utility.
• You can create a parameter file.

Using the osconfig Utility

When you run osconfig, the utility prompts you for the name of the Server log file. If you do not accept the default, this also results in a modification to the Server parameters.

Creating a Parameter File

Parameter file format

• One parameter and its value can appear on a line.
• A parameter has a name, such as Deadlock Victim.
• The parameter name is followed by a colon.
• The colon is followed by the parameter's value. According to the parameter, this can be numeric or text.
• The colon and value are separated by tabs or spaces.
• Comment lines must contain a # as the first nonblank character.
• Case is not significant for parameter names.
• Embedded spaces are significant.
• If the same parameter name appears twice in the parameter file, only the first occurrence is read.

Log File: /support2/local/ostore/sun4.r300/.log
Partition0: /support2/local/ostore/sun4.r300/.part0
Authentication Required: Unix Login

1. File specified with the -p option to osserver.
   
   
2. $OS_ROOTDIR/etc/host_server_parameters, where host is the name of the local host.
   
   

Starting the Server

The pathname of the Server executable is $OS_ROOTDIR/lib/osserver. See the installation instructions for setting OS_ROOTDIR).

Syntax

$OS_ROOTDIR/lib/osserver [options]

Description

Debug mode

Use -i and -I with
caution

When you initialize the transaction log, anything in the log is lost. The Server resizes the log to the values specified by the Log Data Segment Initial Size and Log Record Segment Initial Size Server parameters. When the log is in the rawfs, this frees space for use by other files. When the log is in the native file system, this reallocates space dedicated to the transaction log. The size of the log does not change.

Initializing when you
have a rawfs

The entire ObjectStore file system on this host is about to be initialized, 
thus destroying any data currently in it. Unless you have a backup of the 
ObjectStore file system, it will be impossible to recover the old contents 
once the initialization is started. Are you sure that you want to reinitialize 
the ObjectStore file system?

Initializing when
there is no rawfs

You have asked for initialization which will create a new transaction log, 
deleting any old log that might exist, thus destroying any recovery data in 
the old log. This might leave some file databases in a broken state. Are 
you sure that you want to create a new log?

Nonroot Server Start-Up

Creating a Rawfs

Before you can create a rawfs, you must set aside some partitions to be in the rawfs.

• For raw partitions, you might need to reorganize your disk space unless you have a new disk.
• For a file partition, create a file. If there is anything in the file, ObjectStore overwrites it.

Restrictions

On SGI with XFS, file partitions can be greater than 2 GB.

The maximum number of partitions for a single Server is 32.

Specifying the Partitions in a Rawfs

PartitionN: type pathname {expandable | nonexpandable}


N

Specifies a positive integer from 0 to n. PartitionN statements can appear in the Server parameter file in any order, but empty slots are not allowed. For example, if you have four partitions, they must be numbered 0 through 3. Required.


type 

Specifies whether the partition is a raw partition or a file partition. Required.

The value for type can be PARTITION or UNIX (except on AIX, HP-UX, and SGI IRIX; see below). If you specify PARTITION, the value of pathname must be the raw device name, for example, /dev/rsd0d, of a UNIX disk partition to be used as the nth partition in the rawfs. If you specify UNIX, the value of pathname is the absolute pathname of a UNIX file that is to be used as the nth partition in the rawfs. 

The raw device is also known as a character special file in UNIX. Typically, each partition is accessible both by a raw device and by a block special device. The ObjectStore Server requires the use of the raw device.


AIX

On AIX, the value for type can be UNIX, LV, or RAW.


UNIX indicates the rawfs is stored in an AIX file.



LV indicates the rawfs is stored in an AIX logical volume.



RAW indicates the rawfs is stored in an AIX physical volume (raw disk).



HP-UX

On HP-UX, the value for type can be UNIX, PARTITION, or DISK.


UNIX indicates the rawfs is stored in an HP-UX file.



PARTITION indicates the rawfs is stored in an HP-UX logical volume.



DISK indicates the rawfs is stored on a raw device.



SGI IRIX

On SGI IRIX, the value for type can be UNIX, LV, or PARTITION. 


UNIX indicates the rawfs is stored in an SGI IRIX file.



LV indicates the rawfs is stored in an SGI IRIX logical volume.



PARTITION indicates the rawfs is stored on a raw device.



pathname 

Specifies the pathname of the partition. It must begin with a slash. For a raw partition, it is the device name. For a file partition, it is the absolute pathname.


AIX

On AIX, specify


An absolute pathname if you specify UNIX for type



The LV name if you specify LV for type, for example, oslv



The PV name if you specify RAW for type, for example, hdisk6



HP-UX

On HP-UX, specify


An absolute pathname if you specify UNIX for type.



The LV name if you specify PARTITION for type. You can use the block special device or a raw device name. For example, /dev/vg00/lvol2 or /dev/vg00/rlvol2 where 00 is the volume group number and 2 is the logical volume.



The pathname for the raw device if you specify DISK for type. For example, /dev/dsk/c207d6s0.



SGI IRIX

On SGI IRIX, specify


An absolute pathname if you specify UNIX for type.



The pathname of the raw device associated with the logical volume if you specify LV for type. For example, /dev/rdsk/lv0.



The pathname of the raw device if you specify PARTITION as type. For example, /dev/rdsk/dks1d457



expandable | nonexpandable

Indicates whether the partition is expandable in size or nonexpandable. By default, raw partitions are nonexpandable and file partitions are expandable.

Modifying Partition Size

Rawfs expansion

• If one file is used, it expands dynamically as needed, as long as there is room in the partition containing the file.
• If multiple files or a mixture of files and raw partitions is used for the rawfs, ObjectStore treats them differently with regard to expansion.
  • You can expand raw partitions only when you start the Server.
  • Files can expand dynamically, if you specify expandable in the PartitionN statement.

Partition0: UNIX /usr1/one expandable
Partition1: UNIX /usr2/two expandable
Partition2: UNIX /usr3/three nonexpandable
Partition3: PARTITION /dev/rsd4x

Shrink rawfs

Adding partitions

1. Make sure your raw partition is in place or that you created the file that will be your file partition.
   
   
2. Use the ossvrshtd utility to shut down the Server.
   
   
3. Edit the file $OS_ROOTDIR/etc/<hostname>_server_parameters. Add a PartitionN for each new partition. See Specifying the Partitions in a Rawfs.
   
   
4. As root, restart the Server with the osserver utility.
   
   

To reinitialize the entire rawfs, see Reconfiguring the Rawfs.

Setting Cache Manager Parameters

You can specify the following Cache Manager parameters:

• Cache Directory
• Commseg Directory
• Hard Allocation Limit
• Mount Table Pathname
• Soft Allocation Limit
• Temporary Files Permission

Specifying the Cache Directory Parameter

If the environment variable OS_CACHE_DIR is set, ObjectStore uses that directory. Cache and commseg files should be in the same directory.

Make sure that this directory exists. The Cache Manager does not automatically create it.

Specifying the Commseg Directory Parameter

If the environment variable OS_COMMSEG_DIR is set, ObjectStore uses that directory. Cache and commseg files should be in the same directory.

Specifying the Hard Allocation Limit Parameter

Cache Manager hard limit (NNNNN) exceeded by request for MMMMM 
bytes of cache and/or commseg

The default of 0 means that no limit is enforced.

Specifying the Mount Table Pathname Parameter

HP-UX and System V

Object Design expects that few users will ever need this parameter. It is provided for the very unlikely situation in which you have something in your default mount table that ObjectStore cannot parse.

Specifying the Soft Allocation Limit Parameter

This parameter allows you to prevent ObjectStore cache files from using too much disk space.

The default of 0 means that no limit is enforced.

Specifying the Temporary Files Permission Parameter

Note that the Cache Manager file permissions setting can also be affected by the umask of the shell that started the Cache Manager. For this reason, you should set the umask to 0 when using this parameter.

Cache Manager Parameter File Location

1. $OS_ROOTDIR/etc/host_cache_manager_parameters, where host is the name of the current host as returned by the hostname program. OS_ROOTDIR is an environment variable.
   
   
2. $OS_ROOTDIR/etc/cache_manager_parameters.
   
   

• Each line in a parameter file contains one parameter and its value.
• Parameters have text names, such as Cache Directory.
• Each parameter name is followed by a colon, some white space (tabs or spaces), and a value (either numeric or text, depending on the parameter).
• Comment lines must contain a # as the first nonblank character.
• Case is not significant for parameter names. Embedded spaces, however, are significant.
• If the same parameter name appears twice in the parameter file, only the first occurrence is read.

Cache Directory: /support2/local/ostore/tmp
Commseg Directory: /support2/local/ostore/tmp
Mount Table Pathname: /new/mount/pathname
Hard Allocation Limit: 10000000

On UNIX, an ObjectStore cache is a memory mapped file. Now, suppose you have a system where the size of this memory mapped file is a significant percentage of the system's real memory. In this situation, an application that is performing memory mapping for a large file and subsequently doing a lot of processing that does not involve the memory mapped file can suffer a much poorer performance than if the application had not memory mapped the file - that is, if the application used straight UNIX file I/O.

The reason for this is that overall system swapping is increased by the presence of the semiactive memory mapped file. That is, the application is not using or reusing the cached database pages frequently enough to benefit from a large cache file.

An example of such an application is a program that populates a database by inserting a large number of objects into a collection. In this case, with the exception of the actual collection object, the pages in the cache are not being reused. Such a program benefits from having a small cache (for example, 2 MB) because the objects are not being revisited and overall UNIX system swapping is low.

A program that would benefit from having a large cache would be one that accesses a large number of objects (pages) and then reaccesses the same objects before replacing the objects (pages) in the cache with other objects (pages) fetched from the database. Of course, as the cache size starts to become a larger and larger percentage of the size of the machine's physical memory, more and more system swapping occurs and the performance gain of a large cache file begins to be lost.

The important issue with a large database is knowing how to properly cluster and segment it to achieve maximum performance. Properly designing a database so that it is clustered/segmented to achieve maximum performance is usually very application specific.

See OS_CACHE_SIZE for information on setting the cache size.

Description of ObjectStore Directories

The ObjectStore directory structure appears in the following illustration. You must set OS_ROOTDIR to Toplevel.

The directory structure for AIX and Solaris 2 each contain one extra directory, sunpro on Solaris 2 and cset on AIX as shown in the following illustration. Each of these two directories contain links to the top level, bin, lib and Other Directories.

The cset and sunpro directories provide backward compatibility. In previous releases, the AIX and Solaris 2 platforms supported two compilers, a native C++ compiler and Cfront. Some components were common to the two compilers and some were compiler-dependent. The cset and sunpro directories contained compiler-specific components, and the common components were contained in a directory called common.

In the modified directory structure of ObjectStore Release 5.1 the common directories have been eliminated, and the sunpro and cset directories contain links to bin, lib, and so on. For backward compatibility, you can set OS_ROOTDIR to Toplevel/cset or Toplevel/sunpro.

Finding Files Containing ObjectStore Messages

If the file does not already exist, ObjectStore creates it; if the file does exist, ObjectStore appends the new 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.

When the daemon process is not running, you can safely delete the corresponding file. Usually, very little is ever sent to these files, so they are unlikely to occupy much disk space.

Using Tapes with the osbackup Utility

ObjectStore Use of /tmp/ostore

AIX Considerations

Using SCSI Tape Drives

You must choose values for these parameters:

• Use Device Buffers as set with chdev or SMIT
• Tape size given to the osbackup command
• Block size for the device as set with chdev or SMIT
• Block size given to the osbackup command

This situation does not occur when Use Device Buffers is set to no, and it is not necessary to specify a tape size to the osbackup command.

Block size

The use of variable-size blocks on QIC-120 or QIC-150 media is apparently unique to IBM. If you write variable-size blocks on such a tape, you will not be able to read it on another system.

You can also use fixed-size records, which can facilitate tape duplication under certain circumstances.

To use fixed-size records, you must either set block_size in bytes in SMIT or with chdev, or use the -b control argument to osbackup to specify the block size in 512-byte sectors. Note that the osbackup command option overrides the SMIT setting, unlike utilities such as tar, where the SMIT setting takes precedence.

The block size must be 512 bytes or less. The osbackup utility cannot work when the block size is greater than 512 bytes.

Setting Up Permissions

-root=server_host_name 

Failing to perform both steps can cause permission errors.

Troubleshooting Permission Denied Error

# lsattr -E -l sys0 -a maxuproc

maxuproc 40 Maximum # of processes allowed per user True

# chdev -l sys0 -a maxuproc=200

sys0 changed

No handler for exception:
permission to access this database was denied
re /usr/lpp/ostore/lib/liboscol.ldb while looking up file database 
/usr/lpp/ostore/lib
/liboscol.ldb (host "aix_server1")
gmake: *** [AIX/os_schema.C] Error 1
aix_server1> ps -efl | grep ostore
260801 S     root 19379  3967   0  60 20 12892   516            Feb 23      -  0:00
/usr/lpp/ostore/lib/cmgr3 -AIX_SRC
 200801 S pbergstr 32347 41739   1  60 20 11051    88  6052824 14:01:27 
pts/15  0:00
grep ostore
262801 S pbergstr 40254  3967   0  60 20  9e3  1372          14:00:31      -  
0:00 /
usr/lpp/ostore/lib/osserver -AIX_SRC
aix_server1>

1. Shut down the Cache Manager ($OS_ROOTDIR/bin/oscmshtd).
   
   
2. Shut down the Server ($OS_ROOTDIR/bin/ossvrshtd -f hostname).
   
   
3. Use ossvrchkpt to ensure that all data is copied from the transaction log to the database that was changed.
   
   
4. Check the files $OS_ROOTDIR/etc/yourhostname_server_parameters and $OS_ROOTDIR/etc/yourhostname_cache_manager_parameters to see where your transaction log and temporary files are going, then remove them.
   
   
5. Remove the install area (/usr/lpp/ODI by default).
   
   
6. Remove links to /usr/bin if you created them with osconfig. Do not remove /usr/bin/oslevel.
   
   
7. Remove links to /usr/lib if you created them (/usr/lib/libos*).
   
   
8. Remove the link to $OS_ROOTDIR/include if you created it (/usr/include/ostore).
   
   
9. Remove /etc/rc.objectstore.
   
   

Updated: 03/26/98 20:44:42