CONNECT( ) method (Progress Application Server for OpenEdge)

Connects and associates an instance of the Progress Application Server (PAS) for OpenEdge with the specified server handle and defines the application session model for the connection. This allows a client program to run remote procedures on a PAS for OpenEdge instance. The CONNECT() method requires the host and port to connect to and the AppServer transport value (apsv) in a URL format. Optionally you can specify a web application name, userid, password, and other connection parameters. The CONNECT( ) method returns TRUE if it completes successfully.

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 a connection to the instance.

PAS for OpenEdge connection parameters
Connection parameter	Required	Description
-URL `scheme`://`host`:`port`/[`web-app-name`/]`transport`	Yes	The URL of the server to which you are connecting, where: `scheme` — Is either HTTP or HTTPS. `host` — Specifies the name or domain of the host. `port` — Specifies the port for the host connection that the instance is running on. `web-app-name` — Specifies the OpenEdge ABL web application to connect with. If `web-app-name` is not specified, a connection to the default OpenEdge ABL web application (ROOT) is used. `transport` — Specifies the ABL client (or Open Client) transport. Must be apsv.
-nosessionreuse	No	Does not reuse the SSL session ID when reconnecting over HTTPS to the same instance.
-nohostverify	No	Turns off host verification for an HTTPS connection. If `host` and the Common Name from the server certificate do not match, no error is raised and the secure encrypted connection is still made if all other certificate information is correct. If the parameter is not specified and `host` does not match the server certificate, an error is raised. See OpenEdge Getting Started: Core Business Services - Security and Auditing for more information.
-pf `filename`	No	Specifies a parameter file containing additional connection parameters. The parameters allowed are described in Table 2. If `filename` contains other OpenEdge startup parameters, they are ignored by this method
-sessionModel `option`	No	Specifies the application session model required by the ABL client for this connection. It can be one of two options: `Session-managed` `Session-free` This value is not case sensitive. `Session-managed` is the default.
-connectionLifetime `nSeconds`	No	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. This parameter is only applicable if `-sessionModel session-free` is used.
-initialConnections `nConnections`	No	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. This parameter is only applicable if `-sessionModel session-free` is used.
-maxConnections `nConnections`	No	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. This parameter is only applicable if `-sessionModel session-free` is used.
-clientConnectTimeout `nMilliseconds`	No	The number of milliseconds to wait before timing out each connection attempt.

The client determines the application session model that the instance uses for each connection, because ABL sessions run using any application model that a given client requires.

Connections to an Internet-secure (HTTPS) instance require the management of digital certificate stores for public keys on the client (SSL client) and private keys on an instance (SSL server). For information on configuring for HTTPS connections, see the Progress Application Server for OpenEdge: Administration Guide. For information on using SSL to secure the client side of a PAS for OpenEdge application, see the Progress Application Server for OpenEdge: Application Migration and Development Guide. For information on managing digital certificate stores for OpenEdge SSL clients, see OpenEdge Getting Started: Core Business Services - Security and Auditing.

userid

Optional string parameter containing the userid to connect with. It is passed as input to the instance's Connect procedure.

password

Optional string parameter containing the password to connect with. It is passed as input to the instance's Connect procedure.

app-server-info

Optional string parameter containing application server information. It is passed as input to the instance's Connect procedure.

Possible values for userid, password, and app-server-info are determined by the Connect procedure for the business application. The Connect procedure is specified by the sessionConnectProc property in the instance's openedge.properties file. If any of these parameters are omitted, the Unknown value (?) is passed.

Example

The following is an example of creating a session-free connection to an OpenEdge ABL web application named GeneralLedger on a local instance:

DEFINE VARIABLE happsrv AS HANDLE NO-UNDO.

CREATE SERVER happsrv.
IF happsrv:CONNECT("-URL http://localhost:8810/GeneralLedger/apsv 
                    -sessionModel session-free") THEN
DO:
    /* Some accounting work on the local PAS for OpenEdge instance */
END.

Notes

If an error occurs while executing the CONNECT( ) method, the method returns FALSE. Some conditions for which an error can occur include:

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 instance executes a Connect procedure that terminates with a STOP condition, a QUIT condition, or after executing a RETURN ERROR statement.

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

For more information on PAS for OpenEdge Connect procedures, see the Progress Application Server for OpenEdge: Application Migration and Development Guide

.