Chapter 17 Creating ActiveX Components

Writing ActiveX components

This section describes how to write the code for ActiveX components that run in EAServer.

When you code the parameters for each method, make sure you use the ActiveX datatypes that are supported by EAServer (see "ActiveX datatype support").

IDL attributes are not supported by ActiveX components.

To write code for ActiveX components:

Implement the IDispatch interface - ActiveX components running on a server are nonvisual, that is, they do not display text or graphics. Consequently, many commonly used ActiveX interfaces are not required for creating ActiveX components in EAServer. ActiveX components running on EAServer need to support only the IDispatch interface. If you develop your component with an automation controller such as Visual Basic, the IDispatch interface is implemented transparently.
Implement the constructor and destructor. See "Implementing a constructor and destructor".
Optionally, implement the IObjectControl interface - You can use this interface to determine, at runtime, whether to pool instances.
Implement methods to perform the following optional tasks:
- Sharing data between components - Enable components to share properties between the same class's instances.
- Issuing intercomponent calls - Execute methods in other components.
- Managing database connections - Connect to databases through connection caches by using the Connection Management API.
- Sending result sets from an ActiveX component - Return result sets using the EAServer Result Sets API.
- Setting transactional state - If your component is transactional, call IObjectContext methods to set the transaction state before returning.
- Accessing SSL client certificates - If the client connected using SSL with mutual (client and server) authentication, you can retrieve the client certificate information in your component. See the EAServer Security Administration and Programming guide for more information.
- Adding error-handling code - If errors occur in a method, raise an ActiveX automation exception. Add code that responds to errors by recording error details to the server log file and sending an exception to the client.

Implementing a constructor and destructor

A constructor is called when a new instance is created. A destructor is called when the instance is destroyed.

Normally, a constructor sets the object's fields to their initial value and allocates any other objects that are used by the component, and a destructor frees any objects that were allocated in the constructor.

However, if the component implements the IObjectControl interface, instance-specific initialization must be performed in the Activate method. See the IObjectControl reference page in the EAServer API Reference for more information about the IObjectControl methods.

Sharing data between components

EAServer allows components in the same package to share data. Shared data is organized within groups. Properties within a group can be referred to by either a string name or a numeric index. Property values are represented by an ActiveX VARIANT structure.

You cannot use shared variables in components that are configured for automatic failover, because these components cannot use local shared resources. See "Component properties: Transactions" for more information. If you need to share data, you can store shared data in a remote database.

Using shared data in C++

For components implemented in C++, EAServer provides the interfaces below for sharing data between components. See Chapter 2, "ActiveX C++ Interface Reference" in the EAServer API Reference for descriptions of these interfaces:

ISharedPropertyGroupManager Interface - Contains methods to create shared property groups or retrieve a handle for access to an existing group.
ISharedPropertyGroup Interface - Represents a shared property group. Contains methods to create new properties and access existing properties.
ISharedProperty Interface - Represents a shared property. Contains methods to get and set the property value.

Using shared data IDispatch interfaces

For components implemented using automation controllers such as Visual Basic, EAServer provides the IDispatch interfaces below. See Chapter 3, "ActiveX IDispatch Interfaces" in the EAServer API Reference for descriptions of these interfaces:

SharedPropertyGroupManager Interface - Contains methods to create shared property groups or retrieve a handle for access to an existing group.
JagSharedPropertyGroup Interface - Represents a shared property group. Contains methods to create new properties and access existing properties.
JagSharedProperty Interface - Represents a shared property. Contains a Value property that allows the shared property value to be retrieved and updated.

Issuing intercomponent calls

To invoke another component, use the ActiveX proxy automation server to create a proxy for the second component. See Chapter 18, "Creating ActiveX Clients" for instructions.

You must use a proxy to issue intercomponent calls. If you instantiate another component directly, EAServer transactions will not work. Also, many EAServer features such as shared objects will not work correctly in the called component. In addition, you must define the Host property as "localhost."

Managing database connections

If your ActiveX methods connect to remote data servers, you should use EAServer's connection caching feature to realize improved performance. See Chapter 24, "Using Connection Management" for more information.

EAServer's transactional model works only with connections obtained from the EAServer Connection Manager. Connections that you open yourself will not be affected by EAServer transactions.

Sending result sets from an ActiveX component

ActiveX methods use the IJagServerResults interface to return rows to the client. For details, see "Sending result sets from an ActiveX component".

Setting transactional state

Transaction state is set using an IObjectContext interface pointer. The IObjectContext interface can be directly accessed only if you are coding the component in C++.

In C++, call GetObjectContext to obtain a reference to an IObjectContext object. Call the appropriate IObjectContext method to set transactional state before returning from the method:

Call SetComplete, if the instance has completed its work without error.
Call EnableCommit, if the work is not necessarily finished but not in error.
Call DisableCommit, if the work is still in progress and has errors.
Call SetAbort if the work cannot be completed.

For nontransactional components, either SetComplete or SetAbort deactivates the component instance. To keep the instance active, call DisableCommit or EnableCommit.

If a method does not explicitly set transaction state before returning, the default behavior is EnableCommit.

Adding error-handling code

Errors occurring during a method call should be handled as follows:

Call the IJagServer::WriteLog method to write a description of the error to the log file.
JagAxWrap.dll must be registered on your machine. If you are developing on a machine that already has EAServer installed on it, JagAxWrap.dll is already registered.
You can also generate an ActiveX automation exception with text that describes the error. EAServer returns the text of the exception to the client. Java clients receive the message as a Java exception (class com.sybase.jaguar.util.JException) and ActiveX clients receive the message as an ActiveX automation exception.

In general, if an error prevents completion of a desired task (such as database updates that represent a new sales order), you should generate an ActiveX automation exception to send a concise description of the problem to the client. Messages sent to the client should be concise and contain language suitable for display to the end user. You can record more detailed messages in the log file.

IDL user-defined exceptions are not supported.

Never write your component to send error messages to the console to display dialog boxes. Servers run unattended; showing a dialog box will do nothing but hang the thread that executes your component.