オプションを使用して、XML-INTO 命令をカスタマイズできます。 オプションは、%XML 組み込み関数の第 2 パラメーターとして指定します。 パラメーターには定数または変数の式を使用できます。 オプションは、「opt1=val1 opt2=val2」の形式で指定します。
オプションの指定方法について詳しくは、%XML (xmlDocument {:options})を参照してください。
// 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');
XML 文書がファイルにある場合は、ファイル全体のコンテンツが構文解析の開始前に別の CCSID に変換される場合があります。
以下の表には、いくつかのファイルとその CCSID がリストされています。
ファイル | ファイル CCSID | 関連する EBCDIC CCSID |
---|---|---|
file1.xml | 37 | 37 |
file2.xml | 1252 | 37 |
file3.xml | 874 | 838 |
file4.xml | 13488 | (該当なし、UCS-2) |
file5.xml | 1208 | (該当なし、UTF-8) |
以下の表には、ccsid オプションの各値に対してファイルの処理に使用される CCSID が示されています。ここでは、ジョブ CCSID が 37 であると想定しています。 アスタリスクは、ファイルが処理前に別の CCSID に変換されることを示しています。
ファイル | CCSID オプション値 | ||
---|---|---|---|
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* |
XML 文書が変数にある場合、構文解析の開始前に文書全体が別の CCSID に変換される場合があります。
以下の変数定義を想定します。
D chrXml S 100A D ucs2Xml S 100C
以下の表には、「ccsid」オプションの各値に対して変数の処理に使用される CCSID が示されています。ここでは、ジョブ CCSID が 37 であると想定しています。 アスタリスクは、変数内のデータが処理前に別の CCSID に変換されることを示しています。
変数 | CCSID オプション値 | ||
---|---|---|---|
best | job | ucs2 | |
chrXml | 37 | 37 | 13488 |
ucs2Xml | 13488 | 37* | 13488 |
デフォルト: path オプションが指定されない場合、RPG 変数に一致する XML 要素の検索は、変数の型に依存します。
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'
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'
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.
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'
必要な XML データが検出されず、'allowmissing=yes' が指定されていない場合、その命令は状況コード 00353 (XML が RPG 変数と一致しない) で失敗します。
XML-INTO 命令で指定された配列に対し少ない数の配列要素を使用する場合には、'allowmissing=yes' の指定は必要ありません。 XML 文書に含まれる要素の数が RPG 配列より少ない場合、その命令は失敗しません。 PSDS の 372 から 379 桁目にある「XML 要素の数」サブフィールドを使用して、命令により正常に設定される要素の数を判別できます。
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.
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;
予期しない XML データが検出され、'allowextra=yes' が指定されていない場合、その命令は状況コード 00353 (XML が RPG 変数と一致しない) で失敗します。
注意: 非データ構造 XML 要素の XML 属性は、任意の時点で RPG ランタイムによる変換処理の対象になる場合があります。 現在、"fmt" および "adjust" は、一部のターゲット・データ型の場合 に RPG ランタイムによりすでに変換処理されています。 PTF であっても、任意の時点でその他の属性のサポートが追加される場合があります。 現在、ある属性がオプション 'allowextra=yes' で無視されていて、その属性が RPG ランタイムに対して意味がある存在になった場合、それがデータの処理に影響を及ぼすことがあります。
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) = ' '
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* '
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'
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
(C) Copyright IBM Corporation 1992, 2006. All Rights Reserved.