SET statement

The SET statement assigns a value to a variable.

Syntax

Read syntax diagramSkip visual syntax diagramSET TargetFieldReference TYPENAMESPACENAMEVALUE =SourceExpression

Introduction

TargetFieldReference identifies the target of the assignment. The target can be any of the following items:
  • A declared scalar variable
  • A declared row variable
  • One of the predefined row variables (for example, InputRoot)
  • A field within any kind of row variable (that is, a sub tree or conceptual row)
  • A list of fields within any kind of row variable (that is, a conceptual list)
  • A declared reference variable that points to any of the above
The target cannot be any kind of database entity.

SourceExpression is an expression that supplies the value to be assigned. It can be any kind of expression and can return a scalar, row or list value.

Assignment to scalar variables

If the target is a declared scalar variable, SourceExpression is evaluated and assigned to the variable. If need be, its value is converted to the data type of the variable. If this conversion is not possible, there will be either an error at deploy time or an exception at run time.

Null values are handled in exactly the same way as any other value. That is, if the expression evaluates to null, the value null is assigned to the variable.

For scalar variables the TYPE, NAME, NAMESPACE, and VALUE clauses are meaningless and are not allowed.

Assignment to rows, lists, and fields

If the target is a declared row variable, one of the predefined row variables, a field within any kind of row variable, a list of fields within any kind of row variable, or a declared reference variable that points to any of these things, the ultimate target is a field. In these cases, the target field is navigated to (creating the fields if necessary).

If array indices are used in TargetFieldReference, the navigation to the target field can only create fields on the direct path from the root to the target field. For example, the following SET statement requires that at least one instance of Structure already exists in the message:

SET OutputRoot.XMLNS.Message.Structure[2].Field = ...
The target field's value is set according to a set of rules, based on:
  1. The presence or absence of the TYPE, NAME, NAMESPACE, or VALUE clauses
  2. The data type returned by the source expression
  1. If no TYPE, NAME, NAMESPACE, or VALUE clause is present (which is the most common case) the outcome depends on whether SourceExpression evaluates to a scalar, a row, or a list:
    • If SourceExpression evaluates to a scalar, the value of the target field is set to the value returned by SourceExpression, except that, if the result is null, the target field is discarded. Note that the new value of the field might not be of the same data type as its previous value.
    • If SourceExpression evaluates to a row:
      1. The target field is identified.
      2. The target field's value is set.
      3. The target field's child fields are replaced by a new set, dictated by the structure and content of the list.
    • If SourceExpression evaluates to a list:
      1. The set of target fields in the target tree are identified.
      2. If there are too few target fields, more are created; if there are too many, the extra ones are removed.
      3. The target fields' values are set.
      4. The target fields' child fields are replaced by a new set, dictated by the structure and content of the list.

      For further information on working with elements of type list see Working with elements of type list

  2. If a TYPE clause is present, the type of the target field is set to the value returned by SourceExpression. An exception is thrown if the returned value is not scalar, is not of type INTEGER, or is NULL.
  3. If a NAMESPACE clause is present, the namespace of the target field is set to the value returned by SourceExpression. An exception is thrown if the returned value is not scalar, is not of type CHARACTER, or is NULL.
  4. If a NAME clause is present, the name of the target field is set to the value returned by SourceExpression. An exception is thrown if the returned value is not scalar, is not of type CHARACTER, or is NULL.
  5. 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 returned value is not scalar.

Notes

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 the following in a Compute node that modifies a message: 
SET OutputRoot = InputRoot; 
SET OutputRoot.XMLNS.Order.Name = UPPER(InputRoot.XMLNS.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 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 the field, use a statement like this: 
 SET OutputRoot.XMLNS.Order.Name VALUE = NULL;