Invoking remote object functions
Once a connection to a server
application has been established, the client application can begin
using the remote objects provided by the server. The client can
call functions associated with the remote objects and access the objects’ instance
variables.
How to invoke a function
To invoke a function of a remote object, you need to execute
the PowerScript statements required to perform these operations:
- Create the remote object.
- Invoke a function of the remote object.
Version 7 proxy objects do not need to be instantiated In PowerBuilder Version 5, you had to include a CREATE statement
to instantiate the proxy object before you could create the corresponding
remote object on the server. In Version 7, you simply create the
remote object directly by calling the CreateInstance function of
the Connection object. The SetConnect function is not supported
for Version 7 proxy objects.
Example
The following script instantiates a remote object on the server
and invokes a function of the remote object:
|
1 |
// Global variable: |
|
1 |
// connection myconnect |
|
1 |
|
1 |
uo_customer iuo_customer |
|
1 |
string ls_custid |
|
1 |
long ll_rc |
|
1 |
|
1 |
ls_custid = Trim(sle_custid.text) |
|
1 |
ll_rc = myconnect.CreateInstance(iuo_customer) |
|
1 |
if ll_rc <> 0 then |
|
1 |
MessageBox("CreateInstance failed", ll_rc) |
|
1 |
end if |
|
1 |
if iuo_customer.retrieve_balance(ls_custid) != 1 then |
|
1 |
MessageBox("Error", "Retrieve failed!") |
|
1 |
end if |
Creating the object instance
When you deploy a remote object’s class definition
in a client application, the definition on the client has the same
name as the remote object definition deployed in the server application.
This allows for location transparency. Variables
declared with this object type can hold a reference to a local object instance
or a remote object instance. In addition, client-side scripts that
use the object do not need to know where the object was created.
The only time you need to be concerned about the physical
location of the object instance is when you actually create the
object instance. At execution time, you can instantiate the object
locally (by using the CREATE statement) or remotely (by using the
CreateInstance function) depending on your application requirements.
In order to instantiate the object locally, you must have the complete
implementation of the class on the client machine. If you always
plan to instantiate the object remotely, you only need the proxy
object on the client.
This example illustrates location transparency:
|
1 |
boolean bWantRemote |
|
1 |
connection myconnect |
|
1 |
uo_customer iuo_customer |
|
1 |
|
1 |
//Determine whether you want a remote |
|
1 |
//object or a local object. |
|
1 |
... |
|
1 |
//Then create the object. |
|
1 |
if bWantRemote then |
|
1 |
//Create a remote object |
|
1 |
if myconnect.CreateInstance(iuo_customer) <> 0 then |
|
1 |
//deal with the error |
|
1 |
... |
|
1 |
end if |
|
1 |
else |
|
1 |
//Create a local object |
|
1 |
iuo_customer = CREATE uo_customer |
|
1 |
end if |
|
1 |
|
1 |
//Call a function of the object. |
|
1 |
//The function call is the same whether the object was |
|
1 |
//created on the server or the client. |
|
1 |
if isValid(iou_customer) then |
|
1 |
iuo_customer.GetCustomerData() |
|
1 |
end if |
Specifying when the function should execute
PowerBuilder supports both synchronous
and asynchronous
function
calls against remote objects. When you issue a synchronous call,
the server executes the function immediately while the client waits
until processing has completed. When you issue an asynchronous call,
the server adds the request to a queue and performs the processing
at a later point in time; meanwhile, the client can continue to
do other work while the server handles the request.
To tell the server when you want the function be executed,
you can specify one of the following keywords in the function call:
- TRIGGER (the default)
tells the server that the function call is synchronous - POST tells the server that the function call is
asynchronous
Destroying the object instance
After you’ve finished using a remote object, you
can explicitly destroy the object by using the DESTROY statement,
or you can let PowerBuilder’s garbage collection facility
clear the object out of memory for you automatically:
- When you issue a DESTROY
statement against a remote object reference, PowerBuilder destroys
the remote object and invalidates all remote and local references
to the object. If a request is made against a remote reference to
a destroyed object, a NULL object error occurs. - When you rely on garbage collection, PowerBuilder
uses reference counting to determine when the object should be deleted
from memory. When all client-side references to the remote object
have been removed, the remote object reference on the client is
deleted and the server is notified. If there are no other references,
the object is destroyed when the garbage collector next runs on
the server.
Distributed cycles are not detected PowerBuilder can detect unused objects that have circular
references as long as these objects share the same local session;
however, it is unable to detect distributed cycles. Therefore, two
unused objects that point to each other from different sessions
will not be destroyed by the garbage collector.
Making asynchronousfunction calls
When the timing of function
execution is not critical, you can use asynchronous function calls
to improve system throughput. Whereas synchronous
calls
force the client to wait until processing has completed, asynchronous
calls
free the client to do other work while the server handles requests.
How to make an asynchronous call
To make an asynchronous function call, you need to call the
remote object function with the POST keyword.
Example
The following script instantiates a remote object on the server
and makes an asynchronous call to a function of the remote object:
|
1 |
// Global variable: |
|
1 |
// connection myconnect |
|
1 |
// |
|
1 |
// Instance variable: |
|
1 |
// uo_custdata mycustdata |
|
1 |
... |
|
1 |
myconnect.CreateInstance(mycustdata) |
|
1 |
mycustdata.<i>post</i> retrieve_data() |
Restrictions
The following restrictions apply to asynchronous function
calls made to remote objects:
- If the function returns
a value, the return value will be ignored. - The client cannot pass parameters by reference in
an asynchronous call. Arguments passed by reference will not cause
errors at compile time, but will result in errors at execution time. - The client cannot poll to determine whether an asynchronous
request has been processed. To notify a client that a request has
been processed, the server can send a message back to the client. - All asynchronous calls are executed in the order
they are received. However, the exact timing of function execution
cannot be guaranteed. - If the client crashes, execution of queued asynchronous
or synchronous requests cannot be guaranteed. If the server crashes,
any queued requests will be lost.
Requesting a message back from the server
Server push
Using a technique called server push,
the server can send messages back to the client. This is particularly
useful when the client needs to be notified of the completion of
an asynchronous request.
Client needs to pass an object reference
To receive a message from the server, the client needs to
pass an object reference to which the server can send messages.
Once the server has the object reference, it creates a remote reference
to the client-side object and calls one or more functions associated
with this object. Function calls made against the remote reference
are passed back over the wire to the client session that contains
the object. The server can make both synchronous and asynchronous calls
against the client-side object.
Once the server has a remote reference to work with, it can
use the remote reference just as it would any other object reference.
For example, the server can place the remote reference into an instance
variable so the client does not have to send the object with every
request.
For more information about pushing messages
from the server to the client, see “Pushing messages to the
client”.