StarQuest Technical Documents

StarSQL for UNIX Quick Start Guide

Updated: 26 June 2008
Product: StarSQL for UNIX
Version: 5.25 or later
Article ID: SQV00SU001

Abstract

This Quick Start Guide describes how to install, configure, and use the StarSQL driver on a UNIX-based computer. It covers the following major tasks:

Step 1: Prepare the StarSQL and StarLicense Packages for Installation.

Step 2: Install StarSQL.

Step 3: Install and Administer StarLicense.

Step 4: Set Environment Variables.

Step 5: Configure a StarSQL Data Source.

Step 6: Test Connectivity.

Solution

The following sections guide you through the steps that are summarized in the preceding Abstract.

Step 1: Prepare the StarSQL and StarLicense Packages for Installation

You can download the StarSQL for UNIX and StarLicense for UNIX software from the StarQuest Ventures Web site, http://www.starquest.com. If the packages you download from StarQuest are compressed (i.e., .Z files), uncompress them using the uncompress <filename> command, such as shown in the following examples.

# uncompress linux.tar.Z # uncompress starlicense-linux.tar.Z

Next, extract the files from the archives using the tar -options <filename> command, as shown in the following examples.

# tar -xvf linux.tar

or

# tar -xvf linux-rpm.tar # tar -xvf starlicense-linux.tar

or

# tar -xvf starlicense-linux-rpm.tar

Step 2: Install StarSQL

Log on as the root user. From the temporary directory that contains the StarSQL installation source files, run the setup script to start the installation. The installation process installs the StarSQL software into the default directory shown below for each supported UNIX platform.

UNIX Platform	Default Installation Directory
AIX	/usr/lpp/starsql
FreeBSD	/usr/share/starsql
HP-UX	/opt/starsql
Linux	/usr/share/starsql
Solaris	/opt/starsql

As the setup script runs you must respond to various prompts and reminders, answering y (Yes) to proceed with the installation. Following is an example of the script, prompts, and responses when the script is run under Linux.

# ./setup

This script uses tar to install StarSQL to /usr/share/starsql and should be run as root.

Do you wish to continue (y/n)? y

This script will now run /usr/share/starsql/etc/post_install
Do you wish to continue (y/n)? y

Checking for pre-requisites:
The StarLicense package was not found. You must install the StarLicense package and configure a valid license before using StarSQL.

/usr/local/etc/odbcinst.ini does not exist.
Would you like to create it (y/n)? y

Installation done.

Be sure to set the environment variables as shown in Step 4: Set Environment Variables before using StarSQL.

Step 3: Install and Administer StarLicense

You must have a license to use the StarSQL software. The StarLicense product manages the licenses for using all StarQuest products and is available for download from the StarQuest Web site. (See Step 1: Prepare the StarSQL and StarLicense Packages for Installation.)

If you have a license key from StarQuest for using the StarSQL for UNIX product, you can enter it and license the product during this step. If you do not yet have a license key, you can install the StarLicense software now and access the StarLicense Configuration Menu after you receive your license key.

Log on as root user. From the temporary directory that contains the StarLicense installation source files, run the setup script to start the installation. The installation process installs the StarLicense software into the default directory shown in the following table for each supported UNIX platform.

UNIX Platform	Default Installation Directory
AIX	/usr/lpp/starlicense
FreeBSD	/usr/share/starlicense
HP-UX	/opt/starlicense
Linux	/usr/share/starlicense
Solaris	/opt/starlicense

As the setup script runs you must respond to various prompts and reminders, answering y (Yes) to proceed with the installation. Following is an example of the prompts and responses for running the script on a Linux computer.

# ./setup

This script uses rpm to install StarLicense for UNIX to /usr/share/starlicense and should be run as root.

Do you wish to continue (y/n)? y

When the installation completes a prompt appears that asks if you want to administer the StarLicense server.

Answer n (No) if you do not have your StarSQL for UNIX license key yet. After you obtain a license key enter configure from the StarLicense installation directory to display the StarLicense Configuration Menu and enter the key.

Answer y (Yes) if you have a StarLicense for UNIX license and want to enter the key now.

The StarLicense Configuration Menu presents the following options:

StarLicense Configuration Menu

1) Configure a client connection to a License Server
2) Set up a License Server
3) Install a local client license
4) Start the License Server daemon
5) Stop the License Server daemon
6) Display status of the License Server daemon
7) Display StarLicense configuration
8) How to contact StarQuest for a license key

9) Exit

Select option 2) Set up a License Server. Enter the license key provided by StarQuest Customer Support and press Enter to continue. The following shows an example of the prompts and responses for setting up a license server, using a fictitious license key, accepting the default TCP/IP Interface, and the default TCP/IP port address of 4999.

Enter license key: 0A971D69D75D52535C8F2BA752908B3B
starlic-admin server-key-add 0A971D69D75D52535C8F2BA752908B3B

