Release 10.1A: OpenEdge Application Server:
Developing AppServer Applications

> ## Understanding procedure handles in distributed Progress 4GL sessions

> Every active Progress 4GL procedure, whether running on a Progress 4GL client or in an AppServer agent, has a procedure handle associated with it. Among the various attributes of the procedure handle, the `PROXY`, `REMOTE`, and `PERSISTENT` attributes combine to provide important information about the procedure and its handle in a distributed application environment.

> ##### REMOTE attribute

> The `THIS-PROCEDURE` system handle returns the current procedure handle value from within any executing block of an external procedure. A current procedure handle created within an AppServer session for a remote procedure request is a remote procedure handle. Its `REMOTE` attribute is, therefore, set to `TRUE`. If the `REMOTE` attribute is `FALSE`, then the current procedure was created as the result of a local procedure call (that is, a procedure call initiated and executed within the current Progress 4GL session context).

> ##### PERSISTENT attribute

> When you execute a persistent procedure from a local procedure call, as with any procedure, the persistent procedure can reference its own context using the `THIS-PROCEDURE` system handle. This system handle returns a procedure handle to the persistent procedure’s own context.

> Also, the procedure that executes the `RUN` statement that creates the persistent procedure can obtain a reference to the same persistent procedure context using the `SET` option of the `RUN` statement. This option returns the same procedure handle as the `THIS-PROCEDURE` system handle accessed from within the persistent procedure.

> Thus, for a local persistent procedure, there is only one handle for a specific persistent procedure context, but there might be many references to it. For any such reference to a persistent procedure handle, the `PERSISTENT` attribute returns the value `TRUE`.

> ##### PROXY attribute

> When a Progress 4GL client application executes a remote persistent procedure, two persistent procedure handles are created: one within the client application session and another separate handle within the AppServer session where the persistent procedure is created. OpenEdge internally maintains a mapping between the two handles. The handle within the client application is a proxy persistent procedure handle, and its `PROXY` attribute and its `PERSISTENT` attributes are set to `TRUE`, but its `REMOTE` attribute is `FALSE`. The handle within the AppServer agent is a remote persistent procedure handle, and its `REMOTE` attribute and the `PERSISTENT` attribute are set to `TRUE`, but its `PROXY` attribute is `FALSE`.

> Unlike persistent procedure handles used for local procedures, the proxy persistent procedure handle and the remote persistent procedure handle are truly separate handles. For example, setting the `PRIVATE-DATA` attribute on a remote persistent procedure handle has no effect on the `PRIVATE-DATA` attribute of the corresponding proxy persistent procedure handle.

> ##### How the attributes work together

> Table 4–8 summarizes the settings of the `PROXY`, `REMOTE`, and `PERSISTENT` procedure handle attributes for various types of procedure call scenarios.

> Table 4–8: PROXY, REMOTE, and PERSISTENT procedure handle attribute settings
> Procedure call type | Caller handle | Callee handle (THIS-PROCEDURE)
> --- | --- | ---
> Local Procedure | Not applicable |
>     PROXY      = FALSE
>     REMOTE     = FALSE
>     PERSISTENT = FALSE
> Local Persistent Procedure |
>     PROXY      = FALSE
>     REMOTE     = FALSE
>     PERSISTENT = TRUE
>     PROXY      = FALSE
>     REMOTE     = FALSE
>     PERSISTENT = TRUE
> Remote Procedure | Not applicable |
>     PROXY      = FALSE
>     REMOTE     = TRUE
>     PERSISTENT = FALSE
> Remote Persistent Procedure |
>     PROXY      = TRUE
>     REMOTE     = FALSE
>     PERSISTENT = TRUE
>     PROXY      = FALSE
>     REMOTE     = TRUE
>     PERSISTENT = TRUE

> In Table 4–8, Caller Handle refers to the handle returned by the `RUN` statement. This column is relevant only for persistent procedures because you can only reference the procedure handle of a procedure that you call persistently using the `SET` option of the `RUN` statement. Callee Handle refers to the procedure handle within the procedure that is being executed. You can reference this handle using the `THIS-PROCEDURE` system handle, whether or not the current procedure was called persistently.

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