StarQuest Technical Documents

Quick Start Guide to Using SQDR Plus for DB2 UDB
on Windows

Last Update: 15 April 2008
Product: SQDR Plus for DB2 UDB
Version: 3.3 or later
Article ID: SQV00PU001

Abstract

This Quick Start Guide provides streamlined procedures to help you quickly set up an environment for performing incremental replication operations using SQDR Plus for UDB. It describes how to install and configure SQDR Plus on a DB2 UDB platform that is running a Windows operating system, how to install and configure SQDR on a Windows platform, and how to install and configure the StarSQL ODBC driver to access the host DB2 system. The procedures include instructions for configuring connections to the DB2 UDB host (source), SQDR (control), and the target (destination) databases, and for creating a subscription using the SQDR Replication Manager.

The first part of this guide focuses on preparing the DB2 UDB host, and the second part describes how to prepare a Windows client computer and define and run an SQDR replication operation. The estimated time to complete all tasks is about an 1 hour and 10 minutes, as summarized below.

Part One (on the DB2 UDB host): approximately 25 minutes

Step 1: Pre-installation Tasks. (estimated time: 15 minutes)

Step 2: Install the SQDR Plus Software. (estimated time: 10 minutes)

Part Two (on the Windows client): approximately 45 minutes

Step 1: Install the StarSQL ODBC Driver. (estimated time: 5 minutes)

Step 2: License the StarQuest Products. (estimated time: 5 minutes)

Step 3: Create DBMS Data Source. (estimated time: 5 minutes)

Step 4: Start the SQL Server Service. (estimated time: less than 5 minutes)

Step 5: Install and Configure SQDR. (estimated time: 10 minutes)

Step 6: Start the Data Replicator Manager and Create a Subscription. (estimated time: 10 minutes)

Step 7: Review the Subscription Status. (estimated time: less than 5 minutes)

Solution

The following sections guide you through the steps that are summarized in the preceding Abstract. The steps in Part One prepare the UDB host computer and install the SQDR Plus software, and the steps in Part Two are performed on a Windows-based computer that has TCP/IP connectivity to the target UDB host computer.

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. You cannot successfully complete the procedures in Part One or Two until these requirements are met.

General Requirements

• You have requested and downloaded evaluation copies of the StarSQL, SQDR, and SQDR Plus 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 Trial Download if the prerequisite software has not been downloaded. Request the download of SQDR Plus on the UDB platform to get bundled download instructions for all the required StarQuest products, including StarSQL, SQDR, and SQDR Plus for UDB.
• 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.

DB2 UDB Host Computer Requirements

• Verify that the DB2 UDB server software has been installed on the host computer and that it is version 8 with FixPak 10 or later, or version 9.1 or later. You can use the db2level command to display the version and service level (build level and FixPak number) of the DB2 instance. For example, a typical result of running the db2level command on a computer that has DB2 UDB v9 installed would be:

DB21085I Instance "DB2" uses "32" bits and DB2 code release "SQL09010" with level identifier "01010107".

Information tokens are "DB2 v9.1.0.189", "n060119", "", and Fix Pack "0".

Product is installed at "c:SQLLIB" with DB2 Copy Name "db2build".

• Verify that you can access the DB2 command line processor (CLP):

From a Windows command prompt, enter db2cmd, and then enter the command db2.

If the DB2 CLP does not start, edit the PATH environment variable to include the directory in which DB2 is installed. Right-click the My Computer icon on the desktop and select Properties. Under the Advanced tab, click the Environment Variables button and locate the PATH system variable. Add the directory in which DB2 is installed to the PATH variable.

DB2 UDB Host Computer Java Requirements

• Ensure that the DB2 UDB computer where you will install SQDR Plus has a Java Virtual Machine (JVM) v1.4 or later installed and specified in the system PATH.

Type java -version at a command prompt to display the active java version.

If the Java version is not returned, or is earlier than v1.4, download the JVM software from the IBM developerWorks Web site.

• If you have more than one version of Java installed, verify that DB2 UDB is configured to use the correct version of the Java Development Kit (JDK):

1. Enter the following command in the DB2 command window and look for the Java Development Kit installation path field, JDK_PATH:

db2 get dbm cfg

2. If you need to set the JDK_PATH value to the correct location of the JDK or JVM, enter the following on the DB2 command window, replacing the path as necessary with the location where Java is installed on your computer.

db2 update dbm cfg using JDK_PATH C:\Program Files\IBM\SQLLIB\java\jdk

