StarQuest Technical Documents

Quick Start Guide to Using the StarSQL ODBC Driver for Windows

Updated: 27 July 2009
Product: StarSQL for Windows
Version: 5.4x or later
Article ID: SQV00SQ008

Abstract

This Quick Start Guide describes how to install, configure, and use the StarSQL ODBC driver (32-bit or 64-bit ) on a Windows computer, and 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 Windows User's Guide for upgrade instructions. Read the complete document before starting your installation.

The estimated time to complete all tasks is approximately 30 minutes.

Before You Begin

Before you begin, review the following list to ensure that you have the information and files you need, and that your computer environment provides the minimum requirements.

General Requirements

  • You have requested and downloaded the StarSQL and StarAdmin software. All software packages are distributed as compressed files that you download from the StarQuest Ventures Web site. From a browser enter the address http://www.starquest.com/ and click on Download for Trial under the Products menu if the prerequisite software has not been downloaded. In addition, the download system will provide a registration key used to obtain a temporary license good for 15 days.
  • You have the Download Instructions that were sent to the email address specified in the StarQuest Product Download Request form. You need these instructions and Internet access to license the software.
  • You have access to a Windows user ID that has administrative authority on the computer where the StarQuest software will be installed.
  • You have a valid DB2 user ID that provides adequate authority to connect to the database.

Prerequisites

In order to connect to a DB2 host, a StarSQL data source must be configured with basic connectivity information. This DB2 connectivity information will also be used after the installation to bind host packages using the StarAdmin application.

  1. Locate the Database Server Name (or Relational Database name).
    • DB2 for OS/390 or 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.
  2. DB2/400 users only: create an empty library on the host called STARSQL for use as the Package Collection name in StarAdmin and in the StarSQL data source configuration. Alternatively, set the Package Collection to the name of an existing library (e.g., QGPL) and verify that the AS/400 user who will run StarAdmin to bind packages has read and write authority to this library.
  3. Determine the IP address or network Host Name of the DB2 host.
  4. Identify the Port number on which DB2 listens for connection requests.
    • DB2 for OS/390 or 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).

Solution

The following sections guide you through the steps that are summarized below.

Step 1: Install StarSQL (estimated time: 5 minutes)
Step 2: License the Software (estimated time: 5 minutes)
Step 3: Install StarAdmin and Bind StarSQL Host Packages (estimated time: 10 minutes)
Step 4: Configure a Data Source Name (DSN) and Test Connectivity (estimated time: 5 minutes)

Step 1: Install StarSQL

Estimated Time: 5 minutes

To successfully complete this section, you will need a user ID that has administrative authority on the Windows computer where the software will be installed.

  1. Log on to Windows as a user with administrative authority.
  2. Extract the contents of the software file that you downloaded into a temporary directory.
  3. From the temporary directory, run the setup.exe application to start the installation. Choose to perform a Typical installation.

At the end of the installation, a License Configuration dialog prompts you to enter your license key for using StarSQL. Leave this dialog open and proceed to Step 2 .

Return to the top

Step 2: License the Software

Estimated Time: 5 minutes

StarSQL requires a license for evaluation purposes. To complete this section, you will need the Registration Key in the Download Instructions that were sent to the email address specified in the StarQuest Product Download Request form.

If the computer running StarSQL has access to the Internet, follow the Online Licensing Instructions below. Otherwise, follow the Alternate Licensing Instructions.

Online Licensing Instructions

  1. If not already open, launch the StarSQL License Configuration utility from Start --> Programs --> StarSQL --> License Configuration.
  2. Click on the License Online tab. Select a License Lock Type, enter in the Registration Key provided in the download confirmation email, and click Get License.

When the request successfully completes, the license(s) for the software you are registered to use appear in the License Keys list of the Licenses tab. The Registration Key may produce several License Keys, depending on the products you are registered to use. Subsequent attempts to use the same Registration Key will result in the identical License Key(s) being retrieved.

Alternate Licensing Instructions

  1. On the computer where StarSQL is installed, open the StarLicense Configuration utility from Start --> Programs --> StarSQL --> License Configuration. Record the Host ID displayed on the License Online tab.
  2. From a computer that has access to the Internet, click on or browse to the following URL:

    http://starcust.starquest.com/Registration/index.html#license

  3. On the StarQuest Online Licensing Form web page, enter in the email address used for the original download request and the Registration Key you received in the download confirmation email.
  4. Enter the Host ID value recorded previously and select the "Node-locked" license option. Click Next.
  5. Review the information provided. If any changes are required, click Previous and modify the values as needed. Otherwise, click the Accept button.
  6. Copy the license key displayed on the web page. You will also receive an e-mail with the license key.
  7. On the computer running StarSQL, open the StarLicense Configuration utility from Start --> Programs --> StarSQL --> License Configuration. Under the Licenses tab, click the Add button and enter in the license key.

