Update

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.

NoteUpdateEx A separate method name, UpdateEx, is provided as an alternative syntax for the Web DataWindow server component, which cannot use overloaded methods.

Applies to

DataWindow type

Method applies to

PowerBuilder

DataWindow control, DataWindowChild object, DataStore object

Web

Client control, server component

Web ActiveX

DataWindow control, DataWindowChild object

Syntax

PowerBuilder

integer dwcontrol.Update ( { boolean accept {, boolean resetflag } } )

Web DataWindow client control

number dwcontrol.Update ( ) 

Web DataWindow server component

short dwcontrol.Update ( ) 
short dwcontrol.UpdateEx ( boolean accept, boolean resetflag ) 

Web ActiveX

number dwcontrol.Update ( { boolean accept {, boolean resetflag } } ) 

Argument

Description

dwcontrol

A reference to a DataWindow control, DataStore, or child DataWindow.

accept (optional)

A boolean value specifying whether the DataWindow control or DataStore should automatically perform an AcceptText prior to performing the update:

  • True – (Default) Perform AcceptText. The update is canceled if the data fails validation.

  • False – Do not perform AcceptText.

resetflag (optional)

A boolean value specifying whether dwcontrol should automatically reset the update flags:

  • True – (Default) Reset the flags.

  • False – Do not reset the flags.

Returns

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.

NoteTest 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.

NoteUse 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.

NoteCaution 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.

NoteApply 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.


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:

If AcceptText is performed, it can trigger these events:

Examples

Example 1

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:

CONNECT USING SQLCA;

dw_employee.SetTransObject(SQLCA)

... // Some processing

dw_employee.Update()

Example 2

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:

CONNECT USING SQLCA;

dw_employee.SetTransObject(SQLCA)

... // Some processing

dw_Employee.Update(false, true)

Example 3

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:

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