Chapter 4 ActiveX Client Interfaces

Orb interface

Description

The core interface used by clients that use CORBA-style proxy instantiation.

Methods

• Init - Initialize the Orb instance.
• resolve_initial_references - Obtain a proxy for a client-side service..
• object_to_string - Obtain a serialized string Interoperable Object Reference (IOR) for a proxy instance.
• string_to_object - Deserialize a string that contains a CORBA IOR representing a proxy for a Jaguar server object.

Usage

Orb is the core interface used by clients for CORBA-style proxy instantiation. In Visual Basic, construct an instance with the new keyword, as in this example:

Dim orbRef as JaguarTypeLibrary.Orb
set orbRef = new JaguarTypeLibrary.Orb

You can create multiple Orb instances, though there is no need to do so unless each is initialized differently by passing different properties to the Init method.

Orb.Init

Description

Initialize the Orb instance.

Syntax

Orb.Init ( options as String )

Parameters

options

A string containing zero or more initialization parameter settings, formatted as follows:

orb.init("param1=setting1,param2=setting2")

Usage

Init initializes an Orb instance. You must call Init once for each Orb instance before calling any other method. It is an error to call Init more than once on one instance. You can create several Orb instances and initialize them with different parameters.

Initialization Parameters

You can pass initialization parameters to the driver class by embedding settings in a formatted string, or setting environment variables. If both the environment variable and initialization parameter are set, the value of the initialization parameter is used. You can set any initialization parameter to a value of none, which overrides the value of the environment variable and sets the value to the default, if any.

You can pass settings for the following propertys to the driver class:

• -ORBAXSSLCBComponent Specifies the PROGID for an ActiveX component that implements the methods in the CtsSecurity.SSLCallback interface. When using SSL connections, you can install a callback to handle requests for required data, such as a certificate label or password, and exceptional conditions, such as server certificate signed by an unknown authority.
• -ORBcertificateLabel When using SSL, specifies the client certificate to use, if the server requests mutual authentication. The label is a simple name that identifies an X.509 certificate/private key in the Sybase PKCS #11 token or the Entrust token.
• -ORBCodeSet This sets the code set that the client uses. This parameter can also be set in an environment variable, JAG_CODESET. The default setting is iso_1.
• -ORBentrustIniFile When using SSL with an Entrust personal certificate, specifies the path name for the Entrust INI file that provides information on how to access Entrust. This is required when the useEntrustID property is set to true.
• -ORBentrustUserProfile When using SSL with an Entrust personal certificate, specifies an Entrust user profile path name. This property is optional when the Entrust single-login feature is available and required when this feature is not available.
• -ORBentrustPassword When using SSL with an Entrust personal certificate, specifies the password for logging in to Entrust with the specified user profile. This property is a null-terminated string, which is optional when the Entrust single-login feature is available and required when this feature is not available. If the password is required but not set, the getPin method in CtsSecurity.SSLCallback is invoked to get the Entrust password. If there is no callback or if the callback does not return a password, the SSL session fails.
• -ORBHttp - This specifies whether the ORB should use HTTP-tunnelling to connect to the server. A setting of of "true" specifies HTTP tunnelling. The default is "false". This parameter can also be set in an environment variable, JAG_HTTP. Some firewalls may not allow IIOP packets through, but most all allow HTTP packets through. When connecting through such firewalls, set this property to "true".
• -ORBLogIIOP - This specifies whether the ORB should log IIOP protocol trace information. A setting of "true" enables logging. The default is "false". This parameter can also be set in an environment variable, JAG_LOGIIOP. When this parameter is enabled, you must set the ORBLogFile option (or the corresponding environment variable) to specify the file where protocol log information is written.
• -ORBLogFile - This sets the path and name of the file to which to log client execution status and error messages. This parameter can also be set in an environment variable, JAG_LOGFILE. There is no default; logging is not enabled unless you specify a filename to receive the log trace.
• -ORBpin When using SSL, specifies the PKCS #11 token PIN. This is required for logging in to a PKCS #11 token for client authentication and for retrieving trust information. If this property is not set and the server requests client authentication, the Login callback implementation is invoked to get the PKCS #11 PIN. If this property is set to the value any , then the getPin method in SSLCallback interface is invoked. If a PKCS #11 token login is required and neither the Login callback property nor the PIN property are set, the SSL session fails. This property can be set application-wide using the SSLServiceProvider context. This property cannot be retrieved once it has been set.
• -ORBqop When using SSL, specifies the name of a security profile characteristic. The security profile characteristic lists the CipherSuites the client uses when negotiating an SSL connection. If the qop is set, the ORB will connect only to listeners with an equal or greater level of security than required by the qop security profile. The "Security Configuration" chapter in the Jaguar CTS System Administration Guide describes the security characteristics that are provided with Jaguar. At run time, you can retrieve a list of characteristics and their descriptions using the CtsSecurity.SSLServiceProvider interface. The default setting is "none", which allows connections to listeners that do not use SSL at all.
• -ORBProxyHost - Specifies the machine name or the IP address of an SSL proxy. There is no default.
• -ORBProxyPort - Specifies the port number of the SSL proxy. There is no default.
• -ORBRetryCount - Specify the number of times to retry when the initial attempt to connect to the server fails. This parameter can also be set in an environment variable, JAG_RETRYCOUNT. The default is 5.
• -ORBRetryDelay - Specify the delay, in milliseconds, between retry attempts when the initial attempt to connect to the server fails.This parameter can also be set in an environment variable, JAG_RETRYDELAY. The default is 2000.
• -ORBSocketReuseLimit - Specifies the number of times that a network connection may be reused to call methods from one server. The default is 0, which indicates no limit. The default is ideal for short-lived clients. The default may not be appropriate for a long-running client program that calls many methods from servers in a cluster. If sockets are reused indefinitely, the client may build an affinity for servers that it has already connected to rather than randomly distributing its server-side processing load among all the servers in the cluster. In these cases, the property should be tuned to best balance client performance against cluster load distribution. In Sybase testing, a setting of 10 to 30 proved to be a good starting point. If the reuse limit is too low, client performance degrades.
• -ORBuseEntrustID When using SSL, specifies whether to use the Entrust ID or the Sybase PKCS #11 token for authentication. This is a Boolean (true or false) property. If this property is set to false, Sybase PKCS #11 token properties are valid and Entrust-specific properties are ignored. If this property is set to true, Entrust-specific properties are valid and Sybase PKCS #11 token properties are ignored. Entrust software is not included with EAServer, however, if your site uses Entrust for personal certificate management, this property allows you to connect to Jaguar servers using Entrust certificates.
• -ORBuserData When using SSL, specifies user data (String datatype). This is an optional property. Client code can set user data during ORB initialization and access it using SSLSessionInfo.getProperty method in the SSL callback implementation. This may be useful as a mechanism to store ORB-level context information that is otherwise not available through the SSLSessionInfo interface.