If the server computer supports both 32-bit and 64-bit instances use the JDK_64_PATH configuration parameter instead of the JDK_PATH parameter. The JDK_64_PATH parameter specifies the directory under which the 64-bit version of the JDK is installed.

3. If you change the JDK_PATH parameter, enter the following commands in a DB2 command window to stop and restart the DB2 instance so the change takes effect.

db2stop
db2start

• Review the CLASSPATH environment variable to ensure it specifies the path to the following files: db2java.zip, db2jcc.jar, and db2jcc_license_cu.jar.

1. Right-click the My Computer icon on the desktop and select Properties. Under the Advanced tab, click the Environment Variables button. Review the system variables and, if needed, add the directory to the db2java.zip, db2jcc.jar, and db2jcc_license_cu.jar files to the CLASSPATH variable. These files are typically located in the directory \Program Files\IBM\SQLLIB\java.

SQL Server (SQDR Platform) Requirements

• The client computer on which you will install SQDR and StarSQL must have some version of Microsoft SQL Server installed. If you do not already have a SQL Server installation, you can obtain the Microsoft SQL Server 2000 Desktop Engine (MSDE 2000) or the SQL Server 2005 Express Edition free of charge from Microsoft to use as a control database for the Data Replicator. The StarQuest Technical Document "Installing SQL Server for a Control Database" provides details for using MSDE 2000 or 2005 Express with SQDR.
• Depending on the type of authentication that is configured for the SQL Server, you must have a SQL Server login (if using SQL Server and Windows authentication) or a Windows user ID (if using Windows-only authentication) that has permission to access the SQL Server Control Database that is used by SQDR. This login must be a member of the System Administrators (sysadmin) fixed server role.
• Your SQL Server user ID (if using SQL Server and Windows authentication) or Windows user ID (if using Windows-only authentication) also must have sufficient permissions to perform the replication operations on the target SQL Server database. If using Windows-only authentication, ensure that the proper logins have been created for the Windows user account that will access the target SQL Server database. For more information on SQL Server Authentication, refer to the Permissions Validation section of Administering SQL Server documentation (SQL Server 2000) or refer to the Authentication Mode section in the Installing SQL Server documentation (SQL Server 2005). 
• If the SQL Server on which SQDR will be installed will also serve as the destination database, ensure that incremental replications will be able to rely on unique fields to identify change data. This requires that the target database be configured with a Case Sensitive collation sequence. If you have SQL Server Enterprise Manager (SQL Server 2000) or the SQL Server Management Studio (SQL Server 2005), you can verify the collation sequence by viewing the database properties. A case-sensitive collation has the characters “CS” appended to the Collation Designator. For example, the collation SQL_Latin1_General_CP1_CS_AS is a case-sensitive collation for U.S. English systems. You can set the collation for a new database using the SQL Server Enterprise Manager or the SQL Server Management Studio.
• If you intend to configure replication subscriptions to run according to a schedule, verify that the SQL Server Agent service is available and running. (MSDE 2000 includes the SQL Server Agent. SQL Server Express does not include the SQL Server Agent component; therefore you cannot schedule subscriptions to run automatically if you use SQL Server Express for the SQDR control database.)

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

Part One: Prepare the DB2 UDB Host Computer

Total Estimated Time to Complete: 25 minutes

Step 1: Pre-installation Tasks

Estimated Time: 15 minutes

1. Log on to the DB2 UDB host computer with a user that has Administrative rights.
2. Determine the current database manager instance by running the command db2 get instance in the DB2 command window. If you want to install SQDR Plus to this database instance, go to Step 3. If you wish to change the default instance, view the available instances using the db2ilist command, and set the default instance using the command:

set db2instance=<instance_name>

3. The SQDR Plus installation will prompt for the host IP and port number on which DB2 listens for remote connections. The default values for the DB2 host IP and port are 127.0.0.1 (localhost) and 50000. If you are unsure of the DB2 host IP and port number, you can review this information using the Windows ipconfig command and the DB2 Control Center, respectively.

To determine the DB2 host IP:

1. Open a Windows command prompt by clicking Start-->Run and entering cmd in the Open field. Click OK.
2. At the command line execute the command ipconfig and record the IP Address of the system.

To determine the port number:

1. Open the DB2 Control Center by clicking Start–>Programs–>IBM DB2–>General Administration Tools–>Control Center.
2. Select the database instance and select Setup communications from the Object Details pane or the context menu.
3. In the Setup communications dialog, click on the Properties(2) button to review the properties for the TCP/IP protocol.
4. Record the value for the port number.

