Copyright Information

StarSQL DRDA Trace Viewer
StarQuest Ventures, Inc.

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, people and events depicted herein are fictitious and no association with any real company, organization, product, person or event is intended or should be inferred.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of StarQuest Ventures, Inc.

StarQuest products contain certain trade secrets and confidential and proprietary information of StarQuest Ventures, Inc. StarQuest may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from StarQuest, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property. Additionally, any public network IDs or addresses referenced in this document are for demonstration/example purposes only. The inclusion of such IDs and addresses in this document does not grant you any express or implied right to test or otherwise use or access any such network ID or address.

StarQuest and StarSQL are trademarks of StarQuest Ventures, Inc.

Microsoft Windows are registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

StarQuest Ventures logo

©Copyright 1994-2019. StarQuest Ventures, Inc. All rights reserved.
121319 edition


Introduction to StarSQL DRDA Trace Viewer

If you encounter a technical problem with StarSQL, it may be helpful to create a binary trace file using the StarSQL DRDA Trace Recorder. You can record DRDA trace files from a StarSQL for Windows, UNIX, or Java client and use the StarSQL DRDA Trace Viewer to decode and display the trace information.

If you are a DRDA expert, you can use the StarSQL DRDA Trace Viewer to decode your own StarSQL trace files. If you are not a DRDA expert, consult your StarSQL support contact about whether a trace file would be helpful in diagnosing and resolving a specific problem you may encounter. You may find the following documents, from the OpenGroup DRDA specification, helpful when analyzing DRDA traces. Visit the Open Group Web site, http://www.opengroup.org for more information about the publications.

DRDA V3 Volume 1: Distributed Relational Database Architecture (DRDA)

DRDA V3 Volume 2: Formatted Data Object Content Architecture (DF:OCA)

DRDA V3 Volume 3: Distributed Data Management (DDM) Architecture

This Help file contains information about the installation and operation of the StarSQL DRDA Trace Viewer application. Before you can view a DRDA trace file you must record the DRDA trace information to a file, as described in Tracing DRDA Operations.


Installing the Trace Viewer

To Install the Trace Viewer, select the Custom option when you install StarSQL. The Trace Recorder application is installed as a feature of the Typical installation option so a trace file can be generated from any StarSQL workstation.

You must select the Custom option when you install StarSQL on a computer on which you want to use the Trace Viewer application to decode the trace files that are generated by the Trace Recorder application.


Tracing DRDA Operations

The StarSQL software includes a DRDA Trace Recorder program that records DRDA activity to a file, and a DRDA Trace Viewer program that displays the DRDA information. You must start the Trace Recorder and capture the DRDA activity to a file before you can view the trace file using the Trace Viewer. The following steps describe how to start the DRDA Trace Recorder so you can capture trace information.

  1. Select DRDA Trace Recorder from the StarSQL program group to start the Trace Recorder program.

  2. Specify a name for the trace file and choose where you want to save the file. The default file extension for trace files is .sqd.

  3. Click Save to save the file and start capturing the DRDA trace information.

A dialog appears with a message that tracing is enabled. The activity for all subsequent DRDA operations between the client computer and the host will be recorded to the specified file until you stop the trace or close the Trace Recorder program.

Right-click the DRDA Trace Recorder icon DRDA Trace Recorder icon in the Windows toolbar to stop the trace, start the trace again, or close the DRDA Trace Recorder program.


Trace Viewer Main Window

The main window of the Trace Viewer application consists of the following elements:

  • Menu bar with commands

  • Toolbar

  • Trace Tree Pane (left side)

  • Trace List Pane (right side)

  • Status bar (bottom of window)

The graphic below shows the Trace Viewer main window after opening a trace file.

TraceViewer main window


Menu Commands

The StarSQL DRDA Trace Viewer contains the following menus.

  • File menu

  • View menu

  • Help menu

The commands that are available from each menu are described below.

File Menu

Command | Description
Open | Opens a StarSQL DRDA trace file. These files have the default filename extension .SQD.
Print | Displays a dialog for selecting which printer to use, and whether you want to print the selected trace item and its subordinate items or the entire DRDA trace file.
Save As Text | Displays a dialog for specifying a filename and location for saving the trace information in an ASCII text file.
Exit | Closes the Trace Viewer application.

View Menu

Command

Description

Toolbar

Displays or hides the Trace Viewer toolbar.

Status Bar

Displays or hides the status bar at the bottom of the Trace Viewer window.

EBCDIC

DRDA trace data may be in ASCII or EBCDIC format depending on the host system involved. If you enable the EBCDIC option, Trace Viewer translates and displays the data in EBCDIC format.

