XML-INTO (XML 文書の変数への構文解析)

自由形式構文 XML-INTO{(EH)} 受信者 %XML(xmlDoc {: オプション });
XML-INTO{(EH)} %HANDLER(handlerProc : commArea) %XML(xmlDoc {: オプション });
コード 演算項目 1 拡張演算項目 2
XML-INTO 受信者 %XML(xmlDoc {: オプション })
XML-INTO %HANDLER(handlerProc : commArea) %XML(xmlDoc {: オプション })

ヒント: XML および XML 文書の処理の基本概念に ついて十分理解していない場合は、以下のセクションを読み進める前に、 WebSphere Development Studio: ILE RPG プログラマーの手引きのセクション『XML 文書の処理』を参照すると理解に役立ちます。

XML-INTO は、以下の 2 つの方法で作動します。

第 1 オペランドには、構文解析されるデータのターゲットを指定します。 変数名または %HANDLER 組み込み関数を使用できます。

第 2 オペランドは %XML 組み込み関数にする必要があり、構文解析される XML 文書およびその構文解析方法を制御するオプションを識別します。 %XML について詳しくは、%XML (xmlDocument {:options})を参照してください。

第 1 オペランドが変数名である場合は、以下のようになります。

第 1 オペランドが %HANDLER 組み込み関数である場合は、以下のようになります。

データ構造のサブフィールドは、XML 文書内にある順序で設定されます。 その順序は、データ構造内でサブフィールドのオーバーラップがある場合に重要になることがあります。

%NULLIND は、XML-INTO 命令の実行中にはフィールドまたはサブフィールドに対して更新されません。

命令拡張 H を指定すると、数値データを四捨五入して代入できます。 命令拡張 E を指定すると、以下の状況コードを処理できます。

00351
XML 構文解析時のエラー。
00352
無効な XML オプション。
00353
XML 文書が RPG 変数に一致しない。
00354
XML 構文解析の準備時エラー。
注:
命令拡張は、自由形式構文が使用された場合にのみ指定できます。

状況 00351 の場合、パーサーからの戻りコードは、PSDS の 368 から 371 桁目のサブフィールド「外部戻りコード」に配置されます。 このサブフィールドは、命令の開始時にゼロに設定され、命令の終了時にはパーサーにより戻された値に設定されます。

%XML 組み込み関数のオプション・パラメーターにおいて不明、無効、または無関係のオプションが検出された場合、その命令は状況コード 00352 (XML オプション・エラー) で失敗します。 PSDS の外部戻りコード・サブフィールドは、命令の開始時に設定された初期値のゼロから更新されません。

XML 文書は、XML の要素および属性の各名前に関して RPG 変数と一致することが期待されます。

path オプションを使用すると、指定された変数の名前と一致する XML 要素の名前を設定できます。 ただし、指定された変数のサブフィールドに一致する XML 要素および/または属性の名前の設定には使用できません。 例えば、変数 DS1 にサブフィールド SF1 がある場合、DS1 の XML 要素に は任意の名前を使用できますが、SF1 の XML 要素または属性には名前「sf1」(または case オプションに応じて「SF1」、「Sf1」など) を使用する必要があります。

RPG 変数が配列またはデータ構造の配列である場合、または %HANDLER 組み込み関数が指定された場合、配列要素に対応する XML 要素は別の XML 要素に含まれることが期待されます。 デフォルトで、各 XML 要素は、文書の最外部の XML 要素の子要素であることが期待されます。 path オプションを使用すると、配列要素に対応する XML 要素への実際のパスを指定できます。 例えば、最外部の XML 要素の名前が「transaction」であり、それに「parts」という名前の子要素があり、さらにその中に「part」という名前の複数の子要素がある場合、配列に「part」XML 要素を読み込むには、オプション「path=transaction/parts/part」を指定します。

  <transaction>
    <parts>
       <part type = "bracket" size="15" num="100"/>
       <part type="frame" size="2" num="500"/> 
    </parts>
  <transaction>

XML 文書が RPG 変数に一致しない場合、例えば XML 文書にデフォルト のパスまたは指定されたパスがない場合、または RPG データ構造のサブフィ ールドに一致する一部の XML 要素または属性が欠落している場合、XML-INTO 命令は状況 00353 で失敗します。 allowextra および allowmissing オプションを使用すると、XML 要素のデータを RPG 変数を完 全に設定するために必要なデータよりも多くするかまたは少なくするかを指定できます。

一部の RPG データ型では、XML 属性を指定して、XML データを RPG 変数に代入する方法を制御できます。 これらの属性について詳しくは、XML データを RPG 変数に転送する場合の規則を参照してください。

事前定義の参照 &amp、&apos、&lt、&gt、&quot、 または 16 進数ユニコード参照 &#xxxx 以外の XML 参照が検出された場 合、結果にはその参照自身が「&refname;」の形式で含まれます。 この値がデータ型に対して無効である場合、その命令は失敗します。 例えば、XML 要素に値 <data>1&decpoint;50/data> がある場合、3 つの部分「1」、「&decpoint;」、および「0」からストリング「1&decpoint;50」が作成されます。 このデータは、文字または UCS-2 変数に対して有効ですが、他の型に変換された場合はエラーが発生します。

ヒント: XML データにそのような参照が含まれ ていることが既知である場合は、XML-INTO 命令の終了後に、文字および UCS-2 データの参照の存在を検査し、%SCAN および %REPLACE などのストリ ング命令を使用して参照に正しい値を置換します。

XML データがそれに一致する RPG 変数の型に対して無効である場合は、その命令は状況コード 0353 で失敗します。 代入エラーに固有の状況コードがメッセージ RNX0353 の置換テキストに表示されます。

ヒント: 日付や数値などの型の RPG フィール ドにデータを正常に代入できなかったことで失敗する XML-INTO 命令を防止するには、文字または UCS-2 の型のすべてのサブフィールドに受信側変数を定義します。 それにより、データは、変換組み込み関数 %DATE や %INTT などを使用して RPG プログラムにより別のデータ型に変換されます。

XML-INTO 命令は、DOCTYPE 宣言を無視します。 DOCTYPE 宣言には、プログラムにより手動で処理する必要があるエンティティー参照の値が含まれている場合があります。 XML 文書の DOCTYPE 宣言を使用する場合は、XML-SAX 命令を使用します。 XML-SAX 処理プロシージャーでは、DOCTYPE 宣言値が検出されるか、または DOCTYPE 宣言が使用されていないと判断されると、構文解析を停止できます。

XML-INTO について詳しくは、以下のリンクを参照してください。