Managing ObjectStore

Chapter 8 Managing ObjectStore on Windows

This chapter provides information for managing ObjectStore on Windows NT and Windows 98. For complete information, you should consult the first six chapters of this book along with this chapter.

The topics covered include the following:

Using ObjectStore Utilities

During installation, you use the ObjectStore Setup Utility (setup.exe) to configure ObjectStore daemons and applications - the Server, Cache Manager, Database Manager, and Browser.

All utility executables are stored in ObjectStore's BIN directory.

Memory Requirements for Windows 98

Object Design recommends a minimum of 16 MB memory on Windows 98 systems. The ObjectStore Server is tuned for high performance on network servers. Because of this, it sometimes does not run efficiently on systems with less than 16 MB physical memory. If you use less than 16 MB physical memory, read this section carefully to ensure that your system can run ObjectStore properly. The information here applies to Server-only and client-only installations. The goal is to minimize memory consumption.

Performance

With less than 16 MB physical memory, ObjectStore's performance might be degraded and, in some cases, Windows 98 itself might be unreliable.

Unsupported configuration

You should never run a network server on Windows 98 with less than 16 MB physical memory; Object Design does not support this configuration. Stand-alone systems with less than 16 MB physical memory require careful tuning to achieve adequate performance and efficient resource consumption.

Run only ObjectStore clients

Generally, systems that run only ObjectStore clients have the fewest problems with memory consumption.

Virtual memory requirements

The sum of your physical memory and the swap file size must be at least 24 MB. For example, if you have 8 MB physical memory, your swap file must be at least 16 MB. In all cases, Object Design recommends a minimum 8 MB swap file. Set up the Windows 98 swap file in the Control Panel System icon.

Modifying Server parameters

When running an ObjectStore Server on a stand-alone system with less than 16 MB physical memory, you can reduce the Server's memory consumption by setting the Server parameters indicated in the following table. You must restart the Server for the new parameter settings to take effect.


Parameter	Setting
Log Record Segment Buffer Size	256 sectors (default is 1024)
Max Data Propagation Per Propagate	256 sectors (default is 256)
Propagation Buffer Size	512 sectors (default is 8192)

Modifying client environment variables

You can reduce memory consumption by setting the OS_CACHE_SIZE environment variable to an amount less than its default size of 8 MB (8388608). The minimum size on Windows 98 is 480 KB (491520). Generally, on systems with 12 MB physical memory, 3 MB (3145728) is a good value. Some applications that access large amounts of data simultaneously might require larger values.

The client cache is filled only as persistent data is actually allocated or referenced. If your application references only a small amount of persistent data, reducing OS_CACHE_SIZE will probably have little or no effect.

Reducing OS_AS_SIZE to conserve memory generally is not worthwhile.

Specifying File Database Pathnames

You specify a file database with an operating system pathname. For example:

os_database::open("d:\\carter\\myfiledb")

UNC pathname

The syntax for specifying a UNC pathname is

os_database::open("\\\\servername\\sharename\\myfiledb")

In C++, you must escape the back slash (\) with another back slash.

You can also specify a relative pathname.

Server-remote databases

You usually store a file database on a host that is running an ObjectStore Server. However, you can use a locator file to allow databases that are remote from the Server. See Chapter 5, Using Locator Files to Set Up Server-Remote Databases.

Server names

You can specify a Server name when you open or create a database. The Server name identifies the Server host on which the database is located. For example:


Server on a UNIX host:	elvis:/usr/barbar/employees
Server on a Windows host:	elvis:D:\usr\barbar\employees

This specifies a database, employees, in the directory \usr\barbar on the host elvis.

This method of specifying a pathname is called Server-relative. The token before the first colon names a Server host and the rest of the string is parsed by that Server in the syntax used on the Server host operating system. Among other things, this is useful when no remote file protocol (such as NFS) is in use between the client and Server hosts.

Setting Server Parameters

The Server, Cache Manager, and Browser store their parameters in a central location.

Each Server parameter that you can specify is described in Chapter 2, Server Parameters.

Windows

On Windows NT and Windows 98, parameters are stored in the Windows registry database.

Changing parameters

You can edit these parameters using the ObjectStore utility setup.exe. To set Server parameters, run setup.exe, select Advanced Options, then select Server Parameters. The ObjectStore installation guide contains additional information about using setup.exe.

After you modify a Server parameter, you must shut down and restart the Server for the parameter to take effect.

Starting the Server

There are several ways to start the Server. One way is to use the ObjectStore setup utility, setup.exe, to configure the Server to start automatically at system start-up.

Windows NT

On Windows NT, you can configure the Server as an NT service. This is the preferred method.

When starting the Server as an NT service, you can specify osserver command-line options in the following table in the NT service administration dialog.

On Windows NT, you can run the Server as an NT console application. In this case, you run OSSERVER.EXE from an NT command window, passing -console as the first argument.

At start-up, ObjectStore configures the Server according to parameter options in the registry database.

Windows 98

