IBM Integration Bus, Version 9.0.0.8 Operating Systems: AIX, HP-Itanium, Linux, Solaris, Windows, z/OS

See information about the latest product version

MOVE statement

The MOVE statement changes the field to which the Target reference variable points.

Syntax


>>-MOVE--------------------------------------------------------->

>--Target----+-TO--SourceFieldReference--------------+---------><
             +-PARENT--------------------------------+     
             '-+-FIRSTCHILD------+--| NAME clauses |-'     
               +-LASTCHILD-------+                         
               +-PREVIOUSSIBLING-+                         
               '-NEXTSIBLING-----'                         

NAME clauses

|--+-+-------------------+--+---------------------------+--+-------------------+-+--|
   | '-TYPE --Expression-'  '-NAMESPACE--+-Expression-+-'  '-NAME --Expression-' |   
   |                                     '-*----------'                          |   
   +-IDENTITY --PathElement------------------------------------------------------+   
   |        (1)                                                                  |   
   '-REPEAT------+-TYPE------+---------------------------------------------------'   
                 +-NAME------+                                                       
                 '-TYPE-NAME-'

Notes:

The RepeatClause can be used only with the PREVIOUSSIBLING and NEXTSIBLING qualifiers.

If you include a TO clause, this clause changes the target reference to point to the same entity as that pointed to by source; this can either be a message field or a declared variable.

If you include a PARENT, PREVIOUSSIBLING, NEXTSIBLING, FIRSTCHILD, or LASTCHILD clause, the MOVE statement attempts to move the target reference variable in the direction specified relative to its current position. If any field exists in the given direction, the move succeeds. If there is no such field, the move fails; that is the reference variable continues to point to the same field or variable as before, and the LASTMOVE function returns false. You can use the LASTMOVE function to determine the success or failure of a move.

If a TYPE clause, NAME clause, or both are present, the target is again moved in the direction specified (PREVIOUSSIBLING or NEXTSIBLING, or FIRSTCHILD or LASTCHILD) but to a field with the given type, name, or both. This is particularly useful when the name or type (or both) of the target field is known, because this reduces the number of MOVE statements required to navigate to a field. This is because fields that do not match the criteria are skipped over; this can also include unexpected message tree fields, for example, those representing white space.

If the specified move cannot be made (that is, a field with the given type or name does not exist), the target remains unchanged and the LASTMOVE function returns false. The TYPE clause, NAME clause, or both clauses can contain any expression that returns a value of a suitable data type (INTEGER for type and CHARACTER for name). An exception is thrown if the value supplied is NULL.

Two further clauses, NAMESPACE and IDENTITY enhance the functionality of the NAME clause.

The NAMESPACE clause takes any expression that returns a non-null value of type character. It also takes an * indicating any namespace. Note that this cannot be confused with an expression because * is not a unary operator in ESQL.

The meaning depends on the presence of NAME and NAMESPACE clauses as follows:

NAMESPACE	NAME	Element located by...
No	No	Type, index, or both
No	Yes	Name in the default namespace
*	Yes	Name
Yes	No	Namespace
Yes	Yes	Name and namespace

The IDENTITY clause takes a single path element in place of the TYPE, NAMESPACE, and NAME clauses and follows all the rules described in the topic for field references (see ESQL field reference overview).

When using MOVE with PREVIOUSSIBLING or NEXTSIBLING, you can specify REPEAT, TYPE, and NAME keywords that move the target to the previous or next field with the same type and name as the current field. The REPEAT keyword is particularly useful when moving to a sibling of the same kind, because you do not have to write expressions to define the type and name.

Example

MOVE cursor FIRSTCHILD TYPE Name NAME 'Field1';

This example moves the reference variable cursor to the first child field of the field to which the cursor is currently pointing, that has the type Name and the name Field1.

See FIELDTYPE function for a list of the types you can use.

The MOVE statement never creates new fields.

A common usage of the MOVE statement is to step from one instance of a repeating structure to the next. The fields within the structure can then be accessed by using a relative field reference. For example:

WHILE LASTMOVE(sourceCursor) DO
  SET targetCursor.ItemNumber  = sourceCursor.item;
  SET targetCursor.Description = sourceCursor.name;
  SET targetCursor.Price       = sourceCursor.prc;
  SET targetCursor.Tax         = sourceCursor.prc * 0.175;
  SET targetCursor.quantity    = 1;
  CREATE NEXTSIBLING OF targetCursor AS targetCursor REPEAT;
  MOVE sourceCursor NEXTSIBLING REPEAT TYPE NAME;
END WHILE;

For more information about reference variables, and an example of moving a reference variable, see Creating dynamic field references.

ak05090_.htm |

Last updated Friday, 21 July 2017