自由形式構文 | 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 組み込み関数である場合は、以下のようになります。
処理プロシージャーの最後の呼び出しでは、RPG 配列要素数が処理プロシージャーが処理する数より少ない場合があります。 処理プロシージャーは常に「要素の数」パラメーターを参照し、XML データがない配列要素にアクセスしないようにする必要があります。
%HANDLER の第 2 オペランドとして指定される通信域変数は、処理プロシ ージャーへの最初のパラメーターとしてパーサーにより受け渡されます。 これにより、XML-INTO 命令をコーディングするプロシージャーは処理プロ シージャーと通信でき、さらに処理プロシージャーはある呼び出しから次の呼び出しに情報を保管できます。
処理プロシージャーでは、以下のパラメーター数および戻り値の型を指定 する必要があります。
パラメーター数または戻り値 | データ型および引き渡しモード | 説明 |
---|---|---|
戻り値 | 4 バイト整数 (10I 0) | 戻り値がゼロの場合、構文解析が継続することを示します。 戻り値がその他の値の場合、構文解析が終了することを示します。 |
1 | 任意の型、参照による受け渡し | XML-INTO 命令とハンドラーの間、およびハンドラーの連続呼び出しの間の通信に使用される。 |
2 | 配列またはデータ構造の配列、読み取り専用の参照による受け渡し (CONST キーワード) | 配列要素には、path オプションにより指定された XML 要素からのデータが含まれています。 |
3 | 4 バイト符号なし整数 (10U 0)、値による受け渡し | XML データを表す第 2 パラメーター内の配列要素の数。 |
データ構造のサブフィールドは、XML 文書内にある順序で設定されます。 その順序は、データ構造内でサブフィールドのオーバーラップがある場合に重要になることがあります。
%NULLIND は、XML-INTO 命令の実行中にはフィールドまたはサブフィールドに対して更新されません。
命令拡張 H を指定すると、数値データを四捨五入して代入できます。 命令拡張 E を指定すると、以下の状況コードを処理できます。
状況 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 変数に転送する場合の規則を参照してください。
事前定義の参照 &、&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 データの参照の存在を検査し、%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 について詳しくは、以下のリンクを参照してください。
(C) Copyright IBM Corporation 1992, 2006. All Rights Reserved.