NPR/DBC Installation Notes - DBC 3.5 and DBC 3.6

Content

Overview

This document outlines installation notes for NPR/DBC 3.5 and NPR/DBC 3.6 only.
All other versions shall refer to its respective documentation sets.

DBC is comprised of 2 components: server and client. DBC server runs on UNIX server, and DBC client runs on PC.

The supported platforms for DBC server are:
HP-UX 11.11i
SOLARIS 9, 10

The support platforms for DBC client:
Windows 2000
Windows NT
Window XP

DBC Client and Supported Applications

DBC client is compatible with the following applications:
Crystal Reports (Version 10)
Actuate (Version 8)
Business Objects (Version 5.1.3)
Microsoft Office applications
Microsoft Access
Microsoft Excel
Microsoft Word (using Microsoft Query)

Note:
Other applications which are fully compliant with Microsoft ODBC 3.0 may work but are not currently supported.

Compatibility Versions between NPR and DBC

In general, DBC 3.4 (and above) is compatible with NPR 3.3 (and above).

Since NPR 3.5.0 and above, it is recommended that the similar version of DBC is installed.

The table bellow shows the compatibility between NPR and DBC:

Table 1: NPR and DBC Compatibility

NPR Version	DBC Version
NPR 3.5.0	DBC 3.5.0
NPR 3.5.1	DBC 3.5.1
NPR 3.5.2	DBC 3.5.2
NPR 3.6.0	DBC 3.6.0

Installation Process

The installation process comprises three phases:

Pre-installation Tasks: The tasks need to be performed before installing the DBC.

Installing DBC (Server) on a UNIX server: Install the DBC server, including the FLEXlm™ licensing software, if applicable. FLEXlm™ licensing software is applicable for NPR/DBC 3.5.0 and below.

Installing DBC (Client) on a PC: Install the DBC client on each PC.

Note:
NPR shall have been installed prior to installing DBC.

Pre-installation Tasks

Install the FLEXlm licence file

This section is applicable for NPR/DBC 3.5.0 and below only.

Install the licence file supplied by Vallent in the FLEXlm licence file directory. The licence file contains the metrica_odbc licence FEATURE. The Licence Manager can not be run without first installing the licence file.

Note:
If a FLEXlm™ Licence Manager has not been previously installed, please refer to Appendix A: FLEXlm Software Installation for details to install the FLEXlm™ licensing software.
The detailed information on using FLEXlm is available in the FLEXlm End User Manual, which can be downloaded from the GLOBEtrotter web site at www.globetrotter.com.

The licence file is a small text file and will typically be supplied by e-mail. If user is to update the licence, directions for updating an existing file will be supplied within the e-mail message.

Copy the licence file to the licences directory, for example:
cp dbc.lic $FLEXLM_DIR/licences


Edit the following lines in the licence file:
– SERVER: enter the node name of the licence server. For example:
SERVER zeus ANY

In this example the server name is zeus, and any port is to be used.

– VENDOR: enter the name of the vendor, followed by the path of the vendor daemon. For example:
VENDOR adc_lmd /npr3.3/flexlm/bin/adc_lmd

In this example, NPR version 3.3 is installed.

Note:
Do not edit any FEATURE lines as this will invalidate the licence file.

Once the licence file is installed, the Licence Manager will have to be started, or restarted if it is currently running.

To start the Licence Manager type:
./S900adcflexlm start

To restart the Licence Manager type:
./S900adcflexlm restart

Installing DBC (Server) on a UNIX server

Copy DBC Files to Server

This section describes how to install DBC from the supplied media. The tape contains a single tar file.
dbc1.x.tar
where:
x is the release version number.

Log on to UNIX server using the account which will run DBC server.
Create a temporary directory to hold the contents of the tar file, and change to this directory. This directory will be referred to as <temp_dir> in the sections that follow.
Use the tar command to untar dbc1.x.tar into the temporary directory, for example:
tar xvf dbc3.4.tar

Install DBC Files

Ensure that the set-up scripts used to set the environment for NPR has been run successfully. Ensure that the $TQL_SERVER_DIR and $TQL_CLIENT_DIR are set, and that $TQL_SERVER_DIR/bin and TQL_CLIENT_DIR/bin are on the current path.

Change directory to the <temp_dir>/INSTALL directory.

Invoke the install script using the command:
./ALL.inst

The install script prompts a number of questions. Users can either type in an answer to each question, or press Return to use the default answer displayed after the question.

Install Script Prompts	Default
Installation directory	/LOCAL/metrica/dbctemp
TQL client directory	/LOCAL/metrica/Metrica5.0/tqlclients
NPR directory	/LOCAL/metrica/npr3.3_wireless
Is this an evaluation copy?	There is no default value. Users must enter eiter Yes or No.

