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 文書の処理の基本概念に ついて十分理解していない場合は、以下のセクションを読み進める前に、 Rational Development Studio for i ILE RPG プログラマーの手引きのセクション『XML 文書の処理』を参照すると理解に役立ちます。
- RPG 変数に直接 XML データを読み取る
- %HANDLER(handlerProc) により指定されたプロシージャーに渡される配列パラメーターに対して段階的に XML データを読み取る。
第 1 オペランドには、構文解析されるデータのターゲットを指定します。 変数名または %HANDLER 組み込み関数を使用できます。
第 2 オペランドは %XML 組み込み関数にする必要があり、構文解析される XML 文書およびその構文解析方法を制御するオプションを識別します。 %XML について詳しくは、%XML (xmlDocument {:options })を参照してください。
- 構文解析は、変数に対して直接実行される。
- 変数の名前は、構文解析する XML 要素の名前を設定するために使用される。 これは path オプションを使用してオーバーライドできます。
- 変数がデータ構造である場合は、その命令がエラーで終了した場合でも、一部のサブフィールドはその命令により設定される。
- 変数が配列である場合、構文解析は配列に適合する量のデータに対してのみ検索を行う。 PSDS の 372 から 379 桁目にある「XML 要素の数」サブフィールドには、命令により正常に設定された要素の数が設定されます。 データ構造の配列の場合、その要素のサブフィールドのデータの構文解析中に構文解析エラーが発生したときは、この値には設定中の要素が含まれません。 ただし、この配列要素には、命令により設定されたそのサブフィールドの一部が含まれています。
- %HANDLER の第 1 オペランドとして指定されたプロシージャーは、そ
のプロシージャーにより処理される RPG 配列要素の指定された数を充てんす
るのに十分な数の XML データがパーサーにより構文解析される
と呼び出される。
ハンドラーから戻ると、配列要素の指定された数が再度充てんされ、処理プロシージャーを呼び出すために十分な数の XML データが構文解析されるまで、パーサーは XML データの構文解析を継続します。
これは、その文書が完全に構文解析されるまで、または構文解析が停止されたことを示す戻りコードをそのプロシージャーが戻すまで継続されます。
処理プロシージャーの最後の呼び出しでは、RPG 配列要素数が処理プロシージャーが処理する数より少ない場合があります。 処理プロシージャーは常に「要素の数」パラメーターを参照し、XML データがない配列要素にアクセスしないようにする必要があります。
%HANDLER の第 2 オペランドとして指定される通信域変数は、処理プロシ ージャーへの最初のパラメーターとしてパーサーにより受け渡されます。 これにより、XML-INTO 命令をコーディングするプロシージャーは処理プロ シージャーと通信でき、さらに処理プロシージャーはある呼び出しから次の呼び出しに情報を保管できます。
- プロシージャーの配列パラメーターの保持に使用される一時変数の各要素は、そのデフォルト値に初期化された後に XML データからロードされる。
- 検索対象の XML 要素の名前を指定するには、path オプションを使用する必要がある。 path オプションについて詳しくは、XML-INTO 命令コードの %XML オプションおよび 期待される XML データの形式を参照してください。
- 配列処理プロシージャーは、XML-INTO 命令の実行中に複数回呼び出される場合がある。
パーサーが第 2 パラメーターの DIM キーワードにより指定された要素の数を検出すると、そのプロシージャーが呼び出されます。
そのプロシージャーが呼び出される最後の回では、要素の数が DIM キーワードで指定された数より少ない場合があります。
要素がない場合、そのプロシージャーは呼び出されません。
処理プロシージャーでは、以下のパラメーター数および戻り値の型を指定 する必要があります。
パラメーター数または戻り値 データ型および引き渡しモード 説明 戻り値 4 バイト整数 (10I 0) 戻り値がゼロの場合、構文解析が継続することを示します。 戻り値がその他の値の場合、構文解析が終了することを示します。 1 任意の型、参照による受け渡し XML-INTO 命令とハンドラーの間、およびハンドラーの連続呼び出しの間の通信に使用される。 2 配列またはデータ構造の配列、読み取り専用の参照による受け渡し (CONST キーワード) 配列要素には、path オプションにより指定された XML 要素からのデータが含まれています。 3 4 バイト符号なし整数 (10U 0)、値による受け渡し XML データを表す第 2 パラメーター内の配列要素の数。 - %HANDLER について詳しくは、%HANDLER (handlingProcedure : communicationArea )を参照してください。
データ構造のサブフィールドは、XML 文書内にある順序で設定されます。 その順序は、データ構造内でサブフィールドのオーバーラップがある場合に重要になることがあります。
%NULLIND は、XML-INTO 命令の実行中にはフィールドまたはサブフィールドに対して更新されません。
- 00351
- XML 構文解析時のエラー。
- 00352
- 無効な XML オプション。
- 00353
- XML 文書が RPG 変数に一致しない。
- 00354
- XML 構文解析の準備時エラー。
状況 00351 の場合、パーサーからの戻りコードは、PSDS の 368 から 371 桁目のサブフィールド「外部戻りコード」に配置されます。 このサブフィールドは、命令の開始時にゼロに設定され、命令の終了時にはパーサーにより戻された値に設定されます。
%XML 組み込み関数のオプション・パラメーターにおいて不明、無効、または無関係のオプションが検出された場合、その命令は状況コード 00352 (XML オプション・エラー) で失敗します。 PSDS の外部戻りコード・サブフィールドは、命令の開始時に設定された初期値のゼロから更新されません。
- RPG データ構造の XML データには、そのデータ構造と同じ名前の XML 要素、および RPG サブフィールドと同じ名前の子要素および/または属性があることが期待されます。
- RPG 配列の XML データには、RPG 配列と同じ名前の一連の要素があることが期待されます。

<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 変数に転送する場合の規則を参照してください。
事前定義の参照 &、&apos、<、>、"、 または 16 進数ユニコード参照 &#xxxx 以外の XML 参照が検出された場 合、結果にはその参照自身が「&refname;」の形式で含まれます。 この値がデータ型に対して無効である場合、その命令は失敗します。 例えば、XML 要素に値 <data>1&decpoint;50/data> がある場合、3 つの部分「1」、「&decpoint;」、および「0」からストリング「1&decpoint;50」が作成されます。 このデータは、文字または UCS-2 変数に対して有効ですが、他の型に変換された場合はエラーが発生します。
ヒント: XML データにそのような参照が含まれていることが分かっている場合は、XML-INTO 命令の完了後に、文字データおよび UCS-2 データを検査して、参照が存在するか、%SCANRPL、 または %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 について詳しくは、以下のリンクを参照してください。