SetFullState

Description

Applies the contents of a DataWindow blob retrieved by GetFullState to a DataWindow or DataStore.

This method is used primarily in distributed applications.

Applies to

DataWindow type

Method applies to

PowerBuilder

DataWindow control, DataStore object


Syntax

PowerBuilder

long dwcontrol.SetFullState ( blob dwasblob )

Argument

Description

dwcontrol

A reference to a DataWindow control or DataStore

dwasblob

A blob that contains the state information you want to apply to the DataWindow control or DataStore


Return value

Returns -1 if an error occurs and one of the following values if it succeeds:

1 -- DataWindow objects match; old data and state overwritten.

2 -- DataWindow objects do not match; old object, data, and state replaced.

3 -- No DataWindow object associated with DataWindow control or DataStore; the DataWindow object associated with the blob is used. The value of the DataObject property remains an empty string.

Null

If any argument's value is null in PowerBuilder or JavaScript, the method returns null.

If any argument's value is null, in PowerBuilder and JavaScript the method returns null.

Usage

GetFullState retrieves the entire state of a DataWindow or DataStore into a blob, including the DataWindow object specification, the data buffers, and the status flags. When you use SetFullState to apply the blob created by GetFullState to another DataWindow, the target DataWindow has enough information to recreate the source DataWindow.

Because the blob created by GetFullState contains the DataWindow object specification, a subsequent call to SetFullState will overwrite the DataWindow object for the target DataWindow control or DataStore. If the target of SetFullState does not have a DataWindow object associated with it, the DataWindow object associated with the blob is used. The value of the DataObject property remains null.

When you use GetFullState and SetFullState to synchronize a DataWindow control on a client with a DataStore on a server, you need to make sure that the DataWindow object for the DataStore contains the presentation style you want to display on the client.

Limitation on calling SetFullState from the current DataWindow

SetFullState destroys the referenced DataWindow and creates a new one using the contents of the DataWindow blob that you specify as an argument to SetFullState. If you call SetFullState from an event in the current DataWindow, the DataWindow is destroyed before the event code can be completed and you might cause the application to crash. Therefore you should never use the "this" pronoun when calling SetFullState.

Examples

These statements in a distributed client application call a remote object function that retrieves database information into a DataStore and puts the contents of the DataStore into a blob by using GetFullState. After the server passes the blob back to the client, the client uses SetFullState to apply the blob to a DataWindow control:

// Global variable:connection myconnect
// Instance variable: uo_employee iuo_employee
 
blob lblb_data
long ll_rv
 
myconnect.CreateInstance(iuo_employee)
iuo_employee.RetrieveData(lblb_data)
 
ll_rv = dw_empdata.SetFullState(lblb_data)
 
IF ll_rv = -1 THEN
      MessageBox("Error", "SetFullState failed!")
END IF

See also

GetChanges

GetFullState

GetStateStatus

SetChanges