%XML options for the XML-INTO operation code

Several options are available for customizing the XML-INTO operation. The options are specified as the second parameter of the %XML built-in function. The parameter can be a constant or a variable expression. The options are specified in the form 'opt1=val1 opt2=val2'.

See %XML (xmlDocument {:options}) for more information on how to specify the options.

The path option specifies where to locate the desired XML element within the XML document.
The doc option specifies whether the first parameter of the %XML built-in function has an XML document, or has the name of a file containing the XML document.
The ccsid option specifies the CCSID to be used to parse the XML document.
The case option specifies whether the names within the XML document are in lower case, upper case, or mixed case.
The trim option specifies whether you want blanks, tabs and line-end characters to be trimmed from the XML data before it is assigned to your RPG variables.
The allow missing option specifies how the RPG runtime should handle the situation when the XML document does not have enough XML elements or XML attributes to provide data for all the RPG subfields of a data structure.
The allow extra option specifies how the RPG runtime should handle the situation when the XML document has additional XML elements or attributes that are not needed to set the RPG variable.
The data subfield option specifies the name of the extra subfield used to handle the situation where there is text data for an XML element that matches an RPG data structure.
The count prefix option specifies the prefix for the names of the additional subfields that receive the number of RPG array elements set by the XML-INTO operation.

doc (default string)

The doc option indicates what the source operand of %XML contains.

string indicates that the source operand contains XML data
file indicates that the source operand contains the name of a file in the Integrated File System

Figure 400. Example of the doc option:

   // In the following example, the first parameter
   // of %XML is the name of a file.  Option
   // "doc=file" must be specified.

   ifsfile = 'myfile.xml';
   opt = 'doc=file';
   XML-INTO myfield %XML(ifsfile : opt);

   // In the following example, the first parameter
   // of %XML is an XML document.  Since the "doc"
   // option defaults to "string", no options are
   // necessary.

   xmldata = '<data><num>3</num></data>';
   XML-INTO data %XML(xmldata);

   // However, "doc=string" may still be specified.

   xmldata = '<data><num>3</num></data>';
   XML-INTO data %XML(xmldata : 'doc=string');

ccsid (default best)

The ccsid option specifies the CCSID to be used for processing the XML document. Some CCSID conversions may be performed during the XML-INTO operation:

CCSID conversion may be required from the XML document to a temporary copy of the XML document, if the CCSID of the XML document differs from the CCSID used for parsing.
CCSID conversion may be required when assigning XML data to an RPG variable, if the CCSID used for parsing differs from the CCSID of the RPG variable.

If the CCSID of the actual document is different from the CCSID to be used for processing the document, CCSID conversion will be done on the entire document before parsing begins. If the CCSID to be used for processing the document is different from the CCSID of an RPG variable, CCSID conversion will be done on the data when it is assigned to the RPG variable.

best indicates that the document should be processed in the CCSID that will best preserve the data in the document. If the document is in the job CCSID or an ASCII CCSID related to the job CCSID, the document will be processed in the job CCSID. Otherwise, the document will be processed in UCS-2 and the data will be converted to the job CCSID before it is assigned to variables with a data type other than UCS-2.
job indicates that the document should be processed in the job CCSID. The data will be converted to UCS-2 when it is assigned to UCS-2 variables.
ucs2 indicates that the document should be processed in UCS-2. The data will be converted to the job CCSID when it is assigned to variables with a data type other than UCS-2.

When the XML document is in a file, the contents of the entire file may be converted to another CCSID before parsing begins.

The following table lists several files and their CCSIDs:

File	File CCSID	Related EBCDIC CCSID
file1.xml	37	37
file2.xml	1252	37
file3.xml	874	838
file4.xml	13488	(N/A, UCS-2)
file5.xml	1208	(N/A, UTF-8)

The following table shows the CCSID that would be used for processing these files for each value of the ccsid option, assuming the job CCSID is 37. An asterisk indicates that the file is converted to a different CCSID before processing:

File	CCSID Option Value
File	`best`	`job`	`ucs2`
file1.xml	37	37	13488*
file2.xml	37*	37*	13488*
file3.xml	13488*	37*	13488*
file4.xml	13488	37*	13488
file5.xml	13488*	37*	13488*

When the XML document is in a variable, the entire document may be converted to a different CCSID before parsing begins.

Given the following variable definitions:

       D chrXml          S            100A
       D ucs2Xml         S            100C

The following table shows the CCSID that would be used for processing these variables for each value of the "ccsid" option, assuming the job CCSID is 37. An asterisk indicates that the data in the variable is converted to a different CCSID before processing.

Variable	CCSID Option Value
Variable	`best`	`job`	`ucs2`
chrXml	37	37	13488
ucs2Xml	13488	37*	13488

path

The path option specifies the path to the element as it appears in the XML document, with elements separated by forward slashes. For example, if this option is path=main/info/name, the parser will expect the document element to be "main", a child of "main" to be "info", and a child of "info" to be "name". If no element can be found, the operation will fail with status 00353 (XML does not match RPG variable).

Note:

The value of the "allowmissing" option has no effect on this situation.

Note:

The path option is required when %HANDLER is used to specify an array-handling procedure.

Default: When the path option is not specified, the search for the XML element matching the RPG variable depends on the type of the variable.

For non-array variables, the outermost XML element is expected to have the |same name as the RPG variable.
For array variables, the outermost XML element is expected to have child elements with the same name as the RPG array variable. The outermost XML element can have any name.

Notes:

