• Find software files and databases as needed.
• Know where you want to create or remove a particular database.
• Modify or list information about all databases in a particular system of distributed databases.
You May Not Need This Chapter
When you installed VERSANT, all configuration parameters needed by VERSANT were stored in such a way that VERSANT can find them.
After installation, you only need to append the location of VERSANT executables to your existing PATH environment variable. (On personal computers, the installation program will do this for you.)
This means that you do not normally need any of the information in this chapter.
You must explicitly specify or change configuration parameters only in the following situations:
• If you did not answer all prompts during installation or if you made a mistake.
• If you want to move software or databases.
A normal installation of VERSANT creates two configuration files, one in the machine configuration file, .oscxxyyzz, and one in the system information file, sysinfo. The combination of these two files after installation completely defines the VERSANT environment. The only additional environmental change made during installation is to place the /bin directory on your path.
When specifying locations in VERSANT parameters, you can use NFS mountings.
Besides these VERSANT parameters, you should also add the VERSANT executables directory to your machine's existing PATH environment variable.
Environment variables
/etc directory or in a system information file in your VERSANT lib directory. The contents of these files depend upon how you installed.You can install VERSANT on a machine in two different ways:
oinstall.
Use files on remote machine — You can install VERSANT so that one machine uses VERSANT files on another machine by invoking the installation program with the command oinstall -f.
Machine configuration file
/etc/.oscxxyyzz
xx is the major release number
yy is the maintenance release number
zz is the minor release number
For example, for Release 5.0.4, the machine configuration file is:
/etc/.osc050004System information file
sysinfo and branches from your lib directory:
/root/release/platform/lib/sysinfoThe 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.
See the chapter "Directories and Files" for more information on the location and nature of the machine configuration and system information files.
Search order
To find the information it needs on each UNIX node, VERSANT searches environmental variables and information files in a predetermined, hierarchial order. If conflicting information is found in the search, the order of the search resolves the conflict: the first value found is the value that is used.
To get needed information on a UNIX node, VERSANT searches in the following order:
1. Environment variables — per process
2. User configuration file — per user
3. Machine configuration file — per machine
4. System information file — per installation
Because VERSANT searches in a hierarchial order, you can supply most information on a per process, per user, per machine, or per installation basis.
For example, if you normally create and use local databases in the directory /usr/local/versant/db, then you can define the following in your machine configuration file (which is the default location):
VERSANT_DB /usr/local/versant/db
Then, if you have an application that embeds VERSANT and works solely with drawings stored in databases in the directory /myapplication/db, before starting VERSANT you can define the following environment variable to override the setting in the machine configuration file:
VERSANT_DB /myapplication/db
On personal computer nodes, VERSANT makes a similar search, although the details differ. (See the section "Configuration Parameters for Personal Computers.")
Passing parameters to remote machines
To specify a command or configuration parameter on a remote machine, you can use @node syntax. For example, to create a database on a remote machine named server, you would use the following @node syntax:
createdb db1@server
Or, to look for an osc-dbid file on a remote machine:
VERSANT_DBID_NODE@server
If you use @node syntax, all parameters are sent to the server on node (local or remote).
If you do not use @node syntax, all parameters, except for versant_root and versant_rel, are sent to the local server. This means that to send versant_root or versant_rel to the local server, you must use @node syntax.
Configuration parameters explicitly passed to a remote machine override those already set on the remote machine. You should pass parameters only in the usual circumstance that you want to override the values set on the remote machine.
For example, suppose the UNIX machine server has the following environment parameter set:
VERSANT_DB /usr/local/versant/db
To create a database on server in a different directory, you could set the following:
VERSANT_DB@server /db
Then, if you invoke the create database utility as createdb@server, the value of your environment parameter VERSANT_DB@server will be passed to the machine named server and the database will be created in a directory branching from /db rather than /usr/local/versant/db.
You can use @node syntax for any parameter and set any parameter for remote use in either a configuration file or in an environment variable.
If you doubly define a parameter for the local machine by defining it both with and without @node syntax, VERSANT will look first for a value in the parameter without @node syntax and then look for it with @node syntax. The first value found will be the value used.
For example, if you are on machine alpha and have defined both VERSANT_DB and VERSANT_DB@alpha, then VERSANT will use the value in VERSANT_DB. However, if you have not defined VERSANT_DB, then VERSANT will use the value in VERSANT_DB@alpha.
In any case, you must, of course, specify parameters to be passed in the syntax appropriate to the remote machine. For example:
VERSANT_DB@unix_server /usr/local/versant/db
VERSANT_DB@nt_server \versant\db
To set a configuration parameter in an environment variable, use the name of the environment parameter followed by its value.
For example, suppose you want to set the local database root directory for Release 5.0.7 on Sun 4 to be the default location:
VERSANT_DB /usr/local/versant/5.0.7/sun4/db
If you use C Shell, to set VERSANT_DB in your .login file in your home directory:
setenv VERSANT_DB /usr/local/versant/5.0.7/sun4/db
If you use Bourne shell, to set VERSANT_DB in the .profile file in your home directory:
VERSANT_DB = /usr/local/versant/5.0.7/sun4/db
export VERSANT_DB
User configuration file
You can specify the locations of the software and database directories in a user configuration file that you create.
The format for lines in the user configuration file is the name of the environment parameter followed by the value.
After creating the user configuration file, use the following environment variable to tell VERSANT about the file:
VERSANT_CFG
myconfig.txt in /usr/local/versant, to set the local database root directory for Release 5.0.7 on Sun 4 to be the default location, create the following line:
VERSANT_DB /usr/local/versant/5.0.7/sun4/db
Then, to set VERSANT_CFG to the location of your configuration file, if you use C Shell:
setenv VERSANT_CFG /usr/local/versant/myconfig.txt
If you use Bourne shell:
VERSANT_CFG = /usr/local/versant/myconfig.txt
export VERSANT_CFG
Machine configuration file
In the VERSANT machine configuration file /etc/.oscxxyyzz, you can create or modify a line for an environment parameter.
The format for lines in the machine configuration file is the name of the environment parameter followed by the value.
For example, to set the local database root directory for Release 3.0.8 on Sun 4 to be the default location, create or modify the following line in /etc/.osc030008:
VERSANT_DB /usr/local/versant/3.0.8/sun4/db
You can make comments in the .oscxxyyzz file on any line in which either the first column is marked with the # sign or after a # sign on a line containing an entry.
For example, for release 3.0.8, local machine mymachine, software root path /usr/local/versant, and database root path /db, the contents of /etc/.osc030008 could be:
# the following line specifies software root
VERSANT_ROOT /usr/local/versant
VERSANT_DB /db #this line is the database root
System information file
In the VERSANT system information file sysinfo in your lib directory, you can create or modify a line for an environment parameter.
To set an environment parameter in the VERSANT sysinfo file, use the name of the environment parameter followed by its value.
For example, to set the local database root directory for Release 3.0.8 on Sun 4 to be the default location, create or modify the following line:
VERSANT_DB /usr/local/versant/3.0.8/sun4/db
Since VERSANT needs to know its software directory in order to find the sysinfo file in the first place, you should not record the location of VERSANT_ROOT in the sysinfo file.
You can make comments in the sysinfo file on any line in which either the first column is marked with the # sign or after a # sign on a line containing an entry.
/etc/.oscxxyyzz or in the system information file lib/sysinfo.
After installation, the only thing that you should do is add the VERSANT executables directory to your machine's existing environment variable PATH.
See also the chapter "Directories and Files" for an explanation of VERSANT file structures.
After installation, append the location of the VERSANT executables directory bin to your PATH environment variable. This will enable VERSANT to find the executables regardless of your current directory.
For a standard installation, the VERSANT executables directory will be named /bin and be located below the platform directory. For example, for Release 3.0.8 on Sun 4:
/usr/local/versant/3.0.8/sun4/bin
If you use C Shell, the search path should be in the .login file in your home directory. To amend it to include the VERSANT /bin directory, use the set path command.
For example, for a default installation for Sun:
set path = (/usr/local/versant/3.0.0/sun4/bin $path)
If you use Bourne shell, the search path should be in the .profile file in your home directory.
For example, to amend it to include the VERSANT /bin directory for a default installation for Sun:
PATH=/usr/local/versant/3.0.8/sun4/bin:${PATH}
export PATH
You must explicitly set them only in the following situations:
• If you did not answer all prompts during installation.
• If you made a mistake during installation.
• If you have moved your software, database directory, or database system identifier file.
• If you have created a user configuration file.
This parameter enables VERSANT to find its own files, because they are placed in predetermined places in directories built from the software root directory. On UNIX installations, the default value of VERSANT_ROOT is /usr/local/versant.
You may set the parameter VERSANT_ROOT in any of the following places:
|
|
In the environment variable |
|
|
In a user configuration file, if you also set |
|
|
In the machine configuration file, which is the default location. |
VERSANT_ROOT in the system information file.
For example, if you use C Shell and set VERSANT_ROOT in your .login file in your home directory:
setenv VERSANT_ROOT /usr/local/versant
For example, if you use Bourne shell and set VERSANT_ROOT in the .profile file in your home directory:
VERSANT_ROOT=/usr/local/versant
export VERSANT_ROOT
Default and non-default directory structures
By default, the basic structure of VERSANT directories is:
|
|
VERSANT_ROOT:
|
|
|
|
|
|
VERSANT_ROOT. If you have static linkage for the executables, the rest of the VERSANT installation tree does not have to be present.You can see the location of your VERSANT installation by typing:
oscp –p
osc-dbid database system file. Mandatory.This parameter is necessary if you want to create, remove, or list databases. There is no default location for the database system file.
If your machine is not connected to a network, you can specify this parameter with a null value to indicate that the osc-dbid file is on the local machine.
If your machine is connected to a network but will use a local database system file, you should supply the network name of your machine as known to your TCP/IP installation.
If your machine is connected to a network and will use a remote database system file, you should supply the network name of the remote machine as known to your TCP/IP installation.
You may set the parameter VERSANT_DBID_NODE in any of the following places:
VERSANT_DBID_NODE
VERSANT_DBID_NODE.
user.cfg
VERSANT_CFG.
/etc/.oscxxyyzz
sysinfo
sysinfo file in the lib directory.
VERSANT_DBID_NODE in your .login file in your home directory:
setenv VERSANT_DBID_NODE myserver
For example, if you use Bourne shell and set VERSANT_DBID_NODE in the .profile file in your home directory:
VERSANT_DBID_NODE = myserver
export VERSANT_DBID_NODE
osc-dbid database system file. Mandatory.This parameter is necessary if you want to create, remove, or list databases. There is no default location for the database system file.
Remote directories must be specified in terms understandable to the operating system on the remote machine. This means that for personal computers you should specify directories with drive:\directory syntax and for UNIX computers you should specify directories with /directory syntax.
You may set the parameter VERSANT_DBID in any of the following places:
VERSANT_DBID
VERSANT_DBID.
user.cfg
VERSANT_CFG.
/etc/.oscxxyyzz
sysinfo
sysinfo file in the lib directory.
This parameter is necessary if you want to access, create, or remove a database on your local machine. New databases are placed in a directory branching from the database root directory.
You may set the parameter VERSANT_DB in any of the following places:
VERSANT_DB
VERSANT_DB.
user.cfg
VERSANT_CFG.
/etc/.oscxxyyzz
sysinfo
sysinfo file in the lib directory.
This parameter is needed only if you create and use a user configuration file to set other configuration parameters on a per user basis.
The format for lines in a user configuration file is the name of the environment parameter followed by the value.
You must set the environment parameter VERSANT_CFG in the environment variable VERSANT_CFG.
VERSANT allows you to assert a release number by setting the environment variable VERSANT_REL for a local machine or VERSANT_REL@node for a remote machine named node.
• You must assert a release number if your application was compiled with one VERSANT Release and you want to access a database of another Release.
• You may want to assert a release number if you have multiple VERSANT Releases on the same machine.
Asserting a release number causes VERSANT to use the configuration specified in the .oscxxyyzz machine configuration file that corresponds to the release number asserted.
Asserting a release number does not alter the normal order in which VERSANT searches for its configuration. If a configuration has been specified in environment variables or in a user configuration file, then asserting a release number will have no effect.
Except in the case when Release 2 applications are accessing Release 3 databases, the ability to assert release numbers is provided as a convenience. For example, when interacting with a remote machine, you may not know what values to assert for VERSANT_ROOT@node, VERSANT_DB@node, VERSANT_DBID_NODE@node, and VERSANT_DBID@node in order to completely specify the remote configuration you want to use. In such a case, it is simpler just to assert a release number with VERSANT_REL@node and then let the remote machine determine the correct configuration to use.
Background
A "complete" installation of VERSANT involves:
1. Copying VERSANT software to a machine, which is normally done for you by the installation program.
2. Setting at least the following configuration parameters: VERSANT_ROOT, which specifies the software root directory, VERSANT_DBID_NODE, which specifies the machine containing the osc-dbid file, VERSANT_DBID, which specifies the directory containing the osc-dbid file, and VERSANT_DB, which specifies the database root directory.
/etc/.oscxxyyzz and system information file /lib/sysinfo. After installation, the combination of these two files completely defines the VERSANT configuration. The only additional environment change made during installation is to place the /bin directory on your path.The ability to use a release number to assert a configuration depends upon the creation of the machine configuration file that contains the release number as part of its name.
/bin directory for the release being installed.
/etc/services and /etc/inetd.conf files to point to the server connection program ss.d in the ../bin directory of the new release. Doing this does not prevent you from using a previous installation of a VERSANT Release.
convertdb utility provided in the new release.If you want to first confirm the compatibility of various applications and databases, you may not want to perform this step right away, which creates the need to be able to assert a particular installation.
1. The connection request is sent to the TCP/IP inetd daemon on the machine on which the database resides, which fowards the request to the server connection program specified in its configuration files.
2. The server connection program starts and looks for values for VERSANT_ROOT, VERSANT_DB, VERSANT_DBID_NODE, and VERSANT_DBID. The ss daemon will search in the following order:
Normally, if needed information is not found in environment variables or in a user configuration file, the server connection program will use the machine configuration file associated with its own release number.
However, if you have asserted a release number and needed information is not found in environment variables or in a user configuration file, the server connection program will use the machine configuration file associated with the release number that has been asserted.
In general, client applications compiled with a lower release number can connect to database servers of a higher release number, but client applications cannot connect to a server of a lower release number. For example, a 4.0.8 client can connect to a 5.2.0 server, but a 5.2.0 client cannot connect with a 4.0.8 database.
Setting VERSANT_REL
The general syntax for setting VERSANT_REL is:
VERSANT_REL xx.yy.zz
For xx, substitute the main release number; for yy, substitute the maintenance number; and for zz substitute the update number. Do not use leading zeroes.
For example, for Release 5.2.1:
VERSANT_REL 5.1.1
You must set the configuration parameter VERSANT_REL in the environment variable VERSANT_REL.
Setting VERSANT_REL@node
The general syntax for setting VERSANT_REL@node is:
VERSANT_REL@node xx.yy.zz
For node, substitute the name of the remote machine.
For xx, substitute the main release number; for yy, substitute the maintenance number; and for zz substitute the update number. Do not use leading zeroes.
For example, for Release 5.2.1 on a machine named server:
VERSANT_REL@server 5.2.1
You must set the configuration parameter VERSANT_REL@node in the environment variable VERSANT_REL@node.
Environment setting on client machine
The following shows how the VERSANT_REL setting on a server machine is affected by an environment variable setting on a client machine (VERSANT_REL or VERSANT_REL@node).
|
|
|
Value passed |
|
Yes |
No |
None |
|
Yes |
Yes |
|
|
No |
Yes |
|
|
No |
No |
none |
Suppose that a local machine and a remote machine named alpha each has more than one installation of VERSANT:
Client process uses Release 3.0.5
bin directory.
alpha uses 3.0.12
alpha point to a server connection program in a Release 3.0.12 bin directory.
alpha use 3.0.10
alpha.
VERSANT_REL 3.0.8
VERSANT_REL@alpha 3.0.10
alpha to be 3.0.10 in order to start Release 3.0.10 server processes, because the server connection program is associated with Release 3.0.12.
This parameter is needed only if a remote machine named node has multiple versions of VERSANT software and you want to specify a particular software root directory.
Remote paths must be specified in syntax understood by the remote machine.
You may set the parameter VERSANT_ROOT@node in any of the following places:
|
|
In the environment variable |
|
|
In a user configuration file, if you also set |
|
|
In the machine configuration file, which is the default location. |
VERSANT_ROOT setting on a server machine is affected by an environment variable setting on a client machine (VERSANT_ROOT or VERSANT_ROOT@server).Environment setting on client machine:
|
|
|
Value passed |
|
Yes |
No |
None |
|
Yes |
Yes |
|
|
No |
Yes |
|
|
No |
No |
none |
You need to specify this parameter only if there are multiple database systems and you want to override the specification for the machine containing the osc-dbid file that has been set on the remote machine named node.
If you supply the name of a remote database when you use the create database, remove database, or list databases utilities, VERSANT will look for the name of the machine containing the osc-dbid database system file in this parameter. If this parameter has not been set, VERSANT will look for the osc-dbid file in the location specified on the remote machine.
The general syntax for setting VERSANT_DBID_NODE@node is:
VERSANT_DBID_NODE@node osc-dbid_machine
Substitute for node the name of remote machine used with dbname@node syntax as an argument to the createdb, removedb, or listdb utilities. Substitute for osc-dbid_machine the name of the machine containing the osc-dbid file that you want to use.
You may set the parameter VERSANT_DBID_NODE@node in any of the following places:
VERSANT_DBID_NODE@node
VERSANT_DBID_NODE@node.
user.cfg
VERSANT_CFG.
/etc/.oscxxyyzz
sysinfo
sysinfo file in the lib directory.
osc-dbid file.
You need to specify this parameter only if there are multiple database systems and you want to override the specification for the machine containing the osc-dbid file that has been set on the remote machine named node.
If you supply the name of a remote database when you use the create database, remove database, or list databases utilities, VERSANT will look for the name of the directory containing the osc-dbid database system file in this parameter. If this parameter has not been set, VERSANT will look for the osc-dbid file in the location specified on the remote machine.
The general syntax for setting VERSANT_DBID@node is:
VERSANT_DBID@node path
Substitute for node the name of remote machine used with dbname@node syntax as an argument to the createdb, removedb, or listdb utilities. Substitute for path the directory containing the osc-dbid file in terms understandable to the operating system of the remote machine.
For example, if you want to create a database on a remote machine named alpha and specify an osc-dbid directory on a UNIX machine in /usr/local/versant/db:
VERSANT_DBID@alpha /usr/local/versant/db
You may set the parameter VERSANT_DBID@node in any of the following places:
VERSANT_DBID@node
VERSANT_DBID@node.
user.cfg
VERSANT_CFG.
/etc/.oscxxyyzz
sysinfo
sysinfo file in the lib directory.
osc-dbid file.
You need to specify this parameter only if there are multiple database root directories on a remote machine and you want to override the specification that has been set on the remote machine named node.
If you specify a remote database in a command or method with the syntax dbname@node, VERSANT will look for a value set by this parameter. If this parameter has not been set, VERSANT will look for the database root directory in the location specified on the remote machine.
The general syntax for setting VERSANT_DB@node is:
VERSANT_DB@node path
For node, substitute the name of the remote machine. For path, substitute the location of the database root directory in terms understandable to the operating system of the remote machine.
For example, if you want to connect with a database on a UNIX machine named alpha whose database root directory is /db, set:
VERSANT_DB@alpha /db
If you want to connect with a database on an OS/2 machine named beta whose database root directory is c:\db, set:
VERSANT_DB@beta c:\db
You may set the parameter VERSANT_DB@node in any of the following places:
VERSANT_DB@node
VERSANT_DB@node.
user.cfg
VERSANT_CFG.
/etc/.oscxxyyzz
sysinfo
sysinfo file in the lib directory.
CHECKING environment variable turns C++/VERSANT debugging on and off. See the C++/VERSANT Reference for further information.
versant_fe_errlog to the name of the file where errors should be logged. By default, error logging is off.On UNIX systems, create this environment variable with its name in all lower case.
In addition to error number and error message, entries in the error log file also include context information, such as operating system error number, file name, and so on. The exact context information varies from error to error.
This error logging mechanism should not be confused with the functionality represented by the file LOGFILE, which is used to report non-panic VERSANT system errors.
For UNIX systems, the general syntax to set this environment variable is similar to the following (depending upon your shell), where filename is the name of your error logging file:
setenv versant_fe_errlog filename
VERSANT_STAT_FILE to the name of a file and then run your application within its scope.
By default, all defined statistics will be collected. You may want to filter the statistics collected to reduce file size and improve application performance. To filter the statistics collected and set other collection parameters, you can use the VERSANT_STAT_STATS, VERSANT_STAT_FUNCS, VERSANT_STAT_TIME, VERSANT_STAT_DBS, and VERSANT_STAT_FLUSH environment variables.
If you set VERSANT_STAT_FILE, statistics will be collected during the time your application is in a database session.
The VERSANT_STAT_FILE environment variable is read each time a session starts, so if your application starts and stops a session, each new session will overwrite the file created by the previous session.
Within the file name, you can use the symbol %p, which will expand to your process identifier number. This can help create differing file names if you exit your application process between sessions, but it is not a guarantee because process id numbers can repeat.
Unlike other VERSANT environment variables, such as VERSANT_ROOT, the VERSANT_STAT_FILE environment variable is not read automatically when an application makes a connection to a database on a local or remote machine. Instead, VERSANT_STAT_FILE is a normal environment variable associated with a particular application process.
If VERSANT_STAT_FILE has been set, statistics are collected and written whenever a collection point is encountered by your application. A default collection point is encountered when your application enters or exits a VERSANT function. You can set additional collection points by inserting o_autostatsenter() and o_autostatsexit() function calls in your code.
Setting VERSANT_STAT_FILE has no effect on statistics collection performed by other mechanisms, such as a separate invocation of the vstats utility.
Setting VERSANT_STAT_FILE is the same as calling o_autostatsbegin() at the beginning of your session, except that uses parameters found in VERSANT_STAT_STAT, VERSANT_STAT_FUNCS, VERSANT_STAT_TIME, VERSANT_STAT_DBS, and VERSANT_STAT_FLUSH.
Even when database replication has been turned on, statistics collection tools and mechanisms operate only on named databases and not on replica databases. To collect statistics for a replica database, you must apply statistics collection mechanisms specifically to the replica database. If the replica database goes down, statistics collection will stop and then restart when the database comes back up.
For an overview of statistics collection and stastics collection usage notes, see the VERSANT Database Fundamentals Manual.
VERSANT_STAT_FILE has been set, by default all statistics are collected and sent to the named file whenever a collection point is encountered. To filter what application, session, connection, and database statistics are sent to a file, set the VERSANT_STAT_STATS environment variable to a space delimited list of the names of the statistics you want to collect.
When statistic names are specified in the environment variable VERSANT_STAT_STATS, they must be entered in lowercase without the leading STAT_ prefix.
For example:
setenv VERSANT_STAT_STATS 'se_net_bytes_read se_net_bytes_written'
Setting VERSANT_STAT_STAT has no effect on what statistics are collected by other mechanisms, such as a separate invocation of the vstats utility. However, you can call o_collectstats() and explicitly turn collection off for specific statistics, which will override the values set by VERSANT_STAT_STATS.
For an overview of statistics collection and stastics collection usage notes, see the VERSANT Database Fundamentals Manual.
VERSANT_STAT_FILE has been set, by default all statistics are collected and sent to the named file whenever a collection point is encountered. To filter what function statistics are sent to the file, set the VERSANT_STAT_FUNCS environment variable to a space delimited list of the names of the function statistics you want to collect.
When function names are specified in the environment variable VERSANT_STAT_FUNCS, they must be entered in lowercase, without the leading CAPI_ prefix and with a leading o_ prefix.
For example:
setenv VERSANT_STAT_FUNCS 'o_xact o_select'
Setting VERSANT_STAT_FUNCS has no effect on what statistics are collected by other mechanisms, such as a separate invocation of the vstats utility. However, you can call o_collectstats() and explicitly turn collection off for specific statistics, which will override the values set by VERSANT_STAT_FUNCS.
For an overview of statistics collection and stastics collection usage notes, see the VERSANT Database Fundamentals Manual.
VERSANT_STAT_FILE has been set, by default statistics are collected and sent to the named file whenever a collection point is encountered. To set a collection interval, set VERSANT_STAT_TIME to a desired number of seconds. After VERSANT_STAT_TIME has been set, statistics will not be written unless the specified number of seconds have elapsed since the last time that statistics were written.Setting a time interval will improve performance, but the trace-like information on which functions were called will not be recorded. It is not necessary to restrict time intervals to be integers.
For example:
setenv VERSANT_STAT_TIME 1.5
For an overview of statistics collection and stastics collection usage notes, see the VERSANT Database Fundamentals Manual.
VERSANT_STAT_FILE has been set, by default statistics are collected for all databases to which an application makes a connection, including the session database. To limit statistics collection to specific databases, set this environment variable to a space delimited list of database names. For remote databases, use the syntax dbname@node.For example:
setenv VERSANT_STAT_DBS 'db1@server1 db2@server2'
Statistics collection for a named database will begin when a connection is made to it and stop when a connection to it is closed.
To ensure that only application and session statistics are sent to file, set VERSANT_STAT_DBS to an empty string:
setenv VERSANT_STAT_DBS ''
For an overview of statistics collection and stastics collection usage notes, see the VERSANT Database Fundamentals Manual.
VERSANT_STAT_FLUSH exists, each batch of statistics is sent to file as soon as it is generated. This eliminates a possible lag time caused by operating system file buffering, which is useful when you want to view the automatic collection file as it is being generated.For an overview of statistics collection and stastics collection usage notes, see the VERSANT Database Fundamentals Manual.
VERSANT_AUTH to point to the application authentication program.The general format for the environment variable is:
VERSANT_AUTH=program_path
For usage notes, see the chapter "User Authentication" in the VERSANT Database Fundamentals Manual.
This parameter provides support for multiple VERSANT releases.
The environment variable VERSANT_SERVICE_NAME allows you to have multiple VERSANT releases on the same machine and connect to servers from one or the other of these releases selectively from different clients. This is an advanced option and requires careful configuration. This is not something you normally need to do, and we recommend that you do it only with the guidance of VERSANT Technical Support.
In the default installation, the VERSANT connection services daemon listens on TCP/IP port 5019, which has the TCP/IP service name "oscssd" associated with it. In the default case, all clients try to connect to the "oscssd" service on the server machine, and the service name is mapped to a port number by looking up the TCP/IP configuration file /etc/services on the client machine (not the server machine).
By specifying the environment variable VERSANT_SERVICE_NAME, you can cause a client application to connect to a different service name and, therefore, a different port number. Correspondingly, on the server machine you can set up different VERSANT releases to listen on different port numbers and allow a client to connect to a VERSANT server process from the release of their choice.
Example
For example, suppose that you have VERSANT Release 5.0.8 as well as 5.2.0 installed on the same server machine. The following procedure illustrates how to set up the server machine and the client machines for selective VERSANT release execution.
In this example, let's assume that the two releases have different VERSANT_ROOT directories. Suppose that Release 5.0.8 resides at /usr/versant/5.0.8/sun4, and Release 5.2.0 resides at /apps/versant/5.2.0/sun4.
In the following description, the sections on configuring TCP/IP services apply only to Unix machines. On Windows NT, a GUI utility named networkservices.exe is provided to configure Windows machines to run multiple Versant releases. This Windows utility is documented with the other DBA utilities.
5020 for Release 5.0.8 and port 5030 for Release 5.2.0.
Next, select service names to associate with these two ports. For this example, let's choose the service names osc508 and osc520.
3. Edit the /etc/services file.
/etc/services and associate the service names with the chosen port numbers by adding the following two lines:
osc508 5020/tcp # Versant 5.0.8 connection service
osc520 5030/tcp # Versant 5.2.0 connection service
/etc/inetd.conf and associate each service name with the desired release by adding the following two lines:
osc508 stream tcp nowait root /usr/versant/5.0.8/sun4/bin/ss.d in.oscssdosc520 stream tcp nowait root /apps/versant/5.2.0/sun4/bin/ss.d in.oscssd
ss.d executable in the VERSANT bin directory for each release.
inetd that it should refresh its configuration, which we changed in the previous step:
ps -ef | grep inetd # Find the process id of inetd
kill -HUP <inetd-process-id> # Ask inetd to refresh
services file and introduce the new service names and port numbers as in Steps 2 and 3 above. The service names and port numbers for VERSANT services must match each other exactly on the client and server machines.
7. Set VERSANT_SERVICE_NAME on each client machine.
VERSANT_SERVICE_NAME to the value "osc508" before running a Release 5.0.8 application. This will automatically connect the application to the server database process for VERSANT Release 5.0.8.
In an appropriate context on the 5.2.0 client machine, set the environment variable VERSANT_SERVICE_NAME to the value "osc520" before running a Release 5.2.0 application. This will automatically connect the application to the server database process for VERSANT Release 5.2.0.
On UNIX running C shell:
For example:
setenv VERSANT_SERVICE_NAME osc508
On UNIX running Bourne shell:
For example:
VERSANT_SERVICE_NAME=osc508; export
On NT:
For a persistent change, go to Control Panel / System / Environment, enter VERSANT_SERVICE_NAME in the Variable entry box, enter the new service name in the Value entry box, click on on Set and then click on either Apply or OK.
For a temporary change, you can set environment variables in a program. For example:
SetEnvironmentVariable("VERSANT_SERVICE_NAME", "osc508");
putenv("VERSANT_SERVICE_NAME=osc508");
In the above, note that you need to execute both SetEnvironmentVariable(), in order to set the variable in the NT process header, and putenv(), in order to set the variable in the C runtime environment.
Suppose you are running on a UNIX machine named myMachine, you are accessing an OS/2 machine named alpha and a UNIX machine named beta, and the osc-dbid database system file is on beta in /dbsys.
To specify information about your machine, you must set:
VERSANT_ROOT /usr/local/versant
PATH <existing PATH>;/usr/local/versant/3.0.8/sun4/bin
If you want to create databases on your local machine, you must set:
VERSANT_DBID_NODE beta
VERSANT_DBID /dbsys
VERSANT_DB /usr/local/versant/db
After setting all of these variables, if you invoke createdb as:
createdb myDatabase
Then VERSANT will look at the following variables:
PATH
createdb utility.
VERSANT_DBID_NODE
osc-dbid file.
VERSANT_DBID
osc-dbid file.
VERSANT_DB
createdb as:
createdb myDatabase@alpha
After making the connection, VERSANT will pass the createdb command to alpha. Machine alpha will then look to its own configuration parameters to decide where to find the osc-dbid file and where to place the new database.
UNIX example using advanced parameters
Suppose your UNIX machine is named myMachine and you are accessing an OS/2 machine named alpha and a UNIX machine named beta, and the osc-dbid database system file is on beta in /dbsys.
If you have multiple releases of VERSANT on your local machine or databases created with multiple releases and want to assert the release number, you may optionally set:
VERSANT_REL 3.0.8
If you want to assert the location of the osc-dbid database system file to machines alpha and beta, you may optionally set:
VERSANT_DBID_NODE@alpha beta
VERSANT_DBID@alpha /dbsys
VERSANT_DBID_NODE@beta beta
VERSANT_DBID@beta /dbsys
If you want to assert the location of database root directories to machines alpha and beta, you may optionally set:
VERSANT_DB@alpha d:\versant\db
VERSANT_DB@beta /versant/db
If you have multiple releases of VERSANT on alpha and beta and databases created with multiple releases, to assert the release number and root directories, you may optionally set:
VERSANT_REL@alpha 3.0.8
VERSANT_ROOT@alpha d:\versant
VERSANT_ROOT@beta /usr/local/versant
VERSANT_REL@beta 3.1.4
After setting all of the above parameters, if you invoke createdb as:
createdb myDatabase@alpha
Then VERSANT will look at the following parameters:
VERSANT_REL@alpha
alpha.
VERSANT_ROOT@alpha
alpha.
VERSANT_DBID_NODE@alpha
osc-dbid machine.
VERSANT_DBID@alpha
osc-dbid directory.
VERSANT_DB@alpha
Because personal computer operating systems differ on how they set and use parameters, please see your Platform Notes and Installation Guide manuals for information on where and how to set configuration parameters. This section just discusses the parameters that can be set and what they do.
To specify a command or configuration parameter on a remote machine, you can use @node syntax. For example, to create a database on a remote machine named server, you would use the following @node syntax:
createdb db1@server
Or, to look for an osc-dbid file on a remote machine:
VERSANT_DBID_NODE@server
If you set a configuration parameter without @node syntax, that parameter applies only to the local machine. If you use @node syntax, the value is sent to the remote machine for its use.
Configuration parameters explicitly passed to a remote machine override those already set on the remote machine. You should pass parameters only in the usual circumstance that you want to override the values set on the remote machine.
For example, suppose an NT machine named server has the following environment parameter set:
VERSANT_DB \versant\db
To create a database on server in a different directory, you could set the following:
VERSANT_DB@server \db
Then, if you invoke the create database utility as createdb@server, the value of your environment parameter VERSANT_DB@server will be passed to the machine named server and the database will be created in a directory branching from \db rather than \versant\db.
You can use @node syntax for any parameter and set any parameter for remote use in either a configuration file or in an environment variable.
If you doubly define a parameter for the local machine by defining it both with and without @node syntax, VERSANT will look first for a value in the parameter without @node syntax and then look for it with @node syntax. The first value found will be the value used.
For example, if you are on machine alpha and have defined both VERSANT_DB and VERSANT_DB@alpha, then VERSANT will use the value in VERSANT_DB. However, if you have not defined VERSANT_DB, then VERSANT will use the value in VERSANT_DB@alpha.
In any case, you must, of course, specify parameters to be passed in the syntax appropriate to the remote machine. For example:
VERSANT_DB@unix_server /usr/local/versant/db
VERSANT_DB@nt_server \versant\db
You must explicitly set them only in the following situations:
• If you did not answer all prompts during installation.
• If you made a mistake during installation.
• If you have moved your software, database directory, or database system identifier file.
When you install VERSANT, all configuration parameters needed by VERSANT are set and stored.
See also the chapter "Directories and Files" for an explanation of VERSANT file structures.
After installation, append the location of the VERSANT executables directory bin to your PATH environment variable. This will enable VERSANT to find the executables regardless of your current directory.
The libraries directory.
For OS/2, append the location of the VERSANT libraries directory lib to your LIBPATH environment variable as set in your config.sys file. This will enable VERSANT to find its libraries regardless of your current directory.
For example, if the lib directory is c:\versant\3_0_8\os2\lib:
libpath <existing path>;c:\versant\3_0_8\os2\lib
You must explicitly set them only in the following situations:
• If you did not answer all prompts during installation.
• If you made a mistake during installation.
• If you have moved your software, database directory, or database system identifier file.
This parameter enables VERSANT to find its own files, because they are placed in predetermined places in directories built from the software root directory.
You must specify the location of the software root directory by setting the environment variable VERSANT_ROOT.
The general syntax is:
set VERSANT_ROOT=drive:directory
For example:
set VERSANT_ROOT=c:\versant
You cannot set VERSANT_ROOT in the sysinfo file.
Default and non-default directory structures
By default, the basic structure of VERSANT directories is:
|
|
VERSANT_ROOT:
|
|
|
|
|
|
VERSANT_ROOT. If you have static linkage for the executables, the rest of the VERSANT installation tree does not have to be present.You can see the location of your VERSANT installation by typing:
oscp –p
This parameter is necessary if you want to create, remove, or list databases. There is no default location for the database system file.
If your machine is not connected to a network, you do can skip specifying this parameter, which will indicate that the osc-dbid file is on the local machine.
If your machine is connected to a network but will use a local database system file, you should supply the network name of your machine as known to your TCP/IP installation.
If your machine is connected to a network and will use a remote database system file, you should supply the network name of the remote machine as known to your TCP/IP installation.
You can set VERSANT_DBID_NODE as an environment variable or with a line in the sysinfo file. The general syntax is:
VERSANT_DBID_NODE osc-dbid_machine
osc-dbid database system file. Usually needed.This parameter is necessary if you want to create, remove, or list databases. There is no default location for the database system file.
Remote directories must be specified in terms understandable to the operating system on the remote machine. This means that for personal computers you should specify directories with drive:\directory syntax and for UNIX computers you should specify directories with /directory syntax.
You can set VERSANT_DBID_NODE as an environment variable or with a line in the sysinfo file. The general syntax is:
VERSANT_DBID path
For path, substitute the location of the software root directory in terms understandable to the operating system of the machine containing the osc-dbid file.
For example, if the machine containing the osc-dbid file is a personal computer and the osc-dbid directory on that machine is c:\versant\db:
VERSANT_DBID c:\versant\db
If the machine containing the osc-dbid file is running UNIX and the osc-dbid directory is /usr/local/versant/db, specify VERSANT_DBID as:
VERSANT_DBID /usr/local/versant/db
This parameter is necessary if you want to create or remove a database on your local machine. New databases are placed in a directory branching from the database root directory.
You can set VERSANT_DB as an environment variable or with a line in the sysinfo file. The general syntax is:
VERSANT_DB path
For path, substitute the location of the database root directory.
For example:
VERSANT_DB c:\versant\db
On a personal computer, you must set this parameter if you want to access, create, or remove a database on a remote machine.
If you are using VERSANT on a standalone basis, you do not have to specify a username.
You can set VERSANT_USER with a line in the sysinfo file or by setting an environment variable. The general syntax is:
VERSANT_USER username
Substitute for username the login name to be used when you make a database connection.
For example, for the login name silas:
VERSANT_USER silas
VDate and VTime classes.
For example, for Pacific time, set TZ to equal PST8PDT.
etc directory, which is needed by TCP/IP network software.The VERSANT installation program will optionally update your TCP/IP services file as appropriate for your operating environment. TCP/IP services are required for other clients to remotely access databases local to your personal computer environment or if you link your application to the VERSANT two process system library (the usual choice).
If you elect to update the TCP/IP services file yourself, want to examine VERSANT's changes, or need to change the VERSANT installation, the following changes are needed for each of the personal computer operating systems supported by VERSANT.
OS/2
On OS/2, the \tcpip\etc\services file should define VERSANT service as:
oscssd 5019/tcp
The \tcpip\etc\inetd.lst should define the VERSANT connection server as:
oscssd tcp path
Where path points to the \bin\ss.exe program in your installed software tree.
Windows NT
In Windows NT, the \winnt\system32\drivers\etc\services file should define VERSANT service as:
oscssd 5019/tcp
VERSANT allows you to assert a release number by setting the environment variable VERSANT_REL for a local machine or VERSANT_REL@node for a remote machine named node.
• You must assert a release number if your application was compiled with one VERSANT Release and you want to access a database of another Release.
• You may want to assert a release number if you have multiple VERSANT Releases on the same machine.
Asserting a release number causes VERSANT to use the configuration specified in the .oscxxyyzz machine configuration file that corresponds to the release number asserted.
Asserting a release number does not alter the normal order in which VERSANT searches for its configuration. If a configuration has been specified in environment variables or in a user configuration file, then asserting a release number will have no effect.
Except in the case when Release 2 applications are accessing Release 3 databases, the ability to assert release numbers is provided as a convenience. For example, when interacting with a remote machine, you may not know what values to assert for VERSANT_ROOT@node, VERSANT_DB@node, VERSANT_DBID_NODE@node, and VERSANT_DBID@node in order to completely specify the remote configuration you want to use. In such a case, it is simpler just to assert a release number with VERSANT_REL@node and then let the remote machine determine the correct configuration to use.
See also the notes for VERSANT_REL in the preceding section, "Configuration Parameters for UNIX."
This parameter is needed only if a remote machine named node has multiple versions of VERSANT software and you want to specify a particular software root directory.
Remote paths must be specified in syntax understood by the remote machine.
You may set the parameter VERSANT_ROOT@node in an environment variable or in the sysinfo file.
The following shows how the VERSANT_ROOT setting on a server machine is affected by an environment variable setting on a client machine (VERSANT_ROOT or VERSANT_ROOT@server).
Environment setting on client machine:
|
|
|
Value passed |
|
Yes |
No |
None |
|
Yes |
Yes |
|
|
No |
Yes |
|
|
No |
No |
none |
You need to specify this parameter only if there are multiple database systems and you want to override the specification for the machine containing the osc-dbid file that has been set on the remote machine named node.
If you supply the name of a remote database when you use the create database, remove database, or list databases utilities, VERSANT will look for the name of the machine containing the osc-dbid database system file in this parameter. If this parameter has not been set, VERSANT will look for the osc-dbid file in the location specified on the remote machine.
You can set VERSANT_DBID_NODE@node as an environment variable or with a line in the sysinfo file. The general syntax is:
VERSANT_DBID_NODE@node osc-dbid_machine
Substitute for node the name of remote machine used with dbname@node syntax as an argument to the createdb, removedb, or listdb utilities. Substitute for osc-dbid_machine the name of the machine containing the osc-dbid file that you want to use.
See the chapter "Directories and Files" for an explanation of the osc-dbid file.
You need to specify this parameter only if there are multiple database systems and you want to override the specification for the machine containing the osc-dbid file that has been set on the remote machine named node.
If you supply the name of a remote database when you use the create database, remove database, or list databases utilities, VERSANT will look for the name of the directory containing the osc-dbid database system file in this parameter. If this parameter has not been set, VERSANT will look for the osc-dbid file in the location specified on the remote machine.
You can set VERSANT_DBID@node as an environment variable or with a line in a configuration file. The general syntax is:
VERSANT_DBID@node path
Substitute for node the name of remote machine used with dbname@node syntax as an argument to the createdb, removedb, or listdb utilities. Substitute for path the directory containing the osc-dbid file in terms understandable to the operating system of the remote machine.
For example, if you want to create a database on a remote machine named alpha and specify an osc-dbid directory on a UNIX machine in /usr/local/versant/db:
VERSANT_DBID@alpha /usr/local/versant/db
See the chapter "Directories and Files" for an explanation of the osc-dbid file.
You need to specify this parameter only if there are multiple database root directories on a remote machine and you want to override the specification that has been set on the remote machine named node.
If you specify a remote database in a command or method with the syntax dbname@node, VERSANT will look for a value set by this parameter. If this parameter has not been set, VERSANT will look for the database root directory in the location specified on the remote machine.
You can set VERSANT_DB@node as an environment variable or with a line in the sysinfo file. The general syntax is:
VERSANT_DB@node path
For node, substitute the name of the remote machine. For path, substitute the location of the database root directory in terms understandable to the operating system of the remote machine.
For example, if you want to connect with a database on a UNIX machine named alpha whose database root directory is /db, set:
VERSANT_DB@alpha /db
If you want to connect with a database on an OS/2 machine named beta whose database root directory is c:\db, set:
VERSANT_DB@beta c:\db
CHECKING environment variable turns C++/VERSANT debugging on and off. See the C++/VERSANT Reference for further information.
versant_fe_errlog to the name of the file where errors should be logged. By default, error logging is off.In addition to error number and error message, entries in the error log file also include context information, such as operating system error number, file name, and so on. The exact context information varies from error to error.
This error logging mechanism should not be confused with the functionality represented by the file LOGFILE, which is used to report non-panic VERSANT system errors.
VERSANT_STAT_FILE to the name of a file and then run your application within its scope.
By default, all defined statistics will be collected. You may want to filter the statistics collected to reduce file size and improve application performance. To filter the statistics collected and set other collection parameters, you can use the VERSANT_STAT_STATS, VERSANT_STAT_FUNCS, VERSANT_STAT_TIME, VERSANT_STAT_DBS, and VERSANT_STAT_FLUSH environment variables.
If you set VERSANT_STAT_FILE, statistics will be collected during the time your application is in a database session.
The VERSANT_STAT_FILE environment variable is read each time a session starts, so if your application starts and stops a session, each new session will overwrite the file created by the previous session.
Within the file name, you can use the symbol %p, which will expand to your process identifier number. This can help create differing file names if you exit your application process between sessions, but it is not a guarantee because process id numbers can repeat.
Unlike other VERSANT environment variables, such as VERSANT_ROOT, the VERSANT_STAT_FILE environment variable is not read automatically when an application makes a connection to a database on a local or remote machine. Instead, VERSANT_STAT_FILE is a normal environment variable associated with a particular application process.
If VERSANT_STAT_FILE has been set, statistics are collected and written whenever a collection point is encountered by your application. A default collection point is encountered when your application enters or exits a VERSANT function. You can set additional collection points by inserting o_autostatsenter() and o_autostatsexit() function calls in your code.
Setting VERSANT_STAT_FILE has no effect on statistics collection performed by other mechanisms, such as a separate invocation of the vstats utility.
Setting VERSANT_STAT_FILE is the same as calling o_autostatsbegin() at the beginning of your session, except that uses parameters found in VERSANT_STAT_STAT, VERSANT_STAT_FUNCS, VERSANT_STAT_TIME, VERSANT_STAT_DBS, and VERSANT_STAT_FLUSH.
Even when database replication has been turned on, statistics collection tools and mechanisms operate only on named databases and not on replica databases. To collect statistics for a replica database, you must apply statistics collection mechanisms specifically to the replica database. If the replica database goes down, statistics collection will stop and then restart when the database comes back up.
For an overview of statistics collection and stastics collection usage notes, see the VERSANT Database Fundamentals Manual.
VERSANT_STAT_FILE has been set, by default all statistics are collected and sent to the named file whenever a collection point is encountered. To filter what application, session, connection, and database statistics are sent to a file, set the VERSANT_STAT_STATS environment variable to a space delimited list of the names of the statistics you want to collect.
When statistic names are specified in the environment variable VERSANT_STAT_STATS, they must be entered in lowercase without the leading STAT_ prefix.
For example:
set VERSANT_STAT_STATS=se_net_bytes_read se_net_bytes_written
Setting VERSANT_STAT_STAT has no effect on what statistics are collected by other mechanisms, such as a separate invocation of the vstats utility. However, you can call o_collectstats() and explicitly turn collection off for specific statistics, which will override the values set by VERSANT_STAT_STATS.
For an overview of statistics collection and stastics collection usage notes, see the VERSANT Database Fundamentals Manual.
VERSANT_STAT_FILE has been set, by default all statistics are collected and sent to the named file whenever a collection point is encountered. To filter what function statistics are sent to the file, set the VERSANT_STAT_FUNCS environment variable to a space delimited list of the names of the function statistics you want to collect.
When function names are specified in the environment variable VERSANT_STAT_FUNCS, they must be entered in lowercase, without the leading CAPI_ prefix and with a leading o_ prefix.
For example:
set VERSANT_STAT_FUNCS=o_xact o_select
Setting VERSANT_STAT_FUNCS has no effect on what statistics are collected by other mechanisms, such as a separate invocation of the vstats utility. However, you can call o_collectstats() and explicitly turn collection off for specific statistics, which will override the values set by VERSANT_STAT_FUNCS.
For an overview of statistics collection and stastics collection usage notes, see the VERSANT Database Fundamentals Manual.
VERSANT_STAT_FILE has been set, by default statistics are collected and sent to the named file whenever a collection point is encountered. To set a collection interval, set VERSANT_STAT_TIME to a desired number of seconds. After VERSANT_STAT_TIME has been set, statistics will not be written unless the specified number of seconds have elapsed since the last time that statistics were written.Setting a time interval will improve performance, but the trace-like information on which functions were called will not be recorded. It is not necessary to restrict time intervals to be integers.
For example:
set VERSANT_STAT_TIME=1.5
For an overview of statistics collection and stastics collection usage notes, see the VERSANT Database Fundamentals Manual.
VERSANT_STAT_FILE has been set, by default statistics are collected for all databases to which an application makes a connection, including the session database. To limit statistics collection to specific databases, set this environment variable to a space delimited list of database names. For remote databases, use the syntax dbname@node.For example:
set VERSANT_STAT_DBS=db1@server1 db2@server2
Statistics collection for a named database will begin when a connection is made to it and stop when a connection to it is closed.
To ensure that only application and session statistics are sent to file, set VERSANT_STAT_DBS to an empty string:
set VERSANT_STAT_DBS=
For an overview of statistics collection and stastics collection usage notes, see the VERSANT Database Fundamentals Manual.
VERSANT_STAT_FLUSH exists, each batch of statistics is sent to file as soon as it is generated. This eliminates a possible lag time caused by operating system file buffering, which is useful when you want to view the automatic collection file as it is being generated.For an overview of statistics collection and stastics collection usage notes, see the VERSANT Database Fundamentals Manual.
VERSANT_AUTH to point to the application authentication program.The general format for the environment variable is:
VERSANT_AUTH=program_path
For usage notes, see the chapter "User Authentication" in the VERSANT Database Fundamentals Manual.
This parameter provides support for multiple VERSANT releases.
The environment variable VERSANT_SERVICE_NAME allows you to have multiple VERSANT releases on the same machine and connect to servers from one or the other of these releases selectively from different clients. This is an advanced option and requires careful configuration. This is not something you normally need to do, and we recommend that you do it only with the guidance of VERSANT Technical Support.
In the default installation, the VERSANT connection services daemon listens on TCP/IP port 5019, which has the TCP/IP service name "oscssd" associated with it. In the default case, all clients try to connect to the "oscssd" service on the server machine, and the service name is mapped to a port number by looking up the TCP/IP configuration file /etc/services on the client machine (not the server machine).
By specifying the environment variable VERSANT_SERVICE_NAME, you can cause a client application to connect to a different service name and, therefore, a different port number. Correspondingly, on the server machine you can set up different VERSANT releases to listen on different port numbers and allow a client to connect to a VERSANT server process from the release of their choice.
Example
For example, suppose that you have VERSANT Release 5.0.8 as well as 5.2.0 installed on the same server machine. The following procedure illustrates how to set up the server machine and the client machines for selective VERSANT release execution.
In this example, let's assume that the two releases have different VERSANT_ROOT directories. Suppose that Release 5.0.8 resides at /usr/versant/5.0.8/sun4, and Release 5.2.0 resides at /apps/versant/5.2.0/sun4.
In the following description, the sections on configuring TCP/IP services apply only to Unix machines. On Windows NT, a GUI utility named networkservices.exe is provided to configure Windows machines to run multiple Versant releases. This Windows utility is documented with the other DBA utilities.
5020 for Release 5.0.8 and port 5030 for Release 5.2.0.
Next, select service names to associate with these two ports. For this example, let's choose the service names osc508 and osc520.
3. Edit the /etc/services file.
/etc/services and associate the service names with the chosen port numbers by adding the following two lines:
osc508 5020/tcp # Versant 5.0.8 connection service
osc520 5030/tcp # Versant 5.2.0 connection service
/etc/inetd.conf and associate each service name with the desired release by adding the following two lines:
osc508 stream tcp nowait root /usr/versant/5.0.8/sun4/bin/ss.d in.oscssdosc520 stream tcp nowait root /apps/versant/5.2.0/sun4/bin/ss.d in.oscssd
ss.d executable in the VERSANT bin directory for each release.
inetd that it should refresh its configuration, which we changed in the previous step:
ps -ef | grep inetd # Find the process id of inetd
kill -HUP <inetd-process-id> # Ask inetd to refresh
services file and introduce the new service names and port numbers as in Steps 2 and 3 above. The service names and port numbers for VERSANT services must match each other exactly on the client and server machines.
7. Set VERSANT_SERVICE_NAME on each client machine.
VERSANT_SERVICE_NAME to the value "osc508" before running a Release 5.0.8 application. This will automatically connect the application to the server database process for VERSANT Release 5.0.8.
In an appropriate context on the 5.2.0 client machine, set the environment variable VERSANT_SERVICE_NAME to the value "osc520" before running a Release 5.2.0 application. This will automatically connect the application to the server database process for VERSANT Release 5.2.0.
On UNIX running C shell:
For example:
setenv VERSANT_SERVICE_NAME osc508
On UNIX running Bourne shell:
For example:
VERSANT_SERVICE_NAME=osc508; export
On NT:
For a persistent change, go to Control Panel / System / Environment, enter VERSANT_SERVICE_NAME in the Variable entry box, enter the new service name in the Value entry box, click on on Set and then click on either Apply or OK.
For a temporary change, you can set environment variables in a program. For example:
SetEnvironmentVariable("VERSANT_SERVICE_NAME", "osc508");
putenv("VERSANT_SERVICE_NAME=osc508");
In the above, note that you need to execute both SetEnvironmentVariable(), in order to set the variable in the NT process header, and putenv(), in order to set the variable in the C runtime environment.
Suppose you are running OS/2 on a machine named myMachine, you are accessing another OS/2 machine named alpha and a UNIX machine named beta, and the osc-dbid database system file is on beta in /dbsys.
To specify information about your machine, you must set:
VERSANT_ROOT c:\versant
PATH c:\versant\3_0_5\os2\bin;%PATH%;
LIBPATH c:\versant\3_0_5\os2\lib;%LIBPATH%;
If you want to access software or databases on a remote machine, you must set:
VERSANT_USER silas
If you want to create databases on your local machine, you must set:
VERSANT_DBID_NODE beta
VERSANT_DBID /dbsys
VERSANT_DB c:\versant\mydb
After setting all of these variables, if you invoke createdb as:
createdb myDatabase
Then VERSANT will look at the following variables:
PATH
VERSANT_DBID_NODE
VERSANT_DBID
VERSANT_DB
createdb as:
createdb myDatabase@alpha
Then VERSANT will look at the following variable:
VERSANT_USER To make a connection to alpha.
After making the connection, VERSANT will pass the createdb command to alpha. Machine alpha will then look to its own configuration parameters to decide where to find the osc-dbid file and where to place the new database.
Personal computer example using advanced parameters
Suppose your OS/2 machine is named myMachine and you are accessing another OS/2 machine named alpha and a UNIX machine named beta, and the osc-dbid database system file is on beta in /dbsys.
If you have multiple releases of VERSANT on your local machine or databases created with multiple releases and want to assert the release number, you may optionally set:
VERSANT_REL 3.0.5
If you want to assert the location of the osc-dbid database system file to machines alpha and beta, you may optionally set:
VERSANT_DBID_NODE@alpha beta
VERSANT_DBID@alpha /dbsys
VERSANT_DBID_NODE@beta beta
VERSANT_DBID@beta /dbsys
If you want to assert the location of database root directories to machines alpha and beta, you may optionally set:
VERSANT_DB@alpha d:\versant\db
VERSANT_DB@beta /versant/db
If you have multiple releases of VERSANT on alpha and beta and databases created with multiple releases, to assert the release number and root directories, you may optionally set:
VERSANT_REL@alpha 3.0.5
VERSANT_ROOT@alpha d:\versant
VERSANT_ROOT@beta /usr/local/versant
VERSANT_REL@beta 3.1.4
After setting all of the above parameters, if you invoke createdb as:
createdb myDatabase@alpha
Then VERSANT will look at the following parameters:
VERSANT_REL@alpha
VERSANT_ROOT@alpha
VERSANT_USER
VERSANT_DBID_NODE@alpha
osc-dbid machine.
VERSANT_DBID@alpha
osc-dbid directory.
VERSANT_DB@alpha
This online documentation is confidential and proprietary to Versant Corporation and is licensed to you, or to your organization, pursuant to the terms of an agreement between you and Versant that restricts the use of this documentation. Please refer to the agreement for more information or call Versant at 510-789-1500 with any questions.