SAND CDBMS Tools Reference Guide
Database Server (nserv)

 

Previous Topic:
Overview of Multi-User Database Access
Chapter Index
Next Topic:
Managing Database Server Access

 

Providing Multi-user Database Access with nserv
 

Multi-user Database Access Prerequisites

The database server utility, nserv, provides access to a database for client programs (for example, nisqlm, ndlm, SAND Analytic Explorer, or other ODBC-enabled tools connecting via the Nucleus ODBC driver). Before executing the nserv program, the following activities must be performed:

  1. SAND CDBMS software must be installed on the host computer.
  2. The NUCLEUS environment variable must be set, specifying the SUPPORT directory that contains the nucleus.ini file and seed database (ndb.n00).
  3. The nserv program file should be located in the directory specified in the PATH environment variable. If it is not, a full path specification will be required to invoke nserv.
  4. A [DATABASE instance-name ] section must be included in the server-side nucleus.ini file, specifying the location of the primary database file (.n00 file) for the instance that is to be started. This must be a location that is accessible to nserv. Note that the name of the primary database file must be in lowercase characters: otherwise nserv will fail to start.


Invoking nserv

After the preparatory activities described above have been completed, nserv can be invoked to start a database instance. The nserv invocation is entered from the operating system command prompt, and has the following form:

nserv [ help flag ] connection-name instance-name [ -APPLY update-file-name | -s snapshot-number ]


nserv Invocation Arguments:

help flag
The -h (equivalently -?) flag displays a help screen which describes the nserv syntax and invocation flags. If this flag is used, it should be the only argument supplied to nserv.

connection-name
Specifies the SAND CDBMS connection that will be used by the database instance. The specified connection must have a corresponding [CONNECTION connection-name] section in the server-side nucleus.ini file, indicating the host name of the computer on which the nserv program is running (the default is the current host name) and the port number (the default is 5001) used to connect to it. Client programs must specify the same connection name when connecting to the database instance. 

instance-name
Specifies the name of the database instance to be started. The specified instance must have a corresponding [DATABASE instance-name] section in the server-side nucleus.ini file, indicating at least the location of the primary database file (.n00 file) for the instance. For Real and Persistent Mode operation, the instance name will be the same as the real database name. When operating in Virtual Mode, the instance name does not have to be the same as the name of the database file.

If instance-name refers to a database that does not currently exist, a database file with the specified name will be created in the location specified by the DatabasePath parameter in the [DATABASE instance-name] section of the nucleus.ini file (unless RunMode is set to Virtual or Persistent). The database instance will then be started.

-APPLY
(Virtual Mode only)
This command option is used only when starting the primary virtual instance of a database. It instructs nserv to write the changes contained in the specified Update File to the real database when starting the database instance, thereby making these changes permanent. The APPLY keyword must be prefixed with a hyphen ( - ), and must be followed by the name of the Update File containing the changes to be applied to the database. Consult the Virtual Mode Operations section of the SAND CDBMS Administration Guide for more information.

update file name
(Virtual Mode only)

This argument is included only when starting the primary virtual instance of a database, and then only in conjunction with the -APPLY command option. It must be included after the -APPLY keyword to specify the Update File containing the changes to be written to the real database upon instance startup. Consult the Virtual Mode Operations section of the SAND CDBMS Administration Guide for more information.

-s snapshot-number
(Persistent Mode only)
This command option may be used when starting a database instance in Persistent (Time Travel) mode. It specifies the database snapshot (version) to be made available to clients. The initial state of the real database is represented by snapshot number 0.0; the snapshot number is increased by 1 each time a KEEP CHANGE operation is performed on the database in Persistent Mode. If the -s option flag is not included in the nserv invocation for a Persistent Mode database instance, the most recent snapshot is used. Consult the Persistent Mode Operations section of the SAND CDBMS Administration Guide for more information.


nserv Output

After execution of the program invocation, nserv displays the following message, indicating the port assigned to the specified SAND CDBMS connection:

Listening on port n...

On UNIX/Linux systems, immediately under the port information, nserv’s virtual memory usage will be displayed (VM limit x, current usage y, and usage as a percentage of the limit z):

STARTUP: VMEM: x MB limit with y MB in-use (z%)

If a new database is being started (Real Mode only), nserv displays the following message while the internal structure of the database is being set up:

Creating new database catalog structure

When the instance is started in Virtual or Persistent Mode, nserv displays the operating mode.

Finally, when instance startup is complete, nserv displays the following message:

Accepting connections

 

Previous Topic:
Overview of Multi-User Database Access
Chapter Index
Next Topic:
Managing Database Server Access