StarQuest Technical Documents

StarSQL for Java Quick Start Guide

Last Update: 02 April 2009
Product: StarSQL for Java
Version: 2.5x or later
Article ID: SQV00SJ007

Abstract

This document is a guide for installing and configuring the StarSQL for Java software on a Windows, UNIX, or Mac OS X computer. Read the complete document before starting your installation.

Solution

This solution describes how to perform the following procedures:

Step 1: Install StarSQL for Java
Step 2: Install StarLicense (UNIX and Mac OS X only)
Step 3: Obtain License
Step 4: Verify Connectivity

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 as described in the StarSQL for Java User's Guide.

General Requirements

  • You have requested and downloaded the StarSQL for Java and, if required, the StarLicense 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.
  • 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 user ID that has administrative (Windows) or root (UNIX/Mac) authority on the computer where the software will be installed.
  • Ensure that the computer where StarSQL for Java will be installed has a compatible Java Virtual Machine (JVM) or Java Runtime Environment (JRE) installed and specified in the system PATH. You can obtain the Java Runtime Environment free of charge from Sun Microsystems at http://www.java.com/en/download/. From a command prompt, run the java -version command to verify that Java is installed and can be located, as shown in the following example.

C:\>java -version
java version "1.6.0_03"
Java(TM) SE Runtime Environment (build 1.6.0_03-b05)
Java HotSpot(TM) Client VM (build 1.6.0_03-b05, mixed mode)

If you are using a 64-bit JVM, contact StarQuest Customer Support for special instructions.

  • FOR OS/400 USERS ONLY: On the OS/400 system you need to either create an empty library called STARSQL to hold the StarSQL driver's SQL packages, or you can specify an existing library as the 'collection' in the connection URL or Datasource configuration.

Step 1: Install StarSQL for Java

Windows

  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.

UNIX

StarSQL for Java is distributed as an .rpm file for installation by the RPM Package Manager and as a .tar file that uses a setup script for installation on UNIX or Linux computers that do not support RPM. To use either of these methods you run the setup shell script. The setup script extracts the contents of the starjdbc.tar file or invokes rpm when using the RPM installer.

  1. Log on to the UNIX computer as root user.

  2. Extract the downloaded package to a temporary directory using the tar -options <filename> command, as shown in the following example.

    # tar -xvf starsql-java-rpm.tar

  3. From the directory where you extracted the files, enter the following command to run the setup shell script.

# ./setup

The installation process installs the StarSQL for Java software into the default directory shown in the following table for each supported UNIX platform.

UNIX Platform Default StarSQL for Java Installation Directory
AIX /usr/lpp/starsql_java
FreeBSD /usr/local/share/starsql_java
HP-UX /opt/starsql_java
Linux /usr/share/starsql_java
Solaris /opt/starsql_java

 

MAC

To install StarSQL for Java on a MacOS X computer:

  1. Use the Finder to open the folder that contains the installation source files.
  2. Double-click setup-macos.command, you will be prompted for your password.

The default directory for installing StarSQL for Java on a Mac OS X computer is /Applications/starsql_java.

Step 2: Install StarLicense (UNIX and Mac OS X only)

You must have a license to use the StarSQL for Java software on a UNIX or Mac OS X computer. The StarLicense product manages the licenses for using all StarQuest products and is available for download from the StarQuest Web site.

Install StarLicense on UNIX

Install StarLicense on Mac OS X

UNIX

  1. Log on as root user.
  2. 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 example.

    # uncompress starlicense-linux.tar.Z

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

    # tar -xvf starlicense-linux.tar

    or

    # tar -xvf starlicense-linux-rpm.tar

  4. 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 StarLicense Installation Directory
AIX /usr/lpp/starlicense
FreeBSD /usr/local/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 are not prepared to request a 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 license key.
  • Answer y (Yes) if you are prepared to request a license key and want to enter it now.

Mac OS X

  1. Extract the StarLicense package to a temporary folder.
  2. Use the Finder to open the folder that contains the installation source files.
  3. Double-click on setup-macos.command and enter in your password, if prompted. You will then be prompted with the following:

This script uses tar to install StarLicense for UNIX to /Applications/starlicense and should be run as root.
Do you wish to continue (y/n)?

Answer y (Yes) to this prompt.

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

  • Answer n (No) if you are not prepared to request a license key yet. After you obtain a license key, double-click configure.command from the StarLicense installation directory to display the StarLicense Configuration Menu and enter the license key.
  • Answer y (Yes) if you are prepared to request a license key and want to enter it now.

Step 3: Obtain License

To license the software, you need 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.

Windows

UNIX/MAC OS X

Windows

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

Online Licensing Instructions

  1. Open the StarLicense Configuration utility from Start --> Programs --> StarSQL for Java --> StarLicense 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 for Java is installed, open the StarLicense Configuration utility from Start --> Programs --> StarSQL for Java --> StarLicense 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

  1. 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.
  2. Enter the Host ID value recorded previously and select the "Node-locked" license option. Click Next.
  3. Review the information provided. If any changes are required, click Previous and modify the values as needed. Otherwise, click the Accept button.
  4. Copy the license key displayed on the web page. You will also receive an e-mail with the license key.
  5. On the computer running StarSQL for Java, open the StarLicense Configuration utility from Start --> Programs --> StarSQL for Java --> StarLicense Configuration. Under the Licenses tab, click the Add button and enter in the license key.

Return to top

UNIX/MAC OS X

Request License and Configure StarLicense

