Using the Database Trace tool

This section describes how to use the Database Trace tool.

About the Database Trace tool

The Database Trace tool records the internal commands that PowerBuilder executes while accessing a database. You can trace a database connection in the development environment or in a PowerBuilder application that connects to a database.

PowerBuilder writes the output of Database Trace to a log file named DBTRACE.LOG (by default) or to a nondefault log file that you specify. When you enable database tracing for the first time, PowerBuilder creates the log file on your computer. Tracing continues until you disconnect from the database.

Using the Database Trace tool with one connection

You can use the Database Trace tool for only one DBMS at a time and for one database connection at a time.

For example, if your application connects to both an ODBC data source and an Adaptive Server Enterprise database, you can trace either the ODBC connection or the Adaptive Server Enterprise connection, but not both connections at the same time.

How you can use the Database Trace tool

You can use information from the Database Trace tool to understand what PowerBuilder is doing internally when you work with your database. Examining the information in the log file can help you:

  • Understand how PowerBuilder interacts with your database

  • Identify and resolve problems with your database connection

  • Provide useful information to Technical Support if you call them for help with your database connection

If you are familiar with PowerBuilder and your DBMS, you can use the information in the log to help troubleshoot connection problems on your own. If you are less experienced or need help, run the Database Trace tool before you call Technical Support. You can then report or send the results of the trace to the Technical Support representative who takes your call.

Contents of the Database Trace log

Default contents of the trace file

By default, the Database Trace tool records the following information in the log file when you trace a database connection:

  • Parameters used to connect to the database

  • Time to perform each database operation (in microseconds)

  • The internal commands executed to retrieve and display table and column information from your database. Examples include:

    • Preparing and executing SQL statements such as SELECT, INSERT, UPDATE, and DELETE

    • Getting column descriptions

    • Fetching table rows

    • Binding user-supplied values to columns (if your database supports bind variables)

    • Committing and rolling back database changes

    • Disconnecting from the database

    • Shutting down the database interface

You can opt to include the names of DBI commands and the time elapsed from the last database connection to the completion of processing for each log entry. You can exclude binding and timing information as well as the data from all fetch requests.

Database Trace dialog box selections

The Database Trace dialog box lets you select the following items for inclusion in or exclusion from a database trace file:

  • Bind variables

    Metadata about the result set columns obtained from the database

  • Fetch buffers

    Data values returned from each fetch request

  • DBI names

    Database interface commands that are processed

  • Time to implement request

    Time required to process DBI commands; the interval is measured in thousandths of milliseconds (microseconds)

  • Cumulative time

    Cumulative total of timings since the database connection began; the timing measurement is in thousandths of milliseconds

Registry settings for DBTrace

The selections made in the Database Trace dialog box are saved to the registry of the machine from which the database connections are made. Windows registry settings for the database trace utility configuration are stored under the HKEY_CURRENT_USER\Software\Sybase\PowerBuilder\19.0\DBTrace key. Registry strings under this key are: ShowBindings, FetchBuffers, ShowDBINames, Timing, SumTiming, LogFileName, and ShowDialog. Except for the LogFileName string to which you can assign a full file name for the trace output file, all strings can be set to either 0 or 1.

The ShowDialog registry string can be set to prevent display of the Database Trace dialog box when a database connection is made with tracing enabled. This is the only one of the trace registry strings that you cannot change from the Database Trace dialog box. You must set ShowDialog to 0 in the registry to keep the configuration dialog box from displaying.

INI file settings for DBTrace

If you do not have access to the registry, you can use PB.INI to store trace file settings. Add a [DbTrace] section to the INI file with at least one of the following values set, then restart PowerBuilder:

[DbTrace]
ShowDBINames=0
FetchBuffers=1
ShowBindings=1
SumTiming=1
Timing=1
ShowDialog=1 
LogFileName=dbtrace.log

The keywords are the same as in the registry and have the same meaning. When you connect to the database again, the initial settings are taken from the INI file, and when you modify them, the changes are written to the INI file.

If the file name for LogFileName does not include an absolute path, the log file is written to the following path, where <username> is your login ID: Users\<username>\AppData\Local\Appeon\PowerBuilder 19.0. If there are no DbTrace settings in the INI file, the registry settings are used.

Error messages

If the database trace utility cannot open the trace output file with write access, an error message lets you know that the specified trace file could not be created or opened. If the trace utility driver cannot be loaded successfully, a message box informs you that the selected Trace DBMS is not supported in your current installation.

Format of the Database Trace log

The specific content of the Database Trace log file depends on the database you are accessing and the operations you are performing. However, the log uses the following basic format to display output:

COMMAND: (time)
   {additional_information}

Parameter

Description

COMMAND

The internal command that PowerBuilder executes to perform the database operation.

time

The number of microseconds it takes PowerBuilder to perform the database operation. The precision used depends on your operating system's timing mechanism.

additional_information

(Optional) Additional information about the command. The information provided depends on the database operation.


Example

The following portion of the log file shows the commands PowerBuilder executes to fetch two rows from a SQL Anywhere database table:

FETCH NEXT: (0.479 MS)
 COLUMN=400
    COLUMN=Marketing
    COLUMN=Evans
FETCH NEXT: (0.001 MS)
 COLUMN=500
    COLUMN=Shipping 
    COLUMN=Martinez

If you opt to include DBI Names and Sum Time information in the trace log file, the log for the same two rows might look like this:

FETCH NEXT:(DBI_FETCHNEXT) (1.459 MS / 3858.556 MS)
 COLUMN=400
    COLUMN=Marketing
    COLUMN=Evans
FETCH NEXT:(DBI_FETCHNEXT) (0.001 MS / 3858.557 MS)
 COLUMN=500
    COLUMN=Shipping 
    COLUMN=Martinez

For a more complete example of Database Trace output, see Sample Database Trace output.

Starting the Database Trace tool

By default, the Database Trace tool is turned off in PowerBuilder. You can start it in the PowerBuilder development environment or in a PowerBuilder application to trace your database connection.

Turning tracing on and off

To turn tracing on or off you must reconnect. Setting and resetting are not sufficient.

Starting Database Trace in the development environment

To start the Database Trace tool in the PowerBuilder development environment, edit the database profile for the connection you want to trace, as described in the following procedure.

To start the Database Trace tool by editing a database profile:

  1. Open the Database Profile Setup dialog box for the connection you want to trace.

  2. On the Connection tab, select the Generate Trace check box and click OK or Apply. (The Generate Trace check box is located on the System tab in the OLE DB Database Profile Setup dialog box.)

    The Database Profiles dialog box displays with the name of the edited profile highlighted.

    For example, here is the relevant portion of a database profile entry for Adaptive Server 12.5 Test. The setting that starts Database Trace is DBMS:

    [Default]     [value not set]
    AutoCommit    "FALSE"
    Database      "qadata"
    DatabasePassword  "00"
    DBMS          "TRACE SYC Adaptive Server Enterprise"
    DbParm        "Release='12.5'"
    Lock          ""
    LogId         "qalogin"
    LogPassword   "00171717171717"
    Prompt        "FALSE"
    ServerName    "Host125"
    UserID        ""
  3. Click Connect in the Database Profiles dialog box to connect to the database.

    The Database Trace dialog box displays, indicating that database tracing is enabled. You can enter the file location where PowerBuilder writes the trace output. By default, PowerBuilder writes Database Trace output to a log file named DBTRACE.LOG. You can change the log file name and location in the Database Trace dialog box.

    The Database Trace dialog box also lets you select the level of tracing information that you want in the database trace file.

  4. Select the types of items you want to include in the trace file and click OK.

    PowerBuilder connects to the database and starts tracing the connection.

Starting Database Trace in a PowerBuilder application

