PROPAGATE statement

Syntax

>>-PROPAGATE--+--------------------------------------+--+----------------+--+----------+-><
              '-TO--+-TERMINAL--TerminalExpression-+-'  '-MessageSources-'  '-Controls-'   
                    '-LABEL--LabelExpression-------'                                       

WHERE

|--MessageSources =--+-------------------------+--+---------------------+--+-----------------------+--|
                     '-ENVIRONMENT--Expression-'  '-MESSAGE--Expression-'  '-EXCEPTION--Expression-'   

|--Controls =--+-----------------------+--+---------------------+--|
               '-FINALIZE--+-DEFAULT-+-'  '-DELETE--+-DEFAULT-+-'   
                           '-NONE----'              '-NONE----'     

You can use the PROPAGATE statement in Compute and Database nodes, but not in Filter nodes. The additions to this statement assist in error handling - see Coding ESQL to handle errors.

TO TERMINAL clause

If the TO TERMINAL clause is present, TerminalExpression is evaluated. If the result is of type CHARACTER, a message is propagated to a terminal according to the rule:

'nowhere' : no propagation
'failure' : Failure
 'out'    : Out 
 'out1'   : Out1
 'out2'   : Out2
 'out3'   : Out3
 'out4'   : Out4

Tip: Terminal names are case sensitive so, for example, Out1 does not match any terminal.

If the result of TerminalExpression is of type INTEGER, a message is propagated to a terminal according to the rule:

-2 : no propagation
-1 : Failure
 0 : Out 
 1 : Out1
 2 : Out2
 3 : Out3
 4 : Out4

If the result of TerminalExpression is neither a CHARACTER nor an INTEGER, the broker throws an exception.

If there is neither a TO TERMINAL nor a TO LABEL clause, the broker propagates a message to the Out terminal.

Tip: Using character values in terminal expressions leads to the most natural and readable code. Integer values, however, are easier to manipulate in loops and marginally faster.

TO LABEL clause

If the TO LABEL clause is present, LabelExpression is evaluated. If the result is of type CHARACTER and there is a Label node with a Label property that matches LabelExpression, in the same flow, the broker propagates a message to that node.

Tip: Labels, like terminals, are case sensitive. Also, note that, as with route to Label nodes, it is the Label Name property of the Label node that defines the target, not the node's label itself.

If the result of LabelExpression is NULL or not of type CHARACTER, or there is no matching Label node in the flow, the broker throws an exception.

If there is neither a TO TERMINAL nor a TO LABEL clause, the broker propagates a message to the out terminal.

MessageSources clauses

The MessageSources clauses select the message trees to be propagated. This clause is only applicable to the Compute node (it has no effect in the Database node).

The values that you can specify in MessageSources clauses are:

ENVIRONMENT : 
  InputLocalEnvironment 
  OutputLocalEnvironment 

Message : 
  InputRoot 
  OutputRoot

ExceptionList : 
  InputExceptionList
  OutputExceptionList

If there is no MessageSources clause, the node's Compute mode property is used to determine which messages are propagated.

FINALIZE clause

Finalization is a process that fixes header chains and makes the Properties folder match the headers. If present, the FINALIZE clause allows finalization to be controlled.

This clause is only applicable to the Compute node (it has no effect in a Database node).

The Compute node allows its output message to be changed by other nodes (by the other nodes changing their input message). However, a message created by a Compute node cannot be changed by another node after:

• It has been finalized
• It has reached any output or other node which generates a bit-stream

If FINALIZE is set to DEFAULT, or the FINALIZE clause is absent, the output message (but not the Environment, Local Environment or Exception List) is finalized before propagation.

If FINALIZE is set to NONE, no finalization takes place. This option is required if you want to preserve and allow updates of the entire output message tree by the nodes downstream in the message flow and is used with DELETE NONE as described in the next section.

DELETE clause

The DELETE clause allows the clearing of the output local environment, message, and exception list to be controlled.

The DELETE clause is only applicable to the Compute node (it has no effect in a Database node).

If DELETE is set to DEFAULT, or the DELETE clause is absent, the output local environment, message, and exception list are all cleared and their memory recovered immediately after propagation.

If DELETE is set to NONE, nothing is cleared. Use DELETE NONE if you want the downstream nodes to be able to see a single instance of output local environment message, and exception list trees. Each propagate starts with the content of these trees as created by the previous propagate rather than starting with empty trees. If you also want these nodes to update the output tree, DELETE NONE must be used with the FINALIZE NONE option described in the previous section.

Note that the output trees that are finalized are cleared, regardless of which ones are propagated.

Propagation is a synchronous process. That is, the next statement is not executed until all the processing of the message in downstream nodes has completed. Be aware that this processing might throw exceptions and, if these exceptions are not caught, they will prevent the statement following the PROPAGATE call being reached. This behavior might be what the logic of your flow requires but, if it is not, you can use a handler to catch the exception and perform the necessary actions. Note that exceptions thrown downstream of a propagate, if not caught, will also prevent the final automatic actions of a Compute or Database node (for example, issuing a COMMIT Transaction set to Commit) from taking place.

If you are using the PROPAGATE statement in your node it is important that you use a RETURN FALSE; to prevent automatic propagation of the message to the next node in the message flow.

The following messages are produced on the Out terminal by the PROPAGATE statement: