Stelo Technical Documents

Quick Start Guide to Using the StarSQL ODBC Driver for UNIX

Last Update: 26 December 2022
Product: StarSQL for UNIX
Version: 6.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. Note that you can use an existing StarLicense Server (running on Windows or another UNIX system).
• 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. Note that this only needs to be run once per database, so if you already using StarSQL for Windows or StarSQL for Java, this has already been done.
• 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. Alternatively, you may be able to use node-locked licensing.
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

1. Download StarSQL for UNIX.
2. System Administrator: Download and install StarLicense. Supply the IP address of the system running StarLicense to Stelo Support, who will then send an evaulation license key; install the license key.
3. Database Administrator: Download and install 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.
4. Client-Platform Administrator:
   1. Install prerequisites (e.g. unixODBC, compat-opensslXX if needed).
   2. Use RPM to install StarSQL for UNIX
   3. 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.
   4. Configure the StarSQL client license using the information provided in step 2, above, or configure node-locked licensing.
   5. Configure an ODBC System Data Source Name (DSN) using the information provided in step 3, above.
   6. Verify StarSQL connectivity to the database host.

Step 1: Request & Download StarSQL Software

Estimated Time: 5 minutes

All software packages are distributed as RPM or compressed files that you download from the Stelo download website. Stelo Support will provide the links to download StarSQL.

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

Estimated Time: 15 minutes

1. Download StarLicense for UNIX.
2. Install and configure the software according to the instructions in the StarLicense for UNIX Quick Start Guide.
3. Supply the IP address of the system running StarLicense to Stelo Support, who will then send an evaulation license key.
4. Install the license key and start the StarLicense service.
5. Provide the Client-Platform Administrator with the following client license configuration information:
   • 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 3: (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.

Note that binding host packages is required only for connecting to IBM Db2; it is not needed when connecting to Apache Derby or Lzlabs SDM. StarAdmin can be run from Windows or Linux and only needs to be run once per database.

1. Download StarAdmin and execute setup.exe (Windows) or setup (Linux), 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 for i users: use the WRKSRVTBLE command and look for the DRDA entry with the port number. Default is 446. Db2 for Linux, UNIX, and Windows users: $ db2 get dbm cfg | grep SVCENAME TCP/IP Service name (SVCENAME) = db2c_db2inst1 $ grep db2c_db2inst1 /etc/services db2c_db2inst1 50000/tcp Default is 50000 for systems installed at 11.5.5 & earlier; default was changed to 25000 in Db2 11.5.6. Note that on Windows, the services file is located in C:\Windows\System32\drivers\etc. 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 for i 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 Linux, UNIX, and Windows users: $ db2 list database directory and examine the value Database name. 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 for i 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.

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 http://support.starquest.com.

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

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

Estimated Time: Less than 5 minutes

1. Install unixODBC (2.3.7 or later): yum install unixODBC
2. If you are using a version of Linux later than RHEL/Oracle 8.x, you may need to install compat-ssl11: yum install compat-openssl11. This is required even if you are not using TLS/SSL communications
3. Install StarSQL for UNIX: rpm -U starsql64-<version>-1.x86_64.rpm. This will install StarSQL to its default location of /opt/stelo/starsql64 and add StarSQL64 and StarSQL (64-bit) entries to /etc/odbcinst.ini

 

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

Estimated Time: Less than 5 minutes

Using Node-locked Licensing:

The UNIX system must be using a static IP address. Node-locked licenses are typically supplied as part of a Stelo Data Replicator solution.

1. Log on as root.
2. From the bin directory of the StarSQL directory (e.g., /opt/stelo/starsql64/bin), run the config-lic application to display the StarLicense Client Configuration Menu.
3. Select Option 4 Add a node-locked license and enter the license supplied by Stelo Support.
   
4. Select Option 7 “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.
5. Choose option 9 to exit the StarLicense Client Configuration Menu.

 

Using a StarLicense Server

You will need the following StarLicense server information from the System Administrator.

• The network host name or IP address of the StarLicense server. This may be localhost.
• 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 (typically SQ).

License Configuration Instructions

1. Log on as root.
2. From the bin directory of the StarSQL directory (e.g., /opt/stelo/starsql64/bin), run the config-lic application to display the StarLicense Client Configuration Menu.
3. Select option 1, “Configure local StarLicense client to use a License Server”.
4. Enter the host name or IP address of the StarLicense server and press Return.
5. 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.
6. Enter the Product ID of the license that is configured on the StarLicense server and press Return. This is typically SQ.
7. 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.
8. Select Option 7 “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.
9. Choose option 9 to exit the StarLicense Client Configuration Menu.

Step 4d (Client-Platform Administrator task): Configure StarSQL 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.

A sample odbc.ini (with comments) is installed with the product in the etc subdirectory (e.g. /opt/stelo/starsql64/etc/odbc.ini).

1. cat /opt/stelo/starsql64/etc/odbc.ini >> $HOME/.odbc.ini
2. Open $HOME/.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. Save the file when finished.

[<your DSN name>]
Driver=StarSQL (64-bit)
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.

# StarSQL sample odbc.ini
[DB2DSN]
Driver=StarSQL (64-bit)
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 System DSNs rather than User DSN's, edit /etc/odbc.ini rather than $HOME/.odbc.ini.

Step 4e (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 above .

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

3. Use isql (simple query app supplied with unixODBC) to test connectivity, licensing, and SQL functionality:
   $ isql -v DB2DSN DB2USER DB2PASS
   +---------------------------------------+
   | Connected! |
   | |
   | sql-statement |
   | help [tablename] |
   | quit |
   | |
   +---------------------------------------+
   SQL> select * from mytable;
   

Continuing Your Software Evaluation

This Quick Start Guide is intended to help you install the Stelo 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 open a problem report with Stelo Customer Support at https://support.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