XML INTO

XML-INTO

XML-INTO parses an XML string into a data structure or array of data structures. It uses the %XML BIF to specify the data source and parsing options.

Basic Usage

DCL-DS order QUALIFIED;
  id       INT(10);
  customer VARCHAR(50);
  qty      INT(10);
END-DS;

DCL-S xml VARCHAR(500);
xml = '<order><id>1001</id><customer>Acme</customer><qty>25</qty></order>';

XML-INTO order %XML(xml : 'case=any');

DSPLY %CHAR(order.id);        // 1001
DSPLY order.customer;          // Acme
DSPLY %CHAR(order.qty);        // 25

Options

The document must match the variable, as on IBM i; one that does not is an error, status 353 (RNX0353), which MONITOR can catch. The options decide what matching means:

Option	Meaning
case=lower	The default: the XML's names are the RPG names in lower case
case=upper	... in upper case
case=any	... in any case
allowmissing=no	The default: every subfield needs an element (or attribute)
allowmissing=yes	A subfield with no element keeps the value it had
allowextra=no	The default: every element needs a subfield
allowextra=yes	Elements with no subfield are ignored
path=a/b/c	The element to read, from the document's root

Without path, the document's outermost element must be named as the variable. An XML attribute can supply a subfield just as an element can.

PATH Option

Use path= to navigate past wrapper elements:

DCL-DS rec QUALIFIED;
  id   INT(10);
  name VARCHAR(40);
END-DS;

xml = '<response><data><record><id>5</id><name>Alice</name></record></data></response>';

XML-INTO rec %XML(xml : 'case=any path=response/data/record');

DSPLY %CHAR(rec.id);    // 5
DSPLY rec.name;          // Alice

Array Target

Map a repeating XML element into an array DS. path= names the repeated element, from the root, and each one fills one element of the array:

DCL-DS item QUALIFIED DIM(5);
  name  VARCHAR(30);
  qty   INT(10);
  price PACKED(9:2);
END-DS;

xml = '<items>' +
      '<item><name>Widget</name><qty>5</qty><price>19.99</price></item>' +
      '<item><name>Gadget</name><qty>3</qty><price>29.50</price></item>' +
      '</items>';

XML-INTO item %XML(xml : 'case=any path=items/item');

DSPLY (item(1).name + ' qty=' + %CHAR(item(1).qty));   // Widget qty=5
DSPLY (item(2).name + ' qty=' + %CHAR(item(2).qty));   // Gadget qty=3

An array takes as many elements as it has room for, and the rest are ignored: a fixed array its dimension, a DIM(*VAR) array its current number of elements (which XML-INTO leaves unchanged). Use DIM(*AUTO: n) for a variable number: it takes up to n, and its number of elements becomes the number read:

DCL-DS emp QUALIFIED DIM(*AUTO: 50);
  id   INT(10);
  name VARCHAR(40);
END-DS;

XML-INTO emp %XML(xml : 'case=any path=employees/emp');

DSPLY ('Count: ' + %CHAR(%ELEM(emp)));

Nested Data Structures with LIKEDS

DCL-DS address QUALIFIED;
  street VARCHAR(50);
  city   VARCHAR(30);
  state  CHAR(2);
END-DS;

DCL-DS customer QUALIFIED;
  name VARCHAR(50);
  age  INT(10);
  addr LIKEDS(address);
END-DS;

xml = '<customer>' +
        '<name>Alice</name><age>30</age>' +
        '<addr><street>123 Main</street><city>Boston</city><state>MA</state></addr>' +
      '</customer>';

XML-INTO customer %XML(xml : 'case=any');

DSPLY customer.name;           // Alice
DSPLY customer.addr.city;      // Boston
DSPLY customer.addr.state;     // MA