CONNECT( ) method (AppServer)

Physically connects and associates an AppServer instance, or logically connects an application service, with the specified server handle. The current application becomes a client application of the connected AppServer.

Return type: LOGICAL

Applies to: Server object handle

Syntax

CONNECT ( { connection-parms } 
          [ , userid ] 
          [ , password ] 
          [ , app-server-info ] )

connection-parms

A character string containing a space-separated list of one or more connection parameters necessary to establish an AppServer connection. These parameters include two types:

• A basic set used to connect to an AppServer instance or application service, regardless of the session model
• A set for specifying and managing the session model of the connection

The following table describes the basic connection parameters you must specify to connect to an AppServer instance or application service, regardless of the session model.

Table 1. AppServer basic connection parameters

Connection parameter1	Description
-AppService application-service	If you connect through a NameServer, the name of an Application Service supported by the specified NameServer. (Defaults to the default service for the specified Name Server.) If you connect directly to an AppServer, this parameter is ignored.
-H [ host_name | IP-address ]	The network address to a NameServer machine or, if you connect directly, to an AppServer machine. You can specify either the TCP/IP host name or the Internet protocol address of the machine. (Defaults to localhost)
-S [ service-name | port-number ]	The UDP port number for a NameServer, or, if you connect directly, the TCP/IP port number for an AppServer connection. You can specify either an explicit port number or a service name. If you use a service name, the method uses the port number associated with that name in the TCP/IP services file. (Defaults to 5162)
-DirectConnect	If specified, the -H and -S parameters are interpreted as the network address and TCP/IP port number of an AppServer connection. Otherwise, the -H and -S parameters are interpreted as the network address and UDP port number of a NameServer.
-ssl	If specified, the connection is direct to the AppServer using Transport Layer Security(TLS) tunneling. (Used in conjunction with the -AppService, -H, and -S parameters). Note: Be sure you need TLS before using this option. TLS incurs more or less heavy performance penalties, depending on resources and load.
-nosessionreuse	If specified, the connection does not reuse the TLS session ID when reconnecting to the same TLS-enabled server (either a Web server with HTTPS or a TLS-enabled AppServer).
-nohostverify	If specified, turns off host verification for a TLS-enabled connection, either using HTTPS with the AIA or using a direct connection to a TLS-enabled AppServer. Without this parameter specified, the client compares the host name specified in the connection with the Common Name specified in the server certificate, and raises an error if they do not match. With this parameter specified, the client never raises the error. For more information, see Learn about Security and Auditing.
-pf filename	A text file containing any of the other AppServer connection parameters described in this table or Table 2. If this file contains any other OpenEdge startup parameters, the method ignores them.
-AppServerKeepalive capstr	Indicates that the client would like to employ the AppServer Keepalive protocol on this connection, if supported and enabled by the AppServer. To enable the protocol, specify the allowServerASK value for capstr. To disable the protocol, specify denyServerASK. The default value is allowServerASK. The absence of this property indicates that the default value for the ServerASK protocol will be used on this connection.
-URL Web-or-AppServer-path	An HTTP (or HTTPS-based) URL to an AIA (for an Internet-secure AppServer connection) or an AppServer-based URL (with or without TLS tunneling for a TLS-enabled AppServer connection). Note: Be sure you need TLS (either, and especially both, an HTTPS or TLS-enabled AppServer) before using this option. TLS at any point in a networked application incurs more or less heavy performance penalties, depending on resources and load.
-clientConnectTimeout nMilliseconds	The number of milliseconds to wait before timing out each connection attempt.

Note: Connections to an Internet-secure (HTTPS) or TLS-enabled AppServer require the management of public keys on the client (TLS client) and private keys on the server (TLS server). For an Internet-secure AppServer, the TLS server is the Web server that hosts the AIA. For a TLS-enabled AppServer, the TLS server is the AppServer itself. For information on configuring a Web server for HTTPS, see your Web server documentation. For information on managing private key and digital certificate stores for TLS clients and servers, see Learn about Security and Auditing.

The following table describes connection parameters for specifying and managing the session model of the connection.

Table 2. AppServer session model connection parameters