ASCII

DRDA trace data may be in ASCII or EBCDIC format depending on the host system involved. If you enable the ASCII option, Trace Viewer translates and displays the data in ASCII format.

Byte Reversed Integers

Some host environments, including IBM Universal Database, record integer values in byte reversed order. If you enable the Byte Reversed Integers option, Trace Viewer translates integer data accordingly.

Expanded Time Stamps

and

Delta Times

For the chains in the trace tree you can view the date and time (Expanded Time Stamp) that the command flow was captured to the trace file, or you can view the time difference (Delta Times). The Delta Times view shows the timestamp of the first command flow, and the subsequent command flows show the number of milliseconds that have elapsed since the previous command flow.

SQLAM 5 and SQLAM 6

When a Distributed Data Management (DDM) client application accesses a DB2 database system, SQL statements are passed to a SQL Application Manager for processing. The initial EXCSAT command typically indicates the requested level for the SQLAM on the target system. Both the SQLAM 5 and SQLAM 6 commands appear dim when the SQLAM level is known.

If the SQLAM level cannot be detected in the SQD file, the trace display defaults to SQLAM 6. If the trace file does not display correctly, select the SQLAM 5 option of the View menu. The SQLAM option applies to the entire trace file, so be sure to record traces that use different levels of the SQLAM into different trace files. Changing the SQLAM option causes the file to be read again, which resets the position to the beginning of the trace file.

Help Menu

Command | Description
Contents | Displays a list of Help topics for Trace Viewer.
About Trace Viewer | Displays version and copyright information for the application.


Toolbar

The StarSQL DRDA Trace Viewer toolbar contains the following buttons. If the toolbar is not visible, select Toolbar from the View menu to display it.

Button | Description
File Open toolbar button | File Open Opens a StarSQL DRDA trace file. These files have the default filename extension .SQD. Note that, to view .SQD files created by the DRDA Trace Recorder, you must have write access to the directory in which the .SQD files are located.
Print File toolbar button | Print File Displays a dialog for selecting which printer to use, and whether you want to print the selected trace item and its subordinate items or the entire DRDA trace file.
View EBCDIC toolbar button | View EBCDIC DRDA trace data may be in ASCII or EBCDIC format depending on the host system involved. If you click this button, Trace Viewer translates and displays the data in EBCDIC format.
View ASCII toolbar button | View ASCII DRDA trace data may be in ASCII or EBCDIC format depending on the host system involved. If you click this button, Trace Viewer translates and displays the data is in ASCII format.
View Byte toolbar button | View Byte Reversed Integers Some hosts, including IBM Universal Database, record integer values in byte reversed order. If you click this button, Trace Viewer translates integer data in byte reversed order.


Trace Tree Pane

The left pane of the Trace Viewer main window contains a hierarchical trace tree that displays the following items:

  • Hexadecimal Connection IDs recorded in the trace. There may be one or more connection IDs in any trace file.

  • Response Time Statistics for each trace connection. When the view is set to Expanded Timestamps, the statistic reported is the Sum Reply, which shows the cumulative number of milliseconds between the timestamp of the first fragment of the request and the timestamp of the first message in the reply. When the view is set to Delta Times, the statistic shows the Mean Reply, which is the average number of milliseconds spent waiting for a reply (the sum of the response times divided by the number of request-reply pairs).

  • Recorded Request Chains for each connection, each marked with a timestamp or the elapsed number of milliseconds since the previous command flow, depending on whether the view is set to Expanded Timestamps or Delta Times.

  • Recorded Reply Chains for each connection, also marked with timestamps or elapsed number of milliseconds since the previous command flow.

  • Code Points in each request or reply chain.

For each connection, the chains are displayed in the order they were traced. However, since a trace file may contain information about several simultaneous connections, it is possible for a later chain to be listed before an earlier chain if they do not share a connection.

Each request or reply chain folder contains the DRDA code points that make up that chain. If a code point includes command instance variables, they are listed under the command. (For example, in the graphic below, PKGNAMCSN is a variable for the PRPSQLSTT command.)

For the SQLDARD object type, the trace tree displays a breakdown of the SQLCARD and SQLDAROW objects that make up the SQLDARD object.

The following graphic shows the Trace Viewer window with trace information for the selected request chain in the right pane. Note that the view is set to Delta Times. The Delta Times view shows the average number of milliseconds waiting for a reply (Mean Reply), the timestamp of the first command flow, and the subsequent command flows show the number of milliseconds that have elapsed since the previous command flow. (See Trace List Pane for an example of the view set to Expanded Timestamps.)