The script now displays the filesets to be installed and asks if users wish to continue. Enter Yes to continue, or No to abort the installation.

As each fileset is installed, press Return to continue.

Users must update each database to be used, so that it is compatible with DBC. For each database, first change directory to the installation directory:
cd $NPR_DIR/install.dbc

Enter:
sh ./dbc_db_upgrade <databasename> <username> <password>

For example:
sh ./dbc_db_upgrade npr3db dba dba

This adds the sqltypes database table. This may take some time to complete.

Note:
You must have root privileges to complete the installation. Use a command such as ‘su root’ to become the root user.

Setup the Internet Daemon

Define the port number to be used by DBC for client/server communication. It is recommended that port number 2622 is used. This is a Registered Port that is reserved for DBC by the Internet Assigned Numbers Authority (IANA). Using this port reduces the possibility of conflicts with other network services.

Depending on users’ network setup, the following are options to add an ODBC entry:
Use a text editor to edit the /etc/services file, for example:
vi /etc/services

Then, add a line to associate a service name with a TCP/IP port. For example:
odbc 2622/tcp #Vallent corp odbc service on port 2622

If you are using NIS™, ask your system administrator to add an equivalent entry for ODBC

Use a text editor to edit the/etc/inetd.conf file, for example:
vi /etc/inetd.conf

Add a line to execute the startup file, for example on an HP machine this might be:
odbc stream tcp nowait metrica <tql_client_dir>/dbc/HP700_SV/startup startup

where:
<tql_client_dir> is the TQL client directory.

If DBC runs on Solaris 10, run the following commands:
inetconv
svccfg -s <FMRI (Fault Management Resource Identifier)>
setprop inetd_start/working_directory = astring: /tmp
svcadm restart inetd

For example:
inetconv
odbc -> /var/svc/manifest/network/odbc-tcp.xml
Importing odbc-tcp.xml ...Done
svccfg -s odbc/tcp setprop inetd_start/working_directory =
astring: /tmp
svcadm restart inetd
svcs | grep odbc
online 15:27:48 svc:/network/odbc/tcp:default

If DBC does not run on Solaris 10, restart the inetd with the following command:
ps -ef|grep inetd
kill -HUP <pid>

You can check that the inetd has started correctly by viewing the system log. On an HP machine, this will be in /var/adm/syslog/syslog.log.
An entry such as 'odbc/tcp:Unknown service' indicates that there is an error in the setup, for example, there may be a typographic or syntax mistake in /etc/services.

Exit from root user.
Use a text editor to edit the inetd daemon’s startup script, for example:
vi $TQL_CLIENT_DIR/dbc/<$MACH>/startup

where
<$MACH> is the machine type, for example, HP700_SV.

The script initially looks like this:

#!/usr/bin/csh
#
# This script gets executed by the inetd daemon when a connect request
# is received on port <port number> on <machine name>.
#
setenv TQL_SERVER_DIR <Location of TQL_SERVER_DIR>
setenv TQL_CLIENT_DIR <Location of TQL_CLIENT_DIR>
setenv DBC_SERVER_DIR <Location of DBC_SERVER_DIR>
setenv LM_LICENSE_FILE <License server nodename>
setenv DBC_LOG_LEVEL 0
#setenv DBC_TIMEOUT_INTERVAL <minutes>
cd <$TQL_CLIENT_DIR>/dbc/<$MACH>
./dbcserver

Users must edit the file as follows:
Set the TQL_SERVER_DIR and TQL_CLIENT_DIR environment variables.
Set the DBC_SERVER_DIR environment variable to the directory in which DBC server log files to be located.
Set the LM_LICENSE_FILE environment variable to the node name of the UNIX server on which the licence file is located. This name must be preceded by an @ symbol, as shown in the example below. This step is applicable for NPR/DBC 3.5.0 and below.
Set the DBC_LOG_LEVEL environment variable to the required log level (1-4).
The DBC_TIMEOUT_INTERVAL can be optionally set to a period following which the dbserver exits if it remains inactive.
Amend the file’s header with the port number and server machine.

Here is an example of a startup script:
#!/usr/bin/csh
#
# This script gets executed by the inetd daemon when a connect request
# is received on port 2622 on zeus.
#
setenv TQL_SERVER_DIR /npr3.3/tqlserver
setenv TQL_CLIENT_DIR /npr3.3/tqlclients
setenv DBC_SERVER_DIR /npr3.3/tqlclients/dbc
setenv LM_LICENSE_FILE @zeus
setenv DBC_LOG_LEVEL 1
#setenv DBC_TIMEOUT_INTERVAL 120
cd $TQL_CLIENT_DIR/dbc/HP700_SV
./dbcserver

