XML イベント

XML 文書の SAX 構文解析時には、いくつかの XML イベントがユーザーの XML-SAX 処理プロシージャーに受け渡されます。 ユーザーのプロシージャーにあるイベントを識別するには、*XML で始まる特殊名 (例えば *XML_START_ELEMENT) を使用します。

ほとんどのイベントの場合、処理プロシージャーにはそのイベントに関連付けられた値が渡されます。 例えば *XML_START_ELEMENT イベントの場合、その値は XML 要素の名前です。

表 76. XML イベント
イベント
1. 最初の XML 要素の前に発見されたイベント
*XML_START_DOCUMENT 構文解析が開始されたことを示します
*XML_VERSION_INFO XML 宣言からの "version" 値
*XML_ENCODING_DECL XML 宣言からの "encoding" 値
*XML_STANDALONE_DECL XML 宣言からの "standalone" 値
*XML_DOCTYPE_DECL 文書タイプ宣言の値
2. XML 要素に関連したイベント
*XML_START_ELEMENT 開始中の XML 要素の名前
*XML_CHARS XML 要素の値
*XML_PREDEF_REF 事前定義参照の値
*XML_UCS2_REF UCS-2 参照の値
*XML_UNKNOWN_REF 不明なエンティティー参照の名前
*XML_END_ELEMENT 終了する XML 要素の名前
3. XML 属性に関連したイベント
*XML_ATTR_NAME 属性の名前
*XML_ATTR_CHARS 属性の値
*XML_ATTR_PREDEF_REF 事前定義参照の値
*XML_ATTR_UCS2_REF UCS-2 参照の値
*XML_UNKNOWN_ATTR_REF 不明なエンティティー参照の名前
*XML_END_ATTR 属性の終了を示す
4. XML 処理命令に関連したイベント
*XML_PI_TARGET ターゲットの名前
*XML_PI_DATA データの値
5. XML CDATA セクションに関連したイベント
*XML_START_CDATA CDATA セクションの開始
*XML_CHARS CDATA セクションの値
*XML_END_CDATA CDATA セクションの終了
6. その他のイベント
*XML_COMMENT XML コメントの値
*XML_EXCEPTION パーサーによるエラーの発見を示す
*XML_END_DOCUMENT 構文解析が終了したことを示す

この XML 文書の例は、XML イベントの記述で参照されます。

図 388. XML イベントの記述で参照される XML 文書の例
<?xml version="1.0" encoding="ibm-1140" standalone="yes" ?>
<!DOCTYPE page [
  <!ENTITY abc "ABC Inc">
]>
<!-- This document is just an example  -->
<sandwich>
  <bread type="baker's best" supplier="&abc;" />
  <?spread   please use real mayonnaise ?>
  <spices attr="&#x2B;">Salt &amp; pepper</spices>
  <filling>Cheese, lettuce,
           tomato, &#0061; &xyz;
  </filling>
  <![CDATA[We should add a <relish> element in future!]]>
</sandwich>junk
*XML_START_DOCUMENT
このイベントは、その文書の構文解析の開始時に一度発生します。 先頭の 2 つのパラメーターのみがこのイベントに関係しています。 ストリング・パラメーターにアクセスすると、ポインターがセットされていないというエラーが発生します。
*XML_VERSION_INFO
このイベントは、XML 宣言にバージョン情報が含まれている場合に発生します。 ストリング・パラメーターの値は、XML 宣言からのバージョン値です。

例:
'1.0'
*XML_ENCODING_DECL
このイベントは、XML 宣言にエンコード情報が含まれている場合に発生します。 ストリング・パラメーターの値は、XML 宣言からのエンコード値です。

例:
'ibm-1140'
*XML_STANDALONE_DECL
このイベントは、XML 宣言にスタンドアロン情報が含まれている場合に発生します。 ストリング・パラメーターの値は、XML 宣言からのスタンドアロン値です。
例:
'yes'
*XML_DOCTYPE_DECL
このイベントは、XML 宣言に DTD (文書タイプ宣言) が含まれている場合に発生します。 文書タイプ宣言は文字列 '<!DOCTYPE' で開始し '>' の文字で終了します。

注: これは、XML テキストに区切り文字が含まれる場合の唯一のイベントで す。

ストリング・パラメーターの値は、開始および終了の文字列を含む DOCTYPE の値全体です。

例:
'<!DOCTYPE page [LF  <!ENTITY abc "ABC Inc">LF]>'
(LF は改行文字を表します。)
*XML_START_ELEMENT
このイベントは、それぞれの要素タグまたは空の要素タグごとに一度発生します。 ストリング・パラメーターの値は、要素名です。

発生する順序での例:
  1. 'sandwich'
  2. 'bread'
  3. 'spices'
  4. 'filling'
*XML_CHARS
このイベントは、コンテンツのそれぞれのフラグメントごとに発生します。 コンテンツは通常、そのテキストが複数の行であっても、単一のストリングで構成されています。 それに参照が含まれる場合、複数のイベントに分割されます。 ストリング・パラメーターの値は、コンテンツのフラグメントです。

例:
  1. 'Salt '
  2. ' pepper'
  3. 'Cheese, lettuce,WWWtomato, '、ここで WWW は複数の「空白文字」 を表します。 詳しくは、のセクションを参照してください。
  4. 'We should add a <relish> element in future!'

注:
  1. コンテンツのフラグメント '&amp;' では、*XML_PREDEF_REF イベントが発生し、フラグメント '&#0061;' では *XML_UCS2_REF イベントが発生します。
  2. 値が XML 文書の複数の行にまたがる場合、それには行末文字が含まれ、また、不必要な一連のブランクが含まれていることもあります。 例において、"lettuce," および "tomato" は改行文字および複数のブランクで分離されています。 これらの文字は空白文字 と呼ばれています。 空白文字は XML 要素の間に現れた場合には無視されますが、要素の中に現れた場合にはデータとみなされます。 XML データに不必要な空白文字が含まれている可能性がある場合は、データをトリムしてから使用する必要があります。 不必要な前後の空白文字をトリムするには、以下のコードを使用します。 図 392の例を参照してください。
      * x'15'=newline  x'05'=tab     x'0D'=carriage-return
     * x'25'=linefeed x'40'=blank
     D whitespaceChr   C                   x'15050D2540'
    /free
         temp = %trim(value : whitespaceChr);
*XML_PREDEF_REF
このイベントは、コンテンツに事前定義の単一文字参照 '&amp;'、'&apos;'、'&gt;'、'&lt;'、および '&quot;' のいずれかがある場合に発生します。 ストリング・パラメーターの値は、以下のような 1 バイト文字です。
表 77.
&amp; &
&apos; '
&gt; <
&lt; >
&quot; "
注:
構文解析が UCS-2 で実行されている場合、ストリングは UCS-2 文字です。
例:
'&'、"spices" 要素のコンテンツから。
*XML_UCS2_REF
このイベントは、コンテンツに形式 '&#dd..;' または '&#xhh..' の参照がある場合に発生します。 ここで 'd' および 'h' は 10 進数および 16 進数字をそれぞれ表します。 ストリング・パラメーターの値は、参照の UCS-2 値です。
注:
このパラメーターは、構文解析が 1 バイト文字で実行されている場合でも、UCS-2 文字 (タイプ C) です。
例:
UCS-2 値 '=' ("&#0061;" として表記)、"filling" 要素の最後のフラグメントから。
*XML_UNKNOWN_REF
このイベントは、コンテンツに現れる、上記の *XML_PREDEF_REF で示された 5 つの事前定義のエンティティー参照以外のエンティティー参照に対して発生します。 ストリング・パラメーターの値は参照の名前であり、開始の '&' と終了の ';' の間にあるデータです。
例:
'xyz'
*XML_END_ELEMENT
このイベントは、パーサーが要素の終了タグ、または空要素の終了の不等号括弧を検出した場合に発生します。 ストリング・パラメーターの値は、要素名です。

発生する順序での例:
  1. 'bread'
  2. 'spices'
  3. 'filling'
  4. 'sandwich'
*XML_ATTR_NAME
このイベントは、要素タグまたは空の要素タグ内のそれぞれの属性ごとに一度、有効な名前を認識した後に発生します。 ストリング・パラメーターの値は、属性名です。

発生する順序での例:
  1. 'type'
  2. 'supplier'
  3. 'attr'
*XML_ATTR_CHARS
このイベントは、属性値のそれぞれのフラグメントごとに発生します。 属性値は通常、そのテキストが複数の行であっても、単一のストリングで構成されています。 それに参照が含まれる場合、複数のイベントに分割されます。 ストリング・パラメーターの値は、属性値のフラグメントです。
発生する順序での例:
  1. 'baker'
  2. 's best'
注:
  1. フラグメント '&apos;' により *XML_ATTR_PREDEF_REF イベントが発生します。
  2. 不必要な行末文字および不必要なブランクの処理の推奨については、*XML_CHARSの説明を参照してください。
*XML_ATTR_PREDEF_REF
このイベントは、属性値に事前定義の単一文字参照 '&amp;'、'&apos;'、'&gt;'、'&lt;'、および '&quot;' のいずれかがある場合に発生します。 ストリング・パラメーターの値は、以下のような 1 バイト文字です。
表 78.
&amp; &
&apos; '
&gt; <
&lt; >
&quot; "
注: 構文解析が UCS-2 で実行されている場合、ストリングは UCS-2 文字です。

"type" 属性の値の例:
' (アポストロフィ文字、"&apos")
*XML_ATTR_UCS2_REF
このイベントは、属性値に形式の参照 '&#dd..;' または '&#xhh..;' がある場合に発生します。 ここで 'd' および 'h' は 10 進数および 16 進数字をそれぞれ表します。 ストリング・パラメーターの値は、その参照の UCS-2 値です。

