Chapter 4: Directories and Files

•    System files,

•    Executable utilities,

•    Header files,

•    Link libraries,

•    Class libraries for each language interface,

•    Application development tools,

•    At least one database consisting of storage and log volumes, which are files or raw devices,

•    Database files, including the application process profile file and the server process profile file, that set operating parameters.

A database system identifier file must exist and be accessible to your machine before you can create a database.

Normally, the database system identifier file will be on a machine acting as a server and will have already been created by the time you perform an installation.

A VERSANT database system is a group of databases among which you can safely connect and share objects.

Per the object model, when you create an object, it is assigned a unique identifier number (called the "loid"). For objects to be safely shared among databases, this number:

•    Must be unique within a particular system of databases,

•    Can never be reused even if an object is deleted,

•    Can never be changed even when an object is moved.

Because of these properties, this number can be used as a persistent link to an object regardless of its database or memory location.

VERSANT also implements the concept of distributed database network systems in which:

•    Any database in a system can safely interact with any other database in that system,

•    Any database in a system can operate while completely disconnected from all network communications,

•    Any number of databases can belong to a particular network system,

•    Databases in a particular system can be located anywhere in a network,

•    Any number of systems can be created.

To ensure that the logical object identifier for each object is unique among all objects in all databases in a system of databases, VERSANT object identifiers are composed of two parts:

•    A unique-within-the-database number, and

•    A unique-among-other-databases number.

A database does not have to communicate with other databases to ensure the uniqueness of the part of the object identifier that is unique within itself: it just needs to keep track of numbers already used.

To assign an object the part of the object identifier that is unique to the database itself, a database does have to communicate with other databases at least once, at the time it is created. Once a database has been created, it can then store its identifier number and no further communication with other databases is necessary to create objects.

So that VERSANT does not have to communicate with all existing databases each time a new database is created, a database system identifier file is used. The name of this file is osc-dbid, and this file contains information about each database in the system that it defines, including its identifier number.

When you create a database, VERSANT finds the osc-dbid file, reads it, assigns the next available identifier number, and updates it with information about the new database. VERSANT also uses the osc-dbid file whenever you remove a database or request information about all databases in the system.

During installation, you will be asked for the machine and path of the osc-dbid file for the database system that you want the new installation to join.

Typically, you will want to place the osc-dbid file not on the local machine but rather in a visible directory on a machine that you designate as a network server, because it must be able to be found by all machines in the network. Only if you have a standalone installation that will never use objects in databases on other machines, you can place the osc-dbid file on your local machine.

If you want your installation to join a system of distributed database, we strongly recommend that you install first on the machine that will act as your database system host, create a database system file at that location, and then specify the machine and path of that file when you install on each client machine. Installing first on the database system host will ensure that when you install on a client machine you know the location of your database system file and do not have to make corrections later.

After a network of databases has been defined, you can move the location of the osc-dbid file. However, this is not recommended, because this would require your going to all machines in the network and revising the VERSANT environment variables and configuration files that point to the old location. See the chapter "Environment Parameters" for further information.

In any case, before you can create a database:

1.  an osc-dbid database system file must exist at a location accessible to your machine, and

2.  the location of the osc-dbid file must have been specified to your machine.

Because the osc-dbid database system identifier file is only used when databases are created, removed, and listed, you can connect to a database even when the node containing the osc-dbid file is down. However, since the osc-dbid file is not read each time you make a database connection, you could conceivably create simultaneous connections to databases belonging to differing database network systems. You must avoid doing this, because databases in differing database network systems could have the same identifier number, and thus there could be objects in the differing systems with the same logical object identifier.

If the osc-dbid database system file for a distributed database network system is destroyed, you must recover the osc-dbid file from a backup before you can create new databases, remove existing databases, or list the databases in that system.

If you have no osc-dbid file backup, recovery procedures are complex. Although you can use the dbid utility to create a new osc-dbid file, creating a new osc-dbid file means that identifiers for new databases will probably duplicate the identifiers for existing databases. This means that you must create a new network of databases, and then create new objects in the new databases that are copies of the old objects (you must be careful not to migrate the old objects). If your osc-dbid file is destroyed, please call VERSANT Customer Support.

The default location for the osc-dbid file on a UNIX installation is the /home directory on the local machine. The default location for the osc-dbid file on a personal computer installation is the database root directory on the local machine.

The following explains what happens after the installation program asks for a path to an osc-dbid database system file:

No path

Because VERSANT does not check for the existence of an osc-dbid file if you specify a remote machine, during installation you do not have to be connected to a network and the first installation of VERSANT does not have to be on the machine that will eventually contain the osc-dbid file.

However, we recommend that the first installation of VERSANT be on the machine that will contain the osc-dbid file in order to reduce the chance of an unintended outcome.

For example, if you specify a remote path to osc-dbid and then later decide on a different path for osc-dbid, then you will not be able to create a database until you manually specify the correct path on each and every installation already made.

Or, if you do not specify a path to osc-dbid at all, there is the danger that before you get a chance to tell the local VERSANT installation about the remote osc-dbid file, you will create a database using the local osc-dbid file, which breaks the object model because unique object identifiers across the system of databases cannot be guaranteed.

Before installation, you can find the machine and path of the database system file by running the oscp system utility of an installation whose database system you want to join.

Or, if VERSANT files are local, you can inspect the local /db/sysinfo system configuration file. If you are using VERSANT files on a remote machine, you can inspect your /etc/.oscxxyyzz machine configuration file. In a configuration file, the machine containing the osc-dbid file will be associated with the entry for VERSANT_DBID_NODE, and the directory will be associated with the entry for VERSANT_DBID.

For example, if osc-dbid is on a machine named server_machine and in the directory /visible_directory, you would see the following entries in a configuration file:

VERSANT_DBID_NODE  server_machine
VERSANT_DBID       /visible_directory

                 software_root
                       |
               release_directory
                       |
              platform_directory
                       |
---------------------------------------------------------
|            |         |           |          |        |
bin          h         lib         install    |        demo
|-compiler   |-cxxcls  |-compiler             |        |-cxx.compiler
|-vhelp                |-compiler.chk         tutorial
|-vdoc                                        |-c
                                              |-cxx.version

During installation, you specify the software root directory, which can be anywhere you want. Once you have specified the software root, all directories are built from it in a way that cannot vary.

The names of the directories in italics depend upon the VERSANT release number, machine, and compiler supported by your installation.

For example, for Release 5.2.0, Sun 4, the default directory structure is:

               /usr/local/versant
                       |
                     5.2.0
                       |
                     sun4
                       |
---------------------------------------------------------
|            |         |           |          |        |
bin          h         lib         install    |        demo
|-sun.3.0    |-cxxcls  |-sun.3.0              |        |-cxx.3.0
|-vhelp                |-sun.3.0.chk          tutorial
|-vdoc                                        |-c
                                              |-cxx.3.0

Following is an explanation of each of these directories.

The software root directory.

All VERSANT directories are built from your choice of root directory made during installation. The default location is:

/usr/local/versant

Although the software root directory can be anywhere and although it can be moved after installation (if you reset appropriate environment parameters), all VERSANT software directories and files must branch in a predetermined manner from the software root directory.

The release directory, whose name depends on the VERSANT release.

For example, for Release 5.2.0 with a default software root directory, the release directory is:

/usr/local/versant/5.2.0

A release directory makes possible installation of multiple releases on the same platform.

The platform directory, whose name depends upon your operating system.

For example, for Release 5.2.0 for Sun 4 with a default software root directory, the platform directory is:

/usr/local/versant/5.2.0/sun4

Directories containing files branch from the platform directory.

The executables directory, which contains command line utilities.

For example, for Release 5.2.0 for Sun 4 with a default software root directory, the bin directory is:

/usr/local/versant/5.2.0/sun4/bin

A directory containing VERSANT executables specific to a compiler, where the name of the compiler directory is specific to the compiler supported by your installation of VERSANT.

For example, for Release 5.2.0, Sun 4, and executables specific to use of SPARCompiler C++ 3.0.1, the compiler directory is:

/usr/local/versant/5.2.0/sun4/bin/sun.3.0

A directory used by the html version of the manuals.

A directory used by the VERSANT Utility Tools program. To start the Utility Tools program, invoke the command vutil in the bin directory.

The system header files directory, which contains system files.

