Type library name |
JaguarTypeLibrary |
DLL name |
jagproxy.dll |
The core interface used by clients that use CORBA-style proxy instantiation.
Init – Initializes the Orb instance.
resolve_initial_references – Obtains a proxy for a client-side service.
object_to_string – Obtains a serialized string Interoperable Object Reference (IOR) for a proxy instance.
string_to_object – Deserializes a string that contains a CORBA IOR representing a proxy for an EAServer component.
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.
Initializes the Orb instance.
Orb.Init ( options as String )
A string containing zero or more initialization parameter settings, formatted as follows:
orb.init("param1=setting1,param2=setting2")
As shown in the example, parameter names and values must be separated by an equals sign, ‘=’, and each name/value pair must be separated from the next with a comma and no white space.
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.
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 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 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 Specifies 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. “Configuring security profiles” in the EAServer System Administration Guide describes the security characteristics that are provided with EAServer. 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 Specifies 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 Specifies 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 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.
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")
CtsSecurity.SSLServiceProvider interface
Obtains a proxy for a client-side service.
Orb.resolve_initial_references ( serviceName as String ) as Object
A string containing the name of the service. The following names are recognized:
Service name |
Returned object |
|---|---|
SSLServiceProvider |
An instance of CtsSecurity.SSLServiceProvider. |
An Object (IDispatch pointer) that must be narrowed to the interface implemented by the service by calling the Object.Narrow_ method, as follows:
Service name |
Type name for Object.Narrow_ |
|---|---|
SSLServiceProvider |
CtsSecurity/SSLServiceProvider |
Obtains a serialized string Interoperable Object Reference (IOR) for a proxy instance.
Orb.object_to_string(objRef as JaguarTypeLibrary.Object) as String
The proxy instance to be serialized. The instance must have been obtained from the EAServer ActiveX proxy server.
A string that encodes the proxy object in CORBA IOR format.
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.
Deserializes a string that contains a CORBA IOR representing a proxy for a EAServer comonent.
Orb.string_to_object(ior as String) as Object
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 server’s listener host address and port number. See SessionManager.Manager for
more information.
An Object (IDispatch pointer) that must be narrowed to an instance of the appropriate interface by calling the Object.Narrow_ method.
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 is allowed when objects created using less secure session are later accessed using a more secure session.
