Default:/tmp/ostore
This chapter describes the ObjectStore client environment variables.
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 value, 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.
<err-0001-0040>The value of variable_name, bad_value, is not a valid integer. (err-misc)
A true setting for an environment variable is anything nonempty or 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:
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 cluster is smaller than OS_AS_SIZE, the largest object you can store is limited to the maximum cluster size. (Allocation is limited to a single cluster.)
Caution
An incorrect value for OS_AS_SIZE or OS_AS_START can cause failures. Be absolutely certain that you understand the way addresses are assigned on your platform before you modify these values. OS_AS_START
Default:
Sets the address of the beginning of the persistent storage region of the process's address space. Specify values in numbers of bytes in decimal values that are 0x10000 aligned (64 KB). Typically, you do not supply a value for this variable. Default values vary by platform, as shown in the table under the heading "Platform".
by platform
Individual platforms impose further constraints on the values that are legal.
Windows NT
On Windows NT, 2 GB is the maximum user-mode address space. Your program, its data, and ObjectStore's address space must fit in 2 GB. A user program on Windows NT uses the bottom 2 GB of address space. DLLs and the like use up space at 0x10000000; stacks use up space at 0x7fxxxxxx. Consequently, there are only 1.75 GB 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 use only 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. SPARCcenter 2000
Up to 1.8 GB can be allocated in a single mmap call. OS_AUTH
Overrides the authentication search protocol (see Authentication Required). The format for specifying this variable is OS_AUTH=type or OS_AUTH=host:type, where type is one of the values listed in the table below and host is the name of the server.
The valid types that OS_AUTH can be assigned are as follows:
You can also use a semicolon-separated list of authentication types to specify authentication types for various hosts. This list can include one default value. See examples following the next paragraph.
Examples
OS_AUTH=server1:DES;SYSInstructs the client to use SYS authentication for all Servers except server1. When connecting to server1, the client uses DES authentication if server1 supports it. If server1 does not support DES or SYS, an authentication method is selected from the list of authentication types that the Server supports.
OS_AUTH=NONEInstructs the client to use no authorization. If a server does not support the NONE type, an authentication method is selected from the list of authentication types the Server supports.
OS_AUTH=server1:NPInstructs the client to use Name Password authentication when connecting to server1. For any other Server, an authentication method is selected from the list of authentication types that Server supports.
The following example sets the display format of all int types to hexadecimal, all float types to four-digit precision, and all ulong types to hexadecimal.
OS_BROWSER_NUMERIC_ FORMAT="int=%x,float=%.4f,ulong=%x"
Default: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; this can result in slower client performance and in potential problems with memory mapping over NFS.
Windows
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. OS_CMGR_STARTUP_LOCK
Specifies an alternative location for the Cache Manager start-up lock file.
Default:
varies
by platform
| Solaris 2 | /var/tmp/cmgr6_startup_lock |
| Other systems (not Windows) | /tmp/cmgr6_startup_lock |
If a Cache Manager is not already running, a client
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.
Default: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
The operating system determines the location of the commseg in shared memory. You cannot change the location. 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
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 locating access violations in your code. To set this variable, specify any nonnull value except 0 to turn on this variable.
Default: false OS_DEBUG_LOCATOR_FILE
Default: 0
Instructs ObjectStore to send diagnostic information about the processing of the locator file to stderr.
OS_DEBUG_RECURSIVE_EXCEPTION
On Windows only, when this is set, recursive exceptions are not handled by ObjectStore, so they can be debugged in a debugger.
Default: false OS_DEF_BREAK_ACTION
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 hard-coded 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.
Default: false 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
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.
Default: not set OS_DEFAULT_AS_PARTITION_SIZE
Default: not set
Specifies, in bytes, the amount of address spaced assigned to newly created sessions, unless overridden by objectstore::set_default_address_space_partition_size(). The actual amount assigned is the specified amount rounded up to the nearest 64 KB
OS_DISABLE_PROPAGATE_ON_COMMIT
Default: false
Intended for use with ObjectStore/Single, OS_DISABLE_PROPAGATE_ON_COMMIT controls when ObjectStore propagates committed data from the transaction log to a database. By default, this environment variable is false and data is propagated to a database when a top-level transaction commits. If this environment variable is set to true, the data is propagated when a database is closed and when an application ends normally. If an application ends prematurely, some of the data might not have been propagated to the database. This data is propagated the next time the ObjectStore is initialized or on a call to progagate_log().
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.
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_FORCE_HANDLE_TRANS
OS_HANDLE_TRANS
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.
Default: false 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).
For information about the locator file, see Description of the Locator File.
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.
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.
Default: not setLANG is a public environment variable that controls the selection of the message catalog sets appropriate for the specific language locale. It also is 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 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 set up to handle remote access to databases and you configure the relevant Server to allow remote access to databases. 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 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/
Specifies the metaschema database.
metaschm.db OS_NETWORK
Specifies the network dynamic link libraries (DLLs) to be loaded and used by all ObjectStore executables. The default is
O6NETNSM,O6NETTCPNormally, you need not change the default setting. In other words, you do not usually set OS_NETWORK. Possible values for OS_NETWORK are
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 manually before running the first ObjectStore application. Many other operations can fail if these DLLs are not specified at all or are not specified first.
ObjectStore internal error connect failed (err_internal)Set OS_NETWORK to O6NETNSM on Windows to prevent the TCP interface from loading and allow the Server to initialize normally.
On Windows, if you have an unsupported TCP/IP stack on your machine and you experience problems, set OS_NETWORK to O6NETNSM so that ObjectStore does not attempt to initialize or use the unsupported network.
Default: true
If an application does not call the set_queue_size() function, 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 higher value, ObjectStore uses 16383 as the value, rather than the value you set.
The API for setting the maximum length of the notification queue is os_notification::maximum_notification_queue_length().
| UNIX | cpp |
| Windows | cl |
OS_PASSWORD
Specifies a password to be used by a client application to connect to an ObjectStore Server, used with the OS_USERNAME environment variable. If the client allows Name Password authentication, the client connects to the Server without prompting for a username and password. 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_RESERVE_AS
An optimization to ObjectStore increases performance, sometimes by a very significant factor. ObjectStore uses this optimization when this environment variable is not set. This means that performance is fast but that there is potential for confusion. ObjectStore does not use the optimization when this environment variable is set.
Default: false OS_ROOTDIR
Default: varies
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.
by platform
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 Server are on the same machine.
| Platform | Default for OS_ROOTDIR |
|---|---|
| Solaris 2 | /opt/ODI/OS6.0 |
| UNIX (except Solaris 2) | /usr/local/ODI/OS6.0 |
| Windows | The parent of the directory containing the O6LOW.DLL that is executing |
Windows
If ObjectStore was not installed in C:\OSTORE, you must set OS_ROOTDIR to the location of the directory in which ObjectStore was installed. OS_ROOTDIR should be kept in the DOS environment, so that makefiles and DOS utilities can reference it. OS_SCHEMA_KEY_HIGH
OS_SCHEMA_KEY_LOW
Default: 0
OS_SCHEMA_KEY_HIGH specifies the high 4 bytes of a 64-bit schema key.
You can, however, build an application that performs the same function as an ObjectStore utility by calling a member of the class os_dbutil, os_compact, or os_schema_evolution. This application can specify the schema key programmatically.
These environment variables determine an application's schema key when an ObjectStore application attempts to access data in a schema-protected database and either of the following is true:
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 such as 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 Preferred Network Receive Buffer Size for additional information about the Server network buffer size. See further discussion about these parameters and the ways they affect performance in OS_RCVBUF_SIZE.
OS_STDOUT_FILE
Specifies the pathname of a file to which you want to redirect output that ObjectStore would otherwise send to stdout and stderr.
Default: not set 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. OS_TIX_BUFFER_SIZE
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.
Default: 8192 OS_TIX_WD
Specifies the working directory for ObjectStore when an unhandled TIX exception causes ObjectStore to create a core dump. (Whether there is a core dump depends on the platform and on the setting of the OS_DEF_EXCEPT_ACTION environment variable.)
Default: none OS_TMPDIR
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.
Default: not set 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
Updated: 03/11/99 11:18:50