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.

In EAServer 6.0 and later,
PowerBuilder components are wrapped as EJBs. For more information,
see the CORBA Components Guide in the EAServer documentation set on the
Sybase Product Documentation Web site.

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.

Datatypes

You can use the following datatypes in the interface of a
user object that you deploy as an EAServer component:

• Standard datatypes (except
  for the Any datatype)

• Structures

• Custom class (nonvisual) user objects that have
  been deployed as EAServer components

These datatypes 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
datatypes supported by PowerBuilder.

The Any datatype 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 datatypes and
arrays of structures, and they can use custom class user objects
to pass arrays.

int and uint map to short

In EAServer 6.x, both the int and uint PowerBuilder
datatypes map to short, so if you have defined
a function that returns int and has an int argument, deployment
will fail if you define a function with the same name on the same component
that returns uint and has a uint argument.

For a list of datatypes used in EAServer,
their CORBA IDL equivalents, and the PowerBuilder datatypes to which
they map, see the PowerScript Reference or
the online Help. For a list of PowerBuilder to EJB datatype mappings,
see the CORBA Components Guide in the EAServer documentation set on the Sybase
Product Documentation Web site.

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:

The client uses the following code to call the method:

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
check box 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.

If you allow null values in the prototype for a component
method, PowerBuilder appends a “_N” suffix
to the method name in the EAServer proxy
that you generate from the Project painter. To call this method,
you must create an instance of the proxy, rather than an instance
of the NVO, and you must reference the method with the “_N” suffix.
For example, if of_gen is the name of
a method in the NVO, and you create an EAServer proxy
that allows null return values, you must instantiate the proxy and
call of_gen_N to use this method.

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:

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”.