Configuring the eloqdb6 service

3 Installing Eloquence on Windows

Configuring the eloqdb6 service

The eloqdb6 is the Eloquence database server. Eloquence uses a client/server database approach.

In order to run the eloqdb6 service it is required to adapt your system configuration. This involves the following steps:

Registering the eloqdb6 server with the Windows operating system
Configuring the eloqdb6 TCP service
Configuring the eloqdb6 server
Creating the database environment
Configuring the eloqdb6 server startup

Registering the eloqdb6 server with the Windows operating system

The eloqdb6 is installed as a Windows service. The installation program installs the eloqdb6.exe executable in the Windows system directory (C:\Windows\System32). In addition, it is automatically registered with the Windows Service Control Manager.

NOTE: Manual registration of the eloqdb6 service with the Windows Service Control Manager is usually not required since the installation program performs a default registration. Unless you are interested in the registration and unregistration details you can skip this section.

In order to manually register the eloqdb6 server with the Windows Service Control Manager you must execute eloqdb6.exe with the -install argument:

Log on as Administrator.
Open a Command Prompt window.
Execute the command: eloqdb6 -install. This makes the eloqdb6 server available to the Windows Service Control Manager. The service name is "eloqdb6".

NOTE: To manually unregister, use the command: eloqdb6 -remove. Note, however, that this is normally not required since the installation program takes care of unregistering the eloqdb6 service during product update or uninstallation.

Configuring the eloqdb6 TCP service

For eloqdb6, the installation program adds the following default TCP service to your local SERVICES file:

eloqdb          8102/tcp    # Eloquence A.06.xx data base server

In rare cases it might be necessary to modify this standard configuration, for example if the port number does not match the one configured on other systems. Please refer to the previous section Modify the standard configuration of Eloquence service names for details.

Configuring the eloqdb6 server

The eloqdb6 server is configured by editing the eloqdb6.cfg configuration file. It is located in the etc subdirectory of your Eloquence installation, for example at C:\Program Files\Eloquence\etc. This file provides complete inline documentation and is included at the end of this chapter for your reference.

The default configuration is not optimized for performance and does not handle a large number of concurrent connections. Therefore, you should adjust the following parameters in the eloqdb6.cfg configuration file to your requirements:

Section [Config], parameter Threads

This parameter specifies how many connections to the database server can be established concurrently. The default is 40 which means that a maximum of 40 users can access the database at the same time. Multiple programs accessing the database count as multiple connections, while accessing multiple databases from within the same program counts as one single connection.

Section [Config], parameter BufferCache

The recommended minimum value is 64 (megabytes). A higher value is recommended. The current limit is approx. 1 gigabyte. The default and minimum buffer cache size is 5 Megabytes which may lead to bad performance.

Section [Config], parameter CheckPtSize

Whenever the transaction journal exceeds this size (in megabytes), eloqdb6 performs an internal checkpoint operation to recycle the journal. The default size is 10 megabytes which probably causes the checkpoint to happen too often, causing a performance impact. It is recommended to set this parameter to 20 or higher.

NOTE: If the configuration of a running eloqdb6 service is changed, the service must be restarted to activate the new configuration.

Creating the database environment

A database environment consists of at least a primary data volume and a transaction log volume. These must be created on a local disk before the eloqdb6 can be started for the first time.

Volume files should be created on NTFS file systems only. If you use a FAT file system, be aware that it limits the maximum file size to 4 gigabytes, while NTFS allows it to grow until its hard size limit of 128 gigabytes.

Additional data volumes can be created at any time to extend the available database storage. Additional transaction log volumes can be added as well, but it is unlikely that these will ever be used because the purpose of a log volume is to hold temporary data only.

The maximum number of volume files in a database environment is 255 which is equivalent to a maximum database storage size of 31.75 terabytes (254 data volumes and 1 log volume).

It is recommended to choose a dedicated directory to hold all volume files belonging to a particular database environment. The following example assumes that the initial volumes are created in the C:\data\db directory:

Open a Command Prompt window.
Change to the directory where the volumes shall be created:

C:
cd \data\db

Create the initial data volume:

dbvolcreate data.vol

Create the initial transaction log volume:

dbvolextend -t log log.vol

Both files are created with their initial minimum size which is 2.5 megabytes. They will grow on demand until they reach their maximum size. The minimum and maximum size and the amount by which the files shall grow can be configured either at creation time or afterwards with the dbvolchange utility.

To view the available command line options, use:

dbvolcreate -help
dbvolextend -help
dbvolchange -help

The dbvolcreate and dbvolextend utilities automatically maintain the list of volume files in the [Volumes] section of the eloqdb6.cfg configuration file.

Configuring the eloqdb6 server startup

After the eloqdb6 server has been registered with the Windows Service Control Manager it can be accessed using the Services applet.

NOTE: The following instructions refer to the default "eloqdb6" service name. If multiple instances of the eloqdb6 service are installed they are separately listed and also separately configured in the Windows Service Control Manager.

NOTE: Multiple eloqdb6 instances are covered in detail in the section Setting up multiple eloqdb6 instances below.

Windows Server 2003 or XP:

Open the Windows Control Panel
Select Performance and Maintenance
Select Administrative Tools
Open the Services applet

Windows 2000:

Open the Windows Control Panel
Select Administrative Tools
Open the Services applet

Windows NT:

Open the Windows Control Panel
Open the Services applet

Locate the eloqdb6 entry in the list and select it with the mouse. On Windows Server 2003/XP/2000, open the Properties dialog either from the menu or using the context menu (right mouse button). On Windows NT, click the Startup... button to open the Startup Options dialog:

If you want the eloqdb6 server to be automatically started each time Windows is restarted, you should select the Automatic Startup Type. This is the recommended setting.
If you select the Manual Startup Type, you have to manually start the eloqdb6 server each time Windows is restarted.
By default, the Log On As option is set to "System Account". This is the recommended setting. Alternatively, you can specify a different account using the This Account option.

After you have setup the startup options, you can define additional arguments for the eloqdb6 server as an option. If a single instance of the eloqdb6 server is used this is usually not required since all settings are normally provided in the eloqdb6.cfg configuration file. However, this can be used to track down problems (e.g. starting the eloqdb6 server temporarily with different log options) and is mandantory if you have multiple eloqdb6 instances.

Possible arguments are:

 -c name    = configuration file
 -d flags   = log flags
 -l name    = log file name
 -s name    = service name (tcp/ip transport)

Option	Description	Equiv.*
-c name	Specifies the configuration file name
-d flags	Specifies the server log flags.	LogFlags
-l name	Specifies the server log file.	LogFile
-s name	The service name (as defined in SERVICES) or the port number where the server should listen for requests. The default value is eloqdb.	Service

*Equivalent configuration file directive.

For example, if you wish to specify a different configuration file (required for additional eloqdb6 instances), you could enter the following into the Startup Parameters field:

  -save -c "C:\Program Files\Eloquence\etc\eloqdb6.instance.2.cfg"

which causes this eloqdb6 server instance to use the eloqdb6.instance.2.cfg configuration file in the C:\Program Files\Eloquence\etc directory. Note that the argument must be put into quotes because the configuration path contains a space.

The leading -save argument makes this command line persistent so that the same arguments are used each time this eloqdb6 server instance is started. If you do not specify the -save argument this command line will be used only once.

If you want to make sure that the command line is empty and that any persistent command line is deleted, just specify -save without any additional arguments.

NOTE: After having entered a command line, use the Start button from within the same dialog, otherwise your command line will not come into effect. In particular, if you use the OK button, the dialog will close without having started the service, i.e. your command line never being applied.

At this point, everything is configured and the eloqdb6 server can be started:

Windows Server 2003/XP/2000:

