XML 文書の SAX 構文解析時には、いくつかの XML イベントがユーザーの XML-SAX 処理プロシージャーに受け渡されます。
ユーザーのプロシージャーにあるイベントを識別するには、*XML で始まる特殊名 (例えば *XML_START_ELEMENT) を使用します。
ほとんどのイベントの場合、処理プロシージャーにはそのイベントに関連付けられた値が渡されます。
例えば *XML_START_ELEMENT イベントの場合、その値は XML 要素の名前です。
この XML 文書の例は、XML イベントの記述で参照されます。
図 1. 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="+">Salt & pepper</spices>
<filling>Cheese, lettuce,
tomato, = &xyz;
</filling>
<![CDATA[We should add a <relish> element in future!]]>
</sandwich>junk
- *XML_START_DOCUMENT
- このイベントは、その文書の構文解析の開始時に一度発生します。
先頭の 2 つのパラメーターのみがこのイベントに関係しています。
ストリング・パラメーターにアクセスすると、ポインターがセットされていないというエラーが発生します。
- *XML_VERSION_INFO
- このイベントは、XML 宣言にバージョン情報が含まれている場合に発生します。
ストリング・パラメーターの値は、XML 宣言からのバージョン値です。
- *XML_ENCODING_DECL
- このイベントは、XML 宣言にエンコード情報が含まれている場合に発生します。
ストリング・パラメーターの値は、XML 宣言からのエンコード値です。
- *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
- このイベントは、それぞれの要素タグまたは空の要素タグごとに一度発生します。
ストリング・パラメーターの値は、要素名です。
- 発生する順序での例:
- 'sandwich'
- 'bread'
- 'spices'
- 'filling'
- *XML_CHARS
- このイベントは、コンテンツのそれぞれのフラグメントごとに発生します。
コンテンツは通常、そのテキストが複数の行であっても、単一のストリングで構成されています。
それに参照が含まれる場合、複数のイベントに分割されます。
ストリング・パラメーターの値は、コンテンツのフラグメントです。
- 例:
- 'Salt '
- ' pepper'
- 'Cheese, lettuce,WWWtomato, '、ここで WWW は複数の「空白文字」
を表します。
注意のセクションを参照してください。
- 'We should add a <relish> element in future!'
注: - コンテンツのフラグメント '&' では、*XML_PREDEF_REF イベントが発生し、フラグメント '=' では *XML_UCS2_REF イベントが発生します。
- 値が XML 文書の複数の行にまたがる場合、それには行末文字が含まれ、また、不必要な一連のブランクが含まれていることもあります。
例において、"lettuce," および "tomato" は改行文字および複数のブランクで分離されています。
これらの文字は空白文字 と呼ばれています。
空白文字は XML 要素の間に現れた場合には無視されますが、要素の中に現れた場合にはデータとみなされます。
XML データに不必要な空白文字が含まれている可能性がある場合は、データをトリムしてから使用する必要があります。
不必要な前後の空白文字をトリムするには、以下のコードを使用します。
図 4の例を参照してください。
* 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
- このイベントは、コンテンツに事前定義の単一文字参照 '&'、'''、'>'、'<'、および '"' のいずれかがある場合に発生します。
ストリング・パラメーターの値は、以下のような 1 バイト文字です。
| & |
& |
| ' |
' |
| > |
< |
| < |
> |
| " |
" |
注: 構文解析が UCS-2 で実行されている場合、ストリングは UCS-2 文字です。
- 例:
- '&'、"spices" 要素のコンテンツから。
- *XML_UCS2_REF
- このイベントは、コンテンツに形式 '&#dd..;' または '&#xhh..' の参照がある場合に発生します。
ここで 'd' および 'h' は 10 進数および 16 進数字をそれぞれ表します。
ストリング・パラメーターの値は、参照の UCS-2 値です。
注: このパラメーターは、構文解析が 1 バイト文字で実行されている場合でも、UCS-2 文字 (タイプ C) です。
- 例:
- UCS-2 値 '=' ("=" として表記)、"filling" 要素の最後のフラグメントから。
- *XML_UNKNOWN_REF
- このイベントは、コンテンツに現れる、上記の *XML_PREDEF_REF で示された 5 つの事前定義のエンティティー参照以外のエンティティー参照に対して発生します。
ストリング・パラメーターの値は参照の名前であり、開始の '&' と終了の ';' の間にあるデータです。
- 例:
- 'xyz'
- *XML_END_ELEMENT
- このイベントは、パーサーが要素の終了タグ、または空要素の終了の不等号括弧を検出した場合に発生します。
ストリング・パラメーターの値は、要素名です。
- 発生する順序での例:
- 'bread'
- 'spices'
- 'filling'
- 'sandwich'
- *XML_ATTR_NAME
- このイベントは、要素タグまたは空の要素タグ内のそれぞれの属性ごとに一度、有効な名前を認識した後に発生します。
ストリング・パラメーターの値は、属性名です。
- 発生する順序での例:
- 'type'
- 'supplier'
- 'attr'
- *XML_ATTR_CHARS
- このイベントは、属性値のそれぞれのフラグメントごとに発生します。
属性値は通常、そのテキストが複数の行であっても、単一のストリングで構成されています。
それに参照が含まれる場合、複数のイベントに分割されます。
ストリング・パラメーターの値は、属性値のフラグメントです。
- 発生する順序での例:
- 'baker'
- 's best'
注: - フラグメント ''' により *XML_ATTR_PREDEF_REF イベントが発生します。
- 不必要な行末文字および不必要なブランクの処理に関する推奨事項については、*XML_CHARS の説明を参照してください。
- *XML_ATTR_PREDEF_REF
- このイベントは、属性値に事前定義の単一文字参照 '&'、'''、'>'、'<'、および '"' のいずれかがある場合に発生します。
ストリング・パラメーターの値は、以下のような 1 バイト文字です。
| & |
& |
| ' |
' |
| > |
< |
| < |
> |
| " |
" |
注: 構文解析が 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 値 '+'、文書内では "+" で表記。
- *XML_UNKNOWN_ATTR_REF
- このイベントは、属性に現れる、上記の *XML_ATTR_PREDEF_REF で示された 5 つの事前定義のエンティティー参照以外のエンティティー参照に対して発生します。
ストリング・パラメーターの値は参照の名前であり、開始の '&' と終了の ';' の間にあるデータです。
- 例:
- 'abc'
注: パーサーは DOCTYPE 宣言を構文解析しません。
そのため、エンティティー "abc" が DOCTYPE 宣言で定義されていても、パーサーには未定義であると認識されます。
- *XML_END_ATTR
- このイベントは、パーサーが属性値の終了に到達した場合に発生します。
ストリング・パラメーターはこのイベントでは関係ありません。
ストリング・パラメーターにアクセスすると、ポインターがセットされていないというエラーが発生します。
- 例:
- 属性 type="baker's best" の場合、属性値の 3 つの部分 ("baker"、' および "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[' です。
- *XML_END_CDATA
- このイベントは、CDATA セクションが終了した場合に発生します。
ストリング・パラメーターの値は、常に終了文字列 ']]>' です。
- *XML_COMMENT
- このイベントは、XML 文書内のすべてのコメントに対して発生します。
ストリング・パラメーターの値は、前後の空白文字を含む、開始区切り文字 '<!--' および終了区切り文字 '-->' の間のデータです。
- 例:
- ' This document is just an example '
- *XML_EXCEPTION
- このイベントは、パーサーがエラーを検出した場合に発生します。
「ストリング」パラメーターは、このイベントで
は関係ありません。
ストリング・パラメーターにアクセスすると、ポインターがセットされていないというエラーが発生します。
ストリングの長さのパラメーターの値は、例外が発生した部分を含む、構
文解析された部分までの文書の長さです。
例外 ID パラメーターの値は、パーサーにより割り当てられた例外 ID です。
これらの例外の意味は、Rational Development Studio for i ILE RPG プログラマーの手引きの XML 戻りコードのセクションに記載されています。
- 例:
- パーサーが単語 "junk" を検出し、それが XML 文書の終了後に出現した非空白文字のデータである場合、この例外イベントが発生します。
(XML 文書は、"sandwich" 要素では要素の終了のタグで終了しています。)
- *XML_END_DOCUMENT
- このイベントは、構文解析の完了時に発生します。
先頭の 2 つのパラメーターのみがこのイベントに関係しています。
ストリング・パラメーターにアクセスすると、ポインターがセットされていないというエラーが発生します。
注: XML-SAX 処理プロシージャーのデバッグを補助するため、制御仕様キーワード DEBUG(*XMLSAX) を指定できます。
このキーワードについて詳しくは、
DEBUG {(*INPUT | *DUMP | *XMLSAX | *NO | *YES) }、および
Rational Development Studio for i ILE RPG プログラマーの手引きのデバッグの章を参照してください。
RPG により使用される XML パーサーの制限など、XML の構文解析について詳しくは、
Rational Development Studio for i ILE RPG プログラマーの手引きの XML についての章を参照してください。