Technical Resources at AEGIS

Methods that are being invoked asynchronously cannot accept arguments that are passed by reference. An attempt to call a method on a shared object and pass an argument by reference will generate the following run-time error: ‘Reference parameters can not be passed to an asynchronous shared / remote object.’

Since we cannot get a return value from a method invoked using POST and cannot pass arguments by reference, how can the calling script determine if the function has run successfully or get any information back from a separate thread? In order to find out if a method has completed processing or get results back from a method running in a separate thread that was called asynchronously we will need to use the server push technique.

PowerBuilder 6.0 introduces the capability of passing object references between threads and processes. This new feature can be used to implement a technique that is called server push. The ability to pass object references between threads and implement server push was added to PowerBuilder to allow a DPB server to send information to a client application and invoke processing on the client.

The server push concept is simple, the server can pass messages to a client application by invoking methods on a client-side object. The client-side object methods that are called by the server can allow the client application to take appropriate action based on information that is received. In order for the server to have access to a client-side object the client application needs to pass an object reference pointing to a local object to the server. We can use this same technique between threads in a multithreaded application to notify one thread when some processing has been completed in a separate thread and thereby synchronize the processing. We do this by passing an object reference from one thread to another. In the examples used in this article we will be passing an object reference from the primary thread to a shared object. As the code sample below illustrates, this is very easy to do.

After running the code sample we have a situation as illustrated in figure 1.

Figure 1 Overview of Server Push

Before continuing let's review the code sample and make some important points. The object reference that is passed to the shared object must point to a valid object instance in the primary thread. Once the shared object has a reference to an object, it can call methods and access attributes on the object as if the object were created locally. All requests that are made against the object reference are sent to the object instance in the primary thread. It is important for the primary thread not to destroy the local object that has been passed to the shared object. If the shared object attempts to use the object and it is not instantiated a null object reference error will be generated. This technique is being shown using the primary thread and a shared object. It can also be used between two shared objects.

The shared object can store the object reference in an instance variable and use it as required to notify the primary thread of its processing status. The code sample below illustrates how the shared object script can use the object reference.

The code sample assumes that the object notify passed in has a method of_Notify that accepts a string argument. The shared object can call methods using the object reference both synchronously and asynchronously. The method called by the shared object is placed on a queue in the primary thread. This is the same way the shared object handles a method call from the primary thread. Function calls made by the shared object should be invoked asynchronously to avoid locking up the thread while it is waiting for the method in the primary thread to complete processing.

The notify object we will build in this article will be generic enough that it can be used in most situations. Our basic notify object will define a function of_notify that will be able to accept a simple string, number, or nothing at all from the server application. To implement a specialized notify object simply inherit from the base class and add the appropriate functionality.

We will declare instance variables to store any data the server returns.

protected long il_number

We will overload the function of_notify to handle getting back a string, a number, and nothing at all.

il_number = al_number

RETURN 0

integer of_notify(value string as_msg)

is_msg = as_msg

RETURN 0

integer of_notify()

RETURN 0

The idea behind the notify object is to provide a simple object that can be used in most cases. Any special processing that needs to be handled as a result of the threads being synchronized should be handled by a specialized object that can be called from the notify object. To handle the specialized object that the notify object may need to interact with we will need an instance variable to hold that object. Since this object could be a window, a single line edit, or another non-visual object we will declare it to be of type powerobject.

We will also need to create a method to allow objects to register themselves with the notify object.

integer of_setpo(value powerobject apo)

ipo = apo

RETURN 0

We will use this technique in are sample application to pass a custom single line edit object on a window to the notify object. This will allow the notify object to receive messages from our counter object that will be running in a separate thread and display them in the single line edit in the primary thread. The code to create the thread and register the single line edit is shown below.

Our shared object will call the function of_notify as the counter runs passing it the number it is on. Our specialized of_notify function will receive this information and call a method on the single line edit passing it the number so that it can be displayed. The code for the specialized of_notify function is shown below.

integer of_notify(value long al_number)

In order to build a multithreaded application we will need to create the object that will be registered as a shared object to handle the processing in a separate thread. Any custom class user object and most non-visual standard objects provided by PowerBuilder can be registered as a shared object. The shared object is typically a custom class user object (see Figure 2). To create the user object, open the user object painter and select the custom class option.

Figure 2

Add an instance variable to hold the notify object. It is declared as follows:

Our thread object will run a simple counter and notify the primary thread of its progress. To do this we will need to create two functions. One to run the counter and another to receive the notify object from the primary thread. The declarations for the functions are shown in figure 3.

Figure 3 Functions in the Thread Object

The function of_DoSomeThing will run a counter and returns its progress. The code listing is shown below.

The function of_PassNotify will receive the object reference to the object n_notify and store it in the instance variable. The code listing is shown below.

The sample application interface is shown in figure 4. It implements two threads running counters as well the ability to search for employees by last name in the PowerBuilder demo database.

Figure 4 Multithreaded Application interface

The start button for each thread simply calls the method of_DoSomeThing.

1. Create the notify object in the primary thread.
2. Register the appropriate controls (if any) with the notify object.
3. Spawn a new thread using SharedObjectRegister.
4. Get an object reference to the new thread using SharedObjectGet.
5. Pass the object reference pointing to the n_notify object to the shared object.
6. Call a method on the shared object asynchronously from the primary thread.
7. The shared object method that is called by the primary thread can use the notify object to return information to the primary thread.
8. The notify object in the primary thread will receive messages from the shared object. It will need to handle the messages accordingly.

Conclusion