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.
DataWindow type |
Method applies to |
|---|---|
PowerBuilder |
DataWindow control, DataStore object |
Web ActiveX |
DataWindow control |
long dwcontrol.GetStateStatus ( blob cookie )
number dwcontrol.GetStateStatus ( blob cookie )
Argument |
Description |
|---|---|
dwcontrol |
A reference to the DataWindow control or DataStore for which you want to get state status |
cookie |
A variable in which you want to store a cookie that contains state information for the DataWindow |
Returns 1 if it succeeds and –1 if it fails.
If any argument value is null, in PowerBuilder and JavaScript the method returns null.
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.
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:
blob lblb_cookie
long ll_rv
ll_rv = ids_datastore.GetStateStatus(lblb_cookie)
return lblb_cookie
