Building Distributed
Applications
Using the Progress AppServer


Understanding Procedure Handles in Distributed Progress Sessions

Every active Progress procedure, whether running on a 4GL client or in an Application Server process, 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 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 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. Progress 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 Application Server process 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 6–3 summarizes the settings of the PROXY, REMOTE, and PERSISTENT procedure handle attributes for various types of procedure call scenarios.

Table 6–3: 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 6–3, 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 © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095