XMLFOREST スカラー関数

XMLFOREST 関数は、一連の XQuery エレメント・ノードである XML 値を戻します。

Notes:

¹ The same clause must not be specified more than once.

スキーマは SYSIBM です。関数名を修飾名で指定することはできません。

xmlnamespaces-宣言XMLNAMESPACES 宣言の結果である XML 名前空間宣言を指定します。宣言される名前空間は、XMLFOREST 関数の有効範囲内にあります。名前空間は、別の副選択の中で現れるかどうかにかかわらず、XMLFOREST 関数内でネストされているすべての XML 関数に対して適用されます。

xmlnamespaces-declaration を指定しないと、名前空間宣言と構成されたエレメントとの関連付けが行われません。

エレメント内容式 (element-content-expression)生成される XML エレメント・ノードの内容を式によって指定します。 element-content-expression のデータ・タイプを BINARY タイプ、VARBINARY タイプ、または構造化タイプにすることはできません (SQLSTATE 42884)。式には任意の SQL 式を指定できます。式が単純な列参照でない場合、エレメント名を指定する必要があります。

AS エレメント名

SQL ID として XML エレメント名を指定します。エレメント名は、 XML 修飾名の形式であるかまたは QName (SQLSTATE 42634) でなければなりません。有効な名前の詳細については、 W3C XML namespace specifications を参照してください。名前が修飾される場合は、名前空間の接頭部をその有効範囲内で宣言する必要があります (SQLSTATE 42635)。 element-name を指定しない場合、 element-content-expression は列名でなければなりません (SQLSTATE 42703)。エレメント名は、列名から QName への完全にエスケープしたマッピングを使用する列名から作成されます。

OPTION

XML エレメントを構成するための追加オプションを指定します。 OPTION 節を指定しない場合、デフォルトは NULL ON NULL XMLBINARY USING BASE64 です。この節は、 element-content-expressionで指定されたネストされた XMLELEMENT 呼び出しには影響しません。

EMPTY ON NULL または NULL ON NULL

各 element-content-expression の値が NULL 値の場合に NULL 値を戻すか、あるいは空エレメントを戻すかを指定します。このオプションはエレメントの内容の NULL 処理にのみ影響し、属性値の NULL 処理には影響を及ぼしません。デフォルトは NULL ON NULL です。

EMPTY ON NULL: それぞれの element-content-expression の値が NULL であれば、空のエレメントが戻されます。
NULL ON NULL: それぞれの element-content-expression の値が NULL であれば、NULL 値が戻されます。

XMLBINARY USING BASE64 または XMLBINARY USING HEX

バイナリー入力データ、FOR BIT DATA 属性を持つ文字ストリング・データ、またはこれらのタイプのいずれかに基づく特殊タイプの想定エンコードを指定します。エンコードはエレメントの内容または属性値に適用されます。デフォルトは XMLBINARY USING BASE64 です。

XMLBINARY USING BASE64: 想定エンコードが Base64 文字である (XML スキーマ・タイプ xs:base64Binary のエンコードに対して定義される) ことを指定します。 Base64 エンコードは、US-ASCII の 65 文字のサブセット (10 個の数字、26 個の小文字、26 個の大文字、'+' および '/') を使用して、サブセット内の 1 つの印刷可能文字により、バイナリーまたはビット・データのすべての 6 ビットを表します。文字を普遍的に表せるようにこれらの文字が選ばれています。この方法を使うと、エンコード・データのサイズが元のバイナリーまたはビット・データより 33 % 大きくなります。
XMLBINARY USING HEX: 想定エンコードが 16 進文字である (XML スキーマ・タイプ xs:hexBinary のエンコードに対して定義される) ことを指定します。 16 進数エンコードは、各バイト (8 ビット) を 2 つの 16 進文字で表します。この方法を使うと、エンコード・データが元のバイナリーまたはビット・データの 2 倍のサイズになります。

この関数は、任意指定の名前空間宣言のセット、および名前とエレメントの内容を構成する 1 つ以上の引数 (エレメント・ノードが 1 つ以上ある場合) を取ります。結果は、一連の XQuery エレメント・ノードまたは NULL 値を含む XML シーケンスとなります。

結果のデータ・タイプは XML です。いずれかの element-content-expression 引数が NULL の可能性がある場合、結果も NULL になる可能性があります。すべての element-content-expression 引数値が NULL で NULL ON NULL オプションが有効になっている場合、結果は NULL 値になります。

XMLFOREST 関数は XMLCONCAT および XMLELEMENT を使って表現できます。例えば、以下の 2 つの式は意味的には同じです。

XMLFOREST(xmlnamespaces-declaration, arg1 AS name1, arg2 AS name2 ...)

XMLCONCAT(
  XMLELEMENT(
    NAME name1, xmlnamespaces-declaration, arg1
  ),
  XMLELEMENT(
    NAME name2, xmlnamespaces-declaration, arg2
  )
  ...
)

注

デフォルトの名前空間を定義する別のエレメントの内容としてコピーされるエレメントを構成する場合、デフォルトの名前空間はコピーされたエレメント内で明示的に宣言解除する必要があります。これは、新規の親エレメントからデフォルトの名前空間を継承した結果として生じる可能性のあるエラーを避けるためです。事前定義名前空間接頭部 (「xs」、「xsi」、「xml」、および「sqlxml」) をその使用時に明示的に宣言する必要もあります。

例

注: XMLFOREST は、出力にブランク・スペースや改行文字を挿入しません。例の出力はすべて、読みやすくするために書式を整えています。

デフォルトの名前空間を持つエレメントのフォレストを構成します。

   SELECT EMPNO,
     XMLFOREST(
       XMLNAMESPACES(
         DEFAULT 'http://hr.org', 'http://fed.gov' AS "d"
       ),
       LASTNAME, JOB AS "d:job"
     )
   AS "Result"
   FROM EMPLOYEE
   WHERE EDLEVEL = 12

この照会は、次のような結果を生成します。

EMPNO  Result
000290 <LASTNAME xmlns="http://hr.org" xmlns:d="http://fed.gov">PARKER
  </LASTNAME>
<d:job xmlns="http://hr.org" xmlns:d="http://fed.gov">OPERATOR</d:job>

000310 <LASTNAME xmlns="http://hr.org" xmlns:d="http://fed.gov">SETRIGHT
  </LASTNAME>
<d:job xmlns="http://hr.org" xmlns:d="http://fed.gov">OPERATOR</d:job> 

200310 <LASTNAME xmlns="http://hr.org" xmlns:d="http://fed.gov">SPRINGER
  </LASTNAME>
<d:job xmlns="http://hr.org" xmlns:d="http://fed.gov">OPERATOR</d:job>