If you opted to administer StarLicense after the installation, you will be presented with the StarLicense Configuration Menu. Or, enter configure (UNIX) or double-click configure.command (Mac OS X) from the StarLicense installation directory to display the StarLicense Configuration Menu. The StarLicense Configuration Menu presents the following options:

StarLicense Configuration Menu

1) Add license with Registration Key (via Internet)
2) Add license with License Key
3) Remove a License Key

4) Start License Server daemon
5) Stop License Server daemon
6) Display License Server status
7) Test licensing checkout
8) Display StarLicense configuration

9) Configure client to use a remote License Server
10) Remove a client-server connection

11) Licensing Help
12) Exit

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

Online Licensing Instructions

  1. Select option 1) Add license with Registration Key (via Internet).
  2. If you want to license this particular computer, answer y (Yes) to the prompt. If you want to license a different computer, follow the Alternate Licensing Instructions below.
  3. Copy the Registration Key provided in the confirmation email from StarQuest and paste it next to the StarLicense prompt for a Registration Key. Press Enter and allow time for StarLicense to connect to the StarQuest licensing server to obtain a license key. If the request fails, correct the error and retry or use the Alternate Licensing Instructions below.
  4. After a license key is obtained, a Listener is configured. Enter the IP Address that StarLicense should listen on. If you want StarLicense to listen on all configured IP Addresses, leave this field at its default value of 0.0.0.0. Press Enter..
  5. Enter in the port number that you want StarLicense to listen on for licensing requests. If the default port, 4999, is acceptable, leave this field at its default value and press Enter. If you decide to configure StarLicense to listen on a port other than the recommended 4999, you will need to manually configure the port number specified under the appropriate [ClientServerN] heading in the StarSQL for Java StarLicense.properties file.

Alternate Licensing Instructions

  1. 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

  2. On the StarQuest Online Licensing Form web page, enter in the e-mail address used for the original download request and the Registration Key you received in the download confirmation email.
  3. Enter the IP Address of the computer where StarLicense is installed. To find the IP Address, choose option 1) Licensing Help. If the computer has multiple IP Addresses configured, any one of the IP Addresses can be used. Enter the address in decimal dot notation (e.g., 192.168.44.12).
  4. Select the License Server radio button. 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 for use in Step 3. You will also receive an e-mail with the license key.
  7. From the StarLicense Configuration Menu, choose option 2) Add license with License Key.
  8. Enter in the license key obtained previously and press Enter.
  9. After a license key is obtained, a Listener is configured. Enter the IP Address that StarLicense should listen on. If you want StarLicense to listen on all configured IP Addresses, leave this field at its default value of 0.0.0.0. Press Enter.
  10. Enter in the port number that you want StarLicense to listen on for licensing requests. If the default port, 4999, is acceptable, leave this field at its default value and press Enter. If you decide to configure StarLicense to listen on a port other than the recommended 4999, you will need to manually configure the port number specified under the appropriate [ClientServerN] heading in the StarSQL for Java StarLicense.properties file.

Start StarLicense

  1. After configuring StarLicense with a license key, return to the StarLicense Configuration Menu and select option 4) Start License Server daemon.
  2. Select option 7) Test licensing checkout to verify that StarLicense is correctly configured.

Return to top

Step 4: Verify Connectivity

StarSQL for Java supplies several sample applications that can be used to verify database connectivity. These applications can be found in the \samples subdirectory in the StarSQL for Java installation directory.

To test basic connectivity, use the simpconn application in the \samples\simpconn directory.

  1. Open the simpconn.bat (Windows) or simpconn.sh (UNIX/Linux or Mac OS X) file in a text editor.
  2. Edit the URL, USER, and PASSWORD variables to specify values appropriate for your database environment. Save the file.
  3. To run the simpconn application on:
    • Windows: open a command prompt, change directory to the \samples\simpconn directory and run the simpconn.bat file.
    • UNIX/Linux or Mac OS X: run the simpconn.sh to launch the simpconn application.

    If the connection is successful, the output will look similar to the following:

Connected to jdbc:StarSQL_JDBC://MYHOST:446/MYRDB
Database DB2/400
Version QSQ05040
Driver StarSQL for Java
Version V2.52.0316
pass 1 completed
Press Enter to close the connections

To test the ability to query the database using either QueryApp or CatalogApp, perform the following procedures:

Windows

  1. Start QueryApp or CatalogApp from Start --> Programs --> StarSQL for Java --> Samples.
  2. Enter the Database, Host, Port, UserID and Password for the DB2 system that you want to connect to.
  3. Click the Connect button. If the connection fails, review the error message at the lower portion of the dialog, correct the problem and retry the connection.
  4. Execute a simple SQL query (QueryApp) or view the catalog information for a specific database object (CatalogApp).

UNIX/Mac OS X

  1. Run the shell script samples.sh (UNIX) or samples.command (for MacOS X).
  2. From the menu of the available sample applications and utilities, as shown below, select either CatalogApp or QueryApp.

    StarSQL for Java Utility & Sample Applications

    1) ShowVersion
    2) CatalogApp
    3) QueryApp
    4) LobTestApp
    5) CreateDS - Create a DataSource
    6) Transaction Log Manager
    7) Exit

  3. Enter the Database, Host, Port, UserID and Password for the DB2 system to which you want to connect.
  4. Click the Connect button. If the connection fails, review the error message at the lower portion of the dialog, correct the problem and retry the connection.
  5. Execute a simple SQL query (QueryApp) or view the catalog information for a specific database object (CatalogApp).

Refer to the StarSQL for Java User's Guide for instructions on running the other sample applications.

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 for Java includes a User's Guide that provides more information about driver configuration and defining connection URLs and data sources.

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.

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.