Defining the component interface

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.

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.

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.

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.

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.

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:

x = x + 1
y = y + 1

The client uses the following code to call the method:

int z
z = 1
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).

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.

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.

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.

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:

---------- Compiler: Information messages
Information C0197: Component Validation
Warning     C0198: illegal Jaguar type: 'window' return type for function: 'of_badfunc'
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.