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[,...]
The optional truth-valued expression immediately following the command is a command post conditional that controls whether or not GT.M executes the command.
When both glvn1 and glvn2 are local variables, the naked indicator does not change.
If glvn2 is a global variable and glvn1 is a local variable, the naked indicator references glvn2.
When both are global variables, the state of the naked indicator is unchanged if glvn2 is undefined ($DATA(glvn2)=0).
In all other cases including $DATA(glvn2)=10, the naked indicator takes the same value that it would have if the SET command replaced the MERGE command and glvn2 had a value.
If glvn1 is a descendant of glvn2, or if glvn2 is a descendant of glvn1; GT.M generates an error.
If $data(glvn2) is 0 then the command is a NOOP and GT.M issues no errors.
An indirection operator and an expression atom evaluating to a list of one or more MERGE arguments form a legal argument for a MERGE.
![[Note]](images/note.jpg) |
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.
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.