Description
Gets a reference to a shared object instance.
Syntax
SharedObjectGet ( instancename , objectinstance )
|
Argument |
Description |
|---|---|
|
instancename |
The name of a shared object instance to which you want to obtain references. The name you specify must match the name given to the object instance when it was first registered with the SharedObjectRegister function. |
|
objectinstance |
An object variable of type PowerObject in which you want to store an instance of a shared object. |
Return value
ErrorReturn. Returns one of the following values:
-
Success! -- The function succeeded
-
SharedObjectCreateInstanceError! -- The local reference to the shared object could not be created
-
SharedObjectNotExistsError! -- The instance name has not been registered
Usage
SharedObjectGet retrieves a reference to an object that was created with SharedObjectRegister.
You can use a shared object on a PowerBuilder client to simulate an asynchronous call to the server. The main thread on the client makes an asynchronous call to a function on the shared object, passing it a callback object that is notified when processing has finished on the server. The method on the shared object makes a synchronous call to the server 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 runs on the server.
Examples
This example shows how you might use a shared object to make an asynchronous request against a server component method and return data back to a client application window. The client has a Retrieve button on a window, a SetDW function, a shared object, and a callback handler. The component deployed to the server retrieves employee information from a database.
The Retrieve button on the window creates a shared object that communicates with the server as well as an instance of a callback handler:
// instance variables
// uo_sharedobject iuo_sharedobject
// uo_callback iuo_callback
long ll_rv
SharedObjectRegister("uo_sharedobject","myshare")
SharedObjectGet("myshare",iuo_sharedobject)
iuo_callback = CREATE uo_callback
// Pass a reference to the window to
// the callback object
iuo_callback.passobject (parent)
iuo_sharedobject.post retrievedata(iuo_callback)The SetDW function applies the contents of the DataWindow blob returned from the server component to a DataWindow control in the window:
long ll_rv
ll_rv = dw_employee.SetFullState(ablb_data)
if ll_rv = -1 then
MessageBox("Error", "SetFullState call failed!")
end if
return ll_rvThe Constructor event of the shared object uses a custom Connection object called n_jagclnt_connect to connect to the server. Then it creates an instance of the server component:
// Instance variables // uo_employee iuo_employee // n_jagclnt_connect myconnect Constructor event long ll_rc myconnect = create n_jagclnt_connect ll_rc = myconnect.ConnectToServer() ll_rv = myconnect.CreateInstance(iuo_employee, & "uo_employee")
RetrieveData
The shared object has a single function called that makes a synchronous call to the RetrieveData function on the server component.
When the function completes processing, it calls the Notify function asynchronously on the callback object, posting it to the DataWindow blob returned from the server component:
blob lblb_data long ll_rv ll_rv = iuo_employee.retrievedata(lblb_data) auo_callback.post notify(lblb_data) return ll_rv
When the server 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.The Notify function calls a function called SetDW on the w_employee window, passing it the DataWindow blob returned from the server component:
long ll_rv
ll_rv = iw_employee.setdw(ablb_data)
if ll_rv = -1 then
MessageBox("Error", "SetDW call failed!")
end if
return ll_rvThe callback handler's 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:
iw_employee = aw_employee return 1
The server 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 // protected TransactionServer txnsrv // protected DataStore ids_datastore long ll_rv ll_rv = ids_datastore.Retrieve() ll_rv = ids_datastore.GetFullState(ablb_data) txnsrv.SetComplete() return ll_rv
See also
GetFullState and SetFullState method for DataWindows in the section called “GetFullState” in DataWindow Reference and the section called “SetFullState” in DataWindow Reference.
