GetStateStatus method (DataWindows)
Description
Retrieves the current status of the internal state flags for
a DataWindow and places this information in a blob.
This method is used primarily in distributed applications.
Obsolete method
GetStateStatus is obsolete and will be
discontinued in a future release. You should remove all use of GetStateStatus as
soon as possible. This method was originally added to PowerScript
to allow you to synchronize a source DataWindow with multiple target
DataWindows. This technique is no longer supported.
Controls
|
DataWindow type |
Method applies to |
|---|---|
|
PowerBuilder |
DataWindow control, DataStore object |
|
Web ActiveX |
DataWindow control |
Syntax
[PowerBuilder]
|
1 |
long <span>dwcontrol</span>.<span>GetStateStatus</span> ( blob <span>cookie</span> ) |
[Web ActiveX]
|
1 |
number <span>dwcontrol</span>.<span>GetStateStatus</span> ( blob <span>cookie</span> ) |
|
Argument |
Description |
|---|---|
|
dwcontrol |
A reference to the DataWindow control |
|
cookie |
A variable in which you want to store |
Return Values
Returns 1 if it succeeds and –1 if it fails.
If any argument value is null, in PowerBuilder and JavaScript
the method returns null.
Usage
In situations where a single DataStore on a server acts as
the source for multiple target DataWindows (or DataStores) on different
clients, you can use GetChanges in conjunction
with GetStateStatus to determine the likely success
of SetChanges. This allows you to avoid shipping
a change blob across the wire when SetChanges will
fail anyway (because changes in the blob conflict with changes made
previously by another client).
To determine the likely success of SetChanges,
you need to:
-
Call the GetStateStatus method
on the DataStore on which you want to do a SetChanges. GetStateStatus checks
the state of the DataStore and makes the state information available
in a reference argument called a cookie. The cookie is generally
much smaller than a DataWindow change blob. -
Send the cookie back to the client.
-
Call the GetChanges method on
the DataWindow that contains the changes you want to apply, passing
the cookie retrieved from GetStateStatus as a
parameter. The return value from GetChanges indicates
whether there are currently any potential conflicts between the
state of the DataWindow blob and the state of the DataStore on which
you want to execute SetChanges.
If the return value from GetChanges indicates
that there are potential conflicts, you can then be certain that
a subsequent call to SetChanges will fail if
the FailOnAnyConflict! argument is specified. On the other hand,
if the return value from GetChanges indicates
no conflicts, the call to SetChanges may still
fail, because the state of the Datastore may have changed since
you called GetStateStatus and GetChanges.
For example, if another client session has called SetChanges or
some other processing has been executed that altered the state of
the DataStore since you retrieved the cookie, then SetChanges will
fail.
Examples
The following example is a script for a remote object
function. The script uses GetStateStatus to capture
the state of a DataStore on the server into a cookie. Once the cookie
has been created, it is returned to the client:
|
1 |
blob lblb_cookie |
|
1 |
long ll_rv |
|
1 |
ll_rv = ids_datastore.<span>GetStateStatus</span>(lblb_cookie) |
|
1 |
return lblb_cookie |