On Windows 98, you can start the Server manually by using Start | Run or from an MS-DOS prompt window.

Command-line options

Ordinarily, you use Server parameters to control the Server's behavior. However, you can also specify the following command-line options to osserver.


-c	Checkpoint. Forces all data to be propagated from the log to the database. The Server does not start after this checkpoint.
-con or -console	Windows NT only: runs the Server as a console-mode application. If you specify this option, it must be the first option you specify.
-d int	Starts the Server in debug mode. Specify an integer from 1 through 9. The larger the number, the more information ObjectStore provides. If the ObjectStore Server Service is running, you must stop it and restart it. Use the Services applet in the Control Panel. Another alternative is to stop the ObjectStore Server Service. You can then specify the -con option so that ObjectStore displays the information on the screen. Debug output goes to %OS_TMPDIR%\osserver.txt. Note that you can use the ossvrdebug utility to turn debug mode on and off without shutting down the Server. For more information, see ossvrdebug: Setting a Server Debug Trace Level.
-i	Initializes the Server log file and the rawfs, if you have one, with a confirmation prompt. Use with caution.
-I	(Uppercase I) Initializes the Server log file and the rawfs, if you have one, without a confirmation prompt. Use with extreme caution.
-v	Displays Server parameter values at start-up.

Use -i and -I with caution

Be sure to move all data out of the log before you initialize it. See ossvrchkpt: Moving Data Out of the Server Transaction Log. Be sure to back up all data in the rawfs before you initialize it. See osbackup: Backing Up Databases.

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

If you have a rawfs, specifying the -i or -I option with osserver initializes the rawfs and the transaction log. When you specify -i, ObjectStore responds with

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?

When you specify -I, this message does not appear.

Initializing when you do not have a rawfs

If you do not have a rawfs, specifying the -i or -I option with osserver initializes only the transaction log. When you specify -i, ObjectStore responds with

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?

When you specify -I, this message does not appear.

Start-up message

After starting, the Server displays the message Server started to let you know that it is ready to accept requests from clients on the network.

Troubleshooting Windows NT

You might have a situation in which you cannot run the Server and the Cache Manager as NT Services, even after defining autostart for them. You receive the following error:

Starting process
Process could not start
error 1067: Process terminated unexpectedly

The first thing to assess is whether the Server and Cache Manager can be started in console mode using the -con option to osserver. If they start properly in console mode, this problem is likely to be a permission problem or an incorrect definition for the ObjectStore image path in the registry.

Try the following to determine what is wrong with the ObjectStore definition of NT Services:

If you ran an earlier ObjectStore release, confirm that it was properly uninstalled before installing the new release. This is necessary so that the image path is properly set for the NT Services.
Ensure that ObjectStore was installed using an account with Administrative privileges.
To run the Server and Cache Manager as NT Services, you must log on with Administrative privileges.
Confirm that the OS_ROOTDIR environment variable is set and that it points to the proper ObjectStore installation.
Make sure that the image path for the Server and Cache Manager is correct. To check this, run Regedt32 from a window and follow the path
```
      HKEY_LOCAL_MACHINE | System | CurrentControlSet | Services

      | ObjectStore Cache Manager R6.0
```
Then verify that the setting for the image path is correct. Do the same for ObjectStore Server R6.0.
Verify that the user account used to log in includes the log in as a service... privilege.

If the same executables do not bring up ObjectStore properly even in console mode (especially if the Server does not start from the command line using the -con option), it is not a permission problem.

If it is not a permission problem, it is very likely that the transaction log has not been initialized. In this case, a message can be seen in the %OS_TMPDIR%osserver.txt output:

When a partition is not specified, the transaction log is needed.

This is usually the last message in osserver.txt or in the Server start-up output in debug mode. If this is not the case, in the window from where you start the Server, enter

>set OS_DEBUG_NETWORK=1

and

>start /min osserver -con -F -v -d 10 > server.out

>osserver -con -F -v -d 10 > server.out

if the start command is not recognized.

After that, send the server.out file to Object Design Technical Support.

Creating a Rawfs

Maintaining a rawfs provides a fast, convenient way to manage all ObjectStore databases at your site. See Managing the Rawfs. On Windows platforms you can use the following rawfs configurations:

File partitions (Windows NT and Windows 98)
Disk partitions (Windows NT only)
Physical disks (Windows NT only)

If you want to use ObjectStore's high-availability features, you need to configure the rawfs to use either disk partitions or a physical disk. In either of these configurations, you should first create the disk partitions with a disk management utility such as NT's Disk Administrator before specifying them for use by the rawfs.

Using setup.exe to Add Rawfs Partitions

You use the ObjectStore setup.exe utility to create and modify rawfs. Be sure to shut down the Server before you run setup.exe. After you specify Server Parameters, setup.exe provides the opportunity to set up a rawfs. If you are configuring a rawfs to use file partitions, you specify the name and size of the file partition and whether or not it is expandable.