Installing DBC (Client) on a PC

Prerequisite

NPR client/server

Ensure NPR client/server environment is installed and configured correctly.
For details, refer to Metrica/NPR installation guide section Heterogeneous networks.

DBC server
Ensure the DBC server installation and setup is completed, as indicated in Installing DBC (Server) on a UNIX server.

To setup DBC to run on a client machine, the software needs details about where the client software is installed and the Metrica/DMS machine. These details are defined in environment variables. These variables must be defined in the inetd daemon’s startup script as follows:

Variable	Description
NPR_SERVER	The name of the Metrica/DMS machine. For example: venus
NPR_SERVICE	The TCP service to use when communicating with Metrica/DMS. Note: NPR_SERVICE defaults to tqlnpr.
TQL_CLIENT_DIR	The pathname of the TQL client directory on the client.
QYHOST	The name of the Metrica/DMS machine. For example: venus
QYINT	The pathname of the query interpreter on the remote server machine.
QYSERVERENV	The remote_env file in $NPR_DIR/server directory on the server. For example: setenv QYSERVERENV /metrica/npr/ \server/remote_env
QYSERVICE	The TCP service to use when communicating with Metrica/DMS. This should point to the tql service.
NPR_USAGE_MODE	This variable determines how NPR installation is used. The variable is automatically set, but can be overwritten. For example: NPR_USAGE_MODE = CLIENT

Use a text editor to edit the inetd daemon’s startup script, for example:
Vi $TQL_CLIENT_DIR/dbc/<$MACH>/startup
where
<$MACH> is the machine type, for example, HP700_SV

Add the following environment setting to the file:
Set NPR_SERVER to SERVERNPR
Set NPR_SERVICE to tql
Set QYHOST to SERVERNPR
Set QYINT to /mnt/SERVERNPR/usr/npr/tqlserver
Set QYSERVERENV to $NPR_DIR/server/remote_env
Set NPR_SERVICE to tql
Set NPR_USAGE_MODE to CLIENT

Here is an example of the startup script:
#!/usr/bin/csh
#
# This script gets executed by the inetd daemon when a connect request
is
# received on port 2622 on zeus.
#
setenv TQL_SERVER_DIR /npr3.3/tqlserver
setenv TQL_CLIENT_DIR /npr3.3/tqlclients
setenv DBC_SERVER_DIR /npr3.3/tqlclients/dbc
setenv LM_LICENSE_FILE @zeus
setenv DBC_LOG_LEVEL 1
#setenv DBC_TIMEOUT_INTERVAL 120
setenv NPR_SERVER venus
setenv NPR_SERVICE tql
setenv QYHOST venus
setenv QYINT /npr3.3/server/tqlserver.npr.HP700_SV
setenv QYSERVERENV /npr3.3/server/remote_env
setenv QYSERVICE tql
setenv NPR_USAGE_MODE CLIENT
cd $TQL_CLIENT_DIR/dbc/HP700_SV
./dbcserver

Installing DBC Client

An InstallShield program is supplied to install the DBC client software on a PC. If the PC has network access to the server, users may run directly from the server. If not, you must copy the InstallShield program to the PC. It can be found in the $NPR_DIR/install.dbc directory, and is called ’Metrica DBC Setup.exe’.

Note:
All running applications should be closed down before starting to install DBC.

Steps to install DBC Client

Run the installation program ‘Metrica DBC Setup.exe’.
A message is displayed showing preparation of InstallShield Wizard.

A ’Welcome’ page is displayed.
Click Next.

The ‘Choose Destination Location’ screen is displayed.
The InstallShield suggests a directory into which DBC will be installed.
If users wish to use a different directory, click on the Browse button to select the new directory.
Click Next to continue.

The ‘Select Program Folder’ screen is displayed.
Choose a program folder for the ‘DBC Configuration Manager’ program. The default is DBC.
Click Next to continue.
The installation program installs the ‘DBC files’ in the selected directory, and adds the ‘DBC Configuration Manager’ to the selected program folder.
The installation program also installs a set of demonstration files in a Demos subdirectory beneath the installation directory.

The program runs the ‘DBC Configuration Manager’.
This program sets the default values that will be associated with Data Source Names (DSNs) created on the PC.

Configuration Manager

Users may start the ‘Configuration Manager’ from the installation program, or run the program directly from the DBC program folder.

