Merges global nodes or subtrees from source into destination.
||Optional A postconditional expression.
|destination and source
||Local variables, process-private globals, or globals to be merged. If specified as a class property, the source variable must be a multidimensional (subscripted) variable.
simplifies the copying of a subtree (multiple subscripts) of a variable to another variable. Either variable can be a subscripted local variable, process-private global, or global. A subtree is all variables that are descendants of a specified variable. MERGE
offers a one-command alternative to the current technique for doing subtree copy: a series of SET
commands with $ORDER
command can take longer than most other ObjectScript commands to execute. As a result, it is more prone to interruption. The effect of interruption is implementation-specific. Under InterSystems IRIS, an interruption may cause an unpredictable subset of the source to have been copied to the destination subtree.
An optional postconditional expression. InterSystems IRIS executes the MERGE
command if the postconditional expression is true (evaluates to a nonzero numeric value). InterSystems IRIS does not execute the command if the postconditional expression is false (evaluates to zero). For further details, refer to Command Postconditional Expressions
in Using ObjectScript
Variables to be merged. Either variable can be a local variable, a process-private global, or a global. If destination
is undefined, MERGE
defines it and sets it to source
. If source
is undefined, MERGE
completes successfully, but does not change destination
You can specify multiple, comma-separated destination
pairs. They are evaluated in left-to-right order.
The following example copies a subtree from one global variable (^a) to another global variable (^b). In this case, the merge is being used to create a smaller global ^b, which contains only the ^a(1,1) subtree of the information in ^a.
SET ^a(1)="The Flintstones",^a(2)="The Simpsons"
SET ^a(1,1)="characters",^a(1,2)="place names"
SET ^a(1,1,1)="Flintstone family"
SET ^a(1,1,2)="Rubble family"
WRITE ^b,!,^b(2),!,^b(2,1)," and ",^b(2,2)
The following example shows how a destination global variable looks after it has been merged with a subtree of a source global variable.
Suppose you execute the following:
The following figure shows the resulting logical structure of ^X and ^Y.
Initial Structure of ^X and ^Y
Consider the following MERGE
When you issue the previous statement, InterSystems IRIS copies part of ^Y into ^X(2,3). The global ^X now has the structure illustrated in the figure below.
Result on ^X and ^Y of MERGE Command
When both destination
are local variables, the naked indicator is not changed. If source
is a global variable and destination
is a local variable, then the naked indicator references source
When the destination
are the same variable, no merge occurs. Nothing is recorded in the journal file. However, the naked indicator may be changed, based on the rules described in the previous section.
command supports watchpoints. If a watchpoint is in effect, InterSystems IRIS triggers that watchpoint whenever that MERGE
alters the value of a watched variable. To set watchpoints, use the ZBREAK