Distributed DataWindows (EAServer only)

"Distributed DataWindows" refers to the use of DataWindow/DataStore objects in a distributed environment. In a distributed PowerBuilder application, a DataWindow control at the Client can associate with a DataStore object in EAServer. The Client DataWindow control is responsible for the visual representation of data and user operations, while the DataStore object in EAServer is responsible for transactions. The state of the Client DataWindow control is synchronized with the state of the DataStore object in EAServer and vice versa, using relevant DataWindow functions.

There are two benefits to using distributed DataWindow technology with Appeon:

  • Provides more scalability by separating user interface and business logic.

  • Works around the Appeon-unsupported DataWindow functions by moving the functions to the server DataStore objects.

AppeonDataWindow and AppeonDataStore

AppeonDataWindow and AppeonDataStore are two standard user objects provided by Appeon. The appeondatawindow is inherited from the PowerBuilder system DataWindow control, and the appeondatastore is inherited from the PowerBuilder system DataStore object.

Why is workaround required if you use distributing DataWindows in Appeon

PowerBuilder GetFullState, SetFullState, GetChanges and SetChanges functions use BLOB (Binary Large Object) parameters for passing DataWindow or DataStore object specifications. Although Appeon supports BLOB, but it cannot directly interpret the BLOB DataWindow or DataStore object specifications. To work around the unsupported features (the BLOB parameter) in GetFullState, SetFullState, GetChanges and SetChanges, you should use appeondatawindow and appeondatastore.

Functions for AppeonDataWindow and AppeonDataStore

There are six functions provided by AppeonDataWindow and AppeonDataStore.

  1. GetFullState, SetFullState, GetChanges and SetChanges functions are derived from corresponding PowerBuilder functions.

  2. AppeonGetFullStateEX and AppeonSetFullStateEX functions.

AppeonGetFullStateEX

Description

Retrieves the complete state of the main DataWindow into a blob, excluding the information of its DropDownDataWindow.

Syntax

Long dwcontrol.AppeonGetFullStatusEX(blob dwasblob)

Argument

Description

dwcontrol

A reference to an appeondatawindow control and an appeondatastore object.

dwasblob

A variable into which the returned DataWindow will be placed.

Return value

Returns the number of rows in the DataWindow blob if it succeeds and returns -1 if an error occurs. If any argument value is NULL, the method returns NULL.

AppeonSetFullStateEX

Description

Applies the contents of a DataWindow blob retrieved by AppeonGetFullStateEX to a DataWindow. If the source DataWindow object matches the target DataWindow, DropDownDataWindow information of the target DataWindow will not be changed.

Syntax

Long dwcontrol.AppeonSetFullStatusEX(blob dwasblob)

Argument

Description

dwcontrol

A reference to an appeondatawindow control and an appeondatastore

dwasblob

A variable into which the returned DataWindow will be placed.

Return value

Long. Return value are:

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.

Workaround steps

This section introduces the main workaround steps you should take for using distributed DataWindows in your application.

Step 1: Add the Workaround PBL and DLLs provided by Appeon to your application.

Step 2: Derive all distributed DataWindows and DataStores from appeondatawindow and appeondatastore.

appeondatastore and appeondatawindow are built in appeon_workarounds.pbl.

Step 3: Migrate n-Tier DataWindows. In PowerBuilder, deploy the server DataWindows and DataStores that are inherited from appeondatastore to Appeon Server.

You also need to deploy appeondatawindow objects and appeondatastore objects to the Appeon Server.

Step 4: Generate stubs and skeletons for the server DataWindows and DataStores as well as n-Tier NVOs in the application by following the instructions in How to deploy NVO to EAServer 6.1.

A detailed sample for the workaround is provided in the section called “Appeon GetFullState/SetFullState/GetChanges/SetChanges (Windows only)”.

Workaround limitations

When using the appeondatawindow and appeondatastore objects to work around the distributed DataWindow technique, there are some limitations regarding the use of Appeon GetFullState, SetFullState, GetChanges, and SetChanges functions.

Limitation/Difference in ...

Limitation/Difference Description

DataWindow styles

The workaround works with DataWindows or DataStores of all styles, except for OLE and Treeview.

Return value of the functions

The return value of Appeon SetFullState may have a different meaning from that of PowerBuilder system SetFullState function.

The Appeon GetChanges function always returns -1 if it fails. In PowerBuilder, the function can return more error numbers (-1, -2 and -3).

The Appeon SetChanges function can return -1 and -3, but cannot return 2 and -2.

DataWindow ImportString function

If using the DW ImportString function in a distributed DataWindow environment, keep the date display format the same at the Client and Appeon Server machines. In addition, the date/time format configuration in AEM should be kept the same as that of Appeon Server.

State information initialization of a DataWindow/DataStore

In PowerBuilder, the state information of a DataWindow/DataStore is initialized whenever you set its DataObject property. However, if using appeondatawindow and appeondatastore, the state information is initialized only when you change the DataObject property to a different DataWindow object.

Truncation of characters in certain cases

When applying Appeon SetChanges to a target DataWindow/DataStore, if a column of Char type in the source DataWindow/DataStore has defined more characters than its corresponding column in the target DataWindow/DataStore, characters from the source column that exceed the length limit of the target column are truncated, but in PowerBuilder the extra characters are preserved.

Un-modified or modified data

When calling PowerBuilder GetFullState and GetChanges, changed (but not accepted) data in a DataWindow control is treated as un-modified data, but if using the Appeon appeondatawindow and appeondatastore, changed (but not accepted) data is treated as modified data.