Skip to main content

MERGE (ObjectScript)

Merges global nodes or subtrees from source into destination.

Synopsis

MERGE:pc mergeargument,...
M:pc mergeargument,...

where mergeargument is:

destination=source

Arguments

Argument Description
pc 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.

Description

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.

MERGE copies 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 issues a <COMMAND> error if the source and destination have a parent-child relationship.

MERGE Execution

MERGE is not an atomic operation.

The MERGE command can take longer than most other ObjectScript commands to execute. As a result, it is more prone to interruption. An interruption may cause an unpredictable subset of the source to have been copied to the destination subtree.

When executing MERGE while other processes are performing concurrent data modification operations, the contents of destination will be the state of the data at the time that MERGE was initiated, minus any variables that were KILLed at the time the MERGE operation concluded. Other data modifications that occurred during MERGE processing may not be reflected in the contents of destination.

Arguments

pc

An optional postconditional expression. InterSystems IRIS® data platform 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.

destination and source

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=source pairs. They are evaluated in left-to-right order.

A mergeargument can reference a destination=source pair by indirection. For example, MERGE @tMergeString.

A mergeargument can be an array passed by reference that specifies a variable number of parameters, such in myargs...

The ^$GLOBAL SSVN can be the source variable. This copies the global directory to a destination variable. MERGE adds each global name as a destination subscript with a null value. This is shown in the following example:

   MERGE gbls=^$GLOBAL("")
   ZWRITE gbls

Examples

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="cartoons"
   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,1,1)="Fred"
   SET ^a(1,1,1,2)="Wilma"
   SET ^a(1,1,2)="Rubble family"
   SET ^a(1,1,2,1)="Barney"
   SET ^a(1,1,2,2)="Betty"
   MERGE ^b=^a(1,1)
   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:

  KILL ^X,^Y
  SET ^X(2,2)="first"
  SET ^X(2,2,4)="second"
  SET ^Y(3,6,7)="third"
  SET ^Y(3,6,8)="fourth"
  SET ^Y(3,6,7,8,4)="fifth"
  SET ^Y(3,6,7,8,9)="sixth"
  WRITE ^X(2,2),!,^X(2,2,4),!
  WRITE ^Y(3,6,7),!,^Y(3,6,8),!
  WRITE ^Y(3,6,7,8,4),!,^Y(3,6,7,8,9)

The following figure shows the resulting logical structure of ^X and ^Y.

Initial Structure of ^X and ^Y
subscripts tree structure. ^X has 1 node at each level. ^Y has 2 nodes at (3,6) and 2 at (3,6,7,8): (3,6,7,8,4) (3,6,7,8,9).

Consider the following MERGE command:

  MERGE ^X(2,3)=^Y(3,6,7,8)

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
^X tree structure: ^X has its prior nodes: (2), (2,2), (2,2,3) and merged nodes from ^Y tree:  (2,3), (2,3,4), (2,3,9)

Naked Indicator

When both destination and source 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 both source and destination are global variables, the naked indicator is unchanged if source is undefined ($DATA(source)=0). In all other cases (including $DATA(source)=10), the naked indicator takes the same value that it would have if the SET command replaced the MERGE command and source had a value. For more details on the naked indicator, see Checking the Most Recent Global Reference.

Merge to Self

When the destination and source 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.

Watchpoints

The MERGE 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 command.

See Also

FeedbackOpens in a new tab