Defining ActiveX components  Deploying ActiveX components

Chapter 19: 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”).

NoteIDL attributes are not supported by ActiveX components.

To write code for ActiveX components:

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

  2. Implement the constructor and destructor. See “Implementing a constructor and destructor”.

  3. Optionally, implement the IObjectControl interface – You can use this interface to determine, at runtime, whether to pool instances.

  4. Implement methods to perform the following optional tasks:

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 interface reference page in the EAServer API Reference for more information.

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.

NoteYou 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:

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 Interface Reference,” in the EAServer API Reference for descriptions of these interfaces:

Issuing intercomponent calls

To invoke another component, use the ActiveX proxy automation server to create a proxy for the second component. See Chapter 20, “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 26, “Using Connection Management” for more information.

NoteEAServer’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:

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:

  1. Call the IJagServer::WriteLog method to write a description of the error to the log file.

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

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

NoteIDL user-defined exceptions are not supported.

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

Copyright © 2005. Sybase Inc. All rights reserved. Deploying ActiveX components