A Connect procedure executes in whatever PAS for OpenEdge session handles the client connection request, before the connection request is accepted. If the Connect procedure completes with no error, the connection request from the client application is accepted. If the Connect procedure completes with an error return value (RETURN ERROR statement), the connection request is rejected.

The Connect procedure can also return a user-defined string to the client. This is accomplished by using either the RETURN string statement or the RETURN ERROR string statement in the connect procedure. The client can access this string if the Connect procedure executes and returns an error or if the Connect procedure succeeds. This feature allows you to return more detailed error messages or provide diagnostic information about a successful connection.

How the client can access the user-defined error depends on the client type:

You can specify the name of an PAS for OpenEdge Connect procedure by setting the sessionConnectProc property in the PAS for OpenEdge properties file (openedge.properties). If you specify this procedure, it runs as part of the connection process initiated when an ABL client application executes the CONNECT( ) method on a server handle or when a Web Service or Open Client executes a corresponding connection method.

You must define the procedure with three character input parameters. The following is an example of how you can define these input parameters:

DEFINE INPUT PARAMETER cUserId        AS CHARACTER NO-UNDO.
DEFINE INPUT PARAMETER cPassword      AS CHARACTER NO-UNDO.
DEFINE INPUT PARAMETER cConnectInfo   AS CHARACTER NO-UNDO.

When the PAS for OpenEdge Connect procedure runs, the values of these three parameters are the same as the corresponding parameters specified via the CONNECT( ) method. If a value is not specified for a parameter to the CONNECT( ) method, the PAS for OpenEdge Connect procedure receives the Unknown value (?) for that parameter.

OpenEdge does not examine the values passed from the CONNECT( ) method to an PAS for OpenEdge Connect procedure. The name of each character input parameter might suggest the content you define for it. For example, cUserId can contain user name information, cPassword can contain password information, and cConnectInfo can contain other user-defined information needed by the PAS for OpenEdge Connect procedure to complete a connection. However, the requirement to specify a particular value for the CONNECT( ) method is based only on the implementation of your PAS for OpenEdge Connect procedure. After examining the values provided to the PAS for OpenEdge Connect procedure, you can reject the connection request from the client application by terminating the procedure with the RETURN ERROR statement.

You can use this procedure to authenticate a client application's request for a connection, or to perform any other initialization steps that you want executed each time a client application initiates an explicit connection request. For example, you typically begin by checking the cAppServerInfo procedure parameter to identify if this is to be a bound or unbound connection and set the SERVER-CONNECTION-BOUND-REQUEST attribute on the SESSION handle appropriately. You might then initialize context for the connection using an application-specific context database or using the SERVER-CONNECTION-CONTEXT attribute on the SESSION handle (see Manage context for bound and unbound session-managed connections). Using the SERVER-CONNECTION-ID attribute, you can uniquely identify the connection. You can then gather the context identified with the connection and store it in the context database or marshal it into the SERVER-CONNECTION-CONTEXT attribute. Any PAS for OpenEdge procedure that executes on behalf of the connection can restore and re-save this context as appropriate. .