If you are configuring a rawfs to use disk partitions or physical disks, you select the partitions from a list of available partitions.

Modifying Partition Size

Before you modify your rawfs configuration, back up your data, using the osbackup utility. See osbackup: Backing Up Databases.

Controlling expansion

You can control expansion of the rawfs as follows:

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 are used for the rawfs, they can expand dynamically if you have configured the files to be expandable.

For more information about modifying a rawfs, see Reconfiguring the Rawfs.

Starting the Cache Manager

Windows NT

The Cache Manager is an NT Service that is usually configured to start when the system is booted. Alternatively, you can configure it to start automatically when it is needed. Use the Control Panel Services applet to configure the Cache Manager for Manual Start-up.

To start the Cache Manager from your account, you must have domain user listed as one of your privileges. If you do not, you might receive the message

Error auto starting Cache Manager. Unable to open service database. 
Access is denied.

You might receive this message when you log in to your domain account rather than logging directly into the computer name account. If this is the case, you need to ask your system administrator to check your user privileges in that domain or configure the Cache Manager for Automatic Start-up.

If you want to start the Cache Manager as a console application, use the following command:

oscmgr6 -con 0 [debug_level]

Windows 98

On Windows 98, the Cache Manager is started automatically as a Windows Service. If you need to start it manually, use Start | Run | oscmgr6 0 [debug_level].

Finding Files Containing ObjectStore Messages

In some cases, when an ObjectStore daemon process reports an error, ObjectStore routes the output to a file. These files are


Server errors	OSSERVER.TXT
Cache Manager errors	OSCMGR6.TXT

If the file does not already exist, ObjectStore creates it; if the file does exist, ObjectStore appends to it.

ObjectStore uses the path assigned to the environment variable OS_TMPDIR to determine the directory in which to place these files. If OS_TMPDIR is not set, ObjectStore uses the path returned by the Win32 API GetTempPath().

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.

Accessing UNIX Databases from Windows

When accessing UNIX file databases over a network (such as with Intergraph PCNFS), the ObjectStore client on Windows NT prompts for a name and password. See Authentication Required.

If you want the ObjectStore client to use RPC authentication, use the Windows NT REGEDT32 utility, and set the following variables, where x.x is the ObjectStore release number, and username is your username:

HKEY_LOCAL_MACHINE\Software\Object DesignInc.\ObjectStorex.x\Remote\username\UNIX.UID 
HKEY_LOCAL_MACHINE\Software\Object DesignInc.\ObjectStorex.x\Remote\username\UNIX.GID

Set these variables (which are strings, such as REG-SZ) to the numeric values of the UNIX user and group IDs required. Note that you can edit these values only from a Windows NT account with Administrator privileges.

Note that the HKEY_LOCAL_MACHINE\Software\Object Design Inc.\ObjectStore 6.0\Remote has Administrator rights only. This is to prevent a security breach that can result if ordinary users have write privileges to this area. If you set up the values for an ordinary user who does not have Administrator privileges and the user tries to run an ObjectStore program, the user must still enter a user name and password to access the Server.

To prevent this, you can change the HKEY_LOCAL_MACHINE\Software\Object Design Inc.\ObjectStore 6.0\Remote to have read-only privileges for users with non-Administrator privileges. You can set the privileges using the Security | Permissions dialog in the registry editor.

About Client/Server Communication

Windows clients and Servers can use two network layers:

Within a single machine, ObjectStore uses an interprocess communication mechanism based on named shared memory objects.
Windows Sockets provide TCP/IP connections. Object Design tests and supports a limited number of Windows Sockets implementations.

A Server can and typically does serve both networks simultaneously. A client chooses the first network available that recognizes the name of the Server host.

For more information, see Network Support in Installation for Windows.

Using an NT Server to Access Remote Databases

Netware

ObjectStore can be used with the Gateway Services for NetWare (GSNW) feature.

All Remote Hosts

If a Server is configured to allow remote databases, the Server can use UNC paths to access such databases. Using UNC paths is the preferred method because of permissions issues surrounding the use by a service of mounted drives. Server-relative paths such as

      serverhost:\\filehost\sharename\directory\foo.odb

or locator files that redirect all UNC paths to a named server host take advantage of this feature. In general, it is unnecessary to

Mount file host drives on your Server host
Use REPLACE statements in locator files

Use this feature with NT as well as with NetWare file hosts.

Access Control for Remote Databases

Windows NT refuses to allow the Server to use credentials obtained from a remote client host on a remote file host. There are two alternatives for dealing with this issue. They are described in Microsoft Knowledge Base article Q132679, available on the Microsoft TechNet CD or at the Microsoft Web site:

http://www.microsoft.com

The first choice is to run the Server normally, as Local System. This requires that the user Everyone is able to access remote files on behalf of remote clients. Note that this solution requires you to create an account for Everyone on non-Windows NT systems.

The second choice is to run the Server as another user. You can set this up by means of the Control Panel Services applet.

[previous]

Updated: 03/11/99 11:21:09