Once the ‘Configuration Manager’ starts, the Welcome page is displayed.
Click Next to continue.

On the ‘Configuration Manager Defaults’ page, make the entries as follows.

Setting	Description
TCP/IP Port	Specifies the port number to be used for communicating with the UNIX server. It is recommended to use the registered port number 2622 for the DBC network service. This service is defined in the /etc/services file.
Buffer Size	Specifies the size of the query buffer in Kilobytes. This buffer is used by the TQL Server when extracting data from the database. This parameter needs to be set to handle the largest expected query, though the default value is sufficient for most queries. The parameter must be in the range 32–4,000,000 KB. The default value is 500 KB.
User Name	Specifies the NPR database user name. The maximum length for a user name is 13 characters. The default is GUEST for which no password is required.
Log File	If driver logging is enabled, this setting defines the name of the log file that will store the logging data produced by the TQL Server driver. The maximum length of a log file name is 256 characters. The default log file is c:\tqldriver.log.

Click Next to continue.

On the ‘Configuration Manager’ UNIX Servers page, make the entries as follows:

Table 5: Configuration Manager UNIX Servers Page Entries

Setting	Description
Add	Add the name or IP address of a UNIX server on which DBC is or will be configured. Each machine named here must have the DBC application installed.
Remove	Remove the selected UNIX server from the list.
Load…	Load a list of UNIX servers from a text file. Server names or IP addresses must be listed one per line.
Save…	Save the list of UNIX servers to a text file, for loading onto other clients. DBC saves the list with one server name or IP address per line.

Click Next to continue.

Click Finish to write the configuration changes made to the registry.

Executables and Files

There are 3 sets of executables and files for server, client, and application dependent files.

Executables/Files	Description
dbcserver	DBC server executable.
startup	The startup script which is invoked by the client to start the server.
Metrica DBC Setup.exe	The InstallShield program. This installs DBC on a PC.
dbc_db_upgrade	Upgrade script which makes a database compatible with DBC.
readme_db_upgrade	Gives information on how to run dbc_db_upgrade.
sqltypes.tsl	A file used by dbc_db_upgrade to create the database.
sqltypes.load	A file used by dbc_db_upgrade to populate the database.

Executables/Files	Description
Metrica DBC Setup.exe	DBC client installation program. This file may have copied to the PC.
MDBC.exe	The Configuration Manager.
MDBC.HLP	The Configuration Manager Help file.
mdbctoc.cnt	A file used by the Configuration Manager Help.
DBCUG.HLP	The DBC User’s Guide supplied as a Help file.
dbcugtoc.cnt	A file used by the DBC User’s Guide Help file.
TQLDriver.dll	The ODBC driver.
Uninst.isu	The uninstall script.
metrica_dbc_wbodbc_test.doc (Demonstration file)	MS Word demonstration macro.
metrica_dbc_xlodbc_test.xls (Demonstration file)	MS Excel demonstration macro.
odbcdemo.exe (Demonstration file)	ODBC demonstration application.

Executables/Files	Description
dbcbo_create.sh	A file for Business Objects Users that creates the tables required for external strategies.
dbcbo_populate.sh	A file for Business Objects users that populates the tables required for external strategies.
BO_ConfigInstr.doc	Provides instructions on how to configure DBC for use with Business Objects.

Appendix A: FLEXlm Software Installation

This section describes how to install FLEXlm licensing software.

Introduction

Note:

You should use these notes if you are installing FLEXlm for the first time.

Licensing is managed by third-party software called FLEXlm. The files required by FLEXlm are installed automatically using an installation script with the exception of the licence file which is supplied by e-mail. This document also describes how to install the licence file, refer to Install the FLEXlm licence file.

Note that detailed information on using FLEXlm is available in the FLEXlm End User Manual, a PDF version of which can be downloaded from the GLOBEtrotter web site at www.globetrotter.com.

The Installation Process

These notes describe how to install FLEXlm on a server machine.
Notes:
For all installations of FLEXlm, we strongly recommend that you read the following sections in their entirety before commencing the installation process.

The installation process comprises three main phases:
Preparation. The tasks you need to perform before you install the software.
Installing the software. Install the FLEXlm™ licensing software.
Post-installation tasks. Set the Licence Manager to start at boot time.

Preparation

Before preceding you should check that you have sufficient disk space on your system. The installation requires at least 4 MB.

You also need to decide where to install the software. During the installation you will be asked to supply two directories:
A temporary directory used to store the installation filesets.
A directory for installing the FLEXlm software.

Notes:
If you make an error during the installation of FLEXlm licensing software, refer to Recovering from an Incorrect Installation, which describes what you must do before restarting the installation procedure.

