Requesting a message back from the server

Simulating server push

A client application cannot
pass a PowerBuilder
object reference to Jaguar. Therefore, you cannot use a PowerBuilder
object reference to push messages from the server back to a PowerBuilder
client, as you might in a distributed PowerBuilder application.
However, you can simulate this behavior by using a shared object
on the client to communicate with Jaguar. This technique can be thought
of as client pull, because the shared object
on the client pulls data back from the server.

How it works

To simulate server push, the client uses the SharedObjectRegister
and SharedObjectGet functions to create a shared object. Once the
object has been created, the main thread on the client makes an
asynchronous call to a method on the shared object, passing it a
callback object that should be notified when processing has finished
on the Jaguar server. The method on the shared object makes a synchronous
call to the Jaguar component method that performs processing. Since
the shared object is running in a separate thread on the client, the
main thread on the client can proceed with other work while the
process is running on the server.

Example

This example shows how you might use a shared object to make
an asynchronous request against a Jaguar component method and return
data back to a client application window.

Client application window

The client application has a window called w_employee
that displays employee data in a DataWindow control. When the user
clicks the Retrieve button in the window, the client creates a shared
object that communicates with Jaguar. In addition, it creates an
instance of a user object that will be used to handle callbacks
from the shared object.

Instance variables

The w_employee window has these instance variables:

Retrieve button

The Retrieve button creates the shared object that will communicate
with Jaguar. In addition, it creates an instance of the user object
that will be used to handle callbacks from the shared object. To
allow the callback object to notify the window of the completion
of processing, the script calls a function called PassObject on
the callback object, passing it a reference to the window. Finally, it
makes an asynchronous call to the RetrieveData function on the shared object,
passing it a reference to the callback object.

The Retrieve button has the following script:

SetDW function

The SetDW function applies the contents of the DataWindow
blob returned from the Jaguar component to a DataWindow control
in the window. The SetDW function takes the argument ablb_data,
which is of type blob, and returns a long value. The function has
the following script:

Jaguar component

The Jaguar component is a PowerBuilder user object called
uo_employee. The uo_employee object has a function
called RetrieveData that uses a DataStore to retrieve employee rows
from the database.

Instance variables

The uo_employee object has these instance variables:

RetrieveData function

The RetrieveData function takes the argument ablb_data,
which is of type blob, and returns a long value. The function has
the following script:

Shared object definition

The client application uses a shared object called uo_sharedobject
to communicate with the Jaguar component. The shared object has
a single function called RetrieveData.

Instance variables

The uo_sharedobject object has these instance variables:

Constructor event

The Constructor event uses a custom Connection object called n_jagclnt_connect
to connect to the Jaguar server. Then it creates an instance of
the Jaguar component:

RetrieveData function

The RetrieveData function makes a synchronous call to the
RetrieveData function on the Jaguar component. When the function
completes processing, it calls the Notify function on the callback
object, passing it the DataWindow blob returned from the server
component.

The RetrieveData function takes an argument called auo_callback,
which is of type uo_callback:

Callback object definition

When the Jaguar component has finished processing, the shared
object notifies a user object called uo_callback, which
in turns notifies the w_employee window. The uo_callback
object has two functions, Notify and PassObject.

Notify function

The Notify function calls a function called SetDW on the w_employee window,
passing it the DataWindow blob returned from the server component. The
Notify function takes the argument ablb_data, which is
of type blob, and returns a long value. The function has the following
script:

PassObject function

The PassObject function caches a reference to the w_employee
window in the iw_employee instance variable. The function
takes the argument aw_employee, which is of type w_employee,
and returns a long value:

---