In a PowerBuilder application that connects to a database, you must specify the required connection parameters in the appropriate script. For example, you might specify them in the script that opens the application.

To trace a database connection in a PowerBuilder script, you specify the name of the DBMS preceded by the word trace and a single space. You can do this by:

  • Copying the PowerScript DBMS trace syntax from the Preview tab in the Database Profile Setup dialog box into your script

  • Coding PowerScript to set a value for the DBMS property of the Transaction object

  • Reading the DBMS value from an external text file

For more about using Transaction objects to communicate with a database in a PowerBuilder application, see Using Transaction Objects in Application Techniques.

Copying DBMS trace syntax from the Preview tab

One way to start Database Trace in a PowerBuilder application script is to copy the PowerScript DBMS trace syntax from the Preview tab in the Database Profile Setup 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 for each selected option, including Generate Trace. Therefore, copying the syntax directly from the Preview tab ensures that it is accurate in your script.

To copy DBMS trace syntax from the Preview tab into your script:

  1. On the Connection tab (or System tab in the case of OLE DB) in the Database Profile Setup dialog box for your connection, select the Generate Trace check box to turn on Database Trace.

    For instructions, see Starting Database Trace in the development environment.

  2. Click Apply to save your changes to the Connection tab without closing the Database Profile Setup dialog box.

  3. Click the Preview tab.

    The correct PowerScript connection syntax for the Generate Trace and other selected options displays in the Database Connection Syntax box.

  4. Select the SQLCA.DBMS line and any other syntax you want to copy to your script and click Copy.

    PowerBuilder copies the selected text to the clipboard.

  5. Click OK to close the Database Profile Setup dialog box.

  6. 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 DBMS property

Another way to start the Database Trace tool in a PowerBuilder script is to specify it as part of the DBMS property of the Transaction object. The Transaction object is a special nonvisual object that PowerBuilder uses to communicate with the database. The default Transaction object is named SQLCA, which stands for SQL Communications Area.

SQLCA has 15 properties, 10 of which are used to connect to your database. One of the 10 connection properties is DBMS. The DBMS property contains the name of the database to which you want to connect.

To start the Database Trace tool by specifying the DBMS property:

  • Use the following PowerScript syntax to specify the DBMS property. (This syntax assumes you are using the default Transaction object SQLCA, but you can also define your own Transaction object.)

    SQLCA.DBMS = "trace DBMS_name"

    For example, the following statements in a PowerBuilder script set the SQLCA properties required to connect to an Adaptive Server database named Test. The keyword trace in the DBMS property indicates that you want to trace the database connection.

    SQLCA.DBMS         = "trace SYC"
    SQLCA.database     = "Test"
    SQLCA.logId        = "Frans"
    SQLCA.LogPass      = "xxyyzz"
    SQLCA.ServerName   = "Tomlin"

Reading the DBMS value from an external text file or the registry

As an alternative to setting the DBMS property in your PowerBuilder application script, you can use the PowerScript ProfileString function to read the DBMS value from a specified section of an external text file, such as an application-specific initialization file, or from an application settings key in the registry.

The following procedure assumes that the DBMS value read from the database section in your initialization file uses the following syntax to enable database tracing:

DBMS = trace DBMS_name

To start the Database Trace tool by reading the DBMS value from an external text file:

  • Use the following PowerScript syntax to specify the ProfileString function with the DBMS property:

    SQLCA.DBMS = ProfileString (file, section, variable, default_value)

    For example, the following statement in a PowerBuilder script reads the DBMS value from the [Database] section of the APP.INI file:

    SQLCA.DBMS=ProfileString("APP.INI", "Database", "DBMS","")

    For how to get a value from a registry file instead, see Getting values from the registry.

Starting a trace in PowerScript with the PBTrace parameter

Instead of tracing all database commands from the start of a database connection, you can start and end a trace programmatically for specific database queries. To start a trace, you can assign the string value pair "PBTrace=1" to the transaction object DBParm property; to end a trace, you assign the string value pair "PBTrace=0".

