Progress
Programming
Handbook


Procedure Handles

A procedure handle is a value that identifies the context of an external procedure. Every active external procedure has a procedure handle associated with it. The THISPROCEDURE system handle returns the current procedure handle value as a HANDLE data type from within any executing block of an external procedure.

NOTE: A system handle, like a function, returns the handle to a Progress widget, procedure, or other system object. For more information on system handles, see Widgets and Handles."

Procedure handles have attributes that you can use to store and retrieve information on the particular procedure. These attributes are especially useful for working with persistent procedures. For information on the attributes of a procedure handle, see the THISPROCEDURE System Handle reference entry in the Progress Language Reference . For information on referencing attributes, see "Widgets and Handles," in this manual. For information on using procedure attributes with persistent procedures, see the "Persistent and Non-persistent Procedures" section.

Procedure Triggers

You can also use the THISPROCEDURE handle to define and execute local procedure triggers and internal procedures from anywhere in your application. A procedure trigger is a block of code defined with the ON statement that executes in response to an event applied to the specified procedure handle. For more information on internal procedures and how to execute them using procedure handles, see the "Internal Procedures" section.

This is the basic syntax to define a procedure trigger:

SYNTAX
ON event-list OF procedure-handle block 

The event–list can be any comma-separated list of Progress event names you choose, from keyboard to high-level widget events. For lists of keyboard events see Handling User Input." For lists of all other events, see the Progress Language Reference . The procedure–handle can specify any valid procedure handle value, but you generally use the THISPROCEDURE system handle for the current procedure. The block can be a single statement or a DO block.

NOTE: Progress processes events for procedure triggers with no interpretation. Although you must use a Progress-supplied event name to specify a procedure event, the name is used only to identify the trigger block for execution.

You can store and pass the procedure–handle to other external procedures using parameters, shared variables, and shared temporary table fields defined with the HANDLE data type. As long as the specified external procedure remains in scope, other procedures can use this handle to execute procedure triggers and internal procedures defined in the specified procedure.

NOTE: A procedure handle value remains valid only as long as the specified procedure is in scope. Once the procedure goes out of scope, the specified value is invalid and can be reused. You can use the VALIDHANDLE function and TYPE procedure handle attribute to test whether a procedure handle value is valid. The TYPE attribute must return “PROCEDURE” to filter out any re-use as a widget handle.

Applying Events to Procedure Triggers

You can execute a procedure trigger anywhere in an application using the APPLY statement with this syntax:

SYNTAX
APPLY event TO procedure-handle 

The event can be a character expression that evaluates to any event name specified in the event–list of a trigger for procedure–handle. The procedure–handle must be a valid procedure handle value for which the specified trigger has been defined.

This example is an external procedure that defines and executes its own procedure trigger, displaying the message “Hi!”. The phandle variable is for illustration. You can also use THISPROCEDURE directly in the ON and APPLY statements:

DEFINE VARIABLE phandle AS HANDLE. 
phandle = THIS-PROCEDURE. 
ON RETURN OF phandle MESSAGE "Hi!". 
APPLY "RETURN" TO phandle. 

Your decision whether to use procedure triggers or internal procedures to execute code in an external procedure context is design dependent. In general, internal procedures provide the greatest flexibility, because you can reference them by any name you define and you can pass them run-time parameters. Internal procedures can also map directly to Windows dynamic link library (DLL) functions.


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