Eloquence - Getting Started

A practical approach to the Eloquence B.08.00 database on HP-UX

Revision: 8.0 - Dec 2009

This document shows how to install and configure the Eloquence database in the HP-UX platform in a few simple steps. For a detailed description, please refer to the Eloquence Installation and Configuration Manual and the B.08.00 release notes.

A separate document exists that covers the Windows platform specifics. As Linux is simlar in priciple to HP-UX, most of this document applies to Linux as well.

Contents


Installation

Obtaining the product

The Eloquence product is available for download from the Eloquence web site . This is the preferred distribution method. A CD-ROM media can be ordered as an alternative for an additional charge. 

   http://eloquence.marxmeier.com/download/B0800/
Please select appropriate subdirectory, according to the target platform (eg. hpux for HP-UX). As an alternative you may access the Eloquence FTP server at 
   ftp://ftp.marxmeier.com/eloq/B0800
Note: Please take care to use binary mode for download with ftp.

For the HP-UX platform, the following depot files are available:

Eloquence-B0800-*-pa20.depot.gzPA-RISC 2.0 This is the default installation depot for PA-RISC based systems. It should work an almost all PA-RISC systems and supports both 32 and 64 bit applications. This build requires HP-UX 11.11 or later.
Eloquence-B0800-*-pa11.depot.gzPA-RISC 1.1 This installation depot is intended to support historic PA-RISC hardware and should only by used on 32 bit PA-RISC systems. This build requires HP-UX 11.11 or later.
Eloquence-B0800-*-ia64.depot.gzItanium This Eloquence depot file should be used for HP Integrity systems (Itanium platform). It installs both 32 bit and 64 bit components and also includes limited support for PA-RISC applications using the ARIES PA-RISC emulation. This build requires HP-UX 11.23 or later.

The asterisk (*) denotes the version of the installation archive. Higher numbers indicate a newer installation archive.

For the Linux platform, the following RPM files are available:

Eloquence.B0800-*.i686.rpm   x86  Eloquence rpm file (x86, 32 bit)
Eloquence.B0800-*.x86_64.rpm  x64  Eloquence rpm file (x86_64, 64 bit). This build requires a 64 bit OS running on AMD64/EM64T (x86_64) based systems. Includes support for 32 bit x86 applications.
Eloquence.B0800-*.ia64.rpm  ia64  Eloquence rpm file (Itanium2, 64 bit). Includes support for 32 bit x86 applications.

The asterisk (*) denotes the version of the RPM archive. Higher numbers indicate a newer installation archive.


Obtaining Eloquence product patches

Eloquence patches are provided to either fix a defect or limitation that was found after release and/or to add new functionality. Installation of the current product patches is strongly recommended.

For an overview on available patches, please refer to the Eloquence B.08.00 patch overview document. 

   http://eloquence.marxmeier.com/support/B0800/patch/index.html

To simpify new installations a patch bundle is available that combines the recommended patches for various Eloquence product components in a single archive.


HP-UX patches

The following HP-UX patches are required to use Eloquence. Please install these patches (or successors) on your HP-UX system.

HP-UX 11i v2 (11.23)

  • PHCO_37940 - pthread library cumulative patch
  • PHNE_37670 - cumulative ARPA Transport patch
  • PHKL_37121 - ksleep kwakeup performance cumulative patch
  • PHCO_37115 - libxcurses cumulative patch
  • PHKL_32542 - swapcontext(), gethrtime()

HP-UX 11i v1 (11.11)
  • PHNE_37671 - cumulative ARPA Transport patch
  • PHCO_36946 - libxcurses cumulative patch
  • PHCO_35743 - libc cumulative patch (PHCO_23093 or newer)
  • PHKL_34926 - Buffer cache performance improvement
  • PHKL_34534 - vPar,callout, abstime, sync perf, wakeup
  • PHCO_33282 - pthread library cumulative patch
  • PHKL_30542 - eventport (/dev/poll) pseudo driver PHKL_28489 - fixes erroneous EFAULT
You may need additional HP-UX patches but these are known to fix problems encountered with Eloquence.

HP-UX patches can be obtained from the Internet at the HP IT resource center site:


Current information on HP-UX patches (required for Eloquence) is available on the Eloquence web site.


Installation of the Eloquence product on HP-UX

Below is a short overview on installing Eloquence on HP-UX. For other platforms, please refer to the INSTALL file.