For example, if you wanted data to be logged to the trace output for a single retrieve command, you could disable tracing from the start of the connection and then surround the retrieve call with DBParm property assignments as follows:

SQLCA.DBMS = "TRACE ODBC"
SQLCA.DBParm="PBTrace=0"
Connect using SQLCA;
...
SQLCA.DBParm="PBTrace=1"
dw_1.Retrieve ( )
SQLCA.DBParm="PBTrace=0"

When you first connect to a database after setting the DBMS parameter to "Trace DBMSName", a configuration dialog box displays. The configuration parameters that you set in this dialog box are saved to the registry. Configuration parameters are retrieved from the registry when you begin tracing by assigning the DBParm parameter to "PBTrace=1".

You can start and stop the SQL statement trace utility in the same way if you set the DBMS value to "TRS DBMSName" instead of "Trace DBMSName". For information about the SQL statement trace utility, see Using the SQL statement trace utility.

Stopping the Database Trace tool

Once you start tracing a particular database connection, PowerBuilder continues sending trace output to the log until you do one of the following:

  • Reconnect to the same database with tracing stopped

  • Connect to another database for which you have not enabled tracing

Stopping Database Trace in the development environment

To stop the Database Trace tool by editing a database profile:

  1. In the Database Profile Setup dialog box for the database you are tracing, clear the Generate Trace check box on the Connection tab.

  2. Click OK in the Database Profile Setup dialog box.

    The Database Profiles dialog box displays with the name of the edited profile highlighted.

  3. Right-click on the connected database and select Re-connect from the drop-down menu in the Database Profiles dialog box.

    PowerBuilder connects to the database and stops tracing the connection.

Stopping Database Trace in a PowerBuilder application

To stop Database Trace in a PowerBuilder application script, you must delete the word trace from the DBMS property. You can do this by:

  • Editing the value of the DBMS property of the Transaction object

  • Reading the DBMS value from an external text file

You must reconnect for the change to take effect.

Editing the DBMS property

To stop Database Trace by editing the DBMS value in a PowerBuilder script:

  • Delete the word trace from the DBMS connection property in your application script.

    For example, here is the DBMS connection property in a PowerBuilder script that enables the Database Trace. (This syntax assumes you are using the default Transaction object SQLCA, but you can also define your own Transaction object.)

    SQLCA.DBMS  = "trace SYC"

    Here is how the same DBMS connection property should look after you edit it to stop tracing:

    SQLCA.DBMS  = "SYC"

Reading the DBMS value from an external text file

As an alternative to editing the DBMS property in your PowerBuilder application script, you can use the PowerScript ProfileString function to read the DBMS value from a specified section of an external text file, such as an application-specific initialization file.

This assumes that the DBMS value read from your initialization file does not include the word trace, as shown in the preceding example in Editing the DBMS property.

Using the Database Trace log

PowerBuilder writes the output of the Database Trace tool to a file named DBTRACE.LOG (by default) or to a nondefault log file that you specify. To use the trace log, you can do the following anytime:

  • View the Database Trace log with any text editor

  • Annotate the Database Trace log with your own comments

  • Delete the Database Trace log or clear its contents when it becomes too large

Viewing the Database Trace log

You can display the contents of the log file anytime during a PowerBuilder session.

To view the contents of the log file:

  1. Open the log file in one of the following ways:

  2. Use the File Editor in PowerBuilder. (For instructions, see the the section called “Using the file editor” in Users Guide.)

  3. Use any text editor outside PowerBuilder.

Leaving the log file open

If you leave the log file open as you work in PowerBuilder, the Database Trace tool does not update the log.

Annotating the Database Trace log

When you use the Database Trace log as a troubleshooting tool, it might be helpful to add your own comments or notes to the file. For example, you can specify the date and time of a particular connection, the versions of database server and client software you used, or any other useful information.