If the variable is a qualified subfield, only the name of the subfield is used in determining the path to the XML variable. For example, if the variable is DS.SUB1, the default is to expect the outermost XML element to be called "sub1".
The path specified by this option is case sensitive. It must be in the same case as the matching elements in the XML document unless the case option is also specified.

Figure 401. Examples of the path option with non-array variables:


D info            DS
D   num                          5P 2

D xmlDoc          S           1000A    VARYING

D qualDs          DS                   QUALIFIED
D   subf                        10A

 /free
  // 1. Specifying a different name for the XML element

  xmlDoc = '<myinfo><num>123.45</num></myinfo>';
  xml-into info %XML(xmlDoc : 'path=myinfo');
  // num now has the value 123.45

  // 2. Neglecting to specify a different name for the XML
  //    element causes the operation to fail

  xmlDoc = '<myinfo><num>456.1</num></myinfo>';
  xml-into info %XML(xmlDoc');
  // The XML-INTO operation fails with status 00353 because the
  // document does not contain the "info" element

  // 3. Specifying that the XML element is not the outermost
  //    element in the document

  xmlDoc = '<data><info><num>-789</num></info></data>';
  xml-into info %XML(xmlDoc : 'path=data/info');
  // num now has the value -789

  // 4. Parsing into a subfield where the data structure is
  //    represented by the XML.  The full path to the "num"
  //    XML element must be specified.

  xmlDoc = '<data><info><num>.3</num></info></data>';
  xml-into num %XML(xmlDoc :
                    'path=data/info/num');
  // num now has the value .3

  // 5. Specifying the "path" option with XML from a file
  //    Assume file myfile.xml contains the following lines:
  //      <?xml version='1.0' ?>
  //      <data>
  //       <val>17</val>
  //      </data>

  xml-into num %XML('myfile.xml' : 'doc=file path=data/val');
  // num now has the value 17

  // 6. Specifying a qualified subfield without the "path"
  //    option.

  xmlDoc = '<subf>-987.65</subf>';
  xml-into qualDs.subf %XML(xmlDoc);
  // qualDs.subf now has the value '-987.65'

  // 7. Specifying a qualified subfield with the "path"
  //    option.
  //    Note that the default path for a qualified subfield
  //    is the subfield name; in this XML document, the
  //    XML element for the subfield is a child element
  //    of another XML element so the 'path' option must
  //    be specified, and it must include the names of all
  //    the ML elements in the path to the required XML
  //    element, including the XML element containing the
  //    data to set the variable.

  xmlDoc = '<qualds><subf>-987.65</subf></qualds>';
  xml-into qualDs.subf %XML(xmlDoc :
                     'path=qualds/subf);
  // qualDs.subf now has the value '-987.65'

Figure 402. Examples of the path option with array variables:


D loc             DS                   DIM(2)
D   city                        20A    VARYING
D   prov                         2A
D arr             S              5I 0  DIM(3)
D xmlDoc          S           1000A    VARYING

 /free
  // 1. Parsing an array from a string where the
  //    string contains array elements. The XML
  //    elements matching the RPG array elements
  //    are children of an XML element "outer".
  //    The "path" option is not needed because
  //    XML elements with the name "arr" are
  //    expected to be child elements of the
  //    outermost XML element.

  xmlDoc = '<outer>'
              + '<arr>3</arr>'
              + '<arr>4</arr>'
              + '<arr>-2</arr>'
              + '</outer> ;
  xml-into arr %XML(xmlDoc);
  // arr(1) = 3
  // arr(2) = 4
  // arr(3) = -2

  // 2. Parsing a DS array from a file where the
  //    file contains array elements with a
  //    container XML element.  The "path" option
  //    is not needed.  The name of the outermost element
  //    does not matter.
  //    Assume file myarray.xml contains the following lines:
  //      <locations>
  //       <loc><city>Saskatoon</city><prov>SK</prov></loc>
  //       <loc><city>Regina</city><prov>SK</prov></loc>
  //      </locations>

  xml-into loc %XML('myarray.xml' : 'doc=file');
  // loc(1).city = 'Saskatoon'  loc(2).city = 'Regina'
  // loc(1).prov = 'SK'         loc(2).prov = 'SK'

  // 3. Parsing a DS array where the XML elements have
  //    a different name from the array name.  The
  //    "path" option specifies the full path to the
  //    XML elements, including the container element
  //    "data".
  //    Assume file mydata.xml contains the following lines:
  //      <data>
  //       <where><city>Edmonton</city><prov>AB</prov></where>
  //       <where><city>Toronto</city><prov>ON</prov></where>
  //      </data>


  xmlfile = 'mydata.xml';
  xml-into loc %XML(xmlfile : 'path=data/where doc=file');
  // loc(1).city = 'Edmonton'   loc(2).city = 'Toronto'
  // loc(1).prov = 'AB'         loc(2).prov = 'ON'

case (default lower)

The case option specifies the case expected for element and attribute names in the XML document when searching for XML data that matches the the RPG field names and the names in the path option. If the XML elements are not in the expected case, they will not be found, and the operation will fail with status 00353 (XML document does not match RPG variable) unless option 'allowmissing=yes' is specified.

lower indicates that the XML element and attribute names matching the RPG variable names are in lower case.
upper indicates that the XML element and attribute names matching the RPG variable names are in upper case.
any indicates that the element and attribute names matching the RPG variable names are in unknown or mixed case. The XML element and attribute names will be converted to upper case before comparison to the upper-case RPG variable names.

Figure 403. Examples of the case option:


D info            DS                   QUALIFIED
D   name                        10A
D   id_no                        5A
D xmlDoc          S           1000A    VARYING

 /free
  // 1. The XML document uses lowercase for element names and
  //    attributes.  The "case" option defaults to lowercase
  //    so it is not needed.

  xmlDoc = '<info><name>Jim</name><id_no>103</id_no></info>';
  xml-into info %XML(xmlDoc);
  // info.name = 'Jim       '
  // info.id_no = '103'

  // 2. The XML document uses uppercase for element names and
  //    attributes.  Option "case=upper" must be specified.

  xmlDoc = '<INFO><NAME>Bill</NAME><ID_NO>104</ID_NO></INFO>';
  xml-into info %XML(xmlDoc : 'case=upper');
  // info.name = 'Bill      '
  // info.id_no = '104'

  // 3. The XML document uses mixed case for element names and
  //    attributes.  Option "case=any" must be specified.

  xmlDoc = '<INFO><name>Tom</name>'
              + '<ID_NO>105</ID_NO></INFO>';
  xml-into info %XML(xmlDoc : 'case=any');
  // info.name = 'Tom       '
  // info.id_no = '104'

  // 4. The XML document uses mixed case for element names and
  //    attributes but the "case" option is not specified.

  xmlDoc = '<INFO><name>Tom</name>'
              + '<ID_NO>105</ID_NO></INFO>';
  xml-into info %XML(xmlDoc);
  // The XML-INTO operation fails with status 00353 because
  // it assumes the XML elements will have lowercase names.

trim (default all)

The trim option specifies whether whitespace (blanks, newlines, tabs etc.) should be trimmed from text data before the data is assigned to RPG variables

all indicates that before text content is assigned to the RPG character or UCS-2 variable, the following steps will be done:
1. Leading and trailing whitespace will be trimmed completely from text content
2. Strings of interior whitespace in the text content will be reduced to a single blank
none indicates that no whitespace will be trimmed from text content. This option will have the best performance, but it should only be used if the whitespace is wanted, or if the XML data is known to contain no unwanted whitespace, or if the RPG program is going to handle the removal of the whitespace itself.

Notes:

Whitespace includes blank, tab, end-of-line, carriage-return, and line-feed.
This option applies only to XML data that is to be assigned to character and UCS-2 RPG variables. Trimming of whitespace is always done for other data types.
This option is mainly provided for XML data from files, but it also applies to XML data from a variable.
Whitespace between XML elements is always ignored. The trim option controls the whitespace within text content of elements and attributes.

Figure 404. Examples of the trim option:


D data            S            100A    VARYING
 //    Assume file data.xml contains the following lines:
 //      <text>
 //          line1
 //          line2
 //      </text>
 //
 //    Here is another view of this same file where
 //          '_' represents a blank
 //          'T' represents a tab
 //          'F' represents a line-feed
 //      <text>____F
 //      Tline1F
 //      ____line2F
 //      </text>F

 /free
  // 1. The default of "trim=all" is used.  Leading and
  //    trailing whitespace is removed.  Strings of
  //    internal whitespace is changed to a single blank.

  xml-into data %XML('data.xml' : 'doc=file');
  // data = 'line1 line2'

  // 2. Option "trim=none" is specified.  No whitespace
  //    is trimmed from text data.

  xml-into data %XML('data.xml' : 'doc=file trim=none');
  // The following line shows the value of data with the
  // line-feed and tab characters shown as ?.
  // data = '    ??line1?    line2?'
  // The following line shows the value of data with the
  // blanks, line-feed and tab characters shown as in the
  // second view of the document.
  // data = '____FTline1F____line2F'

allowmissing (default no)

For the situation where the XML document does not have sufficient XML elements or attributes for the subfields of an RPG data structure, you can use the allowmissing option to indicate whether this is considered an error. XML data is considered to be missing in the following circumstances:

For an XML element matching an RPG data structure (including a data structure subfield), if the XML element does not have attributes or child elements for all RPG subfields.
For XML data matching an array subfield of an RPG data structure, if the number of XML elements is less than the dimension of the RPG subfield array.

If expected XML data is not found, and 'allowmissing=yes' is not specified, the operation will fail with status 00353 (XML does not match RPG variable).

Tip: The countprefix option can also be used to handle the situation where the XML document might not have sufficient XML data for every subfield in the data structure.

To allow fewer array elements for the array specified on the XML-INTO operation, it is not necessary to specify 'allowmissing=yes'. If the XML document contains fewer elements than the RPG array, the operation will not fail. The "Number of XML Elements" subfield in positions 372 - 379 of the PSDS can be used to determine the number of elements successfully set by the operation.

no indicates that XML data must be present for every subfield of a data structure (including subfields of data structure subfields), and XML data must be present for every element of every subfield array.
yes indicates that when XML data is not present for every subfield and subfield array element, the operation will not fail. If a variable is specified as the first operand of XML-INTO, the unset subfields will hold the same value they held before the operation. If %HANDLER is specified as the first operand of XML-INTO, the unset subfields of the array passed to the handling procedure will have the default value for the type (zero for numeric values, *LOVAL for date values and so on).

Figure 405. Examples of the allowmissing option with insufficient data for subfield arrays:


D employee        DS                   QUALIFIED
D   name                        10A    VARYING
D   type                        10A

D empInfo3        DS                   QUALIFIED
D   emp                                LIKEDS(employee)
D                                      DIM(3)

D empInfo2        DS                   QUALIFIED
D   emp                                LIKEDS(employee)
D                                      DIM(2)

D empInfo4        DS                   QUALIFIED
D   emp                                LIKEDS(employee)
D                                      DIM(4)

 //  Assume file emp.xml contains the following lines:
 //    <employees>
 //     <emp><name>Jack</name><type>Normal</type></emp>
 //     <emp><name>Mary</name><type>Manager</type></emp>
 //     <emp><name>Sally</name><type>Normal</type></emp>
 //   </employees>


 /free
  // 1. The "empInfo3" data structure has an array "emp"
  //    with a dimension of 3.
  //    The "allowmissing" option is not required.
  //    The default of "allowmissing=no" can be used, since
  //    the XML document exactly matches the data structure.

  xml-into empInfo3 %XML('emp.xml' :
                         'doc=file path=employees');
  // empInfo3.emp(1)    .name = 'Jack'    .type = 'Normal'
  // empInfo3.emp(2)    .name = 'Mary'    .type = 'Manager'
  // empInfo3.emp(3)    .name = 'Sally'   .type = 'Normal'

  // 2. Option "allowmissing=no" may be specified, however.

  xml-into empInfo3 %XML('emp.xml' :
                         'doc=file ' +
                         'allowmissing=no path=employees');
  // empInfo3.emp(1)    .name = 'Jack'    .type = 'Normal'
  // empInfo3.emp(2)    .name = 'Mary'    .type = 'Manager'
  // empInfo3.emp(3)    .name = 'Sally'   .type = 'Normal'

  // 3. Option "allowmissing=yes" must be specified with
  //    data structure "empInfo4", since the XML document
  //    has only three "emp" XML elements, and the RPG "emp"
  //    array has four elements.

  xml-into empInfo4
           %XML('emp.xml' : 'doc=file ' +
                        'allowmissing=yes path=employees');
  // empInfo4.emp(1)    .name = 'Jack'    .type = 'Normal    '
  // empInfo4.emp(2)    .name = 'Mary'    .type = 'Manager   '
  // empInfo4.emp(3)    .name = 'Sally'   .type = 'Normal    '
  // empInfo4.emp(4)    .name = ''        .type = '          '

  // 4. Option "allowmissing" is not specified for data
  //    structure "empInfo4"

  xml-into empInfo4 %XML('emp.xml' :
                         'doc=file path=employees');
  // The XML-INTO operation fails with status 00353 because
  // the XML document does not have enough "emp" elements
  // for the RPG array.

Figure 406. Examples of the allowmissing option with insufficient data for all subfields:


D qualName        DS                   QUALIFIED
D   name                        10A
D   lib                         10A

D copyInfo        DS                   QUALIFIED
D   from                               LIKEDS(qualName)
D   to                                 LIKEDS(qualName)

 //    Assume file cpyA.xml contains the following lines:
 //      <?xml version='1.0' ?>
 //      <copyInfo>
 //       <to><name>MYFILE</name><lib>*LIBL</lib></to>
 //       <from name="MASTFILE" lib="CUSTLIB"></from>
 //      </copyInfo>

 //    Assume file cpyB.xml contains the following lines:
 //      <copyInfo>
 //       <from><name>MASTER</name><lib>PRODLIB</lib></from>
 //       <to><name>MYCOPY</name></to>
 //      </copyInfo>


 /free
  // 1. Data structure "copyInfo" has two subfields, "from"
  //    and "to".  Each of these subfields has two subfields
  //    "name" and "lib".  File "cpyA.xml" exactly matches
  //    the "copyInfo" structure, so the "allowmissing" option
  //    is not needed.

  xml-into copyInfo %XML('cpyA.xml' : 'doc=file');
  // copyInfo.from  .name = 'MASTFILE  ' .lib = 'CUSTLIB   '
  // copyInfo.to    .name = 'MYFILE    ' .lib = '*LIBL     '

  // 2. File "cpyB.xml" is missing the "lib" subfield from
  //    the XML element "copyinfo.to".  Option
  //    "allowmissing=yes" must be specified to allow
  //    a subfield to be missing from the XML document.
  //    The copyInfo structure is cleared before the
  //    operation so the program can determine
  //    which subfields were not assigned any data.

  clear copyInfo;
  xml-into copyInfo %XML('cpyB.xml'
                     : 'doc=file allowmissing=yes');
  // copyInfo.from  .name = 'MASTER    ' .lib = 'PRODLIB   '
  // copyInfo.to    .name = 'MYCOPY    ' .lib = '          '
  //
  // The RPG program inspects the data to see if any subfields
  // have not been set.

  if copyInfo.from.lib = *blanks;
    copyInfo.from.lib = '*LIBL';
  endif;
  if copyInfo.to.lib = *blanks;
    copyInfo.to.lib = '*LIBL';
  endif;

allowextra (default no)

For the situation where the XML document has XML elements or attributes that are not needed for assignment to the subfields of an RPG data structure, you can use the allowextra option to indicate whether this is considered an error. XML data is considered to be extra in the following circumstances:

For XML data matching an RPG data structure, if non-whitespace text content is found.
For XML data matching an array subfield of an RPG data structure, if the number of XML elements is greater than the dimension of the RPG subfield array.
For XML data matching a RPG scalar variable (neither data structure nor unindexed array), if the XML element contains child elements or attributes, other than the special formatting attributes allowed for some data types (see Rules for transferring XML data to RPG variables).

If unexpected XML data is found, and 'allowextra=yes' is not specified, the operation will fail with status 00353 (XML does not match RPG variable).

Warning: At any time, XML attributes for non-data-structure XML elements elements may be subject to interpretation by the RPG runtime. Currently, "fmt" and "adjust" are already being interpreted by the RPG runtime for some target data types. Support for other attributes may be added at any time, possibly even through PTFs. If an attribute is being ignored by option 'allowextra=yes', and that attribute becomes meaningful for the RPG runtime, it may affect the handling of the data.

no indicates that the XML elements used to set the RPG variable or array elements must contain only the data necessary to set the variable.
yes indicates that additional XML data will be ignored.

Figure 407. Examples of the allowextra option with extra elements for a subfield array:


D employee        DS                   QUALIFIED
D   name                        10A    VARYING
D   type                        10A

D empInfo2        DS                   QUALIFIED
D   emp                                LIKEDS(employee)
D                                      DIM(2)

D empInfoAway     DS                   QUALIFIED
D   emp                                LIKEDS(employee)
D                                      DIM(2)
D   away                        10A    DIM(2)

 //  Assume file emp.xml contains the following lines:
 //    <employees>
 //     <emp><name>Jack</name><type>Normal</type></emp>
 //     <emp><name>Mary</name><type>Manager</type></emp>
 //     <emp><name>Sally</name><type>Normal</type></emp>
 //   </employees>


 /free

  // 1. Option "allowextra=yes" must be specified with
  //    data structure "empInfo2", since the XML document
  //    has three "emp" XML elements, and the RPG "emp"
  //    array only has two elements.

  xml-into empInfo2
           %XML('emp.xml'
              : 'doc=file allowextra=yes path=employees');
  // empInfo2.emp(1)    .name = 'Jack'    .type = 'Normal'
  // empInfo2.emp(2)    .name = 'Mary'    .type = 'Manager'

  // 2. Option "allowextra" is not specified for data structure
  //    "empInfo2"

  xml-into empInfo2
           %XML('emp.xml' : 'doc=file path=employees');
  // The XML-INTO operation fails with status 00353 because
  // the XML document has too many "emp" elements for the
  // RPG array.

  // 3. Structure "empInfoAway" requires 2 "emp" elements and
  //    2 "away" elements.  The XML document contains
  //    3 "emp" elements and zero "away" elements.
  //    Option "allowextra=yes allowmissing=yes" is specified,
  //    so the operation will succeed with any number of
  //    "emp" and "away" XML elements.  The extra "emp"
  //    element and missing "away" elements will be ignored.

  xml-into empInfoAway
           %XML('emp.xml' : 'allowextra=yes ' +
                            'allowmissing=yes ' +
                            'path=employees ' +
                            'doc=file');
  // empInfoSite.emp(1)  .name = 'Jack'    .type = 'Normal'
  // empInfoSite.emp(2)  .name = 'Mary'    .type = 'Manager'
  // empInfoSite.away(1) = ' '
  // empInfoSite.away(2) = ' '

Figure 408. Examples of the allowextra option with XML data not corresponding to RPG subfields:


D qualName        DS                   QUALIFIED
D   name                        10A
D   lib                         10A

D copyInfo        DS                   QUALIFIED
D   from                               LIKEDS(qualName)
D   to                                 LIKEDS(qualName)

D copyInfo3       DS                   QUALIFIED
D   from                               LIKEDS(qualName)
D   to                                 LIKEDS(qualName)
D   create                       1N

 //    Assume file cpyA.xml contains the following lines:
 //      <copyInfo>
 //       <to><name>MYFILE</name><lib>*LIBL</lib></to>
 //       <from name="MASTFILE" lib="CUSTLIB"></from>
 //      </copyInfo>

 //    Assume file cpyC.xml contains the following lines:
 //      <copyinfo errors="tolerate">
 //       <to><name>MYFILE</name><lib>MYLIB</lib></to>
 //       <from><name>MASTFILE</name><lib>CUSTLIB</lib></from>
 //       <to><name>MYFILE2</name></to>
 //      </copyinfo>

 //    Assume file cpyD.xml contains the following lines:
 //      <copyinfo to="MYLIB/MYFILE">
 //       <from><name>MASTFILE</name><lib>CUSTLIB</lib></from>
 //      </copyinfo>


 /free
  // 1. Data structure "copyInfo" has two subfields, "from"
  //    and "to".  Each of these subfields has two subfields
  //    "name" and "lib".  File "cpyA.xml" exactly matches
  //    the "copyInfo" structure, so the "allowextra" option
  //    is not needed, since "allowextra" defaults to "yes".


  xml-into copyInfo %XML('cpyA.xml' : 'doc=file');
  // copyInfo.from  .name = 'MASTFILE  ' .lib = 'CUSTLIB   '
  // copyInfo.to    .name = 'MYFILE    ' .lib = '*LIBL     '

  // 2. File "cpyC.xml" has an XML attribute for the
  //    for the XML element "copyinfo" that does not
  //    match an RPG subfield.  It also has the
  //    "to" subfield specified more than once.  Option
  //    "allowextra=yes" must be specified to allow
  //    extra subfields in the XML document.
  //    The extra XML data will be ignored.

  xml-into copyInfo
           %XML('cpyC.xml' : 'doc=file allowextra=yes');
  // copyInfo.from  .name = 'MASTFILE  ' .lib = 'CUSTLIB   '
  // copyInfo.to    .name = 'MYFILE    ' .lib = 'MYLIB     '

  // 3. Data structure copyInfo3 has a subfield
  //    "create" that does not appear file "cpyC.xml".
  //    "cpyC.xml" has both missing and extra subfields
  //    for data structure "copyInfo3".
  //    Options "allowextra=yes allowmissing=yes" must
  //    both be specified.
  //    The extra subfields will be ignored and the
  //    missing subfield will retain its original value.

  clear copyInfo3;
  xml-into copyInfo3
           %XML('cpyC.xml' : 'allowextra=yes ' +
                             'allowmissing=yes ' +
                             'doc=file' +
                             'path=copyinfo');
  // copyInfo3.from  .name = 'MASTFILE  ' .lib = 'CUSTLIB   '
  // copyInfo3.to    .name = 'MYFILE    ' .lib = 'MYLIB     '
  // copyInfo3.create = '0' (from the CLEAR operation)

  // 4. File "cpyD.xml" has an XML element "copyInfo"
  //    with an attribute "to".  Subfields can be specified
  //    by attributes only when the subfield is neither
  //    an array nor a data structure.

  xml-into copyInfo %XML('cpyC.xml' : 'doc=file');
  // The XML-INTO operation fails because the "to" attribute
  // is not expected, and because the "to" XML element is
  // not found.

  // 5. Options "allowextra=yes allowmissing=yes" are
  //    specified, allowing the extra "to" attribute to be
  //    ignored and the missing "to" element to be tolerated.
  //    The "to" subfield is not changed by the XML-INTO
  //    operation.

  copyInfo.to.name = '*UNSET*';
  copyInfo.to.lib = '*UNSET*';
  xml-into copyInfo %XML('cpyD.xml' : 'doc=file ' +
                    'allowextra=yes allowmissing=yes');
  // copyInfo.from  .name = 'MASTFILE  ' .lib = 'CUSTLIB   '
  // copyInfo.to    .name = '*UNSET*   ' .lib = '*UNSET*   '

Figure 409. Examples of the allowextra option with unexpected text content for a data structure:


D part            DS
D   size                        10A

 //    Assume file part.xml contains the following lines:
 //      <?xml version='1.0' ?>
 //       <part>light bulb<size>medium</size></part>

 /free
  // 1. "part" is a data structure.  The XML file
  //    part.xml has an element called "part" with
  //    both element and text children

  xml-into part %XML('part.xml' : 'doc=file');
  // The XML-INTO operation fails because the "part" XML
  // element has text content ("light bulb"),
  // and the "allowextra" option defaults to "no".

  // 2. "allowextra=yes" is specified, allowing the
  //    text content to be ignored

  xml-into part %XML('part.xml' : 'doc=file allowextra=yes');
  // size = 'medium'

Figure 410. Examples of the allowextra option with unexpected non-text content for a scalar variable or subfield:


D text            S            200A    VARYING

D order           DS                   QUALIFIED
D   part                        25A    VARYING
D   quantity                    10I 0

 //    Assume file txt.xml contains the following lines:
 //      <?xml version='1.0' ?>
 //      <text><word>Hello</word><word>World</word></text>

 //    Assume file ord.xml contains the following lines:
 //      <?xml version='1.0' ?>
 //      <order>
 //       <part>Jack in a box<discount>yes</discount></part>
 //       <quantity multiplier="10">2</quantity>
 //      </order>


 /free
  // 1. "text" is a standalone variable.  The XML file
  //    txt.xml has an element called "text" with two
  //    child elements called "word".

  xml-into text %XML('txt.xml' : 'doc=file');
  // The XML-INTO operation fails because the "text" XML
  // element has child elements, and the "allowextra"
  // option defaults to "no".

  // 2. "allowextra=yes" is specified.  The child elements
  //    are ignored.

  xml-into text %XML('txt.xml' : 'allowextra=yes doc=file';
  // The XML-INTO operation succeeds, but since the
  // only content for the "text" XML element is the child
  // XML elements, no data is available for RPG field "text".
  //   text = ''

  // 3. "order" is a data structure with two subfields
  //    which are not themselves data structures.
  //    The XML elements representing the subfields
  //    should not have child elements or attributes, but the
  //    "part" XML element does have one child, "discount",
  //    and the "quantity" XML element has an attribute
  //    "multiplier".  Option "allowextra=yes" is specified,
  //    so the "discount" element and "multiplier" attribute
  //    are ignored.

xml-into order %XML('ord.xml' : 'doc=file allowextra=yes');
  // order.part = "Jack in a box"
  // order.quantity = 2

datasubf

The datasubf option specifies the name of the extra scalar subfield used to handle the situation where there is text data for an XML element that matches an RPG data structure.

For example, if this option is specified as datasubf=txt, and an RPG data structure has a scalar subfield with name txt, then that subfield will receive the text data for the XML element matching the data structure.

Default: When the datasubf option is not specified, XML elements matching RPG data structures cannot have text data. Text data can only be associated with the subfields of the data structure.

Notes:

When an RPG data structure has a scalar subfield whose name is specified by the datasubf option, the following rules apply:
- If the matching XML element has text data, that text data will be assigned to the scalar subfield.
- The values for all the other subfields of the data structure must be set by XML attributes. Therefore, the XML element cannot have any child elements, and the other subfields of the data structure must all be scalar subfields.
- The XML element matching the data structure cannot have an XML attribute or child XML element with the same name as the datasubf option.
- If the XML element does not have any text data, the datasubf subfield will be set to an empty value. If the datatype of the subfield does not support the empty value, for example numeric and date types, assigning the subfield will result in an exception.
When an RPG data structure does not have a scalar subfield whose name is specified by the datasubf option, the datasubf option is ignored for that data structure. The XML element matching the RPG data structure cannot have text data.
When an RPG data structure has an array or data structure subfield whose name is the same as the name specified by the datasubf option, the datasubf option is ignored for that data structure. The XML element matching the RPG data structure cannot have text data.
A complex RPG data structure may have many data structure subfields. The datasubf option is considered separately for each data structure subfield. The XML data for one data structure subfield might require the datasubf option for the XML-INTO operation to complete successfully, while another data structure subfield might not require it.
A datasubf subfield cannot be the same as a countprefix subfield. For example, if countprefix=num_ was specified, and the data structure has subfields arr and num_arr, then num_arr is a countprefix subfield. Option datasubf=num_arr cannot also be specified for this data structure.

Figure 411. Examples of the datasubf option:

D customer        ds                  qualified
D    id                         10a
D    value                     100a   varying

D order           ds                  qualified
D    id                         10a
D    type                       10a

D customers       ds                  qualified
D    customer                         likeds(customer) dim(2)

D orderinfo       ds                  qualified
D    customer                         likeds(customer)
D    order                            likeds(order)
 /free

  // 1. The datasubf option specifies the "value" subfield.
  //
  //    Assume file customer1.xml contains the following
  //    <customer id="A34R27K">John Smith</customer>

  //    When XML-INTO encounters "John Smith", it is
  //    processing the "customer" data structure.  It
  //    finds that the "customer" data structure has a
  //    subfield called "value", so it uses that subfield
  //    for the "John Smith" data.
  xml-into customer %xml('customer1.xml'
                       : 'doc=file datasubf=value');
  // customer.id = "A34R27K"
  // customer.value = "John Smith"

  // 2. The datasubf option is not specified.
  //
  //    Assume file customer2.xml contains the following
  //    <customer id="A34R27K">John Smith</customer>

  //    When XML-INTO encounters "John Smith", it is
  //    processing the "customer" data structure.  XML-INTO
  //    does not normally support having data for a data
  //    structure, so the XML-INTO operation fails due to
  //    extra XML data.
  xml-into(e) customer %xml('customer2.xml'  
                          : 'doc=file');
  // %error = *on

  // 3. The XML document has an ordinary XML element
  //    whose name is the same as the datasubf option.
  //
  //    Assume file customer3.xml contains the following
  //    <customer id="A34R27K">
  //       <value>John Smith</value>
  //    </customer>

  // The datasubf option is not specified.
  // The XML document has an ordinary XML element called
  // "value", so the "value" subfield of the "customer"
  // data structure is filled in the usual way.
  // The datasubf option is not needed.
  xml-into customer %xml('customer3.xml' : 'doc=file');
  // customer.id = "A34R27K"
  // customer.value = "John Smith"

  // The datasubf=value option is specified.
  // The XML document has an ordinary XML element called
  // "value".  The XML-INTO operation fails because a
  // scalar subfield with the name of the datasubf option
  // cannot be filled by an XML attribute or an XML element.
  xml-into(e) customer %xml('customer3.xml'
                          : 'doc=file datasubf=value');
  // %error = *on

  // 4. For a complex data structure, the datasubf option
  //    is sometimes needed, and sometimes not needed.
  //
  //    Assume file customer4.xml contains the following
  //    <orderinfo>
  //      <customer id="A34R27K">John Smith</customer>
  //      <order id="P8H41"><type>telephone</type></order>
  //    </orderinfo>

  // The datasubf=value option is specified.
  // The "customer" data structure subfield has a "value"
  // subfield so the datasubf option is used.
  // The "order" data structure subfield does not have a
  // "value" subfield, so the datasubf option is ignored.
  xml-into orderinfo %xml('customer4.xml'
                        : 'doc=file datasubf=value');
  // orderinfo.customer.id = "A34R27K"
  // orderinfo.customer.value = "John Smith"
  // orderinfo.order.id = "P8H41"
  // orderinfo.order.type = "telephone"

countprefix

The countprefix option specifies the prefix for the subfields that can receive the number of elements that were set by an XML-INTO operation for a subfield array. The name of the count subfield is formed by adding the array name to the countprefix value. For example, if a data structure has a subfield array meeting.attendees, and countprefix=num was specified, the XML-INTO operation would set meeting.numattendees to the actual number of elements of the meeting.attendees array that were set by the XML-INTO operation. In the subsequent discussion of the countprefix option, subfield meeting.numattendees is referred to as the countprefix subfield and meeting.attendees is referred to as the counted subfield.

The processing for the countprefix option is done after the XML data for a data structure or data structure subfield has been parsed.

Notes:

A countprefix subfield must be numeric, and it must be scalar; that is, it cannot be an array or a data structure. If a subfield has a countprefix name, but is not numeric or scalar, that subfield will be processed normally; it will not be considered to be a countprefix subfield.
A counted subfield can be any type of subfield; it is not required to be an array. If a counted subfield is not an array, its countprefix subfield will be set to 0 (zero) if there is no XML data to set the subfield, and it will be set to 1 (one) if there is XML data to set it.
When a subfield is counted by a countprefix subfield, the allowmissing option is not considered for that subfield. Option allowmissing=yes is implied for all subfields that are counted by a countprefix subfield.
If there is too much XML data for a subfield, the countprefix subfield will only reflect the number of array elements that were actually set by the XML-INTO operation. For example, if array arr has ten elements, and there is XML data for eleven elements, the countprefix subfield for arr would have the value 10.
If the XML-INTO operation ends in error, the countprefix subfields may not reflect the exact number of RPG subfields that were updated by the XML-INTO operation. The countprefix processing is done after the XML data for each data structure or data structure subfield has been parsed; if an error occurs during parsing, or during the countprefix processing, the countprefix processing would not be completed.
A countprefix subfield is not considered to be countable. For example, if countprefix=num_ was specified, and the data structure has subfields arr, num_arr and num_num_arr, then num_arr would be considered a countprefix subfield for array arr, but num_num_arr would not be considered a countprefix subfield for num_arr.
A countprefix subfield cannot be explicitly set by XML data. Any XML attributes or XML elements that set a countprefix subfield are considered to be extra.
A countprefix subfield cannot be the same as a datasubf subfield. For example, if countprefix=num_ was specified, and the data structure has subfields arr and num_arr, then num_arr is a countprefix subfield. Option datasubf=num_arr cannot also be specified for this data structure.

Figure 412. Examples of the countprefix option:

D attendee_type...                                         
D                 DS                  qualified template   
D   name                        20a   varying              
D   phone                        4s 0                      
                                                           
D meeting         DS                  qualified            
D   location                    20a   varying              
D   attendee                          likeds(attendee_type)
D                                     dim(100)             
D   numAttendee...                                         
D                               10i 0                      

D email           DS                  qualified        
D   to                          40a   varying          
D   cc                          40a   varying          
D   from                        40a   varying          
D   countCc                      5i 0                  
D   subject                    100a   varying          
D   countSubject                 5i 0                  
D   body                      1000a   varying          
                                                       
D order1          DS                  qualified        
D   numpart                     10i 0                  
D   part                        20a   varying dim(100) 
                                                       
D order2          DS                  qualified        
D   numpart                     10i 0                  
D   part                        20a   varying dim(100) 
D   countpart                   10i 0

1. File meeting123.xml:
<meeting>
   <location>Room 7a</location>
   <attendee name="Jim" phone="1234"/>
   <attendee name="Mary" phone="2345"/>
   <attendee name="Abel" phone="6213"/>
</meeting>

 // a. The countprefix option specifies the "num" prefix.
 //
 // The XML-INTO operation sets countprefix subfield
 // "numAttendee" to 3, the number of "attendee" subfields
 // set by the operation.  It is not necessary to 
 // specify option allowmissing=yes, because the 
 // presence of the countprefix subfield for array
 // attendee implictly allows missing XML data for
 // that particular array. 
 xml-into meeting %xml('meeting123.xml'
                  : 'doc=file countprefix=num');
 // meeting.attendee(1):  name='Jim'   phone=1234
 // meeting.attendee(2):  name='Mary'  phone=2345
 // meeting.attendee(3):  name='Abel'  phone=6213
 // meeting.numAttendee = 3 
 for i = 1 to meeting.numAttendee;
    // process meeting.attendee(i)
 endfor;
 
 // b. The countprefix subfield is not specified.
 //
 // The XML-INTO operation fails because there is 
 // insufficient XML data for array "attendee", and
 // there is no XML data at all for "numAttendee" 
 xml-into(e) meeting %xml('meeting123.xml'
                  : 'doc=file');
 // %error is set on
 
2. File email456.txt:
<email to="jack@anywhere.com" from="jill@anywhere.com">
   <subject>The hill</subject>
   <body>How are you feeling after your fall?</body>
</email>

 // countprefix=count is specified.
 //
 // The XML-INTO operation is successful even 
 // though there is no XML data for the cc subfield,
 // because the countprefix subfield "countCc" is
 // available to receive the information that the
 // "cc" subfield did not get set from the XML. 
 xml-into email %xml('email456.xml' 
                   : 'doc=file countprefix=count');
 // email.to = 'jack@anywhere.com'
 // email.from = 'jill@anywhere.com'
 // email.cc = ??  (not set by XML-INTO)
 // email.countCc = 0
 // email.subject = 'The hill'
 // email.countSubject = 1
 // email.body = 'How are you feeling after your fall?' 
 ...
 if email.countCc = 1;
    // process the cc subfield
 endif;
 if email.countSubject = 1;
    // process the subject subfield
 endif;

3. File order789.txt:
<order numpart="2">
   <part>hammer</part>
   <part>saw</part>
</order>

 // The XML document contains an attribute 
 // "numpart" that indicates how many "part"
 // elements there are in the document.

 // a. countprefix=num is specified, attempting
 //    to identify "numpart" as the countprefix
 //    subfield for array "part".
 //
 // The XML-INTO operation fails.  Subfield "numpart"
 // is a countprefix subfield, so it cannot be
 // explicitly set by the XML-INTO operation. 
 xml-into(e) order1 %xml('order789.xml' 
             : 'doc=file countprefix=num path=order');
 // %error is set on

 // b. countprefix=count is specified, identifying
 //    "countpart" as the countprefix subfield for 
 //    array "part".
 //
 // The XML-INTO operation succeeds.  Subfield
 // "numpart" is set to 2 from the XML document,
 // and subfield "countpart" is set to 2 by the
 // countprefix processing.  The "part" array
 // is counted by countprefix, so it is not an
 // error that there is insufficient XML data
 // to set the entire array. 
 xml-into order2 %xml('order789.xml' 
          : 'doc=file countprefix=count path=order');
 // order2.numpart = 2
 // order2.part(1) = 'hammer'
 // order2.part(2) = 'saw'
 // order2.countpart = 2

[ Top of Page | Previous Page | Next Page | Contents | Index ]