StarQuest Technical Documents

How to Generate DRDA and Debug Traces Using StarPipes for Windows

Last Update: 28 January 2016
Product: StarPipes for Windows
Version: 2.x or later
Article ID: SQV00SW003

Abstract

It may be difficult to obtain DRDA traces using the StarSQL DRDA Trace Recorder under certain conditions, such as when running a web server or a multi-threaded application. In these situations, you may be asked by StarQuest Customer Support to install StarPipes in order to generate DRDA traces for troubleshooting purposes. The StarPipes Debug traces may also be helpful in troubleshooting connectivity issues.

Solution

Install and configure StarPipes to capture DRDA and/or Debug traces. A Starpipes license is required to install and use StarPipes.

Download and Install StarPipes

Install StarPipes on a computer that is using the StarSQL or StarSQL for Java driver to connect to the host. You need to be able to reproduce the problem from this computer after StarPipes is installed.

1. From a browser, download the StarPipes software using the URL provided by StarQuest Customer Support. Save the compressed archive file to a temporary directory.
2. Uncompress the file into a temporary directory using a file archiver program of your choice.
3. Run the StarPipes setup.exe program and follow the installation prompts to install the software. If you need APPC-SNA support (for Host Integration Server), choose the SNA Server option during the installation.
4. Use the License Configuration application to enter a StarPipes (SP) license.

Configure a StarPipes Route to DB2 Host

1. Open the StarPipes Configuration from Start –> Programs –> StarPipes for Windows. 
   
2. On the Select StarPipes Server dialog, leave [LOCAL MACHINE] as the StarPipes Server Machine and click OK. Answer Yes to the prompt asking if you wish to start the StarPipes service.
3. Click on the Listeners tab; if necessary, create a TCP/IP listener, listening on all interfaces (0.0.0.0) and port 446.
4. Click on the Communications tab. 
5. Click Add to configure an RDB route to the DB2 host. Note that the RDB Name that you specify for the route must match the Database Server Name in the StarSQL DSN definition. If necessary, review the StarSQL DSN configuration for the correct values to use.
   
   • If connecting to DB2 via direct TCP/IP, select the TCP/IP radio button and supply the RDB Name of the database, the network name or IP address of the DB2 host server, and the port on which DB2 listens for DRDA requests. Click OK to add this route to the StarPipes configuration.
   • If connecting to DB2 through a Host Integration Server, select the SNA LU 6.2 radio button and enter the RDB Name of the database, Local LU, Remote LU, and Mode values for the connection. DB2 Server for VSE & VM users may need to check the Use Custom DRDA TP Name checkbox and supply a custom DRDA TP Name value. Click OK to add this route to the StarPipes configuration. 
6. In the Routing section of the Communication panel, verify that the route configured in Step 4 is correct. Leave the StarPipes Configuration dialog open as it will be used later to enable tracing.
   

Modify the StarSQL DSN to Connect Through StarPipes

1. Open the Windows ODBC Data Source Administrator from Control Panel –> Administrative Tools. If you are running StarSQL on a Windows 64-bit operating system, use the 32-bit ODBC Data Source Administrator (typically located in \WINDOWS\SysWOW64\odbcad32.exe) to modify the data source.
2. Highlight the StarSQL DSN and click Configure.
3. In the Navigation Panel on the left, click on Network. Select TCP/IP as the Network Option (even if you connect through Host Integration Server).
4. Make a note of the original configuration, as you will revert back to these settings after troubleshooting the problem. Then change the Host Name to the network name or IP Address of the computer that is running StarPipes (or 127.0.0.1 if you are running StarPipes on the same machine as StarSQL), and specify a Port Number of 446. Do not click the Test Connection button. Click Next.
5. On the UserID/Password panel, enter a valid DB2 UserID and Password. Check the option labeled “Connect to host database...” and click Summary. This will test the connection to DB2 through StarPipes.
   
6. If the connection is successful, the Summary displays "The Setup Wizard successfully connected to the database." If an error occurs, review the message and verify that the values specified in the StarPipes route and StarSQL DSN configuration are correct.
   

Modify the StarSQL for Java URL to Connect Through StarPipes

If you are using StarSQL for Java:

1. Examine the connection URL to obtain the values to configure StarPipes. For example, if the URL is jdbc:StarSQL_JDBC://myhost.mydomain.com:446/MYRDB, use the parameters host myhost.mydomain.com, port 446, and RDB (database name) MYRDB when configuring StarPipes.
2. Make a backup of the connection URL and modify it to connect to jdbc:StarSQL_JDBC://127.0.0.1:446/MYRDB.

Enable StarPipes Tracing

1. Return to the StarPipes Configuration dialog and click on the Logging tab.
2. Check the Enable DRDA Tracing and/or the Enable Debug Tracing option as instructed by StarQuest Customer Support. If Debug Tracing is enabled, choose Debug as the Debug Tracing Level.
3. Click Apply and then click OK to exit the Configuration dialog.

Reproduce the Problem

1. With StarPipes tracing enabled, reproduce the steps to create the problematic situation. If you are working with StarQuest Customer Support on more than one StarSQL issue, reproduce only one problem at a time while tracing is enabled.
   

Disable Tracing

1. Open the StarPipes Configuration from Start –> Programs–> StarPipes for Windows. 
2. Click on the Logging tab and click the checkmark(s) to disable any logging option that was enabled.
3. Click Apply and OK to exit the dialog.

Collect and Send the Trace Files

1. Locate the Trace directory, which is either \Users\Public\Documents\StarQuest\StarPipes\Trace (Windows Vista and later) or \Documents and Settings\All Users\Documents\StarQuest\StarPipes\Trace (Windows Server 2003/XP).
   
2. Compress all of the files into a single archive file and send it to StarQuest Customer Support.
3. If you need to collect another set of trace files for another problem, move all of the trace files to another directory before you enable the StarPipes tracing again.

After the problem has been resolved you can remove StarPipes using Windows Add/Remove Programs, and restore the StarSQL DSN or StarSQL for JDBC URL to its original configuration.