StarQuest Technical Documents

Quick Start Guide to Using the StarSQL ODBC Driver for UNIX

Last Update: 26 August 2009
Product: StarSQL for UNIX
Version: 5.5x or later
Article ID: SQV00SU001

Abstract

This Quick Start Guide describes how to install, configure and use StarSQL for UNIX and its associated components, StarLicense and StarAdmin. Read the complete document before starting your installation.

This document is intended for first-time users of StarSQL. Users who are upgrading an existing installation should refer to the Release Notes and the StarSQL for UNIX User's Guide for upgrade instructions.

The estimated time to complete all tasks is approximately 1 hour and 15 minutes.

StarSQL for UNIX Quick Start Guide Outline

The same individual or a combination of individuals must be capable of performing in the following three roles in order to successfully complete the evaluation.

• System Administrator is someone with authority to install the StarLicense network license service on a platform that is accessible to the computer to be used in conjunction with StarSQL. This user typically must be a root user on a UNIX platform.
• Database Administrator is someone with user credentials suitable for creating collections and binding packages on the database host. The Database Administrator runs the standalone application StarAdmin - which is available to run as a GUI application on either Windows or UNIX - and the only requirement is that the platform have TCP-IP access to the database host.
• Client-Platform Administrator is someone with root authority to install StarSQL on a UNIX server. This person must also have a set of DB2 user credentials to test the database connectivity.

General considerations

1. The StarLicense Server Platform can be the same or a different platform as the StarSQL Client Platform. In the latter case, the StarLicense Server Platform must be on the same network as the Client Platform.
2. The StarAdmin platform must have TCP-IP access to the database host.
3. The Client platform must have TCP-IP access to the database host.

Summary of tasks

Steps 3 and 4 below may be performed at the same time (or even step 4 before step 3.) Otherwise perform the steps in the order described. Note that some of the steps provide information used in subsequent steps.

1. Request to download StarSQL for UNIX for the platform of interest (i.e., Linux, Solaris, HP-UX, etc.).
2. Receive the e-mail with a Registration Key and download links for the StarLicense, StarAdmin and StarSQL for UNIX (32-bit and 64-bit) components.
3. System Administrator: Download StarLicense using the download link from step 2 and install the software. Using the registration key in the download confirmation e-mail (step 2), license the evaluation software and provide client license configuration information to be used in step 5c.
4. Database Administrator: Download StarAdmin using the download link from step 2 and bind packages to the database. This requires knowledge of the database host and sufficient user privilege. Provide database connectivity information to the Client-Platform Administrator to be used in step 5d.
5. Client-Platform Administrator:
   1. Download StarSQL for UNIX using the download link from step 2 and run the setup script to install.
   2. If a unixODBC driver manager is not present or is not at a supported level, set environment variables to use the newly installed copy of unixODBC.
   3. Configure the StarSQL client license using the information provided in step 3, above.
   4. Configure an ODBC System Data Source Name (DSN) using the information provided in step 4, above.
   5. Verify StarSQL connectivity to the database host.

Step 1: Request StarSQL Software

Estimated Time: 5 minutes

All software packages are distributed as compressed files that you download from the StarQuest Ventures Web site. From a web browser enter the address http://www.starquest.com/ and click on Download for Trial under the Products menu. Request to download StarSQL for the platform of interest (i.e., Linux, Solaris, HP-UX, etc.). When the request is fulfilled, you will receive both 32-bit and 64-bit versions of StarSQL for UNIX.

Step 2: Receive the Download Confirmation E-mail from StarQuest

Estimated Time: Less than 5 minutes

After submitting a request to download StarSQL for UNIX, you will receive an e-mail containing a Registration Key and download links for the StarLicense, StarAdmin and StarSQL for UNIX (32-bit and 64-bit) components. The registration key will be used in step 3 to obtain a temporary license valid for 15 days and the download links will be used in steps 3-5 below.

Step 3: (System Administrator task) Download, Install, and License StarLicense

Estimated Time: 15 minutes

1. Download StarLicense for UNIX using the download link from step 2.
2. Install and configure the software according to the instructions in the StarLicense for UNIX Quick Start Guide. You will need to use the Registration Key in the download confirmation e-mail (step 2) to license the evaluation software.
3. Provide the Client-Platform Administrator with the following client license configuration information, to be used in step 5c:
   • Network host name or IP address of the StarLicense server.
   • The port number on which StarLicense is configured to listen for licensing requests, the default is 4999.
   • The Product ID (ProdID) specified by the license.

Step 4: (Database Administrator task) Bind Host Packages Using StarAdmin

Estimated Time: 15 minutes

The user who installs StarAdmin must be an administrator (Windows) or root user (UNIX/Linux) on the platform. The database connectivity information collected in this section will be provided to the Client-Platform Administrator for use in step 5d.

1. Download StarAdmin using the download link from step 2 and execute setup.exe (Windows), setuplinux.bin (Linux), or setupsolaris.bin (Solaris). After the installation is complete, click Finish.

2. Collect the DB2 host information and fill in the values for your environment in the space provided in the table below.

Connection Parameter	Description	Your Value
Host	The network Host Name or IP address of the DB2 host.
Port	DB2 for z/OS users: the port number can be found on the DSNTIP5 panel. DB2/400 users: use the WRKSRVTBLE command and look for the DRDA entry with the port number. DB2 for Windows, Linux and Unix users: in the DB2 Control Center, right-click the DB2 instance, select Setup Communications, and select the TCP/IP option. In Properties, locate the port number that is configured for DRDA communications. DB2 Server for VSE & VM: the DBNAME directory contains an entry for each DB2 server that specifies the TCP/IP port number to use (the TCPPORT parameter).
Database Name	DB2 for z/OS users: this is the DDF Location Name of the database. DB2/400 users: run the AS/400 command WRKRDBDIRE and locate the entry with a Remote Location value of *LOCAL. If such an entry does not exist, create it with the 1=ADD option. DB2 for Windows, Linux and Unix users: in the left pane of the DB2 Control Center, the databases are shown below the "Database" folder. DB2 Server for VSE & VM: for VSE the database name typically is defined in the DBNAME directory, and for VM the dbname parameter is specified in the CMS Communications Directory in the CMS file of type NAMES.
Package Collection	Set this value to STARSQL. DB2/400 users only: create an empty library on the host called STARSQL or set this value to the name of an existing library (e.g., QGPL).
Username/Password	A DB2 user account that has authority to create and bind packages on the database.

3. From the StarAdmin program group (Windows) or /opt/StarQuest/StarAdmin directory (UNIX/Linux), start the StarAdmin GUI application.
4. Enter the database connectivity values, as collected in the previous step, in the Connection Settings dialog and click OK.
5. Upon connecting successfully, StarAdmin will immediately bind one package, which will be displayed in the package list. The status bar at the bottom of the dialog will display the Database Name, Package Collection, DB2 Type, and Version. If StarAdmin fails to connect to the database, review the suggested resolutions in the Binding StarSQL Packages Using StarAdmin technical document and make any necessary corrections to the values in the connection dialog.
6. Leave the default values for the Package Settings and Grant Options.
7. From the Command menu, select Bind to create and bind the remaining packages.
8. Review the summary dialog and provide the database connection parameters, as displayed in the summary text to the Client-Platform Administrator, to be used in step 5d.

If the packages are created and bound successfully, the summary output will look similar to the following:

Package binding starting: Wed Jul 29 14:44:03 PDT 2009
UID=SUPERUSER
HostName=DB2HOST.DOMAIN.COM
Port=446
Server=DB2PROD
PkgColID=STARSQL
AutoTypDefOvr=
BindRules=RUN
CustomizePrdid=No
UseJumboPackages=No
UseEncryption=Any

jdbc:StarSQL_JDBC://DB2HOST.DOMAIN.COM:446/DB2PROD;collection=STARSQL

SQL package SWNC0000 in collection STARSQL has been created.
Granted execute privileges on STARSQL.SWNC0000 to PUBLIC
SQL package SWRU0000 in collection STARSQL has been created.
Granted execute privileges on STARSQL.SWRU0000 to PUBLIC
SQL package SWRC0000 in collection STARSQL has been created.
Granted execute privileges on STARSQL.SWRC0000 to PUBLIC
SQL package SWRR0000 in collection STARSQL has been created.
Granted execute privileges on STARSQL.SWRR0000 to PUBLIC
SQL package SWTS0000 in collection STARSQL has been created.
Granted execute privileges on STARSQL.SWTS0000 to PUBLIC
SQL package SWNC1000 in collection STARSQL has been created.
Granted execute privileges on STARSQL.SWNC1000 to PUBLIC
SQL package SWRU1000 in collection STARSQL has been created.
Granted execute privileges on STARSQL.SWRU1000 to PUBLIC
SQL package SWRC1000 in collection STARSQL has been created.
Granted execute privileges on STARSQL.SWRC1000 to PUBLIC
SQL package SWRR1000 in collection STARSQL has been created.
Granted execute privileges on STARSQL.SWRR1000 to PUBLIC
SQL package SWTS1000 in collection STARSQL has been created.
Granted execute privileges on STARSQL.SWTS1000 to PUBLIC
SQL package QSYS2 in collection STARSQL has been created.
Granted execute privileges on STARSQL.QSYS2 to PUBLIC