Select the eloqdb6 entry in the list (or the additional instance you want to start), then choose Start either from the menu or using the context menu (right mouse button).

Windows NT:

Select the eloqdb6 entry in the list (or the additional instance you want to start), then click the Start button.

If you did not specify a log file, the eloqdb6 server will write log messages to the Windows Event Log. In case the eloqdb6 does not start, the Event Log will probably contain an error message pointing out the cause of the problem. You should also periodically check the Event Log in order to get aware of possible configuration problems:

Windows Server 2003 or XP:

Open the Windows Control Panel
Select Performance and Maintenance
Select Administrative Tools
Open the Event Viewer applet
Select the Application Log

Windows 2000:

Open the Windows Control Panel
Select Administrative Tools
Open the Event Viewer applet
Select the Application Log

Windows NT:

Select Programs - Administrative Tools in the Windows Start Menu
Start the Event Viewer
From the Log menu, select Application

Having started the eloqdb6 service for the first time after installation, the Application Log should already contain a few entries noting that the eloqdb6 was successfully installed and started.

Controlling the eloqdb6 server from the command line

The net start and net stop system commands can be used to start and stop the eloqdb6 server from the command line. This is equivalent to starting and stopping the server using the Windows Services applet as explained in the previous section.

Command syntax:

net start SERVICE
net stop SERVICE

where SERVICE is either eloqdb6 or the name of an additional instance, for example:

net start eloqdb6
net stop eloqdb6

The eloqdb6 HTTP status display

When ServiceHttp is defined in the eloqdb6.cfg configuration file, you can use a web browser such as Mozilla, Netscape or Internet Explorer to view the configuration and state of the eloqdb6 process in your network.

To access the eloqdb6 server, you provide an URL like this:

http://server:port/

where server is the host name or IP address of the system running the eloqdb6 server and port is the port number used for ServiceHttp in the eloqdb6.cfg file.

NOTE: Each eloqdb6 instance on the same system requires an unique HTTP port number.

Setting up multiple eloqdb6 instances

Multiple instances of the eloqdb6 server can coexist on the same system. This makes sense if multiple database environments should be kept separate from each other, either to keep the databases in separate namespaces or simply to maintain discrete database storage.

The following steps are required to setup an additional eloqdb6 server instance:

Each instance requires a separate service name, i.e. a separate entry in the Windows Service Control Manager. You can use any name you like, although we recommend that it starts with "eloqdb6".

The additional service name is specified after the -install or -remove arguments, respectively (see the previous section Registering the eloqdb6 server with the Windows operating system).

For example, to register an additional instance named "eloqdb6.instance.2", open a Command Prompt window and execute the command:

eloqdb6 -install eloqdb6.instance.2

If the service name contains spaces it must be enclosed in quotes. However, to retain compatibility with legacy Windows NT systems, any space is converted into an underscore character, so we do not recommend to use spaces in a service name.

NOTE: During product update, the installation program does not retain additional eloqdb6 instances. After an update has been applied, only the standard "eloqdb6" service name is present. Any additional instances must be re-created manually.

Each eloqdb6 instance needs a separate configuration file. You can copy either the configuration of any existing instance or the eloqdb6.cfg.sam template file located in the etc subdirectory of your Eloquence installation (for example:
C:\Program Files\Eloquence\etc\eloqdb6.cfg.sam).

In this example, we create a new configuration file named eloqdb6.instance.2.cfg in the default C:\Program Files\Eloquence\etc configuration directory. This is not mandatory, the configuration file may have any name and can be located anywhere.

C:
cd "\Program Files\Eloquence\etc"
copy eloqdb6.cfg.sam eloqdb6.instance.2.cfg

Next, the new configuration file must be edited. Besides the parameters mentioned in the previous section Configuring the eloqdb6 server, the following parameters must be adjusted:

* Section [Server], parameter Service

Each instance requires an unique TCP service name or port number. You can either configure a dedicated service name in your local SERVICES file (please refer to the previous section Configuring the eloqdb6 TCP service for details) or simply enter an unique port number.

