$ZAHANDLE() returns a unique identifier (handle) for the array associated with a name or an alias container; for an subscripted lvn, it returns an empty string. To facilitate debugging, the handle is a printable string representation of a hexadecimal number. The only meaningful operation on the value returned by a call to $ZAHANDLE() is to compare it for equality with the value returned by another call. Changing nodes within the array doesn't change its handle. $ZAHANDLE() returns different results for copies of an array.

Example:

GTM>set A=1,*B(1)=A
GTM>write "$zahandle(A)=""",$zahandle(A),""" $zahandle(B(1))=""",$zahandle(B(1)),""""
$zahandle(A)="17B8810" $zahandle(B(1))="17B8810"
GTM>set A("Subscript")="Value" ; Change array - but $ZAHandle() doesn't change
GTM>write "$zahandle(A)=""",$zahandle(A),""" $zahandle(B(1))=""",$zahandle(B(1)),""""
$zahandle(A)="17B8810" $zahandle(B(1))="17B8810"
GTM>merge D=A ; A copy of the data has a different $zahandle()
GTM>Write "$ZAHandle(A)=""",$ZAHandle(A),""" $ZAHandle(D)=""",$ZAHandle(D),""""      
$zahandle(A)="17B8810" $zahandle(D)="17B8C10"
GTM>

Since GT.M does not provide a way for a function to return an array or alias variable as its result, the uniqueness of $ZAHandle() can be exploited to effect this capability, by placing the result in a local variable with an agreed prefix (e.g., "%") and its $ZAHANDLE() as a suffix. The handle can be returned as the value.

$ /usr/lib/fis-gtm/V5.4-002B_x86/gtm -run retval
retval        ; Return an array / object from a function
    ;;Data for the object array
    ;;Albert Einstein,14-March-1879
    ;;Arthur Eddington,28-December-1882
    ;;
    zprint    ; Print this program
    new tmp1,tmp2,tmp3
    for i=3:1 set tmp1=$text(+i),tmp2=$piece(tmp1,";;",2) quit:'$length(tmp2)  do  
    .set tmp3="%"_$$NewPerson($piece(tmp2,",",1),$piece(tmp2,",",2))
    .set @("*Relativists("_(i-2)_")="_tmp3)
    .kill @("*"_tmp3)
    kill tmp1,tmp2,tmp3
    write "------------",!
    write "Array of objects of relativists:",!
    zwrite
    quit
    ;    
NewPerson(name,birthdate)    ; Create new person object
    new lname,fname,dob,tmp1,tmp2 ; New variables used by this function
    set lname=$Piece(name," ",2),fname=$Piece(name," ",1)
    set dob=$$FUNC^%DATE(birthdate)
    set tmp1("fname")=fname,tmp1("lname")=lname,tmp1("dob")=dob
    set tmp2=$ZAHandle(tmp1)
    set @("*%"_tmp2_"=tmp1")
    quit tmp2
------------
Array of objects of relativists:
$ZWRTAC=""
*Relativists(1)=$ZWRTAC1
$ZWRTAC1("dob")=13952
$ZWRTAC1("fname")="Albert"
$ZWRTAC1("lname")="Einstein"
*Relativists(2)=$ZWRTAC2
$ZWRTAC2("dob")=15337
$ZWRTAC2("fname")="Arthur"
$ZWRTAC2("lname")="Eddington"
i=5
$ZWRTAC=""
$