Installing the Software

This section describes how to install FLEXlm from the supplied media.

The tape contains a single tar file:
flexlm.<arch>.tar
where
<arch> is the type of machine on which the software will run, for example DECALPHA, HP700_SV or SUN4SOLARIS (these are the three supported platforms).

Login as or switch user to metrica.

Create a temporary installation directory into which the file from the tape can be copied. It can be removed once the installation process has completed.

mkdir /tmp/install_dir

We recommend you create this directory on the same mounted filesystem as the one on which you will install the software. If you use a different filesystem, the disk space requirements determined above apply to each filesystem independently.

Notes:
This directory is only a temporary directory for use during the installation process. It must not be one of the directories in which the software is to be permanently installed.

Make this directory your current directory.
cd /tmp/install_dir

Load the tape into the tape-drive and then extract the FLEXlm file.
tar xf <tape-dev>/flexlm.<arch>.tar
where
<tape-dev> is the name of the special device file associated with your tape device. This extracts the software for all the filesets on the tape.

Device files are generally stored in the /dev directory. If you do not know the name of the device file associated with your tape device, check with your Systems Administrator.

If you wish to check that the required filesets are present, list the contents of the directory:
ls

The following two directories should be present:
FLEXLM.<arch> and INSTALL

Move to the directory containing the installation scripts:
cd /tmp/install_dir/INSTALL

Run the top-level installation script:
sh ./ALL.inst

The script asks you to supply pathnames for the temporary installation directory and the directory into which to install the software. If you supply a pathname to a directory that does not exist, the script creates a new directory. Each pathname must not exceed 45 characters. When prompted, supply the name of:

– The installation directory (the directory you created in step 2).
Press return to accept the displayed default.
– The name of the FLEXlm directory.
Type a pathname of the directory to hold FLEXlm software or press return to accept the default (/usr/metrica/flexlm).

Note that we recommend that the FLEXlm directory remains separate from the Metrica/NPR installation directory.

Notes:
Do not specify directories that are subdirectories of the temporary installation directory. If you do, when you remove the temporary directory you will also remove the installed software and will have to start the installation again.

The script lists the filesets that will be installed and asks if you wish to continue. Enter y or n as appropriate.

The installation begins and as the script executes it displays information about the filesets that are being installed.

Assuming that no errors were encountered, when the script terminates, installation is complete.

Remove the temporary installation directory.
Most of the files in the installation directory will have been moved during the installation process, however the installation scripts themselves and some empty directories will still be there. Tidy up by removing the directory, for example:
cd /
rm -rf /tmp/install_dir

Notes:
This directory is not removed automatically by the installation scripts. You must therefore remove it manually.

Install the FLEXlm utilities
Vallent supplies the FLEXlm utilities as a single executable file named lmutil. You can install this file anywhere on your system, we recommend that you install lmutil in the directory /usr/local/bin.

Post-Installation Tasks

The following tasks must be performed before you can use the Licence Manager:

Set the Licence Manager to start at boot time
The file S900adcflexlm is a shell script that starts the Licence Manager automatically at boot time. To use this script:

Change directory to the flexlm/bin directory, for example:
cd /usr/metrica/flexlm/bin

Save S900adcflexlm to the directory in which the UNIX server’s boot script is located. This location varies between versions:

DECALPHA /sbin/rc3.d
HP /sbin/rc2.d
SUN /etc/rc2.d

Note it is advisable to stop the Licence Manager when you shutdown your machine. You can do this by using the stop parameter with the S900adcflexlm file.

Recovering from an Incorrect Installation

This section describes how to recover if you make an error during the installation—for example, by giving an incorrect reply to one of the installation script’s prompts. If you make an error, you must remove both the temporary directory and the target installation directory before restarting the installation procedure.

Remove the target installation directory and the temporary directory using the following command:
rm -rf <dir_name>

where
dir_name is the pathname of the directory.

For example:
rm -rf /tmp/install_dir
rm -rf /usr/metrica/flexlm

Executables and files

The FLEXlm executables and files are as follows:

Files	Description
<filename>.lic	The Vallent licence file (supplied by e-mail), where <filename> is the name of the file.
adc_lmd	The Vallent vendor daemon.
S900adcflexlm	A shell script that runs the Licence Manager at startup.
lmgrd	The FLEXlm Licence Manager.
lmutil	The FLEXlm utilities, supplied as a single executable.

Managing log files

All log entries generated by the Licence Manager are stored in the flexlm.log file. This file may become very large if the log files are not regularly archived. We would therefore recommend that you regularly archive the files either manually or automatically using cron.