Release 10.1A: OpenEdge Application Server:
Developing AppServer Applications

> ## Activate and deactivate procedures

> Activate and Deactivate procedures encapsulate logic that executes automatically for certain client requests on an AppServer running in stateless and state-free operating modes. (For information on the stateless operating mode, see the sections on operating modes in Chapter 1, " AppServer and Client Interaction.") When a client application sends remote procedure requests to a stateless AppServer, each request might execute in a different AppServer agent instance. To maintain application continuity between AppServer agents, 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.

> Note: Context management using the `SERVER-CONNECTION-CONTEXT`, `SERVER-CONNECTION-ID`, and `SERVER-CONNECTION-BOUND-REQUEST` attributes applies only to the stateless operating mode. In state-free operating mode, these attributes have no meaning.

> ##### 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 and state-free 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 AppServer agent 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 Progress 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 and state-free 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 Progress 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:

> - The deleted procedure was the last instantiated remote persistent procedure for the connection.

> - The `SERVER-CONNECTION-BOUND-REQUEST` attribute has a value of `FALSE`.

> For more information on how stateless connections transition between bound and unbound states, see the "Managing stateless and state-free 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 AppServer agent is valid for these procedures.

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