SET statement

The SET statement evaluates sourceexpression and assigns the resulting value to the entity identified by target.

Syntax

The target can be either a declared variable or a field in a message tree that can be modified, for example Environment, InputLocalEnvironment, OutputLocalEnvironment, OutputRoot, or OutputExceptionList.

If the target is a declared variable, omit the TYPE, NAME, NAMESPACE, and VALUE clauses. The source expression must return a scalar value of a type that is the same as, or can be converted to, the declared data type of the variable. NULL values are handled in exactly the same way as any other value.

If the target is a field, it is navigated to (creating the fields if necessary) and its value is set according to a set of rules, which depend on the presence or absence of the TYPE, NAME, NAMESPACE, or VALUE clauses, and the data type returned by source expression.

If array indices are used in the field reference, only one instance of a particular field can be created. If you write a SET statement starting:
SET OutputRoot.XML.Message.Structure[2].Field = ...
at least one instance of Structure must already exist in the message. That is, the only fields in the tree that are created are ones on a direct path from the root to the field identified by the field reference.

If a TYPE clause is present, the type of the target field is changed to that returned by sourceexpression. An exception is thrown if the result is not scalar, is not of type INTEGER, or is NULL.

If a NAMESPACE clause is present, the namespace of the element is set. Setting the namespace of an element automatically sets its NAME flag.

If a NAME clause is present, the name of the target field is changed to that returned by sourceexpression. An exception is thrown if the result is not scalar, is not of type CHARACTER, or is NULL.

If a VALUE clause is present, the value of the target field is changed to that returned by sourceexpression. An exception is thrown if the result is not scalar.

If you do not use TYPE, NAME, or VALUE clauses (the most common case) the behavior depends on whether sourceexpression evaluates to a scalar, a field reference, or a list (various kinds) :
  • If sourceexpression is a scalar, the value of the target field is changed to that returned by sourceexpression. The exception to this is that, when the result is NULL, the target field is detached.
  • If sourceexpression is a field reference, the target field's value is taken from the source field, any child fields are detached and the new field is given copies of the source field's child fields (and grandchildren and so on). If the field indicated by sourceexpression does not exist, the target field is detached.
  • If sourceexpression is a list, any child fields are detached and a new set of child fields are added according to the type and content of the list.
SET statements are particularly useful in Compute nodes that modify a message, either changing a field or adding a new field to the original message. SET statements are also useful in Filter and Database nodes to set declared variables or the fields in the Environment tree or Local Environment trees. You can use statements such as these in a Compute node that modifies a message:
SET OutputRoot = InputRoot;
SET OutputRoot.XML.Order.Name = UPPER(InputRoot.XML.Order.Name);

This example puts one field in the message into uppercase. The first statement constructs an output message that is a complete copy of the input message. The second statement sets the value of the Order.Name field to a new value, as defined by the expression on the right.

If the Order.Name field does not exist in the original input message, it does not exist in the output message as generated by the first statement. The expression on the right of the second statement returns NULL (because the field referenced inside the UPPER function call does not exist). Assigning the NULL value to a field has the effect of deleting it if it already exists, and so the effect is that the second statement has no effect.

If you want to assign a NULL value to a field without deleting it, use a statement like this:
SET OutputRoot.XML.Order.Name VALUE = NULL;

Related concepts
ESQL

Related tasks
Developing ESQL
Accessing elements in the message body

Related reference
Syntax preference
ESQL statements