Update
method (DataWindows)
Description
Updates the database with the changes made in a DataWindow control
or DataStore. Update can also call AcceptText for the current row and
column before it updates the database.
Applies to
|
DataWindow type |
Method applies to |
|---|---|
|
PowerBuilder |
DataWindow control, DataWindowChild object, DataStore |
Syntax
PowerBuilder
|
1 |
integer dwcontrol.Update ( { boolean accept {, boolean resetflag } } ) |
|
Argument |
Description |
|---|---|
|
dwcontrol |
A reference to a DataWindow control, DataStore, or |
|
accept (optional) |
A boolean value specifying whether the DataWindow
|
|
resetflag (optional) |
A boolean value specifying whether dwcontrol should
|
Return value
Returns 1 if it succeeds and -1 if an error occurs. If any
argument’s value is null, Update returns null. If there is no DataWindow
object assigned to the DataWindow control or DataStore, this method
returns 1.
Usage
In PowerBuilder, you must use the SetTrans or the
SetTransObject method to specify the database connection before the Update
method will execute. When you use SetTransObject, the more efficient of
the two, you must do your own transaction management, which includes
issuing the SQL COMMIT or ROLLBACK statement to finalize the
update.
Test success/failure code
It is good practice to test the success/failure code after calling
Update. You can also verify the number of rows inserted, updated, and
deleted by a DataWindow update by examining the values of the arguments
of the UpdateEnd event.
By default, Update resets the update flags after successfully
completing the update. However, you can prevent the flags from being reset
until you perform other validations and commit the changes. When you are
satisfied with the update, call ResetUpdate to clear the flags so that
items are no longer marked as modified.
Use SetTransObject when resetflag is False
You would typically use SetTransObject, not SetTrans, to specify
the transaction object for the DataWindow control or DataStore when you
plan to update with the resetflag argument set to false. Only
SetTransObject allows you to control when changes are committed.
If you want to update several tables in one DataWindow control or
DataStore, you can use Modify to change the Update property of columns in
each table. To preserve the status flags of the rows and columns, set the
resetflag argument to false. Because the updates all occur in the same
DataWindow control or DataStore, you cannot allow the flags to be cleared
until all the tables have used them. When all the updates are successfully
completed and committed, you can call ResetUpdate to clear the changed
flags in the DataWindow. For an example of this technique, see Modify.
If you are updating multiple DataWindow controls or DataStores as
part of one transaction, set the resetflag argument to false. This will
prevent the DataWindow from “forgetting” which rows to update in case one
of the updates fails. You can roll back, try to correct the situation, and
update again. Once all of the DataWindows have been updated successfully,
use COMMIT to finalize the transaction and use ResetUpdate to reset the
DataWindow’s status flags.
If you call Update with the resetflag argument set to false and do
not call ResetUpdate, the DataWindow will attempt to issue the same
SQL statements again the next time you call Update.
Caution
If you call Update in an ItemChanged event, be sure to set the
accept argument to false to avoid an endless loop and a stack fault.
Because AcceptText triggers an ItemChanged event, you cannot call it in
that event (see AcceptText).
If you call Update in the ItemChanged event, then the item’s old
value is updated in the database, not the newly entered value. The newly
entered value in the edit control is still being validated and does not
become the item value until the ItemChanged event is successfully
completed. If you want to include the new value in an update in the
ItemChanged event, use the appropriate SetItem method first.
Apply GetChanges after deleting rows in a distributed
application
If a DataWindow or data store is populated using SetChanges or
SetFullState, and an Update is done that includes deleted rows, the
deleted rows remain in the delete buffer until a subsequent
GetChanges is applied to the DataWindow or data store.
Events
Update can trigger these events:
| DBError |
| SQLPreview |
| UpdateEnd |
| UpdateStart |
If AcceptText is performed, it can trigger these events:
| ItemChanged |
| ItemError |
Examples
This example connects to the database, specifies a transaction
object for the DataWindow control with SetTransObject, and then updates
the database with the changes made in dw_employee. By default,
AcceptText is performed on the data in the edit control for the current
row and column and the status flags are reset:
|
1 2 3 4 |
CONNECT USING SQLCA; dw_employee.SetTransObject(SQLCA) ... // Some processing dw_employee.Update() |
This example connects to the database, specifies a transaction
object for the DataWindow control with SetTransObject, and then updates
the database with the changes made in dw_employee. The update resets the
status flags but does not perform AcceptText before updating the
database:
|
1 2 3 4 |
CONNECT USING SQLCA; dw_employee.SetTransObject(SQLCA) ... // Some processing dw_Employee.Update(false, true) |
As before, this example connects to the database, specifies a
transaction object for the DataWindow control with SetTransObject, and
then updates the database with the changes made in dw_employee. After
Update is executed, the example checks the return code and, depending on
the success of the update, executes a COMMIT or ROLLBACK:
|
1 2 3 4 5 6 7 8 9 10 11 |
integer rtn CONNECT USING SQLCA; dw_employee.SetTransObject(SQLCA) rtn = dw_employee.Update() IF rtn = 1 THEN COMMIT USING SQLCA; ELSE ROLLBACK USING SQLCA; END IF |
See also