Connection parameter	Session model/ default	Description
-sessionModel sessionModel	Session-managed Session-free	Session model supported by the AppServer operating mode, specified by one of the following values: Session-managed Session-free This value is not case sensitive. This parameter is required for session-free applications and is optional for session-managed applications. This value must match the AppServer operating mode or the CONNECT( ) method fails. The default value is Session-managed.
-connectionLifetime nSeconds	Session-free	The maximum number of seconds that a given connection can be used before it is destroyed. Connections whose lifetime exceeds the specified value are destroyed as they become available. An available connection is one that is not currently reserved to run a request. Bound connections associated with remote persistent procedures are not available for re-use until the persistent procedure is deleted. So, bound connections remain available as long as necessary, even if they exceed the specified value. The default value is 300 seconds.
-initialConnections nConnections	Session-free	The number of connections established when the CONNECT( ) method executes on a given server handle. The value must be greater than zero. If the specified number of connections cannot be created, the CONNECT( ) method fails and any successfully-created connections are closed. The default value is 1.
-maxConnections nConnections	Session-free	The maximum number of connections that can be created for a given server handle to execute non-persistent external procedures. The value must be greater than or equal to zero. If this value is zero, there is no limit to the number of connections that can be created. Note: For calls to persistent procedures, their internal procedures, and user-defined functions, the client has no limit on the number of connections that can be created. The default value is 0.
-nsClientMaxPort portNum	Session-managed Session-free	The maximum value for the UDP port number used by the client when communicating with the NameServer. If this value is zero, the AVM chooses the NameServer client port randomly. This value should be greater than or equal to the value of the -nsClientMinPort parameter. The default value is 0.
-nsClientMinPort portNum	Session-managed Session-free	The minimum value for the UDP port number used by the client when communicating with the NameServer. If this value is zero, the AVM chooses the NameServer client port randomly. The default value is 0.
-nsClientPicklistExpiration nSeconds	Session-free	The maximum amount of time, in seconds, that the client retains an AppServer pick list for an application service. The default value is 300.
-nsClientPicklistSize nPicks	Session-free	The number of AppServer picks to request from the NameServer each time it looks up the available AppServer connections for a given application service name. The default value is 1.
-nsClientPortRetry nRetries	Session-managed Session-free	The maximum number of attempts that the client makes to get a valid local UDP port number when attempting to communicate with the NameServer. The default value is 0.
-nsClientDelay nMilliSeconds	Session-managed Session-free	The interval, in milliseconds, that the client waits between attempts to get a valid UDP port number when attempting to communicate with the NameServer. The default value is 0.

Note that the actual AppServer that the client connects to is controlled by the NameServer based on the application service (-AppService) name specified by the client. The ABL interface in cooperation with the NameServer connect the client application to one of the AppServer instances that supports the specified application service. If you do not specify an application service, the NameServer uses whatever AppServer registers itself as the default service, if any.

If the application service is unknown to the NameServer, the client application receives an error. Otherwise, the connection proceeds and any configured Connect procedure executes for the connected AppServer.

[ userid ][ , password][ , app-server-info]

From one to three character string parameters passed as input to the AppServer Connect procedure. The possible values that you can specify for these parameters are determined by the Connect procedure for the AppServer application. If you omit a parameter, it defaults to the Unknown value (?).

If an error occurs while executing the CONNECT( ) method, the method returns FALSE. Otherwise, it returns TRUE. An error can occur if:

• The server handle is invalid.
• One of the parameters contains an invalid value.
• One of the values specified in the connection-parms parameter is invalid.
• The Name Server cannot be located.
• The specified Application Service is not registered to a NameServer.
• The client application cannot connect to the AppServer selected by the NameServer.
• The AppServer selected by the NameServer cannot allocate a connection for the client application.
• The AppServer executes a Connect procedure that terminates with a STOP condition, a QUIT condition, or after executing a RETURN ERROR statement.

If the CONNECT( ) method completes successfully, the CONNECTED( ) method returns TRUE.

The connection lasts until the client application executes the server handle DISCONNECT( ) method or until the AVM detects any failure conditions that automatically terminate the connection.

The -URL connection parameter allows you to connect to an AppServer using the AppServer Internet Adapter (AIA) with the following protocols: HTTP and HTTPS.