Using the JDBC Driver Manager Trace
This section describes how to use the JDBC Driver Manager
Trace tool.
About JDBC Driver ManagerTrace
You can use the JDBC Driver Manager Trace tool to trace a
connection to any database that you access in PowerBuilder through
the JDBC interface.
Unlike the Database Trace tool, the JDBC Driver Manager Trace
tool cannot
trace connections through one of
the native database interfaces.
What this tool does
JDBC Driver Manager Trace logs errors and informational messages originating
from the Driver object currently loaded (such as Sybase’s
jConnect JDBC driver) when PowerBuilder connects to a database via
the JDBC interface. It writes this information to a default log
file named JDBC.LOG or to a log file that you specify. The amount
of trace output varies depending on the JDBC driver being used.
What both tools do
The information from JDBC Driver Manager Trace, like Database
Trace, can help you:
- Understand what PowerBuilder is
doing internally
while connected to a database
via the JDBC interface - Identify and resolve problems with your JDBC connection
- Provide useful information to Technical Support
if you call them for help with your database connection
When to use this tool
You should use JDBC Driver Manager Trace instead
of
the Database Trace tool if you want more detailed information about
the JDBC driver.
Performance considerations Turning on JDBC Driver Manager Trace can slow your performance
while working in PowerBuilder. Therefore, you should use JDBC Driver
Manager Trace for debugging purposes only and keep it turned off
when you are not debugging.
Platform differences
The way you use JDBC Driver Manager Trace is the same on all PowerBuilder platforms
that support JDBC.
JDBC.LOG file On all platforms, PowerBuilder writes JDBC Driver Manager Trace
output to a default log file named JDBC.LOG or to a log file that
you specify. The default location of JDBC.LOG depends on the platform you
are using.
| Platform | Location |
|---|---|
| Windows | A temp directory |
| UNIX | Your $HOME directory |
Starting JDBC Driver Manager Trace
By default, JDBC Driver Manager Trace is turned off in PowerBuilder.
You can start it in the PowerBuilder development environment or in
a PowerBuilder application to trace your ODBC connection.
| To start JDBC Driver Manager Trace in | Do this |
|---|---|
| The PowerBuilder development environment | Edit your database profile |
| A PowerBuilder application | Edit your application script |
Starting JDBC Driver ManagerTrace in the development environment
To start JDBC Driver Manager Trace in the PowerBuilder development environment,
edit the database profile for the connection you want to trace,
as described in the following procedure.
To start JDBC Driver Manager Trace by editing
the database profile:
-
Open the Database Profile Setup – JDBC
dialog box for the JDM or JDS connection you want to trace. -
On the Options tab, select the Trace JDBC Calls
checkbox. -
(Optional) To specify a log file where you want PowerBuilder to
write the output of JDBC Driver Manager Trace, type the pathname
in the Trace File box.or
(Optional) Click Browse to display the pathname of an
existing log file in the Trace File box.By default, if the Trace JDBC Calls checkbox is selected and
no alternative trace file is specified, PowerBuilder sends JDBC Driver Manager
Trace output to the default JDBC.LOG file.
-
Click OK or Apply.
The Database Profiles dialog box displays with the name of
the edited profile highlighted.PowerBuilder saves your settings in the database profile entry
in the PowerBuilder initialization file.For example, here is the relevant portion of a database profile
entry for a database named Employee. The settings that start JDBC
Driver Manager Trace (corresponding to the TraceFile DBParm parameter)
are shown in bold.1[PROFILE Employee]1SQLCA.DBMS = "JDM - MS JavaVM"1...1SQLCA.DbParm = "Driver='com.sybase.jdbc.SybDriver',<br />URL='jdbc:sybase:Tds:199.93.178:151:5007/tsdata',<br /><i>TraceFile='c: empjdbc.log</i> '"1... -
Click Connect in the Database Profiles dialog
box to connect to the database.PowerBuilder connects to the database, starts tracing the JDBC connection,
and writes output to the log file you specified.
Starting JDBC Driver Manager Trace in a PowerBuilder application
To start JDBC Driver Manager Trace in a PowerBuilder application,
you must specify the TraceFile DBParm parameter in the appropriate
script. For example, you might include them in the script that opens
the application.
You can specify the TraceFile parameter in a PowerBuilder script
by:
- (Recommended
) Copying
the PowerScript TraceFile DBParm syntax from the Preview tab in
the Database Profile Setup dialog box into your script - Coding PowerScript to set a value for the DBParm
property of the Transaction object - Reading the DBParm values from an external text
file
For more about using Transaction objects to
communicate with a database in a PowerBuilder application, see Application
Techniques
.
About the TraceFile DBParm parameter
TraceFile controls the operation of JDBC Driver Manager Trace
for any JDBC-compatible driver you are using in PowerBuilder:
Copying TraceFile syntax from the Preview tab
The easiest way to start JDBC Driver Manager Trace in a PowerBuilder application
script is to copy the PowerScript TraceFile DBParm syntax from the
Preview tab in the Database Profile Setup – JDBC dialog box into
your script, modifying the default Transaction object name (SQLCA)
if necessary.
As you complete the Database Profile Setup dialog box in the
development environment, PowerBuilder generates the correct connection
syntax on the Preview tab. Therefore, copying the syntax directly
from the Preview tab into your script ensures that it is accurate.
To copy TraceFile syntax from the Preview tab
into your script:
-
On the Options tab in the Database Profile
Setup – JDBC dialog box for your connection, select the Trace JDBC
Calls checkbox and (optionally) specify a log file in the Trace
File box to start JDBC Driver Manager Trace.For instructions, see “Starting JDBC Driver Manager
Trace in the development environment”.
-
Click Apply to save your changes to the Options
tab without closing the dialog box. -
Click the Preview tab.
The correct PowerScript syntax for JDBC Driver Manager Trace
and other selected options displays in the Database Connection Syntax
box.In the following example, the PowerScript syntax that starts
JDBC Driver Manager Trace and sends output to the file C:TEMPJDBCTRCE.LOG
is shown in bold.1// Profile Employee1SQLCA.DBMS = "JDM - MS JavaVM"1SQLCA.DbParm = "Driver='com.sybase.jdbc.SybDriver',<br />URL='jdbc:sybase:Tds:199.93.178.151:5007/tsdata',<br /><i>TraceFile='c: empjdbctrce.log</i> '" -
Select the DBParm line and any other syntax you
want to copy to your script and click Copy.PowerBuilder copies the selected text to the clipboard.
-
Paste the selected text from the Preview tab into
your script, modifying the default Transaction object name (SQLCA)
if necessary.
Coding PowerScript to set a value for the DBParm
property
Another way to start JDBC Driver Manager Trace in a PowerBuilder application
script is to include the TraceFile parameter as a value for the DBParm
property of the Transaction object.
To start JDBC Driver Manager Trace by setting
the DBParm property:
-
In your application script, include the
TraceFile parameter to start the trace and specify a nondefault
trace file.For example, the portion of the following statement shown
in bold starts JDBC Driver Manager Trace in your application and
sends output to a file named MYTRACE.LOG. (This example assumes
you are using the default Transaction object SQLCA, but you can
also define your own Transaction object.)1SQLCA.DbParm = "Driver='com.sybase.jdbc.SybDriver',<br />URL='jdbc:sybase:Tds:199.93.178.151:5007/tsdata',<br /><i>TraceFile='c:MYTRACE.LOG</i> '"
Reading the DBParm value from an external text file
As an alternative to setting the DBParm property in your PowerBuilder application
script, you can use the PowerScript ProfileString function to read DBParm
values from a specified section of an external text file, such as
an application-specific initialization file.
This assumes that the DBParm value read from your initialization
file includes the TraceFile parameter to start JDBC Driver Manager
Trace, as shown in the preceding example.
To start JDBC Driver Manager Trace by reading
DBParm values from an external text file:
-
Use the following PowerScript syntax to
specify the ProfileString function with the DBParm property:1<b>SQLCA.dbParm = </b><b><i></i><i></i>ProfileString</b>(<i>file</i>, <i>section</i>, <i>variable</i>,<br /><i> default_value</i>)For example, the following statement in a PowerBuilder script
reads the DBParm values from the [Database] section
of the APP.INI file:1SQLCA.dbParm =1ProfileString("APP.INI","Database","DBParm","")
Stopping JDBC Driver Manager Trace
Once you start tracing an JDBC connection with JDBC Driver
Manager Trace, PowerBuilder continues sending trace output to the
log file until you stop tracing.
Stopping JDBC Driver Manager Trace in the development
environment
To stop JDBC Driver Manager Trace by editing a
database profile:
-
Open the Database Profile Setup – JDBC
dialog box for the connection you are tracing.For instructions, see “Starting JDBC Driver Manager
Trace in the development environment”. -
On the Options tab, clear the Trace JDBC Calls
checkbox.If you supplied the pathname of a log file in the Trace File
box, you can leave it specified in case you want to restart tracing
later. -
Click OK in the Database Profile Setup – JDBC
dialog box.The Database Profiles dialog box displays, with the name of
the edited profile highlighted. -
Click Connect in the Database Profiles dialog
box.PowerBuilder connects to the database and stops tracing the
connection.
Stopping JDBC Driver Manager Trace in a PowerBuilder application
To stop JDBC Driver Manager Trace in a PowerBuilder application
script, you must delete the TraceFile parameter. You can do this
by:
- Editing the value of
the DBParm property of the Transaction object - Reading the DBParm values from an external text
file
Editing the DBParm property
One way to change the TraceFile parameter in a PowerBuilder script
is to edit the DBParm property of the Transaction object.
To stop JDBC Driver Manager Trace by editing the
DBParm property:
-
In your application script, edit the DBParm
property of the Transaction object to delete the TraceFile parameter.For example, the following statement starts JDBC Driver Manager
Trace in your application and sends the output to a file named MYTRACE.LOG. (This
example assumes you are using the default Transaction object SQLCA,
but you can also define your own Transaction object.)1SQLCA.DbParm = "Driver='com.sybase.jdbc.SybDriver',<br />URL='jdbc:sybase:Tds:199.93.178.151:5007/tsdata',<br /><i>TraceFile='c:MYTRACE.LOG</i> '"Here is how the same statement should look after you edit
it to stop JDBC Driver Manager Trace.1SQLCA.DbParm = "Driver='com.sybase.jdbc.SybDriver',<br />URL='jdbc:sybase:Tds:199.93.178.151:5007/tsdata'"
Reading DBParm values
As an alternative to editing the DBParm property in your PowerBuilder application
script, you can use the PowerScript ProfileString function to read DBParm
values from a specified section of an external text file, such as
an application-specific initialization file.
This assumes that the DBParm is no longer read from your initialization
file, as shown in the preceding example.
Viewing the JDBC Driver Manager Trace log
You can display the contents of the JDBC Driver Manager Trace
log file anytime during a PowerBuilder session.
Location of JDBC.LOG For information about where to find the default
JDBC.LOG file on different platforms, see “About JDBC Driver Manager
Trace”.
To view the contents of the log file:
-
Open JDBC.LOG or the log file you specified
in one of the following ways:- Use the File Editor
in PowerBuilder. (For instructions, see the PowerBuilder
User’s Guide
.) - Use any text editor outside PowerBuilder.
- Use the File Editor
Leaving the log file open If you leave the log file open as you work in PowerBuilder,
JDBC Driver Manager Trace does not update it
.