The SET statement assigns a value to a variable.
Introduction
TargetFieldReference identifies
the target of the assignment. The target can be any of the following:
- 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 which supplies the value to be assigned. It may be any kind
of expression and may 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.XML.Message.Structure[2].Field = ...
The
target field's value is set according to a set of rules, based on:
- The presence or absence of the TYPE, NAME, NAMESPACE, or VALUE clauses
- The data type returned by the source expression
- 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 may not be of the same data type as its previous value.
- If SourceExpression evaluates to a row:
- The target field is identified.
- The target field’s value is set.
- 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:
- The set of target fields in the target tree are identified.
- If there are too few target fields, more are created; if there are too
many, the extra ones are removed.
- The target fields' values are set.
- The target fields' child fields are replaced by a new set, dictated by
the structure and content of the list.
- 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.
- 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.
- 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.
- 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.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 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.XML.Order.Name VALUE = NULL;