Defining the component interface
How the interface is specified
EAServer stores all component interfaces in CORBA Interface
Definition Language (IDL) modules. IDL is defined by
the Object Management Group as a standard language for defining
component interfaces. When you deploy a PowerBuilder custom class
user object as an EAServer component, the methods (functions and
events) and instance variables defined for the object are added
to the component interface. You do not need to write IDL for the interface,
because the EAServer component generator writes the IDL for you.
What gets included in the interface
The EAServer component generator includes all public functions
declared for the user object in the component interface. Depending
on the build options you specify for the component, the generator
may also include accessor methods for the public instance variables
and also expose user events as methods.
Method names and method overloading
Although IDL does not provide support for method overloading,
you can nonetheless deploy PowerBuilder custom class user objects
to EAServer that have overloaded methods. To work around the IDL
restriction, the component generator appends two underscores (__)
and a unique suffix to the method name that will be overloaded.
If you look at the IDL generated for a PowerBuilder object, you
therefore see suffixes appended to methods that were overloaded
in PowerBuilder.
When you generate stubs or proxy objects for components that
have overloaded methods, EAServer strips off the IDL suffix so that
the client can access the method by using its correct name.
For more information about IDL, see the EAServer documentation.
Do not use two consecutive underscores in your method
names Because EAServer treats two underscores (__)
as a reserved delimiter, you should not use two consecutive underscores
in a function name in a custom class user object that you plan to
deploy as an EAServer component.
Data types
You can use the following data types in the interface of a
user object that you deploy as an EAServer component:
- Standard data types
(except for the Any data type) - Structures
- Custom class (nonvisual) user objects that have
been deployed as EAServer components
These data types can be used for public instance variables
as well as for the arguments and return values of public methods.
Private and protected instance variables and methods can use all
data types supported by PowerBuilder.
The Any data type is not supported in the public interface
of a component. In addition, with the exception of the ResultSet
and ResultSets objects, the component interface cannot include built-in
PowerBuilder system objects (for example, the Transaction or DataStore
object). The component interface also cannot include visual objects
(such as windows or menus).
Component methods can pass arrays of standard data types and
arrays of structures, and they can use custom class user objects
to pass arrays.
For a list of data types used in EAServer, their CORBA IDL
equivalents, and the PowerBuilder data types to which they map,
see the PowerScript Reference
or the online
Help.
Passing by reference
You can pass arguments to component methods by reference.
However, the behavior is somewhat different in a distributed application
than in a nondistributed application.
When you pass by reference, the variable is actually copied
to the server before the method is executed and then copied back
when the method completes execution. This behavior is usually transparent
to the application, but in some situations it can affect the outcome
of processing.
For example, suppose you define a method called increment_values
that takes two arguments called x and y, both of which are passed
by reference. The script for the method increments x and y as shown
below:
|
1 |
x = x + 1<br /> y = y + 1 |
The client uses the following code to call the method:
|
1 |
int z<br /> z = 1<br /> increment_values(z,z) |
In a nondistributed application, the value of z after the
method completed execution would be 3 (because the local invocation
passes a pointer
to z, and z is incremented
twice). In a distributed application, the value of z would be 2 (because
the remote invocation passes two copies
of
z, which are incremented separately).
Passing a read-only value
When
you pass a read-only value, the behavior is similar to passing by
value, except that the data cannot be modified. A copy of the data
is passed across the wire to the server.
Passing objects
Objects created within EAServer components can be passed back
to clients, but these objects must be installed EAServer components.
If you try to pass back a PowerBuilder object that is not an EAServer
component, you will get a runtime error. To use a component that
was passed back from the server, the client must have the corresponding
EAServer proxy (for a PowerBuilder client) or stub (for a non-PowerBuilder
client).
A client application cannot
pass a PowerBuilder
object reference to EAServer. Therefore, you cannot use a PowerBuilder
object reference to push messages from the server back to a PowerBuilder
client. However, you can simulate this behavior by using a shared
object on the client to communicate with EAServer.
To simulate server push, the client uses the SharedObjectRegister
and SharedObjectGet functions to create a shared object. Once the
object has been created, the client can post a method to the shared
object, passing it a callback object that should be notified when
processing has finished on the server. The method on the shared
object makes a synchronous call to the EAServer component method
that performs processing. Since the shared object is running in
a separate thread on the client, the client application can proceed with
other work while the process is running on the server.
Providing support for NULL values
PowerBuilder allows you to specify whether the methods of
an EAServer component can accept NULL values as function arguments
or return types. To provide support for NULL values in the component
interface, check the Support NULL Values checkbox in the property
sheet for the project used to generate the EAServer component. If
this box is not checked, clients cannot pass NULL values in any
argument and the server cannot set any argument to NULL or return
a NULL value.
EAServer validation
If you are designing a custom class user object that you plan
to deploy as an EAServer component, you can have PowerBuilder warn
you when you use code elements that are not valid in EAServer. EAServer
validation checks public instance variables and public functions
for system types, visual types, structures, and any variables.
EAServer validation is on by default if you created the user
object using an EAServer wizard. To check, select the Design menu
in the User Object painter and make sure EAServer Validation is
checked. When you save the object, the Output window lists warnings
such as the following:
|
1 |
---------- Compiler: Information messages<br /> Information C0197: Component Validation<br /> Warning C0198: illegal Jaguar type: 'window' return type for function: 'of_badfunc'<br /> Warning C0198: illegal Jaguar type: 'any' return type for function: 'of_badfunc' |
Validation is associated with the object you are editing,
not with the User Object painter. When you reopen an object, it
has the same validation state as when you closed it.
Throwing exceptions
When you declare an exception on a function of a user object
deployed to EAServer, the exceptions are translated to CORBA IDL
as part of the method prototype. The exceptions can be handled by
any type of EAServer client application or calling component. For
more information, see “Exception handling in PowerBuilder”.