Chapter 19 Creating ActiveX Components

Writing ActiveX components

This section describes how to write the code for ActiveX components that run on a Jaguar server.

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

   IDL 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 Jaguar. ActiveX components running on a Jaguar server 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:
   • 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 Jaguar 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.
   • 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 Jaguar CTS API Reference for more information about the IObjectControl methods.

Sharing data between components

Jaguar 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 "Transactions tab component properties" for more information. If you need to share data, you can store shared data in a remote database. See "Thread-safety features" for more information.

Using shared data in C++

For components implemented in C++, Jaguar provides the interfaces below for sharing data between components. See Chapter 2, "ActiveX C++ Interface Reference" in the Jaguar CTS 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, Jaguar provides the IDispatch interfaces below. See Chapter 3, "ActiveX IDispatch Interfaces" in the Jaguar CTS 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 20, "Creating ActiveX Clients" for instructions.

You must use a proxy to issue intercomponent calls. If you instantiate another component directly, Jaguar transactions will not work. Also, many Jaguar 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 Jaguar's connection caching feature to realize improved performance. See Chapter 28, "Using Connection Management" for more information.

   Jaguar's transactional model works only with connections obtained from the Jaguar Connection Manager. Connections that you open yourself will not be affected by Jaguar 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.

Accessing SSL client certificates

Clients can connect to a secure IIOP port using an SSL client certificate. You can issue intercomponent calls to the built-in CtsSecurity/SessionInfo component to retrieve the client certificate data, including:

• The distinguished SSL user name
• The client certificate fingerprint (MD5 message digest)
• The client certificate data
• The chain of issuing certificates

This component implements CtsSecurity::SessionInfo IDL interface. HTML documentation is available for the interface in the html/ir subdirectory of your Jaguar installation. You can view it by loading the main Jaguar HTML page, then clicking the "Interface Repository" link.

   The CtsSecurity::UserCredentials interface is deprecated The CtsSecurity::UserCredentials interface, which is implemented by the CtsSecurity/UserCredentials component, has been replaced by the CtsSecurity::SessionInfo interface, which provides additional functionality such as certificate parsing. Jaguar supports the CtsSecurity::UserCredentials interface for backwards compatibility. Please use the interface CtsSecurity::SessionInfo if developing new components.

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.

      JagAxWrap.dll must be registered on your machine. If you are developing on a machine that already has Jaguar installed on it, JagAxWrap.dll is already registered.

2. You can also generate an ActiveX automation exception with text that describes the error. Jaguar 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.

Copyright © 2000 Sybase, Inc. All rights reserved.