For example, for Release 5.2.0 for Sun 4 with a default software root directory, the h directory is:

/usr/local/versant/5.2.0/sun4/h

The C++ header files directory.

For example, for Release 5.2.0 for Sun 4 with a default software root directory, the cxxcls directory is:

/usr/local/versant/5.2.0/sun4/h/cxxcls

The C++ header files directory contains definitions of the database and library classes that comprise the C++/VERSANT interface.

The system libraries directory.

For example, for Release 5.2.0 for Sun 4 with a default software root directory, the lib directory is:

/usr/local/versant/5.2.0/sun4/lib

The libraries directory contains both system libraries files as well as error message files.

A directory containing C++/VERSANT production libraries, where compiler is specific to your C++ compiler.

For example, for VERSANT 5.2.0, Sun4, SPARCompiler C++ supporting cfront 3.0, and a default software root, the compiler library is:

/usr/local/versant/5.2.0/sun4/lib/sun.3.0

A directory containing the C++/VERSANT debugging libraries, where compiler is specific to your C++ compiler.

For example, for VERSANT 5.2.0, Sun4, SPARCompiler C++ 3.0.1 supporting cfront 3.0, and a default software root, the compiler.chk library is:

/usr/local/versant/5.2.0/sun4/lib/sun.3.0.chk

A directory containing the installation program oinstall.

A directory for the source code for tutorials documented in the reference set for individual interfaces.

Sub-directories are:

/c

A directory for demonstration programs. These programs are not documented, but you may inspect them for examples of using various routines. If you call VERSANT Customer Service with a coding question, a Customer Service Engineer may direct you to a program in this directory.

A directory for demontration programs specific to a compiler.

Following are descriptions of the database root directory, and the directories and files associated with each individual database.

The database root directory.

The database root directory is the root directory for individual database directories created by the database utility makedb.

The database root directory can be either local or remote.

Normally you will create this directory apart from the VERSANT software root directory, as you will probably want to continue to use the databases that you create even after you install a newer version of VERSANT at a later time.

The location of the local database root directory must be specified with the VERSANT_DB location parameter before you can access, create, or remove a database located under that root directory. The location of a remote database root directory must be specified with the VERSANT_DB@node location parameter before you can access, create, or remove a database on a remote machine named node.

In (extremely) unusual circumstances, you might want to create multiple database root directories on the same machine. In such a case, you must specify the location of the root directory you want to use with the VERSANT_DB and/or VERSANT_DB@node location parameters before you can access, create, or remove a database located under that root directory. This practice is not recommended.

The default database root directory is on the local machine under the software root directory. For example, for Release 5.2.0, Sun 4, and a default software root:

/usr/local/versant/5.2.0/sun4/db

A database directory.

Each time you take the first step in creating a database by using the makedb utility, a database directory with the same name as the database will be created under the database root directory. Database directories must branch from a database root directory.

For example, if the database root directory is /usr/local/versant/5.2.0/sun4/db and you create a database named mydb, VERSANT will create the following database directory:

/usr/local/versant/5.2.0/sun4/db/mydb

If a database consists of files, the database directory contains the database volumes for that database.

If you are using files, they may be local or remote. If the database volumes are remote UNIX files, they may be accessed through NFS. However, we strongly discourage you from accessing database files through NFS, because performance will be severely affected.

It is much better to create a database on the host where the file system is physically located and then access it with VERSANT db@host protocol rather than with NFS protocol. This allows a VERSANT server process to directly access the database files.

If you want to use a UNIX raw device for a database volume, make sure that the partition you use does not include cylinder 0 or cylinder 1. When a UNIX partition is used for a raw device, all cylinders allocated to that partition will be used.

See also the chapter "Create a Database."

The database system volume, system, is a file or raw device associated with a database that stores class descriptions and object instances.

There is one system volume for each database. Additional data volumes can be added to a database to increase capacity.

The system volume for a database is created with the createdb utility. If system is a file, it is located in the database directory.

The logical log volume, logical.log, and physical log volume, physical.log, are files or raw devices associated with a database that record transaction activities and provide information for roll back and recovery.

There is one physical.log and one logical.log for each database.

The logical and physical log volumes for a database are created with the createdb utility. If physical.log and logical.log are files, they will expand as needed and be located in the database directory.

