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.
UpdateEx
A separate method name, UpdateEx, is provided
as an alternative syntax for the Web DataWindow server component,
which cannot use overloaded methods.
Controls
|
DataWindow type |
Method applies to |
|---|---|
|
PowerBuilder |
DataWindow control, DataWindowChild object, DataStore |
|
Web |
Client control, server component |
|
Web ActiveX |
DataWindow control, DataWindowChild object |
Syntax
[PowerBuilder]
|
1 |
integer <span>dwcontrol</span>.<span>Update</span> ( { boolean <span>accept</span> {, boolean <span>resetflag</span> } } ) |
[Web DataWindow client control]
|
1 |
number <span>dwcontrol</span>.<span>Update</span> ( ) |
[Web DataWindow server component]
|
1 |
short <span>dwcontrol</span>.<span>Update</span> ( ) <br>short <span>dwcontrol</span>.<span>UpdateEx</span> ( boolean <span>accept</span>, boolean <span>resetflag</span> ) |
[Web ActiveX]
|
1 |
number <span>dwcontrol</span>.<span>Update</span> ( { boolean <span>accept</span> {, boolean <span>resetflag</span> } } ) |
|
Argument |
Description |
|---|---|
|
dwcontrol |
A reference to a DataWindow control, |
|
accept |
A boolean value specifying whether the
|
|
resetflag |
A boolean value specifying whether dwcontrol should automatically
|
Return Values
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 isFalse
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 distributedapplication
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.
Web DataWindow client control
Calling Update in the client control causes
changed data to be passed to the server and updated there. Data
is retrieved again and the page is reloaded.
If the DataWindow object has retrieval arguments, they must
be specified in the HTMLGen.SelfLinkArgs property. For more information,
see the HTMLGen.property,
the Retrieve method, and the DataWindow Programmers
Guide.
All methods that reload the page perform an AcceptText before
sending data back to the server. If the method fails (returns –1),
this means that pending data changes were not accepted and nothing
was sent back to the server. In this situation the ItemError event
occurs.
Frequent updating improves
performance
The Web DataWindow DataWindow client maintains the state of
the server component in string form and the information is sent
to the server and back again with every request. If the user hasn’t
modified the data, the amount of client side state information is
small. The amount of client side state information grows proportionally
to the number of outstanding changes that have not been updated
to the database. When the client control or a server-side script calls
the Update method, the state information returns
to the minimum amount, so calling Update frequently
can reduce the amount of information transferred back and forth.
Web DataWindow server component
Call GetLastError and GetLastErrorString to
get information about database errors that cause SetAction, Update, Retrieve,
and RetrieveEx to return –1.
Web DataWindow PSWebDataWindowClass
If Retrieve or Update return –1,
the OnDBError event is triggered.
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 |
CONNECT USING SQLCA; |
|
1 |
dw_employee.SetTransObject(SQLCA) |
|
1 |
... // Some processing |
|
1 |
dw_employee.<span>Update</span>() |
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 |
CONNECT USING SQLCA; |
|
1 |
dw_employee.SetTransObject(SQLCA) |
|
1 |
... // Some processing |
|
1 |
dw_Employee.<span>Update</span>(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 |
integer rtn |
|
1 |
|
1 |
CONNECT USING SQLCA; |
|
1 |
dw_employee.SetTransObject(SQLCA) |
|
1 |
rtn = dw_employee.<span>Update</span>() |
|
1 |
|
1 |
IF rtn = 1 THEN |
|
1 |
COMMIT USING SQLCA; |
|
1 |
ELSE |
|
1 |
ROLLBACK USING SQLCA; |
|
1 |
END IF |