Package binding completed: Wed Jul 29 14:44:55 PDT 2009

If any errors are reported, review the suggested resolutions in the Binding StarSQL Packages Using StarAdmin technical document, correct the problem and execute the bind operation again. If you are unable to resolve the error condition, copy the entire Summary text and send it to StarQuest Customer Support at contact@starquest.com.

7. Click the Finished button to return to the main dialog.
8. From the File menu, choose Close Database and then Exit.

Step 5a (Client-Platform Administrator task): Download and Install StarSQL for UNIX

Estimated Time: Less than 5 minutes

1. Download StarSQL for UNIX using the download link from step 2.
2. Uncompress the package using the uncompress <filename> command, such as shown in the following example.

# uncompress linux.tar.Z

3. Extract the files from the archive into a unique, temporary directory using the tar -options <filename> command, as shown in the following examples.

   # tar -xvf linux.tar -C /tmp/starsql

   or

   # tar -xvf linux-rpm.tar -C /tmp/starsql

4. 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 StarSQL32-bit Installation Directory	Default StarSQL64-bit Installation Directory
AIX	/usr/lpp/starsql	Platform not yet supported.
FreeBSD	/usr/local/share/starsql	Platform not yet supported.
HP-UX	/opt/starsql	/opt/starsql64
Linux	/usr/share/starsql	/usr/share/starsql64
Solaris	/opt/starsql	/opt/starsql64

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

# ./setup

This script uses rpm 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

The existing ODBC Driver Manager (version 2.2.11), as indicated by /usr/bin/odbcinst, does not meet the minimum version requirement (2.2.12).

The StarQuest-supplied unixODBC Driver Manager in /usr/share/starsql/odbc will be used for installation.

odbcinst: Driver installed. Usage count increased to 1.
    Target directory is /usr/local/etc

The StarQuest-supplied unixODBC Driver Manager was used for installation.
Be sure to modify your PATH to use /usr/share/starsql/odbc/bin and modify your LD_LIBRARY_PATH or ld.so.conf to include /usr/share/starsql/odbc/lib.

Installation done.

Step 5b (Client-Platform Administrator task): Configure unixODBC Environment

Estimated Time: Less than 5 minutes

StarSQL supports the following unixODBC driver manager versions:

• 32-bit clients: unixODBC version 2.2.12 and later
• 64-bit clients: unixODBC version 2.2.14 and later

If the installation script reports that a suitable version of the unixODBC driver manager is already installed, proceed to step 5c. Otherwise, set environment variables to use the newly installed copy of unixODBC.

1. Log on as the root user.
2. Modify your PATH environment variable to include the location of the StarSQL odbc/bin directory, as in the following Linux example:

export PATH=/usr/share/starsql/odbc/bin:$PATH

3. Modify your LD_LIBRARY_PATH environment variable or ld.so.conf to include the location of the StarSQL odbc/lib directory, as in the following Linux example:

   export LD_LIBRARY_PATH=/usr/share/starsql/odbc/lib:$LD_LIBRARY_PATH

4. Verify that the system is configured to use the StarSQL-provided unixODBC driver manager by running the which odbcinst and which ODBCConfig commands, as shown in the sample output on a Linux system.

   $ which odbcinst
   /usr/share/starsql/odbc/bin/odbcinst

   $ which ODBCConfig
   /usr/share/starsql/odbc/bin/ODBCConfig

Step 5c (Client-Platform Administrator task): Configure StarSQL License

Estimated Time: Less than 5 minutes

To successfully complete this section, you will need the following StarLicense server information from the System Administrator, obtained in step 3.

• The network host name or IP address of the StarLicense server.
• The port number on which StarLicense is configured to listen for licensing requests, the default is 4999.
• The Product ID (ProdID) specified by the license.

License Configuration Instructions

