Updated: 26 June 2008
Product: StarSQL for UNIX
Version: 5.25 or later
Article ID: SQV00SU001
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 3: Install and Administer StarLicense.
Step 4: Set Environment Variables.
Step 5: Configure a StarSQL Data Source.
The following sections guide you through the steps that are summarized in the preceding Abstract.
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
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.
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.
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 |
|
FreeBSD |
STARSQL=/usr/share/starsql |
|
HP-UX |
STARSQL=/opt/starsql |
|
Linux |
STARSQL=/usr/share/starsql |
|
Solaris |
STARSQL=/opt/starsql |
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.
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
StarSQL man pages
StarLicense man pages
The information in technical documents comes without any warranty. The author(s) or distributor(s) will not accept responsibility for any damage incurred directly or indirectly through use of the information contained in these documents. The information in technical documents may be gathered from various sources, including IBM, Microsoft, and other organizations.