Return to the top

Step 3: Install StarAdmin and Bind StarSQL Host Packages

Estimated Time: 10 minutes

To successfully complete this section you will need the following:

  • a Windows user ID with administrative authority,
  • a DB2 user ID that has authority to create and bind packages on the DB2 host, and
  • the database connectivity information collected in the Before You Begin section.

This step might be best performed by the database administrator.

Install StarAdmin

  1. Log on as an administrative user.
  2. Execute setup.exe to launch the installer.
  3. If prompted to install the Microsoft Visual C++ 2008 SP1 Redistributable package, click the Install button.
  4. On the Welcome dialog, click Next.
  5. Accept the License Agreement and click Next.
  6. Accept to install StarAdmin in the default directory of C:\Program Files\StarQuest\StarAdmin or browse to select an alternate directory. Click Next to continue.
  7. Click Install to being the installation or click the Back button to make any changes.
  8. After the installation is complete, click Finish.

Bind DB2 Host Packages

  1. From Start -> Programs -> StarAdmin, click on the StarAdmin shortcut to start StarAdmin.
  2. Enter the database connectivity values, as collected in the Before You Begin section and explained below, and click OK.
    • Host: the Host Name or IP address of the DB2 host
    • Port: the DB2 listening Port, in most cases the default value of 446 is correct
    • Database Name: the Database Server Name
    • Package Collection: DB2/400 users should specify a valid library, others should use the default value of STARSQL
    • Username/Password: DB2 user account that has authority to create and bind packages
  3. 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.
  4. Leave the default values for the Package Settings and Grant Options.
  5. From the Command menu, select Bind to create and bind the remaining packages.
  6. Once the packages have been created, the Summary dialog will display the results. Record the connection information in the Summary dialog to assist with the data source configuration for StarSQL.

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.

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

Return to the top

Step 4: Configure a Data Source Name (DSN) and Test Connectivity

Estimated Time: 5 minutes

To complete this section successfully, you will need a valid DB2 user ID that provides adequate authority to connect to the database.

Configure a DSN

You must configure a data source name (DSN) to your host before you can use StarSQL. To configure a data source after StarSQL is installed, start the ODBC Data Source Administrator. The ODBC Administrator is typically available from the Administrative Tools item of the Windows Control Panel. If you are running Windows x64, there is a 32-bit ODBC Administrator (located in Windows\SysWOW64) and a 64-bit ODBC Administrator (located in Windows\System32). If you have both versions of StarSQL installed, the ODBC Administrator shortcut in the StarSQL (32-bit) program group starts the 32-bit ODBC Administrator and the shortcut in the StarSQL (64-bit) program group starts the 64-bit version of the ODBC Administrator.

Add a new System or User DSN, configuring it with the values collected in the Before You Begin section and explained below. You may also refer to the Summary output from StarAdmin for these configuration values.


OS/390 OS/400* UDB
Database Server Name DDF location Database Server Name Database Name
Package Collection Name STARSQL QGPL STARSQL
Host Name Name or IP Address Name or IP Address Name or IP Address
Port Number 446 446 446
Catalog Schema SYSIBM QSYS2 SYSCAT

*OS/400 users can alternatively create a library, such as STARSQL, to use as the Package Collection instead of using QGPL.


Note: If you are using StarPipes, enter the IP Address or network name of the StarPipes server in the Host Name field. By default, StarPipes for Windows listens on port 446.

Test Connectivity

Test your connection to the host while in the data source configuration wizard by entering in a valid userid and password. Check the option "Connect to host database..." and click either the Summary or Advanced button.

Return to the top

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 provides an online help system that provides more information about defining ODBC data sources. Press F1 or click a Help button from the StarSQL Data Source Configuration Wizard to display the online help system.

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

Additional References:

StarSQL User’s Guide
StarSQL Wizard Help system
StarSQL Technical Documents

DISCLAIMER

The information in technical documents comes without any warranty or applicability for a specific purpose. 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 instructions may need to be modified to be appropriate for the hardware and software that has been installed and configured within a particular organization.  The information in technical documents should be considered only as an example and may include information from various sources, including IBM, Microsoft, and other organizations.