StarQuest Technical Documents

Quick Start Guide for StarPipes for Windows

Last Update: 27 May 2011
Product: StarPipes for Windows
Version: 4.x or later
Article ID: SQV00SW002

Abstract

This document is a guide for installing and configuring StarPipes for Windows. Please read through it completely before starting your installation. Please follow the instructions specific to your purpose. If you are using StarPipes with IBM Communications Server for Windows, please refer to the StarPipes for Windows Help.

Solution

Step 1: Complete Pre-installation Tasks
Step 2: Install StarPipes
Step 3: Configure Licensing
Step 4: Create a Listener
Step 5: Configure a Route
Step 6: Configure a StarSQL Data Source or StarSQL for Java Connection

Step 1: Pre-Installation Tasks:

Complete pre-Installation tasks for TCP/IP listener:

There are no pre-Installation tasks for using StarPipes as a TCP/IP gateway other than confirming that the desired port is not already in use by another application.

Complete pre-Installation tasks for SSL listener:

If you will be creating an SSL listener (i.e. StarPipes will be acting as an SSL front-end proxy for a DB2 host that is not enabled for SSL), you must install a server certificate named StarPipes on the Windows server running the StarPipes service; see the Certificate Management chapter of the Communications section in the StarPipes Help file.

Other certificate management tasks that may be needed for using SSL are beyond the scope of this document.

Complete pre-Installation tasks for TCP/IP to SNA gateway function:

This document assumes that you already have a Microsoft Host Integration Server configured to connect to your DB2 host. Gather the following information from your Host Integration Server:

  • Local LU
  • Remote LU
  • Mode

Return to the top

Step 2: Install StarPipes

When installing StarPipes, you will be given the following choices:

  • Install StarPipes for Windows:
    Choose this option to install StarPipes on any Windows server or workstation for users to connect through to the DB2 host.
  • Install StarPipes Management Utilities:
    Administrators can choose this option if they would like to remotely monitor StarPipes connections.

Next, you will be asked to specify the connectivity method you will be using:

  • If you are using SNA, choose Microsoft SNA Server.
  • If you are connecting directly via TCP/IP to your DB2 host, choose None.

Return to the top

Step 3: Configure Licensing:

The StarPipes service requires an "SP" license to accept requests from clients. In addition, it can optionally manage "SQ" licenses on behalf of StarSQL and StarSQL for Java clients, eliminating the need to configure licensing on individual workstations.

  1. Open Licence Configuration from the StarPipes program group.
  2. Select the Licenses tab.
  3. Select the Add... button and enter the licenses that you have received from StarQuest.
  4. Stop and restart the StarPipes service and any other applications (e.g. StarQuest Data Replicator service or ODBC applications using StarSQL) that may have be using StarQuest licensing. License configuration changes do not take effect until all applications using StarQuest licensing are restarted.

Step 4: Create a Listener:

You must configure at least one StarPipes listener and one route to your host before you can use StarSQL.

A listener defines the port(s) that StarPipes monitors for incoming DRDA messages.You may create multiple listeners; for example you may want to create both encrypted (SSL) and standard TCP/IP listeners, or, in the case of a multi-homed server, configure different listeners on different interfaces.

  1. Open the StarPipes Configuration from the StarPipes program group and select LOCAL MACHINE when prompted for StarPipes Server machine.
  2. Start the StarPipes service from the Service Control panel if it is not running.
  3. Select the Listeners tab and select the Add... button.
  4. To create a standard TCP/IP listener, leave the IP address as 0.0.0.0 (listen on all interfaces) and enter a port number (typically 446). After selecting OK, verify that that status of the listener is "Listening"; if the status is "Not Licensed", refer to the Configure Licensing section above.
  5. To create an SSL listener, leave the IP address as 0.0.0.0 (listen on all interfaces) and enter a port number (typically 448). Select the SSL/TLS checkbox, and, if desired, select SSL/TLS Options to configure additional SSL/TLS parameters, then select OK. An error dialog will be displayed if you have not installed a server certificate (see Complete pre-Installation tasks for SSL listener above). Verify that that status of the listener is "Listening"; if the status is "Not Licensed", refer to the Configure Licensing section above.

Step 5: Configure a Route:

You must configure a route for each DB2 server you wish to access. The route can be either TCP/IP, SSL/TLS, or SNA.

  1. Select the Routing tab and select the Add... button.
  2. Enter the RDB Name; this corresponds to the Database Server Name in your StarSQL data source. Note that it is case-sensitive and is typically entered in upper case.
  3. Select the radio button for the desired connection type (TCP/IP, SSL/TLS, or SNA LU 6.2).
  4. For TCP/IP and SSL connections, enter the Host Name (your DB2 TCP/IP host name or IP address) and Port number (the number of the port on your host that is configured to listen for DRDA requests; typical values are 446 for TCP/IP connections and 448 for SSL connections).
  5. For SNA LU6.2 connections, enter the Local LU, Remote LU, and Mode from Step 1.
  6. Click OK to save the route.
  7. Click on the Service Control tab and verify that StarPipes is running.

Note: You may wish to change the StarPipes service from "manual" to "automatic" so that it will start automatically every time this computer is started. This change can be made in the Windows Services control panel.

Return to the top

Step 6: Configure a StarSQL data source or StarSQL for Java Connection

Please refer to the Quick Start Guide for StarSQL for directions on how to configure a StarSQL ODBC data source to your host.

Note: These are the exceptions to the data source configuration.

  • Host Name: This is the name or IP address of the Windows computer on which StarPipes is installed.
  • Port: This is the port StarPipes is listening on (default is 446).

 

Please refer to the Quick Start Guide for StarSQL for Java for directions on configuring a StarSQL for Java client; substitute the StarPipes host name and listening port in place of the DB2 server's host name and port.

To configure an SSL connection from a StarSQL for Java client, include both StarSQL_SSL14.jar and StarSQL_JDBC.jar in the CLASSPATH and include the ssl property in the URL. Here is a sample URL:

jdbc:StarSQL_JDBC://mystarpipes:448/MYRDB;ssl=TLS

If you have installed an SQ license on the StarPipes server, then StarPipes will manage licenses on behalf of the StarSQL and StarSQL for Java clients, and there is no need to license the individual workstations..

Return to the top

Other references:
StarPipes for Windows Help (.chm)

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.