Ok
Enter TCP/IP interface [0.0.0.0]:
Enter TCP/IP port address [4999]:
starlic-admin server-listener-add 0.0.0.0 4999

Ok
[Press RETURN to continue]

Press Enter to return back to the menu.

At the StarLicense Configuration Menu select option 1) Configure a client connection to a License Server. The following example prompts and responses show how to configure a connection for the StarSQL product, which uses SQ for the product ID.

Enter Hostname or TCP/IP address of the license server: localhost
Enter TCP/IP port address [4999]:
Enter ProdID (SQ=StarSQL or StarSQL for Java; CA=Client Access for UNIX): SQ
starlic-admin client-server-add SQ localhost 4999 PRI

Ok
[Press RETURN to continue]

Press Enter to return to the main menu and then select option 4) Start the License Server daemon to start StarLicense. After the daemon starts, press Enter to return to the main menu and select option 9 to exit the Configuration Menu.

Step 4: Set Environment Variables

Each StarSQL user must have the appropriate environment variables specified in their .profile or .cshrc file. The following table shows the environment variables, as appropriate for each of the supported UNIX platforms, that must be defined for StarSQL.

UNIX Platform	Environment Variables
AIX	STARSQL=/usr/lpp/starsql PATH=$PATH:$STARSQL/bin MANPATH=$MANPATH:$STARSQL/man LIBPATH=$STARSQL/lib:$LD_LIBRARY_PATH
FreeBSD	STARSQL=/usr/share/starsql PATH=$PATH:$STARSQL/bin MANPATH=$MANPATH:$STARSQL/man LD_LIBRARY_PATH=$STARSQL/lib:$LD_LIBRARY_PATH
HP-UX	STARSQL=/opt/starsql PATH=$PATH:$STARSQL/bin MANPATH=$MANPATH:$STARSQL/man SHLIB_PATH=$STARSQL/lib:$LD_LIBRARY_PATH
Linux	STARSQL=/usr/share/starsql PATH=$PATH:$STARSQL/bin MANPATH=$MANPATH:$STARSQL/man LD_LIBRARY_PATH=$STARSQL/lib:$LD_LIBRARY_PATH
Solaris	STARSQL=/opt/starsql PATH=$PATH:$STARSQL/bin MANPATH=$MANPATH:$STARSQL/man LD_LIBRARY_PATH=$STARSQL/lib:$LD_LIBRARY_PATH

Step 5: Configure a StarSQL Data Source

To configure an ODBC data source to use the StarSQL driver, create a symbolic link to $STARSQL/etc/swodbc.ini from each user's home directory, such as:

# ln -s $STARSQL/etc/swodbc.ini .swodbc.ini

Copy the odbc.ini file from $STARSQL/etc to the user home directory and rename it .odbc.ini (preceded with a period), such as:

# cp $STARSQL/etc/odbc.ini $HOME/.odbc.ini

Use the Change Mode command to ensure the .odbc.ini file can be written to:

# chmod 644 $HOME/.odbc.ini

Edit the .odbc.ini file to configure a StarSQL data source. The following example shows only the required data source parameters. Note that the Netlib parameter value should not be modified. Only modify the Driver parameter value if StarSQL was installed into a non-default directory. The StarSQL for UNIX User's Guide provides details about all the required and optional data source configuration parameters.

# StarSQL sample .odbc.ini

[ODBC Data Sources]
DB2PROD=StarSQL

[DB2PROD]
Server=DB2P
Driver=/usr/share/starsql/lib/libSWODBC.so
PkgColId=STARSQL
Netlib=SWTCP32.DLL
HostName=DB2HOST
port=446

If you want to use the unixODBC driver manager, refer to the StarSQL for UNIX User's Guide for instructions.

Step 6: Test Connectivity

Use the starping sample application to test end-to-end connectivity between the StarSQL client and the DB2 host.

$ starping

Enter Data Source: DB2PROD
Enter User Name: DB2USER
Enter Password: DB2PASS

Connection Succeeded!

Driver Name: libswodbc.so
Driver Version: 5.25.0721

Database Name: DB2P
DBMS: DB2/400
Version: 05.03.0000

Use the simpleconn test application to test connectivity and verify that the license is working properly. The syntax for the simpleconn command is:

simpleconn <DSN> <UID> <PWD> <# of connections>

For example, the following command tests the StarSQL license for one connection to a DSN named DB2PROD:

simpleconn DB2PROD DB2USER DB2PASS 1

Connection #1

Driver Name: libswodbc.so
Driver Version: 5.25.0721
Database Name: DB2/400
Database Version: 05.03.00

Additional References

StarSQL man pages

StarLicense man pages

StarSQL for UNIX User's Guide

StarLicense Release Notes

Site Map
Products | Trial Download | Customer Support | Partners | About StarQuest | Press & Events | Contact StarQuest

©Copyright 2008 StarQuest Ventures, Inc. All rights reserved.

Legal Notice • Privacy Policy
Email contact@starquest.com with site comments.