VALID-HANDLE function

Verifies that a handle is valid.

Syntax

VALID-HANDLE ( handle )

handle

An expression that evaluates to a value of type HANDLE. If the handle represents an object that is currently valid, VALID-HANDLE returns TRUE. If the handle is no longer valid (if, for example, some procedure deleted the object), the function returns FALSE.

Example

In the following example, the user creates a window dynamically. The WINDOW-CLOSE trigger uses the VALID-HANDLE function to determine whether the window has been created.

r-valhnd.p

DEFINE VARIABLE mywin AS HANDLE NO-UNDO.

DEFINE BUTTON mkwin LABEL "New Window".

ENABLE mkwin.

ON CHOOSE OF mkwin DO:
  CREATE WINDOW mywin ASSIGN 
    VISIBLE          = TRUE
    TITLE            = "Second Window"
    MAX-WIDTH-CHARS  = 40
    MAX-HEIGHT-CHARS = 10.
  SELF:SENSITIVE   = FALSE.
END.

ON WINDOW-CLOSE OF DEFAULT-WINDOW DO:
  IF VALID-HANDLE(mywin) THEN 
    DELETE WIDGET mywin.
END.

WAIT-FOR WINDOW-CLOSE OF DEFAULT-WINDOW.

In the example, the VALID-HANDLE function returns a TRUE value only if the window has been created (that is, mywin does not have the Unknown value (?)) and the window has not been deleted. Therefore, the DELETE WIDGET statement executes only if mywin is a valid handle.

Notes

• A handle becomes invalid if the associated widget or procedure is deleted or is out of scope.
• This function is useful when walking through a list of widgets or persistent procedures using the PREV-SIBLING or NEXT-SIBLING attributes.

  VALID-HANDLE(handle:PREV-SIBLING) is FALSE when you reach the first handle in the list. VALID-HANDLE(handle:NEXT-SIBLING) is FALSE when you reach the last handle in the list.

• If a handle is valid, it can still point to an obsolete object. That is, ABL can recycle a previously used handle value to reference a new object instance, leaving previously set handles with the same value pointing to older objects. So you can recognize that seemingly identical handles are actually handle copies that point to different objects, ABL supports the UNIQUE-ID attribute on some types of object handles. For more information, see the UNIQUE-ID attribute reference entry.
• The VALID-HANDLE function supports handles to AppServers, proxy procedures, remote persistent procedures, and COM objects. For more information on AppServers, see OpenEdge Application Server: Developing AppServer Applications. For more information on COM objects, see OpenEdge Development: Programming Interfaces.

See also

CREATE SERVER statement, HANDLE function