The logical log volume, logical.log, and physical log volume, physical.log, are files or raw devices associated with a database that record transaction activities and provide information for roll back and recovery.

There is one physical.log and one logical.log for each database.

The logical and physical log volumes for a database are created with the createdb utility. If physical.log and logical.log are files, they will expand as needed and be located in the database directory.

The application process profile file.

A client application process contains the application, part of the VERSANT Manager software module, a network layer, and an object cache.

When an application starts a session, the operating environment will be set according to the settings in the application process profile file. You can customize the operating environment for an application process by modifying the application process profile. If there is no application process profile file, the system uses defaults.

On UNIX installations, there is one application process profile file per database. When you use either the makedb or makeprofile utilities, VERSANT will check the .osc directory to determine if a file with the same name as the database exists. If an application process profile file exists, VERSANT will not create a new one. If it does not exist, VERSANT will create one.

You can use the makeprofile utility to create several application process profiles, change their names, edit them, and then specify which one you want to use at run time by changing its name to the database name.

In the application process profile are parameters that you can specify either before or after a database has been created. These parameters are read each time a session starts.

Functional parameters in the application process profile file are:

alias

heap_size

This file logs database and system messages and errors.

The database server process profile file.

When a database starts up, the database server process reads the server process profile to determine the location of the database volumes and to set the database operating environment. If a server process profile does not exist for a database, you cannot start that database.

The server process profile file is named profile.be and is located in the directory for the database, which must branch from the database root directory.

The server process profile is created with the makedb utility.

The server process profile contains several kinds of parameters. Some are used only when a database is created, and others are used each time a database is started. See the chapter "Database Profiles" for more information.

The .lock file contains database state information. The .lock file is created when you create a database with the makedb utility. If the lock file is missing, you will not be able to start or recreate the database.

If the .lock file is destroyed for some reason, use the dbinfo utility to create a new one:

1.  Change directory to the appropriate database directory.

2.  Run the dbinfo utility with the following arguments:

The contents of the sharemem file in a database directory are used as a key to get a unique id for the shared memory of the database server process.

The createdb utility creates the .sharemem file. The removedb utility removes the .sharemem file. You should never remove the .sharemem file yourself, because if the .sharemem file is missing, you will not be able to start or recreate the database.

If the .sharemem file is removed, in some cases shared memory used by the database will exist, but the stopdb, startdb, and removedb utilities cannot discover it. Then, when you recreate the database, a sharemem file may have the same memory identifier, which causes problems when you try to start the new database.

If the .sharemem file is removed, do the following:

1.  Remove outstanding shared memory associated with this database using ipcrm.

2.  Change to the database directory.

3.  Create an empty .sharemem file in the database directory with touch.

After creating the empty .sharemem file, you can then start the database with the startdb utility or, if it has been removed with removedb, you can recreate it with the createdb utility.

The contents of the .dbtype file in a database directory indicates the database type, whether personal or group.

The .dbtype file is created when you create a database with the makedb utility.

If the .dbtype file is missing, you will not be able to start or recreate the database. If the .dbtype file is destroyed, create an empty file named .dbtype in the database root directory. The permission bits on the .dbtype file establish the database type: 0600 means a personal database and 0660 indicates a group database.

This file contains the trace log when tracing is turned on. If tracing is not on, this file will contain "error messages." Some of these "error messages" may not really be errors, because they may have been handled at a higher level.

See also the dbtool utility in the chapter "Database Utilities."

The contents of the machine and system information files will vary depending upon the type of installation you perform:

                 contents if oinstall   contents if oinstall -f
file             (local installation)   (files on remote machine)
------------------------------------------------------------------
.oscxxyyzz       software root dir      software root dir
                 database root dir      database root dir
                                        osc-dbid machine
                                        osc-dbid directory
sysinfo          osc-dbid machine        *
                 osc-dbid directory

*  Installing on a local machine with oinstall will create a local sysinfo file with osc-dbid information. If you then install from that machine onto a remote machine using oinstall -f, the remote machine will use the sysinfo file on the local machine and will not create another sysinfo file.

For information on how to use these files, see the chapter "Environment Parameters."

The machine configuration file, where xx is the major release number, yy is the maintenance release number, and zz is the minor release number.