Eloquence on HP-UX requires HP-UX release 11.11 or later on PA-RISC and HP-UX release 11.23 on Itanium. Eloquence is installed in the /opt/eloquence/8.0 directory. Configuration files are located in the /etc/opt/eloquence/8.0 directory.

Eloquence installation files downloaded from the Eloquence ftp server are compressed with gzip and must be uncompressed before installation. Eloquence is available as a depot package and is installed with swinstall.

As "superuser" (root) follow the steps below to install the Eloquence software.

  1. Unpack the archive at a temporary location 
       gzip -d Eloquence-B0800-*-pa20.depot.gz
    This uncompresses Eloquence-B0800-*-pa20.depot.gz to Eloquence-B0800-*-pa20.depot. The compressed archive file is deleted.

  2. Run "swinstall" by typing: 
       /usr/sbin/swinstall -s /tmp/Eloquence-B0800-*-pa20.depot
    where /tmp/Eloquence-B0800-*-pa20.depot is the absolute path of the Eloquence-B0800-*-pa20.depot file.

  3. In the Software Selection Window, select/highlight the Eloquence product then choose the "Mark for Install" item from the Actions menu. The "Marked?" column will automatically be set to "Yes".

  4. Select the "Install (analysis...)" item from the Actions Menu. When the analysis is finished with no error, i.e. Status:Ready, choose OK.

  5. Choose Yes in the Confirmation window to begin the actual installation process.
    When the installation is completed, a dialog is displayed to notify you that the install task is completed. You may exit then.


Installation of Eloquence product patches

Below is a short overview on installing Eloquence product patches on HP-UX.

To install a patch (or patch bundle) it simply is uncompressed and unpacked with gzip and tar. The gzip utility is included with HP-UX. Installation requires root privileges. 

  cd /opt/eloquence/8.0
  gzip -dc /path/to/PE80-<id>-hpux-<arch>.tar.gz | tar xf -

Eloquence patches include a README file that is placed in the share/doc subdirectory for later reference.


