PROPAGATE statement

Start of changeThe PROPAGATE statement propagates a message to the downstream nodes.End of change

SYNTAX

When used in a Compute node, the PROPAGATE statement finalizes the node's output message trees (that is, it fixes their header chains) and propagates to the downstream nodes within the message flow. The PROPAGATE statement then clears the output message trees and reclaims the memory ready for further use.

The Environment tree is always propagated. The Local Environment, message, and exception list trees, that are propagated, can be either the input or output trees under the control of the Compute Mode property as normal. However, it is the output trees that are finalized and cleared, regardless of which ones are propagated.

By default, the Compute node automatically propagates to its downstream nodes when its ESQL terminates. To prevent this make the ESQL return FALSE (see RETURN statement).

When used in a Database node, the PROPAGATE statement behaves similarly. It propagates the input message to the downstream nodes within the message flow. By default the Database node also automatically propagates to its downstream nodes when its ESQL terminates. This can be prevented by having the ESQL return FALSE (see RETURN statement).

Do not use the PROPAGATE statement within Filter nodes.

When you use the PROPAGATE statement, the path that the message takes as a result, and the processing that is applied to it by subsequent nodes, are considered part of the processing of the PROPAGATE statement itself. The execution of the node that issues the PROPAGATE does not complete until control has returned and the ESQL terminates. If you use PROPAGATE in a node that has Transaction set to Commit, any database updates that you have made in this node are not committed until the ESQL terminates. Therefore if the processing on the PROPAGATE path results in an exception, and the message flow rolls back its unit of work, the database activity is also rolled back.

The ESQL in this example produces three messages on the OUT terminal, using the sample message in Example message:

DECLARE i INTEGER 1;

WHILE i <= CARDINALITY(InputRoot.XML.Invoice.Purchases."Item"[]) DO
    SET OutputRoot = InputRoot;
    SET OutputRoot.XML = NULL;
    SET OutputRoot.XML.BookSold."Item" = InputRoot.XML.Invoice.Purchases."Item"[i];
    PROPAGATE; 
    SET i = i+1;
END WHILE; 
RETURN FALSE;

Here are the messages produced on the OUT terminal by the PROPAGATE statement:

<BookSold>
 <Item>
  <Title Category="Computer" Form="Paperback" Edition="2">The XML Companion </Title>
  <ISBN>0201674866</ISBN>
  <Author>Neil Bradley</Author>
  <Publisher>Addison-Wesley</Publisher>
  <PublishDate>October 1999</PublishDate>
  <UnitPrice>27.95</UnitPrice>
  <Quantity>2</Quantity>
 </Item>
</BookSold>
<BookSold>
 <Item>
  <Title Category="Computer" Form="Paperback" Edition="2">A Complete Guide to 
   DB2 Universal Database</Title>
  <ISBN>1558604820</ISBN>
  <Author>Don Chamberlin</Author>
  <Publisher>Morgan Kaufmann Publishers</Publisher>
  <PublishDate>April 1998</PublishDate>
  <UnitPrice>42.95</UnitPrice>
  <Quantity>1</Quantity>
 </Item>
</BookSold>
<BookSold>
 <Item>
  <Title Category="Computer" Form="Hardcover" Edition="0">JAVA 2 Developers
  Handbook</Title>
  <ISBN>0782121799</ISBN>
  <Author>Phillip Heller, Simon Roberts </Author>
  <Publisher>Sybex, Inc.</Publisher>
  <PublishDate>September 1998</PublishDate>  <UnitPrice>59.99</UnitPrice>
  <Quantity>1</Quantity>
 </Item>
</BookSold>
Related concepts
ESQL overview
Related tasks
Developing ESQL
Generating multiple output messages
Committing database updates
Related reference
Syntax diagrams: available types
ESQL statements
RETURN statement
Example message