Accessing known multiple occurrences of an element

When you refer to or create the content of messages, it is very likely that the data contains repeating fields. If you know how many instances there are of a repeating field, and you want to access a specific instance of such a field, you can use an array index as part of a field reference.

For example, you might want to filter on the first line of an address, to expedite the delivery of an order. Three instances of the element Billling.Address are always present in the sample message. To test the first line, write an expression such as:

IF Body.Invoice.Customer.Billing.Address[1] = 'Patent Office' THEN
   DO;
     -- more ESQL --
END IF;   

The array index [1] indicates that it is the first instance of the repeating field that you are interested in (array indices start at 1). An array index such as this can be used at any point in a field reference, so you could, for example, filter on the following test:

IF Body.Invoice."Item"[1].Quantity > 2 THEN
   DO;
     -- more ESQL --
END IF;   

You can refer to the last instance of a repeating field using the special [<] array index, and to instances relative to the last (for example, the second to last) as follows:

You can also use the array index [>] to represent the first element, and elements relative to the first element in a similar way.

The following examples refer to the Invoice message using these indexes:

IF Body.Invoice.Customer.Billing.Address[<] = 'Hampshire' THEN 
      DO;
     -- more ESQL --
END IF;   
IF Body.Invoice.Customer.Billing.Address[<2 ] = 'Southampton' THEN
   DO;
     -- more ESQL --
END IF;   

You can also use these special indexes for elements that repeat an unknown number of times.

Deleting repeating fields

If you pass a message with several repeats of an element through a message flow and you want to delete some of the repeats, be aware that the numbering of the repeats is reordered after each delete. For example, if you have a message with five repeats of a particular element, and in the message flow you have the following ESQL:

SET OutputRoot.MRM.e_PersonName[1] = NULL;
SET OutputRoot.MRM.e_PersonName[4] = NULL;

You might expect elements one and four to be deleted. However, because repeating elements are stored on a stack, when you delete one, the one above it takes its place. This means that, in the above example, elements one and five are deleted. To avoid this problem, delete in reverse order, that is, delete element four first, then delete element one.

Related concepts
Message flows
ESQL
Message modeling

Related tasks
Accessing unknown multiple occurrences of an element
Designing a message flow
Defining message flow content
Managing ESQL files

Related reference
Compute node
Database node
Filter node
ESQL
IF statement
SET statement
Example message