Performing updates – PB Docs 125

DataWindow synchronization

In a conventional
client/server application, where database updates are initiated
by a single application running on a client machine, PowerBuilder
can manage DataWindow state information for you automatically. In
a distributed application, the situation is somewhat different.
Because application components are partitioned between the client
and the server, you need to write logic to ensure that the data
buffers and status flags for the DataWindow control on the client
are synchronized with those for the DataStore on the server.

PowerBuilder provides four functions for synchronizing DataWindows
and DataStores in a distributed application:

• GetFullState

• SetFullState

• GetChanges

• SetChanges

Although these functions are most useful in distributed applications,
they can also be used in nondistributed applications where multiple
DataWindows (or DataStores) must be synchronized.

Moving DataWindow buffers and status flags

To synchronize a DataWindow control on the client with a DataStore
on the server, move the DataWindow data buffers and status flags
back and forth between the client and the server whenever changes
occur. The procedures for doing this are essentially the same whether
the source of the changes resides on the client or the server.

To apply complete state information from
one DataWindow (or DataStore) to another, you need to:

1. Invoke the GetFullState function
   to capture the current state of the source DataWindow.

2. Invoke the SetFullState function
   to apply the state of the source DataWindow to the target.

To apply changes from one DataWindow
(or DataStore) to another, you need to:

1. Invoke the GetChanges function
   to capture changes from the source DataWindow.

2. Invoke the SetChanges function
   to apply changes from the source DataWindow to the target.

SetChanges can be applied to an empty DataWindow

You can call SetChanges to apply changes
to an empty DataWindow (or DataStore). The target DataWindow does
not need to contain a result set from a previous retrieval operation.
However, the DataWindow must have access to the DataWindow definition.
This means that you need to assign the DataWindow object to the
target DataWindow before calling SetChanges.

DataWindow state is stored in blobs

When you call GetFullState or GetChanges,
PowerBuilder returns DataWindow state information in a Blob.
The Blob returned from GetFullState provides
everything required to recreate the DataWindow, including the data buffers,
status flags, and complete DataWindow specification. The Blob returned
from GetChanges provides data buffers and status
flags for changed and deleted rows only.

Synchronizing after Update

By default, the Update function resets
the update flags after a successful update. Therefore, when you
call the Update function on the server, the status flags
are automatically reset for the server DataStore. However, the update flags
for the corresponding client DataWindow control are not reset.
Therefore, if the Update function on the server
DataStore succeeds, call ResetUpdate on the client
DataWindow to reset the flags.

One source, one target

You can synchronize a single source DataWindow (or DataStore)
with a single target DataWindow (or DataStore). Do not
try to synchronize a single source with multiple targets, or vice
versa.