VALID-HANDLE function

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.

VALID-HANDLE ( `handle` )

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.

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.

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 persistent 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.