Configuring the Eloquence product
  1. Add the supplied license keys to the /etc/opt/eloquence/8.0/license file. We recommend that you comment out any existing license keys. If you created a temporary license during installation you may skip this step and add the permanent license later. Use the /opt/eloquence/8.0/etc/chklic utility to verify the license file.

  2. Make sure the service names and port numbers added to your /etc/services file during installation are appropriate. The important one is the eloqdb service.

    In your /etc/services file should be a line like below. Please make sure the specified port number is available on your system: 

       eloqdb      8102/tcp # Eloquence data base server

  3. Create a user and a group eloqdb. The account may be disabled as it is not needed for login. It is only used as the owner of the database files.

  4. Modify the file /etc/rc.config.d/eloquence8 as below: 
       START_ELOQSD=0
   START_ELOQDB=1
    This ensures that the Eloquence data base server starts automatically each time the system is restarted and also disables other Eloquence services that are not used with the database.

  5. A more recent template configuration file may be available through a previously installed patch. When starting a new server instance it is recommended to copy the most recent server config file template. 
       # cd /etc/opt/eloquence/8.0
   # cp /opt/eloquence/8.0/newconfig/config/eloqdb.cfg eloqdb.cfg
  6. Modify the configuration file /etc/opt/eloquence/8.0/eloqdb.cfg as outlined below: 
       [Server]
   ...
   UID = eloqdb
   GID = eloqdb
   EnableIPC = 2
   SyncMode = 1

   [Config]
   Threads = 100
   BufferCache = 64
   CheckPtSize = 25
    The configuration above allows for 100 concurrent users using a 64 MB cache. You should have at least 128 MB memory in your HP-UX system.

    Note: When changing a configuration item please remove any leading hash (#) signs, they are used to mark the line as a comment.

Additional recommended configuration options:

  • If the ServiceHttp configuration item is set, a web browser can be used to monitor data base server status, such as active connections or data base locks. 
       ServiceHttp = 8103
    In this case enter the following URL after the eloqdb process is active. 
       http://server:8103/
    where server is the host name or IP address of your server system and 8103 is the value specified with the ServiceHttp configuration item.

  • If you have sufficient memory you should consider increasing the value of BufferCache to a larger value, such as 256 MB. In general, the more cache memory is available for the data base (without starving the operating system or applications) the better is its performance for cached responses. The setting below defines a data base cache size of 256 MB. 
      BufferCache = 256

  • For large data bases you might also consider setting IOThreads to 8 instead of the default value of 4. IOThreads defines the number of concurrent I/O requests which are processed at one time. With slow disk performance and large data sets, having more requests active improves performance.

Configuring the HP-UX kernel

 Enabling the use of shared memory for the Eloquence data base requires configuring the HP-UX kernel parameters. The following changes to the HP-UX kernel parameters are recommended for one Eloquence database server instance with a 100 concurrent user configuration:

In SAM, select -> Kernel Configuration -> Configurable Parameters Change the kernel parameters as outlined below and then build a new kernel.

  • set the 'semmni' parameter to at least 120 (*1)
  • set the 'semmap' parameter to semmni+2
  • set the 'semmns' parameter to at least 140 (*1)
  • set the 'semume' parameter to at least 120 (*2)
  • set the 'maxdsiz' parameter to at least 0x08000000 (128 MB)
Each process connecting to an Eloquence database server requires a semaphore.

Notes:

  • *1 - This value is influenced by the total number of configured threads in all db instances on the system
  • *2 - This value is influenced by the configured number of threads for the largest db instance on the system

This is documented in the Installation and Configuration manual:
http://eloquence.marxmeier.com/doc/html/manuals/install/inst-16.html


Setup the Eloquence data base environment

 The next step is to create the database environment and to bring up the data base server. The example below assumes disk space for the databases is allocated in the /var/opt/eloquence/8.0 directory. You may choose another location as you see fit.

As "superuser" (root) execute the commands below: 

   mkdir /var/opt/eloquence/db
   dbvolcreate /var/opt/eloquence/db/data01.vol
   dbvolextend -t log /var/opt/eloquence/db/log.vol
This will create two Eloquence volume files.

The dbvolcreate and dbvolextend commands are documented in the data base manual:
http://eloquence.marxmeier.com/doc/html/manuals/dbms/dbms-41.html
http://eloquence.marxmeier.com/doc/html/manuals/dbms/dbms-42.html

The Eloquence data base does not reside in the file system but uses volume files which reside in the file system as a container for the data and structural information. Please note that you need both a data volume and a log volume in order to start the data base server.

A single volume file by default is limited to 2 GB and you may want to either change the configuration or create additional data volumes. To create additional data volumes execute something like below (when the server is not active): 

  dbvolextend -t data /var/opt/eloquence/db/data02.vol
  dbvolextend -t data /var/opt/eloquence/db/data03.vol
  ...
This creates the additional volume files data02.vol and data03.vol.

To start the Eloquence data base server process, enter the command below as "superuser" (root): 

   /sbin/init.d/eloq8 start
Please verify the server process is active. You should get a process listing like below: 
$ ps -ef|fgrep eloqdb
  eloqdb 29171     1  0  Jul  3  ?        671:40 eloqdb32: active
If the data base server did not start, please take a look at the syslog (file /var/adm/syslog/syslog.log) for any error messages.


Creating a data base

 Please transfer your data base schema from your HP3000 to the HP-UX system.

Then run the schema processor as below: 

   schema -T schemafile
Where
  • -T specifies this as a TurboIMAGE schema file
  • schemafile is the schema text file
As an alternative, you may also run the schema processor with the dbschema command which calls the Eloquence schema processor with the -T option.

The Eloquence schema processor should be fully compatible with HP e3000 schema files. If you encounter any problem, please contact the Eloquence support at support@marxmeier.com. If possible please attach the schema file. An error message -700 indicates the Eloquence data base server has not been started. 

(18095) X0: Unable to connect remote host. [111] Connection refused
*** (FATAL) Unable to connect to database server localhost:9999
*** (FATAL) REMOTE: Unable to connect server [-700:-2]
Note: If you omit the -T option the schema file is understood as an Eloquence schema file and schema may still succeed. However Eloquence item sizes are specified in bytes while TurboIMAGE uses either halfwords, bytes or nibles, depending on item type so the resulting data base is likely different from what you expect.

After running schema, you need to create the database. 

   $ dbcreate database
Where
  • database is the database name


Moving your data base

 Moving your data base to HP-UX involves the following steps:
  1. Install the DBEXPORT utility on HP3000
  2. Export the data base
  3. Transfer the schema file and the export files to the target system
  4. Create and import the data base on Eloquence
All of this is covered in detail in the Eloquence TurboIMAGE database migration document.


© Copyright 2002-2009 Marxmeier Software AG, Germany. All rights reserved.