GetStateStatus

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.

NoteObsolete 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

Web ActiveX

DataWindow control

Syntax

PowerBuilder

long dwcontrol.GetStateStatus ( blob cookie )

Web ActiveX

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

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:

  1. 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.

  2. Send the cookie back to the client.

  3. 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

Example 1

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

See also