Properties that configure SSL connections can also be set using the CtsSecurity.SSLServiceProvider interface, or by callback methods in a CtsSecurity.SSLCallback object that you install using the ORBAXSSLCBComponent property.

Example

This example creates an Orb instance and configures the -ORBlogFile property and the -ORBpin property, to specify a file name for logging errors and the Sybase SSL-certificate-database password, respectively:

Dim orb as JaguarTypeLibrary.Orb
set orb = new JaguarTypeLibrary.Orb
orb.init("-ORBlogFile=d:\jagorb.log,-ORBpin=sybase")

See Also

CtsSecurity.SSLServiceProvider interface

Orb.resolve_initial_references

Description

Obtain a proxy for a client-side service.

Syntax

Orb.resolve_initial_references ( 
    serviceName as String 
    ) as Object

Parameters

serviceName

A string containing the name of the service. The following names are recognized:

Return Values

An Object (IDispatch pointer) that must be narrowed to the interface implemented by the service by calling the Object.Narrow_ method, as follows:

Orb.object_to_string

Description

Obtain a serialized string Interoperable Object Reference (IOR) for a proxy instance.

Syntax

Orb.object_to_string(objRef as JaguarTypeLibrary.Object) as String

Parameters

objRef

The proxy instance to be serialized. The instance must have been obtained from the Jaguar ActiveX proxy server.

Return Values

A string that encodes the proxy object in CORBA IOR format.

Usage

object_to_string serializes a proxy object into a string, using the CORBA IOR format. You can call string_to_object to deserialize the object later.

See Also

string_to_object

Orb.string_to_object

Description

Deserialize a string that contains a CORBA IOR representing a proxy for a Jaguar server object.

Syntax

Orb.string_to_object(ior as String) as Object

Parameters

ior

A string that was returned by object_to_string, or as a special case when obtaining a SessionManager.Manager instance, a URL formatted as follows:

protocol://host:port

Where protocol is iiop or iiops and host:port is the Jaguar server's listener host address and port number. See SessionManager.Manager for more information.

Return Values

An Object (IDispatch pointer) that must be narrowed to an instance of the appropriate interface by calling the Object.Narrow_ method.

Usage

string_to_object deserializes an object that was serialized using object_to_string.

The following restrictions apply when serializing and deserializing component proxy references:

• Unless the proxy is for an Enterprise Java EntityBean, the serialized reference remains valid only as long as the server has not been restarted since the time when proxy was first instantiated. When deserializing, the proxy instance will connect back to the same host and port as was used to create the original instance. An EntityBean proxy can be deserialized at any time, as long as the EntityBean is still installed on the original server.
• If the original proxy instance was created by connecting to a secure port with a client-side SSL certificate, the proxy must be deserialized in a session that connects using the same client certificate and equal or greater security constraints. For example, if you create an object with session that uses 128-bit SSL encryption, serialize the object, then later try to deserialize the object using during a session that uses 40-bit SSL encryption, the ORB will throw the CORBA::NO_PERMISSION exception. Access will be allowed when objects created using less secure session are later accessed using a more secure session.

See Also

object_to_string

Copyright © 2000 Sybase, Inc. All rights reserved.