Readme for CLI Trace Parser 1.0.4d

Files included in CLITraceParser.zip
====================================

CLITraceParser     - a script to run CLITraceParser on Unix.
CLITraceParser.bat - an Intel batch file to run the tool.
CLITraceParser.jar - an archive containing all the classes
                     used in CLI Trace Parser.

Readme.txt         - this file.


Installation
============

Please refer to the script applicable to your OS level for instructions on how
to configure this tool.  The script contains an explanation on how to easily
set up the tool to run.

Note: this tool is written in Java and uses the JRE.  Please ensure that the
      JRE is installed and functioning before attempting to use this tool.


For tool help and options
=========================

CLITraceParser -help


Features
========

- Trace time analysis
    - application processing time
    - cli processing time
    - network processing time
    - time analysis for overall trace
    - time analysis per CLI function call

- Network flow analysis
    - bytes sent/recd
    - time to send/recv
    - number of total send/recv flows
    - network flow analysis on a per CLI function call basis
    
- Error report identifying
    - the line number of the error
    - the CLI API function call that caused the error
    - the return code
    - the error message if there is one
    
- Automatic extraction of multiple traces from a single file


Input
=====

A valid CLI trace is the required input.  Some traces may have 
anomalies if an error occurred while running the application.  
If this occurs, a Java Exception or CLI Trace Parser exception
may be thrown. If you encounter this problem, please report the
error according to the Support section described below.

Please include your CLI trace, the CLI Trace Parser version and
the error message you are seeing.

Output
======

The output is one or more report files (depending on how many 
times the driver is loaded/unloaded).  Please see the
Sample Output section at the bottom of this readme for an
example.


Release Notes for v1.0.4
========================

Multiple "Build Date" Statements in a Trace File

In some trace files, you will see multiple "Build Date"
statements. This statement is outputted when our CLI driver 
is loaded.

Each time the "Build Date" statement is encountered, the 
current trace statistics are stored and the remainder of 
the trace file is processed as a new CLI trace.

There is an important reason for this.  When the final
environment handle is freed, the application is no longer
using the CLI driver.  If it uses the CLI driver again, it
will be reloaded.

Since the CLI trace does not currently include a timestamp,
there is no way to determine the amount of time from when
the driver was unloaded and when it was reloaded.


Defects Fixed in V1.0.4d
========================
Added ADONET  functions

Defects Fixed in V1.0.4c
========================
Added SQL_jta functions
Added OLEDB   functions

Defects Fixed in V1.0.4b
========================
Fixed problem with SQLGetSqlca() function in DB2 for Linux/390

Defects Fixed in v1.0.4
=======================
Fixed Time Elapsed = 0 problem
Fixed comma decimal separator problems (see language restrictions below)
Added full V7.1 header output information

Defects Fixed in v1.0.3
=======================
Parsing algorithm problem with SQLGetInfo function.
NumberFormatException with 0 time elapsed value at beginning of trace.

Defects Fixed in v1.0.2
=======================

First call in trace was not being added to overall trace counter.
SQLGetDataInternal was not recognized as a CLI call.
SQL_NO_DATA_FOUND no longer registered in error log.


To generate a CLI Trace
=======================

Edit the db2cli.ini file used by the CLI/ODBC application, adding 
the following:

  [COMMON]
  Trace=1
  TracePathName=<path>
  TraceComm=1
  TraceFlush=1
  
  where <path> is an existing path. The resulting files will be located in
  <path> and will be called PID.TID, where PID is the process ID of the
  application, and TID is the relative thread id.


Tool Limitations
================

Language Types

The following Language Type limitation has been removed with v1.0.4.

The tool now supports both comma ',' and period '.' as the decimal place
separator. Any other separator will fail.

The tool will only work for CLI traces that have the "." sign as the decimal
point character. Thus for German traces, the trace will fail and you will need
to replace the "," characters in the time elapsed strings with a "." each time.
This can be done by looking for
+1,
+2,
+3,
.
.
+9,

