Merge

The MERGE command copies a variable and all its descendants into another variable. MERGE does not delete the destination variable, nor any of its descendants.

The format of MERGE command is:

M[ERGE][:tvexpr] glvn1=glvn2[,...]
[Note] Note

GT.M may permit certain syntax or actions that are described by the standard as in error. For example, a MERGE command that specifies an operation where the source and destination overlap but $DATA(source)=0 does not produce an error (which is equivalent to a no-operation).

MERGE simplifies the copying of a sub-tree of a local or global variable to another local or global variable. A sub-tree is all global or local variables that are descendants of a specified variable. MERGE offers a one-command alternative to the technique of using a series of SET commands with $ORDER() or $QUERY() references for doing sub-tree copy.

Examples of MERGE

Example:

GTM>Set ^gbl1="one"
                
GTM>Set ^gbl1(1,1)="oneone"

GTM>Set ^gbl1(1,1,3)="oneonethree"

GTM>Set ^gbl1(1,2,4)="onetwofour"

GTM>Set ^gbl2(2)="gbl2_2"

GTM>Set ^gbl2(2,1,3)="gbl2_2_1_3"

GTM>Set ^gbl2(2,1,4,5)="gbl2_2_1_4_5"

GTM>Merge ^gbl1(1)=^gbl2(2)

GTM>WRITE $Reference
^gbl1(1)
GTM>ZWRite ^gbl1
^gbl1="one"
^gbl1(1)="gbl2_2"
^gbl1(1,1)="oneone"
^gbl1(1,1,3)="gbl2_2_1_3"
^gbl1(1,1,4,5)="gbl2_2_1_4_5"
^gbl1(1,2,4)="onetwofour"
GTM>ZWRITE ^gbl2
^gbl2(2)="gbl2_2"
^gbl2(2,1,3)="gbl2_2_1_3"
^gbl2(2,1,4,5)="gbl2_2_1_4_5"
GTM>

This example illustrates how MERGE copies a sub-tree of one global into another. The nodes in the sub-tree of ^gbl(2), for which $DATA() value is 1 or 11, are copied to sub-tree of ^gbl1(1) as follows:

^gbl1(1) is updated from the value of ^gbl2(2)
^gbl1(1,1,3) is updated from the value of ^gbl2(2,1,3)
^gbl1(1,1,4,5) is updated from the value of ^gbl2(2,1,4,5)

Since ^gbl1(2,1) and ^gbl2(2,2,4) do not have values ($DATA()=0), the corresponding nodes ^gbl1(1,1) and ^gbl(1,2,4) respectively are left unchanged. The naked indicator takes the value ^gbl(1) as if SET replaced MERGE. Notice that the MERGE command does not change ^gbl2(2) or its descendants. Ancestor nodes of ^gbl(1) are also left unchanged.

Example:

GTM>Kill
                
GTM>Set ^gbl(1,2)="1,2"

GTM>Merge lcl(3,4)=^gbl(1)

GTM>Set ^("naked")=2

GTM>ZWRite ^gbl
^gbl(1,2)="1,2"
^gbl("naked")=2
GTM>ZWRite lcl
lcl(3,4,2)="1,2"
GTM>

This example illustrates how MERGE creates a sub-tree of a variable when the variable does not exist. Also, notice how the naked indicator is set when the source of the MERGE is a global and the destination a local.