Caché MultiValue Basic Reference
$MERGE
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Merge two arrays.
Synopsis
$MERGE destination=source
Arguments
destination A local variable, process-private global, or global to be merged. If specified as a class property, the source variable must be a multidimensional (subscripted) variable.
source A local variable, process-private global, or global to be merged. If specified as a class property, the source variable must be a multidimensional (subscripted) variable.
Description
The $MERGE statement is used to merge two arrays. $MERGE destination=source copies source into destination and all descendants of source into descendants of destination. It does not modify source, or kill any nodes in destination.
Note:
$MERGE operates only on non-MultiValue arrays. It cannot be used with a MultiValue static dimensioned array that has been declared using DIM.
$MERGE 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.
If destination is undefined, $MERGE defines it and sets it to source. If source is undefined, $MERGE completes successfully, but does not change destination. When the destination and source are the same variable, no merge occurs. $MERGE issues an error if the source and destination have a parent-child relationship.
You can specify multiple, comma-separated destination=source pairs. They are evaluated in left-to-right order.
The $MERGE command can take longer than most other Caché MVBasic commands to execute. As a result, it is more prone to interruption. The effect of interruption is implementation-specific. Under Caché, an interruption may cause an unpredictable subset of the source to have been copied to the destination subtree.
See Also