and replacing each with

+1. etc.

Simply changing the language definition for the environment will not work
because Java specifies that the "." is used as the decimal point, irrespective
of the language environment.

Workaround

Replace +1, +2, +3, .... +9, with +1. +2. +3. ... +9.


Trace file size

It is recommended that if your trace exceeds 100 MB in size that you use 
the -c feature to conserve memory and store less information.  The only effect
of using this feature at this time is a less complete error report (only the
return code and the line number of each error are outputted - error messages
are not).


Support
=======

The CLI Trace Parser tool is not supported by IBM Technical Support.

Sample Trace Report
===================

       CLI Trace Report generated by CLITraceParser
==========================================================

CLI Trace file    : E:\utils\clitool\259.0
Lines read in file: 287
Trace build info  : Build Date: %E% - Product: QDB2/NT (5) - Driver Version: 06.01.0000

Overall Trace statistics
========================================================

             37 statements in trace.
          6.159 seconds total trace time.
          0.961 seconds spent for application processing.
          5.198 seconds spent for CLI processing.

Network Specific CLI processing time statistics
========================================================
             10 network flows sent to transmit 
           6815 bytes, requiring a total of
          0.070 seconds.

             10 network flows received, transmitting 
           6363 bytes, requiring a total of
          4.116 seconds.

End of overall trace statistics report

*********************************************************************************************************************

Function specific statistics
========================================================

                               Timing                     Network Send         Network Receive
Function Name       Total  Application CLI         Flows Bytes       Time   Flows Bytes       Time   
------------------------------------------------------------------------------------------------------
SQLSetConnectOption 3      0.090       0.030       0     0           0.000  0     0           0.000  
SQLExecDirect       2      0.070       3.715       2     608         0.020  2     1812        3.575  
SQLGetEnvAttr       1      0.000       0.020       0     0           0.000  0     0           0.000  
SQLFreeConnect      3      0.060       0.020       0     0           0.000  0     0           0.000  
SQLDisconnect       3      0.060       0.070       2     144         0.010  2     54          0.020  
SQLAllocEnv         1      0.030       0.020       0     0           0.000  0     0           0.000  
SQLError            6      0.230       0.181       0     0           0.000  0     0           0.000  
SQLConnect          3      0.030       0.981       6     6063        0.040  6     4497        0.521  
SQLFreeEnv          4      0.060       0.020       0     0           0.000  0     0           0.000  
SQLAllocHandle      10     0.331       0.141       0     0           0.000  0     0           0.000  

End of function specific statistics report

*********************************************************************************************************************

Report of errors that occurred in this CLI Trace
================================================
Error #1:
Function name : SQLAllocEnv
Line number   : 4
Return code   : SQL_ERROR

Error #2:
Function name : SQLDisconnect
Line number   : 171
Return code   : SQL_ERROR
Error message : [IBM][CLI Driver] CLI0116E  Invalid transaction state. SQLSTATE=25000
SQL Error code: -99999

Error #3:
Function name : SQLError
Line number   : 183
Return code   : SQL_NO_DATA_FOUND

Error #4:
Function name : SQLFreeConnect
Line number   : 189
Return code   : SQL_ERROR
Error message : [IBM][CLI Driver] CLI0125E  Function sequence error. SQLSTATE=HY010
SQL Error code: -99999

Error #5:
Function name : SQLError
Line number   : 201
Return code   : SQL_NO_DATA_FOUND

Error #6:
Function name : SQLFreeEnv
Line number   : 207
Return code   : SQL_ERROR
Error message : [IBM][CLI Driver] CLI0125E  Function sequence error. SQLSTATE=HY010
SQL Error code: -99999

Error #7:
Function name : SQLError
Line number   : 219
Return code   : SQL_NO_DATA_FOUND


End of error report.

==========================================================
                End of CLI Trace Report