4. As you install SQDR Plus you also must specify a DB2 user name and password that has access to the DB2 UDB database that SQDR Plus will monitor. Create this account before you start the installation if it does not already exist. The DB2 user account needs authority to:

• Connect to the database
• Create tables
• Create packages
• Create and register routines
• Create schemas
• Create external routines

5. The database must be configured to use archive logging for SQDR Plus to access the log files it needs to ensure incremental replication operations are applied properly. You can use the DB2 Control Center to enable archive logging for the database before you install SQDR Plus. From the DB2 Control Center select the database, right-click, and select the Configure Database Logging command to change the type of logging to Archive.
6. This Quick Start Guide assumes that the default configuration values are used during the installation as they are generally appropriate in most environments. Make a note of the optional email notification values for your environment if you want to specify these values during installation. You can leave these fields blank during the installation and configure the email notification feature at a later time. Refer to the SQDR Plus for DB2 Universal Database User's Guide for more information about these parameters.

Configuration Parameter	Sample Value	Your Value
SMTP Server:	mail.mydomain.com
From:	sqdr@mydomain.com
To:	sqdradmin@mydomain.com
Notification Level:	SEVERE

Step 2: Install the SQDR Plus Software

Estimated Time: 10 minutes

You run the SQDR Plus installer directly from the Windows computer on which you want to install SQDR Plus.

1. Copy the DATA1.JAR, media.inf, and setup.bat files to the computer on which you want to run the installation.
2. Log on to the computer as a user with Administrator rights, and change to the directory where you copied the SQDR Plus installation files.
3. Execute the setup.bat file to begin the installation.
4. Click Next to proceed with the installation process after the Welcome dialog appears.
5. Click Next once more to proceed to the DB2 connection information dialog. Select the database on which to install SQDR Plus, and provide the host IP, port, and DB2 User ID as determined in Steps 3 and 4 of the Pre-Installation tasks.
6. After you review the License Agreement for using the software, click Next to accept the terms and proceed with the installation.
7. Accept all of the default values in the installer dialogs, except for those values gathered in the prior section if you want to configure the email notification feature.
8. After you review the installation summary information, click Install to begin the installation phase, and click Next as the Wizard displays panes that show the task results. If an error is encountered during the installation, back up to the prior installation pane and correct the error.
9. When the installation completes, select Capture Agent Log from the SQDR Plus for DB2 UDB program group and review the log file for errors.

Additional References

SQDR Plus for DB2 Universal Database User’s Guide

Part Two: Prepare a Windows Computer

Total Estimated Time to Complete: 50 minutes

All of the procedures in this part are performed from a Windows-based computer that has TCP/IP connectivity to the UDB computer where SQDR Plus is installed.

For best results with SQDR, StarQuest recommends using the StarSQL ODBC driver for access to DB2. However, SQDR does support the use of the IBM DB2 Connect driver. If you plan to use the IBM DB2 Connect driver with SQDR, skip Step 1 and proceed with Step 2 below. If you need to replicate LOB data, in the DB2 Connect data source configuration add the LONGDATACOMPAT parameter from the Advanced Settings tab of the CLI/ODBC Settings and set this value to “As LONGVAR data”. Set the Maximum LOB column size value if desired, or accept the default value.

Step 1: Install the StarSQL ODBC Driver

Estimated Time: 5 minutes

The StarSQL software is distributed as a compressed file that you download from the StarQuest Ventures Web site. See the section “Before You Begin” on page 2 if you have not already downloaded the StarSQL  software.

1. To install StarSQL, run the setup.exe program from the StarSQL installer image.
2. Select 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. You can enter the license keys for all the StarQuest products you want to use, as described in the next step.

Step 2: License the StarQuest Products

Estimated Time: 5 minutes

If you have not already received temporary license keys for the evaluation software, refer to the Download Instructions that were sent via email in response to the software evaluation request. The Download Instructions provide specific instructions for obtaining a license key that allows you to use the product(s). You can add the license key for multiple products at once, as described below for adding the StarSQL, SQDR, and SQDR Plus license keys.

1. From the Licenses tab of the License Configuration dialog, click Add to display the Add License dialog.
2. In the Add License dialog enter the license key for StarSQL and click the Add button. Repeat this step to enter the license key for SQDR and SQDR Plus. After you have added the license key for each of the products, click OK in the License Configuration dialog.

Step 3: Create DBMS Data Source

Estimated Time: 5 minutes

An ODBC data source name (DSN) defines the information that a driver needs to access a specific instance of data in a DBMS. You must define an ODBC DSN for each host DBMS that you want to replicate to or from. The following provides instructions on how to configure a StarSQL ODBC DSN. If you plan to use DB2 Connect as the ODBC driver, refer to the appropriate IBM documentation for instructions on how to configure a DB2 Connect DSN.

1. Launch the ODBC Administrator from the Windows Control Panel. For most versions of Windows the ODBC Administrator is typically found in the menu path Settings—>Control Panel
   —>Administrative Tools—>Data Sources (ODBC).
2. Click the System DSN tab of the ODBC Data Source Administrator window. Click Add and, in the next dialog, select StarSQL 32 for the driver and click Finish.
3. In the first dialog of the StarSQL Data Source Wizard, enter a name for the data source and, optionally, a description. Click Next to step through the Wizard panes, specifying values appropriate for your environment. A typical data source connecting to a UDB server has the following configuration values:

Database Server Name	Database name (as it appears in the Control Center)
Package Collection Name	SQDR
Host Name	Network name or IP address of the UDB computer
Port	50000 (unless configured differently)
Catalog Schema	SYSCAT

4. From the Network pane of the StarSQL Data Source Wizard, click the Test Connection button to ensure you can connect to the host database. If the connection fails, modify the data source configuration until the ODBC DSN can successfully connect to the host.

Additional References

StarSQL Quick Start Guide
StarSQL User’s Guide
StarSQL Online Help

Step 4: Start the SQL Server Service

Estimated Time: less than 5 minutes

The StarQuest Data Replicator requires a control database in which to store definitions for sources, destinations, subscriptions, and groups of subscriptions. If you do not already have a SQL Server installation, you can obtain the Microsoft SQL Server 2000 Desktop Engine (MSDE 2000) or SQL Server 2005 Express Edition free of charge from Microsoft, as further described in the StarQuest Technical Document "Installing SQL Server for a Control Database.”

The SQL Server service must be running for the Replicator Service to access its control database. If you intend to configure replication subscriptions to run according to a schedule, also start the SQL Server Agent service. Start the SQL Server and SQL Server Agent services from Windows Services, typically found under Control Panel—> Administrative Tools—> Services.

The SQL Server 2005 Express Edition does not include the SQL Server Agent component, which the Data Replicator Manager uses to schedule subscriptions to run automatically. If you use the free SQL Server 2005 Express Edition as a control database for Data Replicator, you can still use the Data Replicator Manager to run subscriptions manually, and you can use other methods, such as Windows Scheduler, to schedule them to run automatically.

Additional References

StarQuest Technical Document: Installing SQL Server for a Control Database

Step 5: Install and Configure the StarQuest
Data Replicator Software

Estimated Time: 10 minutes

The StarQuest Data Replicator software is distributed as a compressed file that you download from the StarQuest Ventures Web site. See the section “Before You Begin” if you have not already downloaded the SQDR software.

1. Run the setup.exe program from the SQDR installer image.
2. At the end of the installation, choose to launch the Data Replicator Configuration and click Finish.

Configure the Data Replicator Service

You must configure the Data Replicator service to specify which SQL Server data source to use for the control tables and how the Data Replicator service should log in to the SQL Server.

1. In the first pane of the Configuration Wizard, select the SQL Server data source that you configured for the Data Replicator control tables and enter the user ID required to log in to the SQL Server. Click Next to proceed.

If you receive an error that the data source cannot be found, launch the ODBC Data Source Administrator from Control Panel--> Administrative Tools-->Data Sources (ODBC), double-click the SQL Server System DSN, and review the configuration. At the configuration summary verify that the Test Connection succeeds. Exit the ODBC Administrator and return to the SQDR Configuration Wizard.

1. Select the option Create a New Control Database and click Next.
2. Choose whether to start the Data Replicator service automatically when the computer is started or manually when the service is needed, and the Windows account under which the Data Replicator service will run. Click Finish to save the Data Replicator configuration.

Step 6: Start the Data Replicator Manager and Create a Subscription

Estimated Time: 10 minutes

You use the Data Replicator Manager to set up and administer replication operations.

1. Select Data Replicator Manager from the StarQuest Data Replicator program group if it is not already running.
2. In the License Configuration dialog, verify that you have a license key entered with a Product ID of DR and click OK. See “Step 2: License the StarQuest Products” if you have not entered license keys for using the evaluation software.

Define a Source

To define the source data that you want to replicate:

1. In the main Data Replicator Manager window, right-click the Sources folder and select the Insert Source command.
2. Select the DSN that connects to the source database that contains the data you want to replicate, and enter a user ID and password that has permission to access that database. Click OK to add the source.

 

3. If the source is enabled with SQDR Plus for UDB, SQDR will automatically detect any available Capture Agent schemas. Click OK to accept the default Capture Agent schema. We recommend that you supply a Notification Address (hostname or IP address) of the computer that you want to receive a UDP notification when changes are committed to this source.

The drop down menu lists the IP addresses of all active network connections. Usually one of the listed values is best; in the case of multiple subnets use the same subnet as the UDB host. If NAT is being used and the IP address known to the host is different than the local address, use the external address that the UDB host uses to communicate with the SQDR computer.

Define a Destination

Now define the destination that will receive the replicated data.

1. Right-click the Destinations folder and select the Insert Destination command.
2. Select the DSN that connects to the database to which you want to replicate the data, and enter a user ID and password that has permission to access that database. Click OK to add the destination.

Create an Incremental Group

In this section you create a group in which to place one or more subscriptions that perform incremental replication operations between the specified source and destination.

1. Right-click the Groups folder and select Insert Incremental Group. In the Group properties dialog, enter a name for the Group and an optional description.

2. On the Advanced tab, select the Source and Destination that will be used for each incremental replication subscription in this group. Click OK to add the group.

Create a Subscription

The Replicator Manager provides a Subscription Wizard to help you define the specific source data and how you want to replicate it.

1. Right-click the Subscriptions folder beneath the source that you added and select the Insert Subscription command. The Add Subscription Wizard appears.
2. In the Select the Source pane, select Incremental as the Replication Type and enter a schema or object name if you want to filter the source objects list. Click the Refresh button to display the available source objects in the right pane and select the source object you want to replicate. Click Next to proceed.

3. In the Select a Destination pane, select the DSN that connects to the destination you added to the Replicator Manager. Review the Destination Options and Replication Options, and click Next to proceed.
4. In the Select Group pane select the incremental replication group that you created earlier. Click Next to continue.

5. The Define Criteria pane allows you to specify a SQL WHERE clause in order to horizontally partition the data to be replicated. Enter a valid WHERE clause and click the Verify Criteria button, or leave the field blank. Click Next to continue.
6. The Define Destination Columns pane allows you to review and change the data type mappings for the source and destination objects. Modify the destination columns if desired and click Next.

7. Click Next in the Create Table Statement pane. The CREATE TABLE statement will not appear until the subscription has been saved.
8. On the Define Processing pane, enter optional host commands to be executed before and/or after the  data is replicated. Click Next to continue.
9. On the Indexes/Constraints pane, click Refresh to display any indexes or constraints defined for the source. Select any that you want to replicate to the destination and click Next.
10. Enter a name for the subscription and click Finish.

The subscription is added beneath the Subscriptions folder of the defined source and to the corresponding group.

Step 7: Review the Subscription Status

Estimated Time: less than 5 minutes

After you define an incremental replication subscription the Data Replicator runs a baseline snapshot replication that forms the base against which incremental changes are tracked. After the baseline snapshot replication succeeds, the incremental subscription actively monitors the source for changes. This step shows you how to monitor the status of a subscription and a group of incremental subscriptions.

1. Review the status of the subscription by highlighting the subscription in the left pane of the Replicator Manager.

2. Double-click the replication event, indicated by the  icon, to view the statistics of the baseline snapshot. If the data did not replicate successfully, review the error(s) and correct the subscription properties as necessary.

3. Locate the member subscription under Groups, and double-click on the Replication Event to view the status of the subscription. After the baseline snapshot operation completes successfully the incremental subscription is automatically enabled and actively monitoring for changes at the source.

Continuing Your Software Evaluation

This Quick Start Guide was intended to help you install the StarQuest software and perform a data replication operation as quickly as possible.  Please continue to experiment with the software by adding additional subscriptions, scheduling replication operations, and performing SQL operations on data before and/or after it is replicated. As you experiment with the SQDR Plus and SQDR software, refer to the product documentation for more information.

• The SQDR Plus for DB2 Universal Database User's Guide manual is available as a PDF file in the SQDR Plus installation image. It provides more detail about configuring and managing the SQDR Plus Capture Agent.
• The Data Replicator Manager provides an online help system that provides more information about defining and running replication operations. Press F1 or click a Help button from the Data Replicator Manager 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.

 

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

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

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