For example, for Release 5.2.0 the machine configuration file is:

/etc/.osc050200

The system information file.

The name of the directory containing the sysinfo file depends upon your installation and choice of software root.

For example, for Release 5.2.0, Sun 4, and a default software root:

/usr/local/versant/5.2.0/sun4/lib/sysinfo

When you install on a local machine, a file named LOGFILE is created in the software root directory. In most cases, VERSANT non-panic system errors are then printed to that file.

When it starts, vstats will read a configuration file in which derived statistics can be pre-defined and named. A system-wide .vstatsrc file in the VERSANT lib directory will always be read. If a file named .vstatsrc exists in your home directory, it will also be read. These files can contain comments beginning with # and commands to define new derived statistics.

Each definition of a derived statistic must appear on a separate line and should have the following syntax:

define stat_name [ args ] = expression

Elements of a definition line are:

stat_name

Statistic names must be specified as shown in the VERSANT Database Fundamentals Manual, except without the STAT_ prefix and transposed to lower case.

For connection and database statistics (those with the prefixes be_ and db_), you must also use a database name since the same statistics may be available for multiple databases. The general syntax is:

'statistic_name database_name'

You can use simple mathematical formulas to combine and modify statistics to produce a derived statistic. For example:

vstats -stats se_reads + se_writes

In these formulas you can use the standard numerical operators +, -, *, /, (, and ). You can also use the following special functions:

delta

define objs_sec = db_objs_sec database1
define o = objs_sec

Once a statistic has been defined, you can use it in vstats commands and options just as if it were a pre-defined VERSANT statistic. Statistics defined in either of the two .vstatsrc files will be listed when the -summary command is invoked.

For example:

define se_hit_ratio = se_locates/(se_locates+se_reads)

define db_hit_ratio db = db_data_bytes_located  db /
(db_data_bytes_located db +db_data_bytes_read db)

define avg3 n1 n2 n3 = (n1+n2+n3)/3

For an overview of statistics collection and stastics collection usage notes, see the VERSANT Database Fundamentals Manual.

                 software_root
                       |
               release_directory
                       |
              platform_directory
                       |
---------------------------------------------------------
|            |         |           |          |        |
bin          h         lib         install    |        demo
             |
             -----------
             |         |
           cxxcls      ilang
             |
             template

During installation, you specify the software root directory, which can be anywhere you want. Once you have specified the software root, all directories are built from it in a way that cannot vary.

The names of the release_directory and platform_directory depend upon the VERSANT Release number and machine.

For example, for Release 5.2.0, OS/2, and the default software root, the directory structure is:

                    versant
                       |
                     5_2_0
                       |
                      os2
                       |
---------------------------------------------------------
|            |         |           |          |        |
bin          h         lib         install    |        demo
             |
             -----------
             |         |
           cxxcls      ilang
             |
             template

Following is an explanation of each of these directories.

The software root directory.

All VERSANT directories are built from your choice of root directory made during installation. The default location is: c:\versant.

Although the software root directory can be anywhere and although it can be moved after installation (if you reset appropriate location parameters), all VERSANT software directories and files must branch in a predetermined manner from the software root directory.

The release directory, whose name depends on the VERSANT release.

For example, for Release 5.2.0 with a default software root directory, the release directory is:

c:\versant\5_2_0

A release directory makes possible installation of multiple releases on the same platform.

The platform directory, whose name depends upon your operating system.

For example, for Release 5.2.0 for OS/2 with a default software root directory, the platform directory is:

c:\versant\5_2_0\os2

Directories containing files branch from the platform directory.

The executables directory, which contains command line utilities.

For example, for Release 5.2.0 for OS/2 with a default software root directory, the bin directory is:

c:\versant\5_2_0\os2\bin

The system header files directory, which contains system files.

For example, for Release 5.2.0 for OS/2 with a default software root directory, the h directory is:

c:\versant\5_2_0\os2\h

The C++ header files directory.

For example, for Release 5.2.0 for OS/2 with a default software root directory, the cxxcls directory is:

c:\versant\5_2_0\os2\h\cxxcls

The C++ templates directory for compilers (such as C Set++) that have native support for templates.

For example, for Release 5.2.0 for OS/2 with a default software root directory, the template directory is:

c:\versant\5_2_0\os2\h\cxxcls\template

The language information directory, which contains files with information about the native language in which you are programming.

For example, for Release 5.2.0 for OS/2 with a default software root directory, the ilang directory is:

c:\versant\5_2_0\os2\h\ilang

The libraries directory.

For example, for Release 5.2.0 for OS/2 with a default software root directory, the lib directory is:

c:\versant\5_2_0\os2\lib

The libraries directory contains both system and C++ libraries files as well as error message files. System library files have the same name for all personal computer releases. The C++ library files have different names for each compiler.

Error message files in this directory are:

error.msg        error.txt       error.msi

System library files in this directory are:

libosc.lib       liboscfe.lib    dllosc.dll
dlloscfe.dll

C++ library files for C Set++ are:

icccls.lib       iccchk.lib      icccls.dll
iccchk.dll

The documentation directory.

For example, for Release 5.2.0 for OS/2 with a default software root directory, the doc directory is:

c:\versant\5_2_0\os2\doc

The documentation directory contains information files and files used by the online help program.

The information files are:

files.lst

The demonstration directory.

For example, for Release 5.2.0 for OS/2 with a default software root directory, the demo directory is:

c:\versant\5_2_0\os2\demo

The demonstration directory contains subdirectories, each with a set of sample source code.

To make the demo programs, use makefile.

The files for the tutorial in the C++/VERSANT Reference Manual are in the tutorial subdirectory.

•    Where you want to create databases?

Your response to this question set the VERSANT database root directory.

Following are descriptions of the database root directory, and the directories and files associated with each individual database.

The database root directory.

The database root directory is the root directory for individual database directories created by the database utility makedb.

The database root directory can be either local or remote. If a remote directory is used, you must be able to access it with your specification of username and password.

Normally you will create this directory apart from the VERSANT software root directory, as you will probably want to continue to use the databases that you create even after you install a newer version of VERSANT at a later time.

The location of the local database root directory must be specified with the VERSANT_DB location parameter before you can access, create, or remove a database located under that root directory. The location of a remote database root directory must be specified with the VERSANT_DB@node location parameter before you can access, create, or remove a database on a remote machine named node.

In (extremely) unusual circumstances, you might want to create multiple database root directories on the same machine. In such a case, you must specify the location of the root directory you want to use with the VERSANT_DB and/or VERSANT_DB@node location parameters before you can access, create, or remove a database located under that root directory. This practice is not recommended.

The default database root directory is on the local machine at c:\versant\db.

A database directory.

Each time you take the first step in creating a database by using the makedb utility, a database directory with the same name as the database will be created under the database root directory. Database directories must branch from a database root directory.

For example, if the database root directory is c:\versant\db and you create a database named mydb, VERSANT will create the database directory c:\versant\db\mydb.

If a database consists of files, the database directory contains the database volumes for that database.

The database system volume, system, is a file associated with a database that stores class descriptions and object instances.

There is one system volume for each database. Additional data volumes can be added to a database to increase capacity.

The system volume for a database is created with the createdb utility. If system is a file, it is located in the database directory.

The logical log volume, logical.log, and physical log volume, physical.log, are files associated with a database that record transaction activities and provide information for roll back and recovery.

There is one physical.log and one logical.log for each database.

The logical and physical log volumes for a database are created with the createdb utility. If physical.log and logical.log are files, they will expand as needed and be located in the database directory.

The logical log volume, logical.log, and physical log volume, physical.log, are files associated with a database that record transaction activities and provide information for roll back and recovery.

There is one physical.log and one logical.log for each database.

The logical and physical log volumes for a database are created with the createdb utility. If physical.log and logical.log are files, they will expand as needed and be located in the database directory.

The application process profile file.

A client application process contains the application, part of the VERSANT Manager software module, a network layer, and an object cache.

When an application starts a session, the operating environment will be set according to the settings in the application process profile file. You can customize the operating environment for an application process by modifying the application process profile. If there is no application process profile file, the system uses defaults.

On personal computer installations, there is one profile.fe file per machine. When you use either the makedb or makeprofile utilities, VERSANT will check the database directory to determine if a file named profile.fe exists. If a profile.fe file exists, VERSANT will not create a new one. If it does not exist, VERSANT will create one.

