$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="" $