Request Chain trace information with Delta Times view


Trace List Pane

The right pane of the Trace Viewer window contains a trace list that provides detailed information about a selected chain, code point, or parameter in the trace tree. If you select a connection in the trace tree, the trace list pane displays no information.

Request or Reply Chain Information

If you select a request or reply chain folder in the trace tree pane, the trace list displays the following information:

  • the length of the data in that folder

  • the code point for the data

  • either an ASCII or EBCDIC translation of the data

  • the hexadecimal representation of the data

Command or Parameter Information

If you select a command or parameter object in the trace tree, the trace list typically includes the following information:

  • the length of the command or parameter

  • the hexadecimal representation of the selected CodePoint

  • either an ASCII or EBCDIC translation of the data

  • the hexadecimal representation of the data

If you select a SQLCARD or SQLDAROW object, the trace list displays information specific to those DRDA objects.

The following graphic shows the Trace Viewer window with trace information for the PRPSQLSTT (PREPARE SQL statement) command in the right pane. Note that the view is set to Expanded Timestamps, which shows the cumulative number of milliseconds (Sum Reply) between the timestamp of the first fragment of the request and the timestamp of the first message in the reply for the connection. For each of the chains in the trace tree the Expanded Timestamps view shows the date and time that the command flow was captured to the trace file.

trace information for a Prepare SQL statement


Contacting StarQuest

Please use the following methods to contact StarQuest Ventures if you need to obtain a license key, or have suggestions or need information about StarQuest products.

Support

If you do not want to use the online licensing feature of the License Configuration utility, you can obtain a license key for your product by sending an email to support@starquest.com with the following information:

  • TCP/IP address or Host ID of the computer on which the license will be installed

  • Number of connections purchased

  • Company Name

  • Contact Name

  • Phone Number

  • Email Address

StarQuest Support will send a reply email that provides the license key for your organization's use of the product. Since the license is unique to the computer on which it will be installed, you must contact StarQuest should you need to move the license from one computer to another.

Additional technical support may be available subject to the prices, terms, and conditions specified in your organization's maintenance contract with StarQuest Ventures, Inc.

Sales and Service

If you have ideas for product enhancements or need more information about how StarQuest products can provide solutions for connecting Windows and UNIX applications to IBM host resources, please contact us via any of the following methods.

Address | StarQuest Ventures, Inc. 548 Market St, #22938 San Francisco, CA 94104-5401 USA
Telephone | +1 415.669.9619 Option 1: Sales Option 2: Technical Support
Fax | +1 415.669.9639
World Wide Web | www.starquest.com
Support | support.starquest.com
Info Center | www.starquest.com/docs


Obtaining Licensing Information

The license key for using StarQuest products is based on which product you are licensing, the number of connections you need, and the particular computer on which the license will be installed. The easiest method for obtaining a license key is to use the online licensing feature of the License Configuration utility. (For details about online licensing, start the License Configuration utility and click the Help button.)

If you prefer to obtain a license key from StarQuest via an email request, you need to provide a static IP address or the Host ID of the computer on which you will install the product. If the computer is in a network that uses the Dynamic Host Configuration Protocol (DHCP), provide the Host ID instead of an IP address to StarQuest when you request the license. IP addresses that are assigned by the DHCP service are dynamic and can invalidate the license key when the computer is assigned a different unique IP address.

Displaying the IP Address

Each node in an IP network must be assigned a unique address, such as 172.19.36.72. The IP address can be static (permanently assigned to the computer) or dynamic (assigned by the DHCP service). If the computer is assigned an IP address by the DHCP service, the IP address can change and you should provide the Host ID instead of the IP address when you request the license from StarQuest.

  1. To display the IP Address of a computer, enter the command ipconfig at a Command Prompt.

A display similar to the following shows the IP address that is currently assigned to the computer.

Connection-specific DNS Suffix: company.com
IP Address....................: 172.19.36.72
Subnet Mask...................: 255.255.255.0
Default Gateway...............: 172.19.24.1

Refer to the documentation for your version of the operating system for more information about displaying a command prompt or using the ipconfig command.

Displaying the Host ID

The Host ID, or Disk ID, of a Windows computer identifies the physical disk in a particular computer. You can display the Host ID from the License Configuration utility by clicking Add from the Licenses tab. Or you can display the Host ID by opening a command window and entering the command label at the command prompt.

The label command displays information similar to the following, from which you provide the Volume Serial Number to StarQuest when you request the license key.

Volume in drive C: has no label
Volume Serial Number is C854-CE05
Volume label <ENTER for none>?