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 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:

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”.
Click Apply to save your changes to the Connection tab without closing the Database Profile Setup dialog box.
Click the Preview tab.

The correct PowerScript connection syntax for the Generate Trace and other selected options displays in the Database Connection Syntax box.
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.
Click OK to close the Database Profile Setup dialog box.
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”.