* Section [Server], parameter ServiceHttp

If you use the eloqdb6 HTTP status display, you are required to configure an unique TCP service name or port number for each eloqdb6 instance.

* Section [Server], parameter LogFile (optional)

By default, all eloqdb6 log messages are written to the Windows Application Event Log. Each log message is labeled with the name of the originating eloqdb6 instance. However, it might be more convenient to configure a separate log file for each instance. This log file could be located within the dedicated, instance-specific directory (see below), for example:

LogFile = C:\data\db\instance.2\eloqdb6.log

When started, this eloqdb6 instance will create this file and write all log messages to it. This is a plain text file which can be viewed with any text editor.

NOTE: If you copied the configuration of an existing instance, it is required that you manually delete all volume references at the end of the file below the [Volumes] section header.

Create the instance-specific database environment. You do this according to the previous section Creating the database environment, but you use the -c command line option to refer to the instance-specific configuration file:

* Open a Command Prompt window.

* Create the instance-specific directory. We recommend to create a dedicated directory for each instance where the instance-specific files are located:

C:
cd \data\db
mkdir instance.2
cd instance.2

* Create the initial data volume (the following command must be entered as a single line):

dbvolcreate
-c "C:\Program Files\Eloquence\etc\eloqdb6.instance.2.cfg"
data.vol

* Create the initial transaction log volume (the following command must be entered as a single line):

dbvolextend
-c "C:\Program Files\Eloquence\etc\eloqdb6.instance.2.cfg"
-t log log.vol

In this example, the argument to the -c command line option refers to the instance-specific configuration file located in the current directory. Note that it must be put into quotes because the configuration path contains a space.

Start the new eloqdb6 instance for the first time, setting-up a persistent command line using the -c command line option to refer to the instance-specific configuration file (for details, please refer to the previous section Configuring the eloqdb6 server startup):

Windows Server 2003 or XP:

* Open the Windows Control Panel

* Select Performance and Maintenance

* Select Administrative Tools

* Open the Services applet

Windows 2000:

* Open the Windows Control Panel

* Select Administrative Tools

* Open the Services applet

Windows NT:

* Open the Windows Control Panel

* Open the Services applet

Locate the new eloqdb6 instance in the list and select it with the mouse. On Windows Server 2003/XP/2000, open the Properties dialog either from the menu or using the context menu (right mouse button). On Windows NT, click the Startup... button to open the Startup Options dialog.

First, choose the Startup Type you want to configure for this instance (Manual or Automatic).

Next, in the Startup Parameter input field at the bottom of the dialog, refer to the instance-specific configuration file, using the absolute path (which must be put into quotes because it contains a space):

-save -c "C:\Program Files\Eloquence\etc\eloqdb6.instance.2.cfg"

Finally, click the Start button. Do not use the OK button to leave the dialog. The command line is only applied if you immediately start the service. If you click OK, the dialog will close without having started the service, i.e. your command line never being applied.

The -save option specifies that this command line is to be saved into the Windows registry. Therefore, it is not necessary to enter this command line ever again. It remains associated with this eloqdb6 instance until a different command line is registered or the instance is removed.

The new instance should now be up and running. You can start and stop it using the Windows Services applet. You can also control it from the command line using the net start and net stop system commands:

net start eloqdb6.instance.2
net stop eloqdb6.instance.2

To access a database in an additional instance, specify the instance-specific service name or port number in addition to the database name. Those utilities which do not expect a database name instead provide the -h command line option. Also, the EQ_DBSERVER environment variable can be set to specify the default instance.

The following examples assume that an additional instance was configured to use the port number 8201. They illustrate different ways to address the same instance:

schema -h :8201 db.schema.txt
dbcreate :8201/db
set EQ_DBSERVER=:8201
schema db.schema.txt
dbcreate db

Eloquence Installation and Configuration - 29 OCT 2004