Connection object (obsolete)

Obsolete object

Connection object is obsolete, because EAServer is no longer supported since PowerBuilder 2017. An obsolete feature is no longer eligible for technical support and will no longer be enhanced, although it is still available.

The Connection object specifies the parameters that PowerBuilder uses to connect to EAServer. You can customize the Connection object by defining a class user object inherited from the built-in Connection object. The user object has three events: Constructor, Destructor, and Error.

For more information about creating a custom Connection object, see Working with User Objects in Users Guide.

For information about connecting to J2EE servers using the EJBConnection object, see the section called “Connecting to the server” in Application Techniques and the the section called “EJBConnection” in PowerBuilder Extension Reference.

Properties

Connection property

Datatype

Description

Application

String

(Optional) Specifies the default package to be used for EAServer components. If you specify the default package in the Application property, you do not need to specify a package in the second parameter of the CreateInstance function.

ClassDefinition

PowerObject

An object of type PowerObject containing information about the class definition of the object or control.

ConnectString (obsolete)

String

Obsolete property. Used for distributed PowerBuilder connections.

Driver

String

The communications driver used for the connection.

ErrCode

Long

Code indicating the success or failure of the most recent operation. Values are:

0  -- Success

50 -- Distributed service error

52 -- Distributed communications error

53 -- Requested server not active

54 -- Server not accepting requests

55 -- Request terminated abnormally

56 -- Response to request incomplete

57 -- Not connected

58 -- Object instance does not exist

62 -- Server busy

75 -- Server forced client to disconnect

80 -- Server timed out client connection

87 -- Connection to server has been lost

92 -- Required property is missing or invalid

ErrText

String

Text indicating the success or failure of the most recent operation.

Handle

Objhandle

Internal use only.

Location

String

Specifies the host name and port number for the EAServer server. Alternatively, the Location property can specify a fully-qualified URL that uses one of the following formats:

iiop://host:port
iiops://host:port
http://host:port
https://host:port

To take advantage of EAServer's load balancing and failover support, you can also specify a semicolon-separated list of server locations (for example, "iiop://srv1:9000;iiop://srv2:9000").

Options

String

Specifies one or more communications options. If you specify more than one option, you need to separate the options with commas.

EAServer clients can use the Options property of the Connection object to set ORB and SSL property values. Each ORB property value you specify must begin with ORB. For example, you can specify the path and name of the log file by specifying a value for ORBLogFile.

See "Options" next.

Password

String

The password that will be used to connect to the server.

Trace (obsolete)

String

Obsolete property. Used for distributed PowerBuilder connections.

UserID

String

The name or ID of the user who will connect to the server.


Options

Option

Description

ORBHttp

Specifies whether the ORB should use HTTP tunneling to connect to the server. A setting of true specifies HTTP tunneling. 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 almost all allow HTTP packets through. When connecting through such firewalls, set this property to false.

ORBIdleConnectionTimeout

Specifies the time, in seconds, that a connection is allowed to sit idle. When the timeout expires, the ORB closes the connection. The default is 0, which specifies that connections can never time out. The connection timeout does not affect the life of proxy instance references; the ORB may close and reopen connections transparently between proxy method calls. Specifying a finite timeout for your client applications can improve server performance. If many instances of the client run simultaneously, a finite client connection timeout limits the number of server connections that are devoted to idle clients. A finite timeout also allows rebalancing of server load in an application that uses a cluster of servers.

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

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. The default setting is no log.

ORBCodeSet

Sets the code set that the client uses. This parameter can also be set in an environment variable, JAG_CODESET. The default setting is utf8.

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.

ORBProxyHost

Specifies the machine name or the IP address of an SSL proxy.

ORBProxyPort

Specifies the port number of the SSL proxy.

ORBWebProxyHost

Specifies the host name or IP address of an HTTP proxy server that supports generic Web tunneling, sometimes called connect-based tunneling. There is no default for this property, and you must specify both the host name and port number properties. You can also specify the property by setting the environment variable JAG_WEBPROXYHOST.

ORBWebProxyPort

When generic Web tunneling is enabled by setting ORBWebProxyHost, specifies the port number at which the HTTP proxy server accepts connections. There is no default for this property, and you must specify both a host name and port. You can also specify the property by setting the environment variable JAG_WEBPROXYPORT.

ORBHttpExtraHeader

An optional setting to specify what extra information is appended to the header of each HTTP packet sent to a proxy server (specified with the ORBWebProxyHost parameter). You can also specify the property by setting the property JAG_HTTPEXTRAHEADER.

There is no need to set this property unless you have configured the ORB to connect through an HTTP proxy server, and your HTTP proxy server has special protocol requirements. By default, the following line is appended to each packet:

User-agent: Jaguar/major.minor

where major and minor are the major and minor version numbers of your EAServer client software, respectively.

You can set this property to specify text to be included at the end of each HTTP header. If multiple lines are included in the setting, they must be separated by carriage return and line feed characters. If the setting does not include a "User-agent: " line, then the default setting above is included in the HTTP header.

ORBsocketReuseLimit

Specifies the number of times a network connection can 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 Appeon testing, a setting of 10 to 30 proved to be a good starting point. If the reuse limit is too low, client performance degrades.

ORBcertificateLabel

Specifies the client certificate to use if the connection requires mutual authentication. The label is a simple name that identifies an X.509 certificate/private key in a PKCS #11 token.

Required for mutual authentication.

ORBqop

Specifies the name of a security characteristic to use.

Required for SSL.

ORBcacheSize

Specifies the size of the SSL session ID cache. Default is 100.

ORBpin

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.

Required for SSL.

ORBuserdata

Optional string that can be used to provide user-specified context information.

ORBentrustIniFile

Specifies the path name for the Entrust INI file that provides information on how to access Entrust.

Required when the ORBuseEntrustid property is set to true.

ORBentrustUserProfile

Specifies the full path to the file containing an Entrust user profile. Optional when the Entrust single-login feature is available, required otherwise.

ORBuseEntrustID

Specifies whether to use the Entrust ID or the Sybase PKCS #11 token for authentication. This is a Boolean property. If set to FALSE, Sybase PKCS #11 token properties are valid and Entrust-specific properties are ignored. If set to true, Entrust-specific properties are valid and Sybase PKCS #11 token properties are ignored.

ORBentrustPassword

Specifies the password for logging in to Entrust with the specified user profile. Optional when the Entrust single-login feature is available, required otherwise.


Events

Connection event

Occurs

Constructor

When the Connection object is created

Destructor

When the Connection object is destroyed

Error

When a client request cannot be satisfied


Functions

Connection function

Datatype returned

Description

ClassName

String

Returns the class of the object

ConnectToServer (obsolete)

Long

Connects a client application to a server application

CreateInstance

Long

Creates an instance of a remote object on a server

DisconnectServer

Long

Disconnects a client application from a server application

GetContextService

Integer

Creates a reference to a context-specific instance of the specified service

GetParent

PowerObject

Returns a reference to the name of the parent object

GetServerInfo (obsolete)

Long

Obsolete function

Lookup (obsolete)

Long

Allows a PowerBuilder client to create an instance of an EAServer component

Obsolete function

Lookup is an obsolete function, because EAServer is no longer supported since PowerBuilder 2017.

PostEvent

Boolean

Adds an event to the end of the message queue for the object

RemoteStopConnection (obsolete)

Long

Obsolete function

RemoteStopListening (obsolete)

Long

Obsolete function

TriggerEvent

Integer

Triggers a specified event in the object and executes the script for the event

TypeOf

Object

Returns the type of the object