1. From the bin directory of the StarSQL directory (e.g., /usr/share/starsql/bin), run the config-lic application to display the StarLicense Client Configuration Menu.
2. Select option 1, “Configure local StarLicense client to use a License Server”.
3. Enter the host name or IP address of the StarLicense server and press Return.
4. Enter the number of the port on which the StarLicense server is listening for license requests. The default value of 4999 appears in brackets; if this is acceptable leave this entry blank. Press Return.
5. Enter the Product ID of the license that is configured on the StarLicense server and press Return.
6. If the entry is added successfully, this will be indicated by an "Ok" confirmation. If this client has already been configured by your System Administrator, as indicated by an "Entry already exists" message, no additional configuration is required. Press the Return key to return to the main menu.
7. Select Option 3 “Test licensing checkout”, enter a value of 1 to check out a single license and press Return. After the license is checked out successfully, press Return to check the license in. Press the Return key to return to the main menu.
8. Choose option 6 to exit the StarLicense Client Configuration Menu.

Step 5d (Client-Platform Administrator task): Configure StarSQL System Data Source Name (DSN)

Estimated Time: 10 minutes

To successfully complete this section, you will need all of the database connectivity information from the Database Administrator, obtained in step 4.

1. Log on as root user.
2. Run the odbcinst -j command to determine the location of the odbc.ini file used by the unixODBC driver manager to store System DSN information. The output will look similar to the following:

   $ odbcinst -j
   unixODBC 2.2.14
   DRIVERS............: /usr/local/etc/odbcinst.ini
   SYSTEM DATA SOURCES: /usr/local/etc/odbc.ini
   FILE DATA SOURCES..: /usr/local/etc/ODBCDataSources
   USER DATA SOURCES..: /home/user/.odbc.ini

3. Open the odbc.ini file in your preferred text editor and insert a new DSN configuration, using the database connectivity parameter values obtained by the Database Administrator in step 4. Save the file when finished.

[<your DSN name>]
Driver=<StarSQL or StarSQL64>
HostName=<host name or IP address of your DB2 server>
Port=<DB2 port, typically 446>
Server=<your database server name>
PkgColId=<your package collection>

The following example shows only the required data source parameters and was created using the sample Summary output from StarAdmin obtained in step 4.

# StarSQL sample odbc.ini
[DB2DSN]
Driver=StarSQL
HostName=DB2HOST.DOMAIN.COM
Port=446
Server=DB2PROD
PkgColID=STARSQL

The StarSQL for UNIX User's Guide provides details about all the required and optional data source configuration parameters. You will also find a sample DSN in the starsql/etc/odbc.ini file. If you would like to configure User DSNs or use the ODBCConfig application to configure System or User DSNs, refer to the StarSQL for UNIX User's Guide for instructions.

Step 5e (Client-Platform Administrator task): Verify StarSQL Connectivity to Database Host

Estimated Time: 5 minutes

To complete this section, you will need a DB2 user ID that has authority to connect to DB2 and the name of the DSN configured in step 5d. The samples below assume that the DSN used to test connectivity is the sample DSN, shown in step 5d.

1. Use the starping sample application to test end-to-end connectivity between the StarSQL client and the DB2 host. From the starsql/bin directory, run starping and specify the Data Source name, User Name and Password, as shown in the example below.

   $ ./starping

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

   Connection Succeeded!

   Driver Name: libswodbc.so
   Driver Version: 5.51.XXXX

   Database Name: DB2PROD
   DBMS: DB2 Universal DataBase
   Version: 08.02.0007

2. Use the simpleconn 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 one StarSQL connection to a DSN named DB2DSN:

   $ ./simpleconn DB2DSN DB2USER DB2PASS 1

   Connection #1
   Driver Name: libswodbc.so
   Driver Version: 5.51.XXXX
   Database Name: DB2 Universal DataBase
   Database Version: 08.02.0007

Continuing Your Software Evaluation

This Quick Start Guide is intended to help you install the StarQuest software and access DB2 data as quickly as possible.

As you use the StarSQL software, refer to the product documentation for more information. StarSQL includes man pages and a User's Guide that provide more information about driver configuration and defining ODBC data sources.

If you encounter any problems while using the evaluation software, please send an e-mail to StarQuest Customer Support at contact@starquest.com or call (+1) 415-669-9619 for assistance.

Additional References

StarSQL man pages
StarLicense man pages
StarLicense for UNIX Quick Start Guide
StarSQL for UNIX User's Guide

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

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

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