A handle-reference allows you to directly reference a handle-based object using a handle value. You can set this handle value by assigning the HANDLE attribute of a static handle-based object (see Object name references), by creating a dynamic handle-based object, by assigning the handle value provided by a system handle, or from any other source of handle values, such as method or function return values. Examples of handle references include CURRENT-WINDOW and BUFFER bCust:HANDLE (from the previous example).

You can access the handle to a static handle-based object using a HANDLE data type (field or variable) that you set to the value of the HANDLE attribute on the static object name reference.

You can access the handle for a dynamic handle-based object through a HANDLE data type (field or variable) whose value is initially set using the CREATE statement for the specified handle-based object. You can also access the handle value to some dynamic handle-based objects, as in the case of a procedure object, that you initially obtain using an appropriate RUN statement or system handle.

The HANDLE attribute of a given object handle can also provide a valid handle value that references the same handle-based object as the given object handle, itself. For example, the following assignment statements set both hProc1 and hProc2 to the same running procedure object using the THIS-PROCEDURE system handle and its HANDLE attribute, and the MESSAGE statement displays the FILE-NAME attribute for the same procedure object:

DEFINE VARIABLE hProc1 AS HANDLE NO-UNDO.
DEFINE VARIABLE hProc2 AS HANDLE NO-UNDO.

/* hProc1 equals hProc2 */
hProc1 = THIS-PROCEDURE.
hProc2 = THIS-PROCEDURE:HANDLE.

MESSAGE hProc1:FILE-NAME SKIP hProc2:FILE-NAME VIEW-AS ALERT-BOX.