Creating dynamic field references

You can use a variable of type REFERENCE as a dynamic reference to navigate a message tree. This acts in a similar way to a message cursor or a variable pointer.

About this task

It is generally simpler and more efficient to use reference variables in preference to array indexes when you access repeating structures. Reference variables are accepted everywhere that field references are accepted, and come with a set of statements and functions to allow detailed manipulation of message trees.

You must declare a dynamic reference before you can use it. A dynamic reference is declared and initialized in a single statement.

All examples in this topic use the Example message as their input message. The following example shows how to create and use a reference.

-- Declare the dynamic reference
DECLARE myref REFERENCE TO OutputRoot.XMLNS.Invoice.Purchases.Item[1];

--  Continue processing for each item in the array
WHILE LASTMOVE(myref)=TRUE 
DO
-- Add 1 to each item in the array
   SET myref = myref + 1;
-- Move the dynamic reference to the next item in the array
   MOVE myref NEXTSIBLING;
END WHILE;

The example works if the message tree was created with typed fields, based on a message model for the Example message. If this is not the case, you can modify the ESQL to work without a model, for example:

SET myref = CAST (myref AS INTEGER) + 1;

This example declares a dynamic reference, myref, which points to the first item in the array within Purchases. The value in the first item is incremented by one, and the pointer (dynamic reference) is moved to the next item. Once again the item value is incremented by one. This process continues until the pointer moves outside the scope of the message array (all the items in this array have been processed) and the LASTMOVE function returns FALSE.

The following examples show further examples.

DECLARE ref1 REFERENCE TO InputBody.Invoice.Purchases.Item[1];

DECLARE ref2 REFERENCE TO 
	InputBody.Invoice.Purchases.NonExistentField;

DECLARE scalar1 CHARACTER;
DECLARE ref3 REFERENCE TO scalar1;

In the second example, ref2 is set to point to InputBody because the specified field does not exist.

With the exception of the MOVE statement, which changes the position of the dynamic reference, you can use a dynamic reference anywhere that you can use a static reference. The value of the dynamic reference in any expression or statement is the value of the field or variable to which it currently points. For example, using the message in Example message, the value of Invoice.Customer.FirstName is Andrew. If the dynamic reference myref is set to point at the Customer field as follows:

DECLARE myref REFERENCE TO Invoice.Customer;

you can then extend this dynamic reference to address children of that field:

SET myref.Billing.Address[1] = 'Oaklands';

This changes the address in the example to Oaklands Hursley Village Hampshire SO213JR.

The position of a dynamic reference remains fixed even if a tree is modified. To illustrate this point the steps that follow use the message in Example message as their input message and create a modified version of this message as an output message:

Procedure

Copy the input message to the output message.
To modify the output message, first declare a dynamic reference ref1 that points at the first item, The XML Companion.
```
DECLARE ref1 REFERENCE TO 
	OutputRoot.XMLNS.Invoice.Purchases.Item[1];
```
The dynamic reference is now equivalent to the static reference OutputRoot.XMLNS.Invoice.Purchases.Item[1].
Use a create statement to insert a new first item for this purchase.
```
CREATE PREVIOUSSIBLING OF ref1 VALUE 'Item'; 
```
The dynamic reference is now equivalent to the static reference OutputRoot.XMLNS.Invoice.Purchases.Item[2].