GetChanges

Description

Retrieves changes made to a DataWindow or DataStore as a blob. This method is used primarily in distributed applications.

Applies to

DataWindow type

Method applies to

PowerBuilder

DataWindow control, DataStore object


Syntax

PowerBuilder

long dwcontrol.GetChanges ( REF blob changeblob {, blob cookie } ) 

Argument

Description

dwcontrol

A reference to a DataWindow control or DataStore.

changeblob

A variable into which the returned DataWindow changes will be placed.

cookie (obsolete)

A read-only blob created by GetStateStatus that is compared with the changeblob to determine the likely success of a subsequent call to SetChanges.

This argument is obsolete and will be disabled in a future release.


Return value

Returns the number of rows in the DataWindow change blob if it succeeds and one of the following values if it fails:

  • -1 -- An internal error occurred.

  • -2 -- There is a conflict between the state of the DataWindow change blob and the state of the DataWindow from which the cookie was created; an attempt to use this blob in a SetChanges call against the DataWindow will fail.

  • -3 -- There is a conflict between the state of the DataWindow change blob and the state of the DataWindow from which the cookie was created; but partial changes from the change blob can be applied.

If any argument is null, the method returns null.

Usage

GetChanges is used in conjunction with SetChanges to synchronize two or more DataWindows or DataStores. GetChanges retrieves data buffers and status flags for changed rows in a DataWindow or DataStore and places this information in a blob. SetChanges then applies the contents of this blob to another DataWindow or DataStore.

Reapplying changes from one DataWindow (or DataStore) to another

If you call GetChanges on a DataWindow and apply the data passed in the changeblob argument to another DataWindow using SetChanges, you must call GetChanges on the second DataWindow before you reapply changes to it from the first DataWindow. The GetChanges call on the second DataWindow updates the original timestamp on that DataWindow so that it matches the current timestamp. (You cannot use the Reset, ResetUpdate, or AcceptText calls to update the original timestamp.) If you try to reapply changes without first calling GetChanges on the second DataWindow, you will get an error due to the conflict between the state of the DataWindow changeblob and the state of the second DataWindow.

The change blob created by GetChanges includes only those rows that have a status of New!, NewModified!, or DataModified!.

For information about status values, see DWItemStatus.

Examples

These statements use GetChanges to capture changes to a DataWindow control on a client. If GetChanges succeeds, the client calls a remote object function that applies the changes to a DataStore on the server and updates the database:

blob lblb_changes
long ll_rv
 
ll_rv = dw_employee.GetChanges(lblb_changes)
 
IF ll_rv = -1 THEN
      MessageBox("Error", "GetChanges call failed!")
ELSE
      iuo_employee.UpdateData(lblb_changes)
END IF

See also

GetFullState

GetStateStatus

SetChanges

SetFullState