A Connect procedure executes in whatever AppServer agent 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 RETURNstring statement or the RETURN ERRORstring 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 AppServer Connect procedure using the OpenEdge Explorer or OpenEdge Management or by setting the srvrConnectProc property in the AppServer properties file (ubroker.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 an Open Client executes a corresponding connection method.

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 might use it to store connection context using an application-specific context database or using the SERVER-CONNECTION-CONTEXT attribute on the SESSION handle (see Managing stateless connection context). 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 marshall it into the SERVER-CONNECTION-CONTEXT attribute. Any AppServer procedure that executes on behalf of the connection can restore and resave this context as appropriate. For more information, see Activateand Deactivate procedures.

If you specify a Connect procedure, you must define it with three character input parameters. The following is an example of how you can define these input parameters:

When the AppServer 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 AppServer Connect procedure receives the unknown value (?) for that parameter.

OpenEdge does not examine the values passed from the CONNECT( ) method to an AppServer Connect procedure. The name of each character input parameter might suggest the content you define for it. For example, the user-id can contain user name information, the password can contain password information, and the app-server-info can contain other user-defined information needed by the AppServer 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 AppServer Connect procedure. After examining the values provided to the AppServer Connect procedure, you can reject the connection request from the client application by terminating the procedure with the RETURN ERROR statement.