Building Distributed
Applications
Using the Progress AppServer


Activate and Deactivate Procedures

Activate and Deactivate procedures encapsulate logic that executes automatically for certain client requests on an AppServer running in stateless operating mode. (For information on the stateless operating mode, see the sections on operating modes in Overview of the Progress AppServer.") When a client application sends remote procedure requests to a stateless AppServer, each request might execute in a different Application Server process instance. To maintain application continuity between Application Server process s, you might need to establish some application-specific resources or context before and discard the resources and context after each request. The Activate and Deactivate procedures help to manage these resources and context more easily.

Activate Procedure

The Activate procedure executes immediately before a remote procedure request when the connection is in the unbound state. A typical use of the Activate procedures is to retrieve connection context using an application-specific context database or the SERVER-CONNECTION-CONTEXT attribute on the SESSION handle (see the "Managing Stateless Connection Context" section). Using the SERVER-CONNECTION-ID attribute, you can uniquely identify (key) the context in the context database. You can then retrieve the connection-identified context from the context database or unmarshall it from the SERVER-CONNECTION-CONTEXT attribute value. You can create the initial context for the connection using the Connect procedure. For more information, see the "Connect and Disconnect Procedures" section.

You can specify the name of an AppServer Activate procedure using the Progress Explorer GUI or by setting the srvrActivateProc property in the AppServer properties file (ubroker.properties). If you specify this procedure, it accepts no parameters and runs as a non-persistent procedure on any Application Server process that executes a remote procedure request for an unbound connection.

NOTE: The Activate procedure only runs prior to remote procedure requests. It does not run in response to connection or disconnection requests.

For the purposes of error handling, the Activate procedure is considered part of the remote procedure request. If the Activate procedure completes with no 4GL termination condition (ERROR, QUIT, or STOP), the remote procedure executes immediately afterward. If the Activate procedure completes with a termination condition, it returns to the client application as if the remote procedure had generated the termination condition. Any return values (using the RETURN [ ERROR ] string statement) are passed to the client and the original remote procedure request is not executed.

Deactivate Procedure

The Deactivate procedure executes immediately after remote procedure and delete procedure requests when the connection is in the unbound state. A typical use of the Deactivate procedures is to store connection context using an application-specific context database or using the SERVER-CONNECTION-CONTEXT attribute on the SESSION handle (see the "Managing Stateless Connection Context" section). Using the SERVER-CONNECTION-ID attribute, you can uniquely identify (key) the context in the context database. 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.

You can specify the name of an AppServer Deactivate procedure using the Progress Explorer GUI or by setting the srvrDeactivateProc property in the AppServer properties file (ubroker.properties). If you specify this procedure, it accepts no parameters and runs as a non-persistent procedure after the request executes, but before any response is returned to the client. Also, the Deactivate procedure runs only if the connection is unbound when the request completes execution.

A stateless connection can be in the unbound or the bound state when a request is initiated and can change to the opposite state before the request completes execution. If the connection ends up in the bound state during execution of the request, the Deactivate procedure does not run when the request completes. However, if the connection ends up in the unbound state, the Deactivate procedure runs even if the original request completes with some 4GL termination condition (ERROR, QUIT, or STOP).

After a delete procedure request, the Deactivate procedure runs only if the connection is unbound. The connection can become unbound only if both of the following are true:

For more information on how stateless connections transition between bound and unbound states, see the "Managing Stateless Connection Context" section.

NOTE: The Deactivate procedure only runs following remote procedure and delete procedure requests. It does not run in response to new connection or disconnection requests.

For the purposes of error handling, only return values from the request (or any executed Activate procedure) are passed to the client. Any return values generated by the Deactivate procedure, itself, are ignored.

Usage Requirements

As described in the previous sections, Activate and Deactivate procedures run only on behalf of connections in the unbound state. If a remote procedure request executes over a bound connection and the connection becomes unbound during execution of this procedure, the Deactivate procedure runs when the request completes with or without error.

Note that both the Activate and Deactivate procedures are optional. There is no requirement to specify either or both of them. Additionally, the content of these procedures is completely application specific, and the AppServer architecture places no constraints on it. Any 4GL logic that is valid within an Application Server process is valid for these procedures.


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095