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.
Applies to
|
DataWindow type |
Method applies to |
|---|---|
|
PowerBuilder |
DataWindow control, DataStore object |
Syntax
PowerBuilder
|
1 |
long dwcontrol.GetStateStatus ( blob cookie ) |
|
Argument |
Description |
|---|---|
|
dwcontrol |
A reference to the DataWindow control or DataStore |
|
cookie |
A variable in which you want to store a cookie that |
Return value
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 2 3 4 |
blob lblb_cookie long ll_rv ll_rv = ids_datastore.GetStateStatus(lblb_cookie) return lblb_cookie |
See also