SetTransObject method (DataWindows)
Description
Causes a DataWindow control or DataStore to use a programmer-specified transaction
object. The transaction object provides the information necessary
for communicating with the database.
Controls
|
DataWindow type |
Method applies to |
|---|---|
|
PowerBuilder |
DataWindow control, DataWindowChild object, DataStore |
|
Web ActiveX |
DataWindow control, DataWindowChild object |
Syntax
[PowerBuilder]
|
1 |
integer <span>dwcontrol</span>.<span>SetTransObject</span> ( transaction <span>transaction </span>) |
[Web ActiveX]
|
1 |
number <span>dwcontrol</span>.<span>SetTransObject</span> ( transaction <span>transaction</span> ) |
|
Argument |
Description |
|---|---|
|
dwcontrol |
A reference to a DataWindow control, |
|
transaction |
The name of the transaction object you |
Return Values
Returns 1 if it succeeds and –1 if an error occurs.
If any argument’s value is null, in PowerBuilder and JavaScript
the method returns null.
Usage
Transaction objects in PowerBuilder
A programmer-specified transaction object gives you more control
over the database transactions and provides efficient application
performance. You control the database connection by using SQL statements such as CONNECT, COMMIT,
and ROLLBACK.
Since the DataWindow control does not have to connect to the
database for every RETRIEVE and UPDATE statement,
these statements run faster. You are responsible for committing
and rolling back transactions after you call the Update method,
using code like the following:
|
1 |
IF dw_Employee.Update()>0 THEN |
|
1 |
COMMIT USING emp_transobject; |
|
1 |
ELSE |
|
1 |
ROLLBACK USING emp_transobject; |
|
1 |
END IF |
You must set the parameters required to connect to your DBMS
in the transaction object before you can use the transaction object
to connect to the database. PowerBuilder provides a global transaction
object called SQLCA, which
is all you need if you are connecting to one database. You can also
create additional transaction objects, as shown in the examples.
To use SetTransObject, write code that
does the following tasks:
-
Set
up the transaction object by assigning values to its fields (usually in
the application’s Open event). -
Connect to the database using the SQL CONNECT statement
and the transaction object (in the Open event for the application
or window). -
Call SetTransObject to associate
the transaction object with the DataWindow control or DataStore
(usually in the window’s Open event). -
Check the return value from the Update method
and follow it with a SQL COMMIT or ROLLBACK statement,
as appropriate.
If you change the DataWindow object associated with the DataWindow control
(or DataStore) or if you disconnect and reconnect to a database,
the connection between the DataWindow control (or DataStore) and
the transaction object is severed. You must call SetTransObject again
to reestablish the connect.
SetTransObject versus SetTrans
In most cases, use the SetTransObject method
to specify the transaction object because it is efficient and gives
you control over when transactions are committed.
The SetTrans method provides another way
of managing the database connection. SetTrans,
which sets transaction information in the internal transaction object
for the DataWindow control or DataStore, manages the connection
automatically. You do not explicitly connect to the database; the
DataWindow connects and disconnects for each database transaction, which
is less efficient but necessary in some situations.
For more information, see SetTrans.
Examples
This statement causes dw_employee to use
the default transaction object SQLCA:
|
1 |
dw_employee.<span>SetTransObject</span>(SQLCA) |
This statement causes dw_employee to use
the programmer-defined transaction object emp_TransObj.
In this example, emp_TransObj is an instance variable,
but your script must allocate memory for it with the CREATE statement
before you use it:
|
1 |
emp_TransObj = CREATE transaction |
|
1 |
... // Assign values to the transaction object |
|
1 |
dw_employee.<span>SetTransObject</span>(emp_TransObj) |
This example has two parts. The first script, for
the application’s Open event, reads database parameters
from an initialization file called MYAPP.INI and
stores the values in the default transaction object (SQLCA). The Database section
of MYAPP.INI has the same keywords as PowerBuilder’s
own PB.INI file. The parameters shown are for
a SQL Server or Oracle database.
The second script, for the window’s Open event, establishes
a connection and retrieves data from the database.
The application’s Open event script populates SQLCA:
|
1 |
SQLCA.DBMS = ProfileString("myapp.ini", & |
|
1 |
"database", "DBMS", " ") |
|
1 |
SQLCA.Database = ProfileString("myapp.ini", & |
|
1 |
"database", "Database", " ") |
|
1 |
SQLCA.LogId = ProfileString("myapp.ini", & |
|
1 |
"database", "LogId", " ") |
|
1 |
SQLCA.LogPass = ProfileString("myapp.ini", & |
|
1 |
"database", "LogPassword", " ") |
|
1 |
SQLCA.ServerName = ProfileString("myapp.ini", & |
|
1 |
"database", "ServerName", " ") |
|
1 |
SQLCA.UserId = ProfileString("myapp.ini", & |
|
1 |
"database", "UserId", " ") |
|
1 |
SQLCA.DBPass = ProfileString("myapp.ini", & |
|
1 |
"database", "DatabasePassword", " ") |
|
1 |
SQLCA.lock = ProfileString("myapp.ini", & |
|
1 |
"database", "lock", " ") |
The Open event script for the window that contains
the DataWindow control connects to the database, assigns the transaction
object to the DataWindow, and retrieves data:
|
1 |
long RowsRetrieved |
|
1 |
string LastName |
|
1 |
|
1 |
// Connect to the database. |
|
1 |
CONNECT USING SQLCA; |
|
1 |
|
1 |
// Test whether the connect succeeded. |
|
1 |
IF SQLCA.SQLCode <> 0 THEN |
|
1 |
MessageBox("Connect Failed", & |
|
1 |
"Cannot connect to database " & |
|
1 |
+ SQLCA.SQLErrText) |
|
1 |
RETURN |
|
1 |
END IF |
|
1 |
|
1 |
// Set the transaction object to SQLCA. |
|
1 |
dw_employee.<span>SetTransObject</span>(SQLCA) |
|
1 |
|
1 |
// Retrieve the rows. |
|
1 |
LastName = ... |
|
1 |
RowsRetrieved = dw_employee.Retrieve(LastName) |
|
1 |
// Test whether the retrieve succeeded. |
|
1 |
IF RowsRetrieved < 0 THEN |
|
1 |
MessageBox("Retrieve Failed", & |
|
1 |
"Cannot retrieve data from the database.") |
|
1 |
END IF |