You can use the makeprofile utility to create several application process profiles, change their names, edit them, and then specify which one you want to use at run time by changing its name to profile.fe.

In the application process profile are parameters that you can specify either before or after a database has been created. The parameters are read each time a session starts.

The server process profile file.

When a database starts up, the database server process reads the server process profile to determine the location of the database volumes and to set the database operating environment. If a server process profile does not exist for a database, you cannot start that database.

The server process profile file is named profile.be and is located in the database root directory.

If profile.be does not exist, you cannot start that database.

The server process profile is created with the makedb utility.

The server process profile contains several kinds of parameters. Some are used only when a database is created, and others are used each time a database is started. See the chapter "Database Profiles" for more information.

The lock file contains database state information. The lock file is created when you create a database with the makedb utility. If the lock file is missing, you will not be able to start or recreate the database.

If the lock file is destroyed for some reason, use the dbinfo utility to create a new one:

1.  Change directory to the appropriate database directory.

2.  Run the dbinfo utility with the following arguments:

The contents of the sharemem file in a database directory are used as a key to get a unique id for the shared memory of the database server process.

The createdb utility creates the sharemem file. The removedb utility removes the sharemem file. You should never remove the sharemem file yourself, because if the sharemem file is missing, you will not be able to start or recreate the database.

If the sharemem file is removed, in some cases shared memory used by the database will exist, but the stopdb, startdb, and removedb utilities cannot discover it. Then, when you recreate the database, a sharemem file may have the same memory identifier, which causes problems when you try to start the new database.

The workaround is to create an empty sharemem file in the database root directory.

After creating the empty sharemem file, you can then start the database with the startdb utility or, if it has been removed with removedb, you can recreate it with the createdb utility.

The contents of the dbtype file in a database directory indicates the database type, whether personal or group.

The dbtype file is created when you create a database with the makedb utility.

If the dbtype file is missing, you will not be able to start or recreate the database. If the dbtype file is destroyed, create an empty file named dbtype in the database root directory.

For information on how to use this file, see the chapter "Environment Parameters."

The system information file.

The name of the directory containing the sysinfo file depends upon your installation and choice of software root.

For example, for Release 5.2.0, OS/2, and a default software root:

c:\versant\5_2_0\os2\lib\sysinfo

The contents of the system information file will include specification of the machine and directory containing the osc-dbid database system identifier file.

When you install on a local machine, a file named LOGFILE is created in the database root directory. In most cases, VERSANT non-panic system errors are then printed to that file.

When you install to use an installation of VERSANT on another machine, a file named LOGFILE is created in the same directory as the server process profile file profile.be. Replication messages are then printed to that file.

When it starts, vstats will read a configuration file in which derived statistics can be pre-defined and named.

Each definition of a derived statistic must appear on a separate line and should have the following syntax:

define stat_name [ args ] = expression

Elements of a definition line are:

stat_name

Statistic names must be specified as shown in the VERSANT Database Fundamentals Manual, except without the STAT_ prefix and transposed to lower case.

For connection and database statistics (those with the prefixes be_ and db_), you must also use a database name since the same statistics may be available for multiple databases. The general syntax is:

'statistic_name database_name'

You can use simple mathematical formulas to combine and modify statistics to produce a derived statistic. For example:

vstats -stats se_reads + se_writes

In these formulas you can use the standard numerical operators +, -, *, /, (, and ). You can also use the following special functions:

delta

define objs_sec = db_objs_sec database1
define o = objs_sec

Once a statistic has been defined, you can use it in vstats commands and options just as if it were a pre-defined VERSANT statistic. Statistics defined in either of the two .vstatsrc files will be listed when the -summary command is invoked.

For example:

define se_hit_ratio = se_locates/(se_locates+se_reads)

define db_hit_ratio db = db_data_bytes_located  db /
(db_data_bytes_located db +db_data_bytes_read db)

define avg3 n1 n2 n3 = (n1+n2+n3)/3

For an overview of statistics collection and stastics collection usage notes, see the VERSANT Database Fundamentals Manual.

If you use UNIX workstations

If you use UNIX workstations, you will note the following changes in the directory structure for personal computers.

•    One level bin and lib directories