About Transaction objects
In a PowerBuilder database connection, a Transaction
object is a special nonvisual object that functions
as the communications area between PowerScript and the database.
The Transaction object specifies the parameters that PowerBuilder
uses to connect to a database. You must establish the Transaction
object before you can access the database in your application:
Communicating with the database
In order to display and manipulate data in a PowerBuilder
application, the application must communicate with the database
in which the data resides:
To communicate with the database in your PowerBuilder
application:
-
Assign the appropriate values to the Transaction
object. - Connect to the database.
-
Assign the Transaction object to the DataWindow
control. - Perform the database processing.
- Disconnect from the database.
For information about setting the Transaction
object for a DataWindow control and using the DataWindow to retrieve
and update data, see the DataWindow Programmer’s
Guide
.
Default Transaction object
When you start executing an application, PowerBuilder creates
a global default Transaction object named SQLCA (SQL Communications
Area). You can use this default Transaction object in your application
or define additional Transaction objects if your application has
multiple database connections.
Transaction object properties
Each Transaction object has 15 properties, of which:
- Ten are used to connect
to the database. - Five are used to receive status information from
the database about the success or failure of each database operation
(these error-checking properties all begin with SQL)
.
Description of Transactionobject properties
The following table describes each Transaction object property.
For each of the ten connection properties, it also lists the equivalent
field in the Database Profile Setup dialog box that you complete
to create a database profile in the PowerBuilder development environment.
Transaction object properties for your PowerBuilder
database interface For the Transaction object properties that
apply to your PowerBuilder database interface, see “Transaction object
properties and supported PowerBuilder database interfaces”.
For information about the values you should
supply for each connection property, see the section for your PowerBuilder
database interface in Connecting to Your Database
.
| Property | Data type | Description | In a database profile |
|---|---|---|---|
| DBMS | String | The DBMS identifier for your connectionFor a complete list of identifiers, see the appendix on supported database interfaces in Connecting to Your Database |
DBMS |
| Database | String | The name of the database to which you are connecting |
Database Name |
| UserID | String | The name or ID of the user who connects to the database |
User ID |
| DBPass | String | The password used to connect to the database | Password |
| Lock | String | For those DBMSs that support the use of lock values and isolation levels, the isolation level to use when you connect to the databaseFor information about the lock values you can set for your DBMS, see the description of the Lock DBParm parameter in Connecting to Your Database |
Isolation Level |
| LogID | String | The name or ID of the user who logs in to the database server |
Login ID |
| LogPass | String | The password used to log in to the database server |
Login Password |
| ServerName | String | The name of the server on which the database resides |
Server Name |
| AutoCommit | Boolean | For those DBMSs that support it, specifies whether PowerBuilder issues SQL statements outside or inside the scope of a transaction. Values you can set are:
For more information, see the AutoCommit description |
AutoCommit Mode |
| DBParm | String | Contains DBMS-specific connection parameters that support particular DBMS featuresFor a description of each DBParm parameter that PowerBuilder supports, see the chapter on setting additional connection parameters in Connecting to Your Database |
DBPARM |
| SQLReturnData | String | Contains DBMS-specific information. For example, after you connect to an INFORMIX database and execute an embedded SQL INSERT statement, SQLReturnData contains the serial number of the inserted row |
— |
| SQLCode | Long | The success or failure code of the most recent SQL operationFor details, see “Error handling after a SQL statement” |
— |
| SQLNRows | Long | The number of rows affected by the most recent SQL operation. The database vendor supplies this number, so the meaning may be different for each DBMS |
— |
| SQLDBCode | Long | The database vendor’s error code.For details, see “Error handling after a SQL statement” |
— |
| SQLErrText | String | The text of the database vendor’s error message corresponding to the error codeFor details, see “Error handling after a SQL statement” |
— |
Transaction objectproperties and supported PowerBuilder database interfaces
The Transaction object properties required to connect to the
database are different for each PowerBuilder database interface.
Except for SQLReturnData, the properties that return status information
about the success or failure of a SQL statement apply to all PowerBuilder
database interfaces.
The following table lists each supported PowerBuilder database
interface and the Transaction object properties you can use with
that interface:
| Database interface | Transaction object properties |
|---|---|
| INFORMIX |
|
| JDBC |
|
| Microsoft SQL Server |
|
| ODBC |
|
| OLE DB |
|
| ORACLE |
|
| Sybase DirectConnect |
|
| Sybase Adaptive Server Enterprise |
|
# UserID is optional for ODBC (be careful
specifying the UserID property; it overrides the connection’s
UserName property returned by the ODBC SQLGetInfo call).
+ PowerBuilder uses the LogID and LogPass
properties only if your ODBC driver does not
support
the SQL driver CONNECT call.