To annotate the log file:

  1. Open the DBTRACE.LOG file in one of the following ways:

  2. Edit the log file with your comments.

  3. Save your changes to the log file.

Deleting or clearing the Database Trace log

Each time you connect to a database with tracing enabled, PowerBuilder appends the trace output of your connection to the existing log. As a result, the log file can become very large over time, especially if you frequently enable tracing when connected to a database.

To keep the size of the log file manageable:

  1. Do either of the following periodically:

  2. Open the log file, clear its contents, and save the empty file.

    Provided that you use the default DBTRACE.LOG or the same nondefault file the next time you connect to a database with tracing enabled, PowerBuilder will write to this empty file.

  3. Delete the log file.

    PowerBuilder will automatically create a new log file the next time you connect to a database with tracing enabled.

Sample Database Trace output

This section gives an example of Database Trace output that you might see in the log file and briefly explains each portion of the output.

The example traces a connection with Sum Timing enabled. The output was generated while running a PowerBuilder application that displays information about authors in a publications database. The SELECT statement shown retrieves information from the Author table.

The precision (for example, microseconds) used when Database Trace records internal commands depends on your operating system's timing mechanism. Therefore, the timing precision in your Database Trace log might vary from this example.

Connect to database

CONNECT TO TRACE SYC Adaptive Server Enterprise:
DATABASE=pubs2
LOGID=bob
SERVER=HOST12
DPPARM=Release='12.5.2',StaticBind=0

Prepare SELECT statement

PREPARE: 
SELECT  authors.au_id, authors.au_lname, authors.state FROM authors 
WHERE ( authors.state not in ( 'CA' ) ) 
ORDER BY authors.au_lname ASC (3.386 MS / 20.349 MS)

Get column descriptions

DESCRIBE: (0.021 MS / 20.370 MS)
name=au_id,len=12,type=CHAR,pbt=1,dbt=1,ct=0,prec=0,
  scale=0
name=au_lname,len=41,type=CHAR,pbt=1,dbt=1,ct=0,
  prec=0,scale=0
name=state,len=3,type=CHAR,pbt=1,dbt=1,ct=0,prec=0,
  scale=0

Bind memory buffers to columns

BIND SELECT OUTPUT BUFFER (DataWindow): 
  (0.007 MS / 20.377 MS)
name=au_id,len=12,type=CHAR,pbt=1,dbt=1,ct=0,prec=0,
  scale=0
name=au_lname,len=41,type=CHAR,pbt=1,dbt=1,ct=0,
  prec=0,scale=0
name=state,len=3,type=CHAR,pbt=1,dbt=1,ct=0,prec=0,
  scale=0

Execute SELECT statement

EXECUTE: (0.001 MS / 20.378 MS)

Fetch rows from result set

FETCH NEXT: (0.028 MS / 20.406 MS)
 au_id=648-92-1872    au_lname=Blotchet-Hall state=OR
FETCH NEXT: (0.012 MS / 20.418 MS)
 au_id=722-51-5454    au_lname=DeFrance    state=IN
...
FETCH NEXT: (0.010 MS / 20.478 MS)
au_id=341-22-1782 au_lname=Smith    state=KS
FETCH NEXT: (0.025 MS / 20.503 MS)
*** DBI_FETCHEND *** (rc 100)

Update and commit database changes

PREPARE:
UPDATE authors SET state = 'NM'
WHERE au_id = '648-92-1872' AND au_lname = 'Blotchet-Halls' AND state = 'OR' (3.284 MS / 23.787 MS)
EXECUTE: (0.001 MS / 23.788 MS)
GET AFFECTED ROWS: (0.001 MS / 23.789 MS)
^ 1 Rows Affected
COMMIT: (1.259 MS / 25.048 MS)

Disconnect from database

DISCONNECT: (0.764 MS / 25.812 MS)

Shut down database interface

SHUTDOWN DATABASE INTERFACE: (0.001 MS / 25.813 MS)