注: このパラメーターは、構文解析が 1 バイト文字で実行されている場合でも、UCS-2 文字 (タイプ C) です。

"attr" 属性の値からの例:
UCS-2 値 '+'、文書内では "&#x2B;" で表記。
*XML_UNKNOWN_ATTR_REF
このイベントは、属性に現れる、上記の *XML_ATTR_PREDEF_REF で示された 5 つの事前定義のエンティティー参照以外のエンティティー参照に対して発生します。 ストリング・パラメーターの値は参照の名前であり、開始の '&' と終了の ';' の間にあるデータです。
例:
'abc'
注:
パーサーは DOCTYPE 宣言を構文解析しません。 そのため、エンティティー "abc" が DOCTYPE 宣言で定義されていても、パーサーには未定義であると認識されます。
*XML_END_ATTR
このイベントは、パーサーが属性値の終了に到達した場合に発生します。 ストリング・パラメーターはこのイベントでは関係ありません。 ストリング・パラメーターにアクセスすると、ポインターがセットされていないというエラーが発生します。
例:
属性 type="baker&apos;s best" の場合、属性値の 3 つの部分 ("baker"、&apos; および "s best") がすべて処理された後、*XML_END_ATTR イベントが発生します。
*XML_PI_TARGET
このイベントは、パーサーが処理命令 (PI) の開始文字列 '<?' に続く名前を認識した場合に発生します。 処理命令により、XML 文書にアプリケーション用の特別な命令を含めることができます。 ストリング・パラメーターの値は、処理命令の名前です。
例:
'spread'
*XML_PI_DATA
このイベントは、処理命令の終了文字列 '?>' までの (終了文字列 は含まない) 処理命令のデータ部分に対して発生します。 ストリング・パラメーターの値は、末尾の空白文字を含むが先導する空白文字を含まない、処理命令データです。
例:
'please use real mayonnaise '
注:
不必要な行末文字および不必要なブランクの処理の推奨については、*XML_CHARSの説明を参照してください。
*XML_START_CDATA
このイベントは、CDATA セクションが開始した場合に発生します。 CDATA セクションは、ストリング '<![CDATA[' で開始され、ストリング ']]>' で終了します。 このようなセクションは、そうしなければ XML マークアップとして認識さ れてしまう文字が含まれるテキストのブロックを「回避」する場合に使用されます。 パーサーは単一の *XML_CHARS イベントとして、これらの区切り文字の間の CDATA セクションのコンテンツをパスします。 ストリング・パラメーターの値は、常に開始文字列 '<![CDATA[' です。

例:
'<![CDATA['
*XML_END_CDATA
このイベントは、CDATA セクションが終了した場合に発生します。 ストリング・パラメーターの値は、常に終了文字列 ']]>' です。

例:
']]>'
*XML_COMMENT
このイベントは、XML 文書内のすべてのコメントに対して発生します。 ストリング・パラメーターの値は、前後の空白文字を含む、開始区切り文字 '<!--' および終了区切り文字 '-->' の間のデータです。
例:
' This document is just an example '
*XML_EXCEPTION
このイベントは、パーサーがエラーを検出した場合に発生します。 「ストリング」パラメーターは、このイベントで は関係ありません。 ストリング・パラメーターにアクセスすると、ポインターがセットされていないというエラーが発生します。 ストリングの長さのパラメーターの値は、例外が発生した部分を含む、構 文解析された部分までの文書の長さです。 例外 ID パラメーターの値は、パーサーにより割り当てられた例外 ID です。 これらの例外の意味は、WebSphere Development Studio: ILE RPG プログラマーの手引きの XML 戻りコードのセクションに記載されています。
例:
パーサーが単語 "junk" を検出し、それが XML 文書の終了後に出現した非空白文字のデータである場合、この例外イベントが発生します。 (XML 文書は、"sandwich" 要素では要素の終了のタグで終了しています。)
*XML_END_DOCUMENT
このイベントは、構文解析の完了時に発生します。 先頭の 2 つのパラメーターのみがこのイベントに関係しています。 ストリング・パラメーターにアクセスすると、ポインターがセットされていないというエラーが発生します。
注:
XML-SAX 処理プロシージャーのデバッグを補助するため、制御仕様キーワード DEBUG(*XMLSAX) を指定できます。 このキーワードについて詳しくは、DEBUG{(*INPUT | *DUMP | *XMLSAX | *NO | *YES)}、およびWebSphere Development Studio: ILE RPG プログラマーの手引きのデバッグの章を参照してください。 RPG により使用される XML パーサーの制限など、XML の構文解析について詳しくは、WebSphere Development Studio: ILE RPG プログラマーの手引きの XML についての章を参照してください。