ObjectStore Management
Chapter 3
Environment Variables
This chapter describes the ObjectStore client environment variables.
These alphabetically-ordered variables are described in the pages that follow:
Specifying Values for Environment Variables
You can set environment variables to modify the characteristics of the client environment. The variables you set apply to the process in which you set them and consequently to ObjectStore applications that you start from that process.
An environment variable is available on all platforms unless noted otherwise in this chapter. Defaults appear in the left margin.
The value for a variable is either an integer, a Boolean, or a string that can have certain values as described in this chapter. When you set a variable string to an empty string, ObjectStore uses the default. When you set an integer or Boolean variable to a blank string (nonempty), ObjectStore interprets it as 0 or false.
Specifying integers
When a variable has a numeric value, it is an unsigned integer (leading + or - is dropped) that ObjectStore reads as a constant according to the rules of the C programming language. An empty setting results in a value of 0. If the whole value cannot be parsed, ObjectStore signals an error such as the following:
<err-0001-0040>The value of variable_name, bad_value, is not a valid
integer. (err-misc)
Specifying Booleans
When a variable has a Boolean value you can specify any nonnull value except 0 to set the variable. When the value for a Boolean variable is false, it means that the variable is not set. To turn off a Boolean variable, set it to 0.
A true setting for an environment variable is anything nonempty/ nonnull that does not completely parse as a constant to the value of 0 according to the rules of the C programming language. For example, the following values return true:
While the following values return false:
OS_AS_SIZE
Default: by platform
Sets the size, in bytes, of the persistent storage region in the address space for each client. If you do not specify a value for this variable, which is common, the default depends on your platform, as shown in the table under the heading Platform. Specify numbers of bytes in decimal values.
The size of the persistent storage region on the creating platform typically determines the size of the largest object you can store in a database. This is because ObjectStore commits the entire object in the transaction that allocates it. However, if the maximum size of a segment is smaller than OS_AS_SIZE, then the largest object you can store is limited to the maximum segment size. (Allocation is limited to a single segment.)
Caution
An incorrect value for OS_AS_SIZE or OS_AS_START can cause failures. Be absolutely certain you understand how addresses are assigned on your platform before you modify these values.
For example, if you quadruple OS_AS_SIZE, your application runs on a SPARCserver/470, but fails on SPARC 1 and SPARC PC systems.
When considering address space, note the important distinction between assigning an address and mapping an address. When ObjectStore assigns an address, it means that the Server determines where it would put those pages if the client needed them. Assigning an address reserves it so that it cannot be assigned to another page. When ObjectStore maps a page to an address, it means that the page is available to the client.
ObjectStore assigns address space to any pages outside the segment containing the initial page that was referred to. This makes it possible, in certain situations, to use up available address space by touching a single page. In many cases, changing OS_AS_SIZE solves this problem. However, there are cases where the schema design could benefit from the strategic application of references, and sometimes a reworking of transaction semantics.
If the application uses a reference, instead of a pointer, to point to data in other segments, ObjectStore does not assign address space to the other segment until the reference is actually resolved. In programs where a complex schema requires the use of a segment that contains pointers to lots of data in other segments or where an extent contains pointers to instances in many segments, use references instead of pointers. If the client exhausts the address space, it might be possible to reorganize some of the client's transactions to reduce the amount of data being referenced in any single transaction.
If necessary, ObjectStore rounds down the number you specify to a page-size boundary, that is, a multiple of the page size.
OS_AS_START
Default:
by platform
Sets the address of the beginning of the persistent storage region of the process's address space. If you do not supply a value for this variable (this is the usual case), the default depends on the platform, as shown in the table under the heading Platform.
Individual platforms impose further constraints on what values are legal.
See OS_AS_SIZE for a caution about the use of this variable.
If OS_AS_START and OS_AS_SIZE are the same on all machines that create and use data in a given database, ObjectStore can often optimize relocation, which improves performance. See OS_RELOPT_THRESH for a discussion of the relocation optimization.
If necessary, ObjectStore rounds down the number you specify to a page-size boundary, that is, a multiple of the page size.
The following table shows the specifications for the persistent storage region in a process's address space.
Windows NT
On Windows NT, two gigabytes is the maximum user-mode address space. Your program, its data, and ObjectStore's address space must fit in two gigabytes. A user program on Windows NT uses the bottom two gigabytes of address space. DLLs and such use up space at 0x10000000; stacks use up space at 0x7fxxxxxx. Consequently, there are only 1.75 gigabytes available.
SPARCstation 10
There is no address space hole on the SPARCstation 10. In a single mmap, you can map any portion of the address space from address 0 to the process stack (around 0xefffe000). However, a single call to mmap has a limit of 0x80000000 bytes (approximately 2 GB). For ObjectStore, that means you can only use half of the entire 32-bit address space.
SPARCstation 1000
On a SPARCstation 1000, the address space available for mapping starts above the break. The break is the top of the process's heap. The heap grows by increasing the break. It is risky to map a persistent range that is too near the break because a growing heap might collide with the persistent range.
The hole in the SPARCstation 2's address space begins at 0x20000000 and ends at 0xe0000000. Addresses above the hole are available for mapping, but ObjectStore requires that the persistent range be contiguous, so the range cannot span the hole.
On Solaris 2, the default start address is 0xe2000000, just above the end of the hole. The persistent range can be placed on either side of the hole on both systems.
On a SPARCstation 2 running Solaris 2, the size of the persistent range is limited on the high end by the area where shared libraries and other objects placed by the system are allocated. This starts below the stack, around 0xf0000000, and grows downward.
On the SPARCstation 1000, though, this area starts around 0xe0000000, and grows downward. Apparently, on the SPARCstation 1000, ObjectStore's default range is sandwiched between the stack and shared libraries. Since the hole does not constrain the available space on this machine, the system gives the stack a bit more room to grow by placing shared libraries at lower addresses.
For a maximum persistent range on the SPARCstation 1000, the range from 0x10000000 to 0xd0000000 should be safe to use and large enough for just about any purpose. However, you should test this before you put an application into production that depends on it.
SPARCcenter 2000
Up to 1.8 gigabytes can be allocated in a single mmap call.
OS_AUTH
Overrides NT Remote authentication. The following table lists values that OS_AUTH can be assigned:
OS_BOOTSTRAP_LRU_CACHE_SIZE
Default:
three-quarters
of cache size
Specifies a number of bytes. When the cache grows to this size, ObjectStore performs an LRU (least recently used) bootstrap routine to start the process of determining which pages are not being used. This allows the first page eviction to be done intelligently, since page eviction chooses pages to evict based on information that must be collected over time. If the size of your cache drops below the OS_BOOTSTRAP_LRU_CACHE_SIZE threshold, ObjectStore suspends this process until you reach the threshold again. This way your application does not have the unnecessary overhead of determining which pages should be evicted.
OS_BOOTSTRAP_LRU_CACHE_SIZE has a default setting that is three-quarters of the cache size.
If your cache is large enough to hold the entire database being used by a program, set OS_BOOTSTRAP_LRU_CACHE_SIZE so that it is greater than the cache size. This improves performance by avoiding execution of the bootstrap routine. Execution is unnecessary since page evictions are not needed when the cache can hold the entire database.
When you set OS_BOOTSTRAP_LRU_CACHE_SIZE to a size greater than (OS_CACHE_SIZE - eviction_pool_size), ObjectStore runs the LRU bootstrap routine when there are eviction_pool_size free pages left in the cache. The eviction_pool_size defaults to 2 percent of the cache and is always at least twice the eviction_batch_size, which defaults to 1 percent of the cache.
Use the API to set eviction sizes: objectstore::set_eviction_pool_size and objectstore::set_eviction_batch_size. See ObjectStore C++ API Reference.
If necessary, ObjectStore rounds down the number you specify to a page-size boundary, that is, a multiple of the page size.
OS_BROWSER_NUMERIC_FORMAT
Default:
ObjectStore defaults
Allows you to set the output format of numeric types. It supports the following types: int, long, double, ldouble, float, uint, ulong, short, and ushort. If you do not set any of these types, ObjectStore defaults are used.
The following example sets the display format of all int types to hex, all float types to four-digit precision, and all ulong types to hex.
OS_BROWSER_NUMERIC_
FORMAT="int=%x,float=%.4f,ulong=%x"
OS_CACHE_DIR
Default:
/tmp/ostore
Specifies the pathname of the directory in which ObjectStore places the client cache and communications segment (commseg) files. Specifying an alternative pathname can be useful when your /tmp/ostore directory is small. ObjectStore places the cache file in the specified directory, and assigns a file name to avoid conflicts between multiple processes that are running ObjectStore and using the same directories.
If OS_CACHE_DIR is not set, ObjectStore places the cache file in the directory specified by the Cache Directory parameter in the Cache Manager parameters file, if one exists. See Setting Cache Manager Parameters.
This directory should not be an NFS mount point because this can result in slower client performance and can result in potential problems with memory mapping over NFS.
Cache and commseg files should be in the same directory. See OS_COMMSEG_DIR for related information.
Windows and OS/2
The operating system determines the location of the cache in virtual memory. You cannot change the location.
OS_CACHE_SIZE
Default: 8 MB ObjectStore Single: 2 MB
Size of client cache, in bytes. The cache size defaults to 8 MB, except for ObjectStore single applications, for which the default cache size is 2 MB. In either case, the default cache size can be overridden using the OS_CACHE_SIZE environment variable.
Note that the size of the client cache does not limit the size of an object that can be in the database. ObjectStore can store an object on multiple pages and can swap pages in and out of the client cache as needed.
When trying to determine the optimum cache size for your application, consider data access patterns as well as how much data is accessed. In other words, both size and operation are important. The goal is to minimize the number of times the client must swap pages out of the cache and send them back to the Server.
You should also consider the amount of physical memory in your machine. Usually, it is desirable for the cache to stay in physical memory rather than be swapped out to disk.
The cache size is limited only by the amount of resources (address space, memory and/or disk space) on the machine.
If necessary, ObjectStore rounds down the number you specify to a page-size boundary, that is, a multiple of the page size.
OS_CMGR_STARTUP_LOCK
Default:
varies
by platform
Specifies an alternate location for the Cache Manager start-up lock file.
On UNIX and OS/2 systems, ObjectStore clients automatically start a Cache Manager if one is not already running. ObjectStore uses a special file, called a start-up lock file, to ensure that only one Cache Manager starts on a host. The default location for this file is
If a Cache Manager is not already running, a client
- Creates the start-up lock file
- Launches the Cache Manager
- Ensures that it can communicate with the Cache Manager
- Deletes the start-up lock file
The start-up lock file does not contain anything. Its existence serves as a lock while a client is starting a Cache Manager. This prevents other clients from also starting a Cache Manager.
If you do not want to use the default location for the start-up lock file, or if the default location is unavailable, you can specify an alternative location with the OS_CMGR_STARTUP_LOCK environment variable. Set this variable to a local pathname.
ObjectStore tries to use the default first. If it is not possible to use the default, ObjectStore uses the pathname you specified for OS_CMGR_STARTUP_LOCK.
The client process must have the authority to create the specified file.
OS_COLL_POOL_ALLOC_CHLIST_BLKS
Default: false
Specifies that chained list blocks should be pool allocated. To set this variable, specify any nonnull value except 0.
OS_COLL_THREAD_LOCKS
Default: true
Determines whether ObjectStore uses a lock to ensure that only one thread at a time can execute within ObjectStore collections code.
When this variable is set to a nonnull value other than 0, ObjectStore uses the collections thread lock. This is the default.
If you are certain that in a multithreaded application only one thread at a time ever executes any collections operation, then you can improve performance by disabling the collections thread lock. In other words, set OS_COLL_THREAD_LOCKS to 0. You can do this when other threads are using ObjectStore entry points other than those involved with collections.
The OS_THREAD_LOCKS (see OS_THREAD_LOCKS) variable determines whether ObjectStore uses a lock to ensure that only one thread at a time can execute within ObjectStore code other than collections code.
If OS_THREAD_LOCKS is disabled, you cannot enable OS_COLL_THREAD_LOCKS. In other words, when OS_THREAD_LOCKS is set to 0, ObjectStore cannot use thread locks in any portion of ObjectStore.
Caution
If you set OS_COLL_THREAD_LOCKS to 0, and you cannot guarantee that only one thread at a time executes within collections code, you must enforce thread safety in some other way. If you do not enforce thread safety, and a multithreaded ObjectStore application has more than one thread executing within an ObjectStore collections entry point or the fault handler, then corruption of your nonpersistent data, ObjectStore's nonpersistent data, or persistent data can occur. The corruption might or might not be detected when it occurs. Program failure can result.
An application cannot repeatedly enable and disable thread locks. Use the default, or establish the desired state before calling objectstore::initialize.
OS_COMMSEG_DIR
Default:
/tmp/ostore
Pathname of the directory used for the communications segment. ObjectStore automatically places the commseg in the /tmp/ostore directory. If the UNIX file system containing /tmp/ostore is very small, it might be desirable to locate the communication segment elsewhere.
ObjectStore places the commseg in the specified directory and assigns a unique file name to avoid conflicts between multiple processes that are all running ObjectStore and using the same OS_COMMSEG_DIR setting.
Commseg and cache files should be in the same directory. See OS_CACHE_DIR for related information.
This directory should not be an NFS mount point because this can result in slower client performance and can create potential problems with memory mapping over NFS.
Windows and OS/2
The operating system determines the location of the commseg in shared memory. You cannot change the location.
OS_COMMSEG_RESERVED_SIZE
Default: 8 MB
Specifies the maximum size, in bytes, to which the commseg (communications segment) can grow. If you set the maximum size to something less than the initial size, OS_COMMSEG_SIZE, ObjectStore automatically increases the reserved size to equal the initial size.
If necessary, ObjectStore rounds down the number you specify to a page-size boundary, that is, a multiple of the page size.
In previous releases, this variable was specified as OS_COMMSEG_MAX_LENGTH. This name is no longer accepted.
OS_COMMSEG_SIZE
Default:
approx. 262,144 bytes,
varies by platform and
OS_CACHE_SIZE
setting
Specifies, in bytes, the initial size of the communications segment (commseg). You must specify an integer that is a multiple of the page size.
The commseg is a preallocated region that holds ObjectStore internal data (global data, cache indexing info, and data that describes databases and segments used by the application).
The size of the commseg depends on the size of the cache file. Modify the size of the cache file as needed and ObjectStore adjusts the size of the commseg. The basic formula for commseg size requirements, roughly, is that you need
For example, for 15,000 segments, assuming an 8 MB cache, which is 2048 four-kilobyte pages, you can expect to need about 12732840 bytes (12.7 MB) of commseg.
Specifying a value below the minimum size needed to store required structures in the communications segment has no effect.
If necessary, ObjectStore rounds down the number you specify to a page-size boundary, that is, a multiple of the page size.
An application can set its own commseg size with the API function objectstore::set_commseg_size.
OS_COMMSEG_START
Default: 0
Allows you to control the address of the commseg (communications segment). Normally, you do not need to set this variable; ObjectStore picks an address automatically.
If necessary, ObjectStore rounds down the number you specify to a page-size boundary, that is, a multiple of the page size.
OS_COMP_SCHEMA_CHANGE_ACTION
Default: error
Controls the severity of the error resulting from a type mismatch during library and compilation schema generation. You can set it to
OS_DEBUG_C0000005
Default: false
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. To set this variable, specify any nonnull value except 0 to turn this variable on.
OS_DEBUG_LOCATOR_FILE
Default: 0
Instructs ObjectStore to send diagnostic information about the processing of the locator file to stderr.
When set to 0, the default, no information is provided.
When set to 1, ObjectStore generates a report every time the locator file is searched. This allows you to determine exactly what the input to the search is, which in turn lets you diagnose why the locator file is not providing the expected results.
If your application is a Windows GUI application, see OS_STDOUT_FILE.
OS_DEBUG_RECURSIVE_EXCEPTION
Default: false
On Windows only, when this is set, recursive exceptions are not handled by ObjectStore, so they can be debugged in a debugger.
OS_DEF_BREAK_ACTION
Default: false
Allows you to set a break point that obtains a stack trace before the stack is unwound. When you set this variable to 1, ObjectStore reaches a hardcoded break point immediately before an exception is signaled. This is useful when your application exits with an unhandled TIX exception and works with Visual C++'s just-in-time debugging. Setting OS_DEF_BREAK_ACTION also hits a breakpoint if ObjectStore's internal abort routine is called.
This environment variable cannot be used for systems running Windows NT on the Digital Alpha architecture.
OS_DEF_EXCEPT_ACTION
Default: not set
Controls what happens if an unhandled exception is signaled; this is useful in debugging unhandled exceptions. You can specify the following values:
OS_DEF_MESSAGE_ACTION
Default:
not set
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.
OS_DIRMAN_HOST
Default: not set
Specifies a rawfs host name that ObjectStore places at the beginning of every pathname that does not already begin with the host:: rawfs prefix. This variable provides a convenient way to toggle between rawfs and native file systems.
The only exception is for paths that start with ::. In other words, when you set OS_DIRMAN_HOST, every path, except a path starting with ::, is a rawfs database pathname. For example, if you specify twinkie for OS_DIRMAN_HOST and you specify snoball:/myfile for a pathname, ObjectStore treats it as though you had specified
twinkie::/myfile
However, if you specify ::/myfile, ::blah or ::../../foo as the pathname, ObjectStore treats it as a file database on the local host. When OS_DIRMAN_HOST is set, this is the only way you can specify a file database.
If OS_DIRMAN_HOST is set, and OS_DIRMAN_USE_SERVER_PREFIX is set to Yes, ObjectStore builds the path using the value specified for OS_DIRMAN_HOST. If the result is a::b:c, ObjectStore interprets it as b::c. The OS_DIRMAN_USE_SERVER_PREFIX variable allows compatibility with previous ObjectStore releases. See OS_DIRMAN_USE_SERVER_PREFIX.
If you use only native file systems, do not set this variable; its use can cause difficulty in finding your databases or Server.
OS_DIRMAN_LINK_HOST
Default: not set
For use in resolving by-ID cross-database references, which have been obsolete since Release 1. Set the variable to the name of a Release 5 Server host to enable that Server as the clearinghouse for such references. The host must have a Release 5 rawfs with a directory called /.ODI_compatibility_links. In this directory there must be a link (possibly cross-server) to the actual database. Each link has a name of the form x_y_z, where x, y, z are the three words of the database ID, in hexadecimal, padded out to eight characters with leading zeros.
OS_DIRMAN_USE_SERVER_PREFIX
Default: false
Specifies an alternate interpretation of rawfs pathnames. Release 3 Directory Manager pathnames were allowed to have the form
a::b:/foo
In Release 4, ObjectStore interprets such names as
a::/foo
If this is not what you want, you can set the environment variable OS_DIRMAN_USE_SERVER_PREFIX. When this variable is set, ObjectStore interprets a::b:/foo as b::/foo.
When OS_DIRMAN_HOST is set and OS_DIRMAN_USE_SERVER_PREFIX is set, ObjectStore applies the setting of OS_DIRMAN_HOST first, and then applies OS_DIRMAN_USE_SERVER_PREFIX.
OS_DISABLE_PRE2_QUERY_SYNTAX_SUPPORT
Default: false
Intended for use with the ObjectStore C++ API. When set, causes the query translator to treat all uses of [ and ] found in query expression strings as array subscripting operations. Any setting of the environment variable is ignored if the application calls
os_coll_query::set_disable_pre2_query_syntax_support()
The use of [ and ] as the query element selection operator is discouraged. The use of [%% and %%] is preferred. In a future release of ObjectStore, support for [ and ] as the query element selection operator will be dropped. After you convert your sources to use the preferred form of the operator, set this variable to any nonnull value except 0.
OS_DISPLAY_INSTALL_MISMATCHES
Default: false
Displays to stdout any mismatches found during MOP dynamic type installation. When this variable is not set, the only indication of failure is that an exception is raised. To set this variable, specify any nonnull value except 0.
If your application is a Windows GUI application, see OS_STDOUT_FILE.
OS_ENABLE_PRE2_QUERY_SYNTAX_WARNINGS
Default: - (for stderr)
For use with the ObjectStore C++ API. When set to a nonnull string, enables warnings from the C++ API query translator about the use of obsolete query syntax for nested element selection [( and )]. The string should name the file to which the warnings should be written. Any setting of this variable is ignored if the application calls os_coll_query::set_enable_pre2_query_syntax_warnings().
OS_ENABLE_REALTIME_COUNTERS
Default: false
Turns on the collection and display of timing statistics that measure ObjectStore performance. ObjectStore displays values of real-time counters that help show where time is being spent. To set this variable, specify any nonnull value except 0.
OS_EVICT_IN_ABORT
Default: false
Instructs ObjectStore to evict rather than relocate locked pages during an abort. This results in improved abort performance if relocation optimization is not in effect. The tradeoff is that pages must be fetched for subsequent operations. Specify any nonnull value except 0.
OS_FORCE_DEFERRED_ASSIGNMENT
Default:false
When set to a nonzero value, causes all segments that are in enhanced format to use deferred assignment. If a segment uses deferred assignment, it cannot benefit from relocation optimization.
OS_FORCE_STANDARD_PRM_FORMAT
Default: false
When set to a nonzero value, causes all new databases to be created with the standard (old) PRM format. The standard format is necessary to ensure compatibility of cross-database pointers for applications that use databases created with ObjectStore prior to Release 5.0 and whose PRM format has not been upgraded with osupgrm.
See ObjectStore Installation and License for Solaris and the ObjectStore C++ Interface Release Notes for further information.
OS_FORCE_HANDLE_TRANS
OS_HANDLE_TRANS
Default: false
Controls what ObjectStore does if there is a memory fault on an address that is not in the persistent storage region of address space, for example, if you happen to dereference a null pointer.
When you set OS_FORCE_HANDLE_TRANS to any nonnull value except 0 (or objectstore::set_handle_transient_faults is called with the true argument) ObjectStore signals the appropriate exception: err_null_pointer or err_deref_transient_pointer. This causes dereferences to illegal non-ObjectStore addresses to signal a TIX exception and display a message, and lets you get a stack trace.
When you set OS_HANDLE_TRANS, ObjectStore runs the SIGSEGV handler that was in force before ObjectStore was fully initialized. If there is no such handler, ObjectStore signals the appropriate exception.
If neither of these variables is set, ObjectStore runs the SIGSEGV handler that was in force before ObjectStore was fully initialized. If there is no such handler, ObjectStore returns the signal to the operating system to handle. The operating system performs the usual actions for SIGSEGVs, for example, dumping core or some other action that depends on other environment variable settings.
If you do not set up your own SIGSEGV handler before ObjectStore is initialized, the error message is Segmentation Violation: Core Dumped. If both variables are set, OS_FORCE_HANDLE_TRANS has precedence.
OS/2 implements a subset of this feature. OS/2 ignores the value of OS_FORCE_HANDLE_TRANS. When you set OS_HANDLE_TRANS, ObjectStore signals the appropriate exception: err_null_pointer or err_deref_transient_pointer. This causes dereferences to illegal non-ObjectStore addresses to signal a TIX exception and display a message, and lets you obtain a stack trace. OS/2 never runs the previous SIGSEGV handler if OS_HANDLE_TRANS is set. If you do not set up your own SIGSEGV handler before ObjectStore is initialized, the error message is SYS3175: Access Violation.
OS_IGNORE_LOCATOR_FILE
Default: false
Indicates that no locator file is associated with any application on the client. This overrides all other settings and function calls, including the existence of $OS_ROOTDIR/etc/locator. Specify any nonnull value except 0 to set this variable. Set this variable to 0 to allow locator files (this is the default).
When this variable is set to a nonnull nonzero value, locator files are not used but a small part of the locator file logic in the client is still executed. Consequently, if you have locator file debugging enabled, you still receive some diagnostic information. See OS_DEBUG_LOCATOR_FILE.
For information about the locator file, see Description of the Locator File.
OS_INBOUND_RELOPT_THRESH
Default: half the size of the persistent storage region
For databases that use enhanced-format PRM segments, sets the amount of process address space that can be used for immediate assignments. Values should be set in byte units.
If process address space already exceeds the threshold set, only immediate assignments that do not further increase process address space are allowed.
The default value is half the size of the persistent storage region. The PSR is controlled with OS_AS_SIZE, described in OS_AS_SIZE.
OS_INC_SCHEMA_INSTALLATION
Default: false
When set, ObjectStore creates new databases in incremental schema installation mode. This means that ObjectStore adds types to the database schema as they are needed. When this variable is not set, ObjectStore creates new databases in batch schema installation mode. This means that when ObjectStore creates a database, it creates a database schema that includes all types that might be allocated in the database.
To set this variable, specify any nonnull value except 0.
An application performs incremental rather than batch schema installation if either of these conditions is true:
You can override the effect of this environment variable for a particular process by using objectstore::set_incremental_schema_installation(). See the ObjectStore C++ API Reference. For a discussion of the issues involved, see the ObjectStore C++ API User Guide.
OS_INHIBIT_TIX_HANDLE
Default: not set
Specifies an error message substring for which exception handling is to be disabled.
Many end-user applications have omnibus error handlers to catch all errors being signaled and present them in an easily readable format to the user. This sometimes makes debugging difficult, because the backtrace information has disappeared. When you specify a substring to OS_INHIBIT_TIX_HANDLE, if the substring appears in the formatted error message, exception handling is disabled for the specific error. You can then generate an unhandled exception dump for analysis, or view the backtrace in a debugger.
Specify all to disable all handling.
OS_LANG_OVERRIDE
Default: not set
OS_LANG_OVERRIDE changes the behavior of ObjectStore without affecting other applications that depend on LANG.
LANG is a public environment variable that controls the selection of the message catalog sets appropriate for the specific language locale. It is also used internally to identify the character encoding used, and thus affects the processing of strings. This variable might already be set by your system manager.
Because the LANG variable is public, Object Design supplies another variable, OS_LANG_OVERRIDE, that takes precedence over LANG. The result is that anywhere ObjectStore uses catalogs, OS_LANG_OVERRIDE can change the catalog path construction as well as the way strings are processed. OS_LANG_OVERRIDE also affects .msg file path construction for Object Design scripts such as osinstal and osconfig on platforms that use them.
There is a possibility that the value of LANG is not one of the variables shown in the following table. If the value set is not one of those listed in the table, English is assumed unless OS_LANG_OVERRIDE is set to one of the values in the table.
The values recognized by ObjectStore appear in the following table.
OS_LIBDIR
Default: OS_ROOTDIR\lib
Specifies the directory that contains schema files distributed with ObjectStore. The directory must be on a machine that has a Server, so you do not receive an error when trying to access the schema files. This is set up by the installation process. The only exception to this is if you have a locator file that is set up to handle remote access to databases and you configure the relevant Server to allow remote access to databases.
If OS_ROOTDIR is on a machine that does not have an ObjectStore Server, you must copy or move the library schema files to a machine that is running a Server. Use this variable to specify the new directory.
OS_LOCATOR_ESCAPE_CHARACTER
Default: $
The default escape character for regular expressions in locator files is $, rather than the usual \. You can specify an escape character explicitly with this environment variable. For information about the locator file, see Description of the Locator File.
OS_LOCATOR_FILE
Default: false
The client environment variable OS_LOCATOR_FILE can be set to any legitimate argument to objectstore::set_locator_file(), with the same meaning. Calls to set_locator_file() override this setting. See the ObjectStore C++ API Reference. See also Description of the Locator File.
OS_LOG_TIX_FORMAT
Default: false
The name of a log file to record all exceptions signaled. This file logs all printf control strings signaled, regardless of whether the exception is handled. This facility is especially useful for debugging two situations: recursive exceptions (common if you get exceptions during message processing), and bad printf strings.
OS_META_SCHEMA_DB
Default: $OS_ROOTDIR/lib/
metaschm.db
Specifies the metaschema database.
The metaschema database, which is shipped with ObjectStore, describes hidden internal types and is needed for operations such as data browsing, schema evolution, database verification, and the Metaobject Protocol (MOP).
The metaschema database must be on the same machine as the Server. The only exception to this is if you have a locator file that is set up to handle remote access to databases and you configure the relevant Server to allow remote access to databases.
Normally, the metaschema database is in $OS_ROOTDIR/lib, but under certain circumstances it might be elsewhere. This can happen when the machine where $OS_ROOTDIR resides does not have a local ObjectStore Server. In this situation, unless you set up a locator file, you must copy the metaschema database to the machine that the Server runs on.
If you move the metaschema database out of $OS_ROOTDIR/lib, be sure to set this variable to the new location so that ObjectStore can find the metaschema database.
OS_NB_LANA_NUM
Default: not set
Specifies the number of the default network protocol. Typically, you set this variable when your system is running more than one protocol. You do this to ensure that ObjectStore uses NetBEUI as its NetBIOS protocol.
On Windows, set OS_NB_LANA_NUM in the system environment so ObjectStore services have access to the proper value.
OS_NETWORK
Specifies the network dynamic link libraries (DLLs) to be loaded and used by all ObjectStore executables. On Windows, the default is
O4NETNSM,O4NETTCP,O4NETBIO
On OS/2, the default is
O4NETNP,O4NETTCP,O4NETSNA,O4NETBIO
You do not normally need to change the default setting. In other words, you do not usually set OS_NETWORK. Possible values for OS_NETWORK are
Possible values
Windows
On Windows, you can also specify
OS/2
On OS/2, you can also specify
In standard operation, ObjectStore automatically detects which networks are present, and OS_NETWORK does not need to be set. However, you can set OS_NETWORK to a comma-delimited list in situations where you want more control over the network used by ObjectStore.
Network list order
The order of the list is important. On Windows, when you set the OS_NETWORK variable, you must almost always specify O4NETNSM as the first network in the list. On OS/2, when you set the OS_NETWORK variable, you must almost always specify O4NETNP as the first network in the list. For local connections, the local network (O4NETNSM for Windows, O4NETNP for OS/2) offers significantly higher performance than any other network.
If you omit the local network, or do not specify it first, starting an ObjectStore application might fail to start the Cache Manager automatically. You must then start the Cache Manager by hand before running the first ObjectStore application. Many other operations can fail if these DLLs are not specified at all or not specified first.
If you specify O4NETBIO, it must always be last. If the NetBIOS network is present, ObjectStore uses it in preference to other networks that might follow it in the list.
When to change
the default
Suppose you originally installed ObjectStore on a system connected to a network. Then you disconnect the system from the network. You must set OS_NETWORK so that it no longer expects to enable network protocols. For example, if your system was previously using TCP and now it is a stand-alone system, you might receive the following error when you try to run ObjectStore:
ObjectStore internal error
connect failed (err_internal)
Set OS_NETWORK to O4NETNSM on Windows or to O4NETNP on OS/2 to prevent the TCP interface from loading and allow the Server to initialize normally.
On OS/2 systems, you might need to change the value of OS_NETWORK if you receive a message like the following when trying to run ObjectStore:
** Network error <err-0033-0705>SNA APPCerror: <maint-0033-0332>
AP_Comm>sub system_not_loaded **
ObjectStore signals an exception when it cannot enable a network protocol that it expects to enable, in this case, SNA networking. Set the OS_NETWORK environment variable to ignore the missing protocol or enable the SNA network.
If you are using TCP/IP on your OS/2 system, do so with a set statement in your config.sys file. For example:
set OS_NETWORK=O4NETNP,O4NETTCP
If you are using NetBIOS on your OS/2 system, the set statement is
set OS_NETWORK=O4NETNP,O4NETBIO
Windows
On Windows, if you have an unsupported TCP/IP stack on your machine, and you experience problems, set OS_NETWORK to O4NETNSM,O4NETBIO so that ObjectStore does not attempt to initialize or use the unsupported network.
OS_NO_MAPPED
Default: true
Instructs ObjectStore not to use mapped communication between the client and the Server. ObjectStore uses mapped communication only if the client and the Server are on the same host and the Server parameter Allow Shared Communications is set. To set this variable, specify any nonnull value except 0.
OS_NOTIFICATION_QUEUE_SIZE
Default: not set
Specifies the maximum number of notifications that can be in a process's notification queue. Notification queues are part of the ObjectStore Cache Manager process. The Cache Manager has a notification queue for each local client.
If an application does not call the set_queue_size() function, then ObjectStore uses the value you specify for OS_NOTIFICATION_QUEUE_SIZE. If an application does not call set_queue_size(), and this environment variable is not set, ObjectStore uses a default value of 50.
The maximum allowable value for this variable is 16383. If you set this variable to a value that is higher, ObjectStore uses 16383 as the value and not the value you set.
The API for setting the maximum length of the notification queue is os_notification::maximum_notification_queue_length().
OS_OSDUMP_APPSCHEMA_PATH
Default:
Allows users to give a different path for osdump.adb.
OS_OSLOAD_APPSCHEMA_PATH
Default:
Allows users to give a different path for osload.adb.
OS_OSSG_CPP
Default:
by platform
Sets the C preprocessor used by ossg. You can set this variable to a nondefault C preprocessor. The following table shows the default preprocessor on each platform.
OS_OUTBOUND_RELOPT_THRESH
Synonymous with OS_RELOPT_THRESH. See OS_RELOPT_THRESH for a description of this environment variable.
OS_PORT_FILE
Default: by platform
The name of a ports file for network services. See Modifying Network Port Settings.
OS_PRINT_CLIENT_COUNTERS
Default: false
Turns on display of counters that provide information about client performance. To set this variable, specify any nonnull value except 0.
OS_RCVBUF_SIZE
Default: 16384 bytes
Sets the default size of the network buffer used by the client to receive data from the Server. For best results, this size should be the same as the Server parameter Preferred Network Send Buffer Size.
See Preferred Network Send Buffer Size for further information.
Note that some applications benefit from an increase in the size of the network buffers used by ObjectStore clients and Servers. You can change the size used by the clients from the default of 16384 bytes by setting the environment variables OS_SNDBUF_SIZE and OS_RCVBUF_SIZE. You can change the size used by the Server by setting the Server parameters, Preferred Network Send Buffer Size and Preferred Network Receive Buffer Size. Usually, you achieve the best performance if OS_SNDBUF_SIZE is the same as Preferred Network Receive Buffer Size and OS_RCVBUF_SIZE is the same as Preferred Network Send Buffer Size.
Depending on the operating system, you might find that large values are rejected, which leads to reduced performance. Object Design recommends that you experiment by doubling the size until performance no longer improves.
OS_RELOPT_THRESH
Defaults:
0x4000000
(64 MB)
0x10000000
(256 MB)
on AIX
The name is short for relocation optimization threshold. Use this variable to specify how much relocation information each segment in a database can store about every other segment in the database, in bytes. ObjectStore uses many criteria to determine whether or not to relocate a page. One factor is whether or not the total amount of pseudoaddress space assigned within the segment's relocation map has exceeded this threshold. If the threshold has been exceeded, ObjectStore suppresses the relocation.
Note that OS_RELOPT_THRESH is used to decide if outbound relocation is allowed. For information on controlling inbound relocation, see osprmgc: Trimming Persistent Relocation Maps.
The most common use of this environment variable is to disable outbound relocation optimization entirely by setting it to 0. You can specify any number of bytes.
Relocation map
Every segment in an ObjectStore database contains a relocation map for the segment. If the database only consists of one segment, this is the relocation map for the entire database. However, if the database contains multiple segments, the relocation map for every segment in the database is stored in every other segment. This is true until the database grows to the size of OS_RELOPT_THRESH. When this occurs, relocation information for external segments is only added when a pointer to an object in another segment is added to the segment.
Performance
When the relocation maps get large and there are a large number of segments in the database, you lose the performance benefits of having the segment relocation map repeated in each segment. In fact, the performance most likely deteriorates.
Setting OS_RELOPT_THRESH to 0 causes the ObjectStore client not to include any relocation information for other segments in the same database that are not being referenced by this segment. When the amount of relocation information becomes large, this saves the database reader the expense of reading in this additional information and also saves the database population program the expense of creating it.
Avoiding large relocation maps
To avoid having large segment relocation maps, you can presize your segments with the os_segment->set_size() function. This limits the need for multiple entries in the relocation map for a segment. When a segment is created it reserves a default amount of persistent address space:
At this point there is only one entry in the relocation map for the segment. Roughly, this entry contains a location and a size. If you enlarge the segment through a persistent new, and the persistent address space above the end of the segment is available, only the size field of the relocation map entry needs to be updated. A new relocation map entry is not required. However, if the persistent address space above the segment at the time of the persistent new is not available and persistent address space looks like this:
Then after the new, persistent address space looks like this:
This forces the need for a new entry in the relocation map for Seg1. In addition, the entry is migrated to all the other segments in the database if the database has not reached the value of OS_RELOPT_THRESH.
Presizing the segment can help avoid this. You can use the ObjectStore utility ossize with the -a and -c options to see how many entries are in the relocation map for each segment of the database. This should help you determine if segment fragmentation is taking place.
Relocation optimization procedure
ObjectStore performs relocation optimization automatically whenever conditions permit. At a minimum, relocation optimization occurs when objectstore::set_check_illegal_pointers is not enabled.
What happens in relocation optimization is that ObjectStore tries to set up the transient address map (the in-use TRM) for a transaction so that all pseudoaddress values stored in a segment (that is, the process-neutral pointer values stored in the database) match up exactly with the process-specific virtual addresses that are used in the current transaction. In other words, inbound pointer relocation can be skipped for any page accessed in that segment because all pointers on any of the segment's pages already have correct address values.
Relocation optimization can result in a noticeable performance improvement, especially when many pages are retained in the client cache and reused in successive transactions.
For relocation optimization to be useful in as many cases as possible, it is important for the persistent relocation maps (PRMs) for each database segment to be as similar as possible. In other words, any two segments that both contain outbound pointers to the same segment should use the same pseudoaddress range to refer to that segment. This way, relocation optimization is effective regardless of the order in which segments are accessed in a transaction.
When relocation optimization is in effect, ObjectStore skips outbound pointer relocation when pages are evicted from the cache or when the current transaction is complete. Normally, it is during outbound pointer relocation that the ObjectStore client adds entries to a segment's PRM. This happens whenever an application updates objects in a segment to point to some other segment for the first time (or to a part of some segment that it never pointed to before).
When relocation optimization is in effect and a segment is modified in a committed transaction, ObjectStore takes the conservative approach of updating the segment's PRM to contain an entry for every entry in the in-use PRM. This includes any segments referenced in the current transaction, as well as any segments reachable from (that is, pointed to by) objects in those segments. The reason for this is that ObjectStore has no record of what changes were made to the segment, after a page in the segment became enabled for write access. It is possible that a pointer to a valid persistent object was copied from any other persistent object that was active in the transaction.
PRM bloat
The effect of this is referred to as PRM bloat. The PRM for a segment is likely to contain entries for segments that are never actually pointed to by that segment. Since address space is reserved for all entries in a PRM (when the segment is first accessed in a transaction), this condition might lead to excessive consumption of address space, especially as databases become large.
ObjectStore uses the environment variable OS_RELOPT_THRESH to put an upper bound on PRM bloat. The way this works is that when the sum of the sizes of all PRM entries in a segment exceeds the value of OS_RELOPT_THRESH, ObjectStore disables relocation optimization, and normal outbound pointer relocation is used to determine when the PRM needs to have new entries added to it.
If you know that a database your application uses is larger than the default value, but less than the maximum size of the persistent storage region, then you might choose to increase the value of OS_RELOPT_THRESH to keep the relocation optimization in force for larger databases.
On the other hand, if an application is trying to conserve address space, it might make more sense to set OS_RELOPT_THRESH to 0 to disable relocation optimization.
OS_REPORT_DLL_LOAD_AND_UNLOAD
Default: true
OS_REPORT_DLL_LOAD_AND_UNLOAD(os_boolean)
Reports that a DLL has been loaded or unloaded.
When os_boolean is true, automatic reporting of DLL loading and unloading is enabled. This is accomplished by calling os_DLL_schema_info::DLL_loaded() and os_DLL_schema_info::DLL_unloaded() from the DLL's initialization and termination functions.
If os_boolean is false, automatic reporting is not enabled and you must write your own code to call os_DLL_schema_info::DLL_loaded() and os_DLL_schema_info::DLL_unloaded() from the DLL's initialization and termination functions. The default is true.
OS_RESERVE_AS
Default: false
There is an optimization to ObjectStore that increases performance, sometimes by a very significant factor. ObjectStore uses this optimization when this environment variable is not set. This means performance is fast but there is potential for confusion. ObjectStore does not use the optimization when this environment variable is set.
This optimization can cause trouble if your own program calls the mmap system call with 0 as the first argument, or if your program calls some subroutine library that does so. If your program does either of these things, you should disable the optimization, either by calling the entry point objectstore::set_reserve_as_mode(os_boolean new_mode), or by setting the environment variable OS_RESERVE_AS to any nonnull value except 0. If you both call the entry point and set OS_RESERVE_AS, the entry point takes precedence.
This variable affects the setting of reserve address space mode. When ObjectStore is in this mode, it always keeps the entire persistent region reserved, from the operating system's point of view, so that any other subsystem in the client process that maps something in and asks the operating system to assign some address space receives address space outside the persistent region.
If reserve address space mode is off, such a request might assign space that is part of ObjectStore's persistent region. This can cause problems because the subsystem appears unable to coexist with ObjectStore.
If reserve address space mode is off, however, operating system calls that manipulate the virtual address space are faster on some platforms.
OS_ROOTDIR
Default: varies
by platform
The top-level directory in the part of the file system hierarchy containing ObjectStore files serves as the prefix of various directory names used in search paths. This environment variable is required to run ObjectStore. You set the value of the variable when you install ObjectStore.
If you change the location of your ObjectStore installation, be sure to change the value specified for OS_ROOTDIR. Not doing so can cause the following message to be displayed:
no handler for exception:
no networks where registered, please verify your ostore network
configuration: <err_0001_0141>
The client tried to find the Server over the network. With an incorrect setting for OS_ROOTDIR, this happens even when the client and the Server are on the same machine.
Defaults
The following table shows the defaults for OS_ROOTDIR.
Windows
If ObjectStore was not installed in C:\OSTORE, you must set OS_ROOTDIR to the location of the directory where ObjectStore was installed. OS_ROOTDIR should be kept in the DOS environment, so that makefiles and DOS utilities can reference it.
OS_SCHEMA_DLL_ID
OS_SCHEMA_DLL_ID(string)
Component schema
For use with component schema, specifies the DLL identifier of the DLL. This macro can be used multiple times, for example, to specify different platform-specific DLL identifiers for different platforms. Do not conditionalize these calls on the platform- you want all the DLL identifiers to be recorded in any database that depends on this DLL.
You must call OS_SCHEMA_DLL_ID at least once in a DLL schema to distinguish it from an application schema.
OS_SCHEMA_INFO_NAME
OS_SCHEMA_INFO_NAME(name)
Use with component schema
For use with component schema, generates a variable extern os_DLL_schema_info name; that i,s the os_DLL_schema_info of this DLL. The default is to generate the schema information with a static name. Call this if you are going to call os_DLL_schema_info::DLL_loaded() yourself, so you can get access to the os_DLL_schema_info.
Use with application schema
This macro also works in an application schema, in which case the type of the variable is os_application_schema_info instead of os_DLL_schema_info.
OS_SCHEMA_KEY_HIGH
OS_SCHEMA_KEY_LOW
Default: 0
OS_SCHEMA_KEY_HIGH specifies the high four bytes of a 64-bit schema key.
OS_SCHEMA_KEY_LOW specifies the low four bytes of a 64-bit schema key.
If you run certain ObjectStore tools and utilities on schema-protected databases, set OS_SCHEMA_KEY_LOW and OS_SCHEMA_KEY_HIGH to specify the schema keys of the databases to be accessed. The tools and utilities for which you must set these variables include
Any ObjectStore application, including an ObjectStore tool or utility, can have a schema key that allows it to access a protected database with a matching key. Normally, you specify a key for an application programmatically. See objectstore::set_current_schema_key() in the ObjectStore C++ API Reference. These environment variables are provided because it is not possible for you to set the schema key of a tool or utility programmatically.
You can, however, build an application that performs the same function as an ObjectStore utility, by calling a member of the class os_dbutil. This application can specify the schema key programmatically.
Deploying applications
If you are deploying an application, you need to know that some ObjectStore tools (such as ossg) cannot be invoked from the ObjectStore API. To allow your customers to use such a tool on a database that you have protected, build an application that spawns the tool as a child process. Specify the key of the child process by setting the environment variables from within the application.
These environment variables determine an application's schema key when an ObjectStore application attempts to access data in a schema-protected database, and either one of the following is true:
Keep in mind that when the environment variables determine an application's schema key, all schema-protected databases that the application accesses must have the same schema key.
If you run an application on a schema-protected database, and the application does not have a schema key, or the application's schema key does not match the database's schema key, ObjectStore signals err_schema_key and issues an error message like the following:
Error using schema keys
<err-0025-0151> The schema is protected and the key, if provided, did
not match the one in the schema of database db1.
See also
For information about the schema protection API, see objectstore::set_current_schema_key(), os_database::change_schema_key(), and os_database::freeze_schema_key() in the ObjectStore C++ API Reference.
OS_SECURE_RPC_DOMAIN
Default: not set
Specifies a local domain name. For use with AUTH_DES authentication. If there is no system getdomainname() routine or if it returns null, this variable is consulted for the name of the local domain.
OS_SNDBUF_SIZE
Default: 16384 bytes
Sets the default size of the network buffer used by the client to transmit data to the Server. For best results, this size should be the same as the Server parameter Preferred Network Receive Buffer Size.
See Preferred Network Receive Buffer Size for additional information about the Server network buffer size. See further discussion about these parameters and how they affect performance in OS_RCVBUF_SIZE.
OS_STDOUT_FILE
Default: not
set
Specifies the pathname of a file to which you want to redirect output that ObjectStore would otherwise send to stdout and stderr.
If your application is a Windows GUI and this variable is not set, ObjectStore displays the output in a MessageBox.
To separate the output from several applications, you can set this variable to a pathname such as C:\TEMP\DEBUG.%d. ObjectStore substitutes the process ID in place of the %d.
OS_SUPPRESS_PRE2_QUERY_SYNTAX_WARNINGS
Default: false
Suppresses warnings when an application contains the pre-Release 2 element selection operator []. To set this variable, specify any nonnull value except 0.
OS_THREAD_LOCKS
Default: true
Determines whether ObjectStore uses a lock to ensure that only one thread at a time can execute within ObjectStore code other than collections code.
When this variable is true (set to a value other than 0), ObjectStore uses the thread lock. This is the default.
If OS_THREAD_LOCKS is not set, you cannot enable OS_COLL_THREAD_LOCKS (see OS_COLL_THREAD_LOCKS). In other words, when OS_THREAD_LOCKS is set to 0, ObjectStore cannot use thread locks in any portion of ObjectStore.
OS_TIX_BUFFER_SIZE
Default: 8192
Specifies the size in bytes of the error report buffer. The default size is large enough for all reasonable and expected errors. However, if an error message is extremely long, it might overflow the buffer and cause the application to abort. If this happens, you can resolve the problem by setting this variable to a larger value.
OS_TIX_WD
Defaul:none:
Specifies the working directory for ObjectStore when an unhandled TIX exception causes ObjectStore to create a core dump. (Whether or not there is a core dump depends on the platform and on the setting of the OS_DEF_EXCEPT_ACTION environment variable.)
When you specify a directory for OS_TIX_WD, ObjectStore sets that directory to be the working directory before it creates the core file.
This is particularly useful for ObjectStore daemons. For example, on UNIX systems the Cache Manager always runs with its working directory set to the root directory. This avoids administration problems such as preventing volumes from being unmounted. Set the OS_TIX_WD variable to control where ObjectStore puts core dumps of the Cache Manager daemon.
OS_TMPDIR
Default: not
set
Specifies a directory in which to place temporary files. If you do not set OS_TMPDIR, ObjectStore uses the path returned by the Win32 API GetTempPath(). To set this variable, specify any nonnull value except 0.
OS_TRACE_MISSING_VTBLS
Default: false
Causes a run-time debugging message to be printed to stderr when a missing vtbl handler is installed for a class. The message identifies the class with the missing vtbl handler. For example:
Installing missing vtbl: Class: CCC Name: NNN Symbol: SSS
When you are missing a vtbl, the err_missing_vtbl run-time error message does not indicate the vtbl that is missing. If you rerun the application with OS_TRACE_MISSING_VTBLS turned on, ObjectStore catalogs vtbls that
When you are debugging problems with missing vtbls, this helps determine which classes need vtbls. Any nonempty value except 0 enables the debugging message.
OS_TURN_ON_ENGLISH_MESSAGES
When set to 1, forces the printing of English messages along with the catalog-retrieved language-specific message.
[previous] [next]
Copyright © 1997 Object Design, Inc. All rights
reserved.
Updated: 03/26/98 20:20:49