$MERGE - Caché MultiValue Basic Reference

docs.intersystems.com

Caché MultiValue Basic Reference

$MERGE

[Home] [Back] [Next]

InterSystems: The power behind what matters

MultiValue Features of Caché > Caché MultiValue Basic Reference > Caché MultiValue Basic Commands > $MERGE

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.