WebSphere Message Brokers
File: ak04864_
Writer: Bill Oppenheimer

Task topic

This build: July 31, 2007 21:31:16

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. 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. 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. 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;

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 examples below 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 FirstName field as follows:

DECLARE myref REFERENCE TO Invoice.Customer;

the value of myref is Andrew. You can extend this dynamic reference as follows:

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:

  1. Copy the input message to the output message.
  2. 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].
  3. Use a create statement to insert a new first item for this purchase.
    CREATE PREVIOUSSIBLING OF ref1 VALUES 'Item'; 
    The dynamic reference is now equivalent to the static reference OutputRoot.XMLNS.Invoice.Purchases.Item[2].
Related concepts
Message flows overview
ESQL overview
Message modeling
Related tasks
Designing a message flow
Defining message flow content
Managing ESQL files
Related reference
Compute node
Database node
Filter node
ESQL reference
DECLARE statement
IF statement
LASTMOVE function
MOVE statement
SET statement
WHILE statement
Example message
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:31:16

ak04864_ This topic's URL is: