HANDLE function

Converts a string representation of a handle to a valid handle.

Syntax 

 

HANDLE ( handle-string )

Caution:

Use this function only to convert a handle previously stored as a string value back to a valid handle. If you convert an arbitrary string to handle using this function and then reference the new handle, a system error will occur. If you use the VALID-HANDLE function to validate a handle generated from an arbitrary string value, a system error will occur.

handle-string

A string representation of a handle. Since handles are integer values, the string must contain only numeric characters.

Example 

The following procedure creates a frame, stores the handle of the frame as a string value, deletes the frame, converts the string representation of the frame handle back to a valid handle, and then tests if the handle is valid:

 

r-widhd.p

DEFINE VARIABLE whand AS HANDLE    NO-UNDO. DEFINE VARIABLE chand AS CHARACTER NO-UNDO.   CREATE FRAME whand. chand = STRING(whand). DELETE WIDGET whand. whand = HANDLE(chand). MESSAGE VALID-HANDLE(whand) VIEW-AS ALERT-BOX INFORMATION BUTTONS OK.

The VALID-HANDLE function returns a FALSE value because the frame was deleted and the handle is no longer valid.

Notes 

The HANDLE function can convert the string representation of procedure, system, and widget handles.

For SpeedScript, the only valid use is to convert the handle of a QUERY object that you create using the CREATE WIDGET statement.

See also 

CREATE widget statement, DATE function, DECIMAL function, INTEGER function, STRING function, VALID-HANDLE function