Start of change

Examples of the allowextra option with XML data not corresponding to RPG subfields

The following definitions are used in the examples
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 that file cpyA.xml contains the following lines:
<copyInfo>
 <to><name>MYFILE</name><lib>*LIBL</lib></to>
 <from name="MASTFILE" lib="CUSTLIB"></from>
</copyInfo>
Assume that 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 that file cpyD.xml contains the following lines:
<copyinfo to="MYLIB/MYFILE">
 <from><name>MASTFILE</name><lib>CUSTLIB</lib></from>
</copyinfo>
  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. The XML-INTO operation fails with status 00353 because the to attribute is not expected, and because the to XML element is not found.
      xml-into(e) copyInfo %XML('cpyC.xml' : 'doc=file');
      // %error = *on
      // %status = 353
  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*   '
End of change