XMLQUERY スカラー関数

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

xquery-expression-constant

サポートされる XQuery 言語構文を使用して、XQuery 式として解釈される SQL 文字ストリング定数を指定します。 定数ストリングは、XQuery ステートメントとして構文解析される前に UTF-8 に変換されます。 XQuery 式は、オプション・セットの入力 XML 値を使用して実行し、XMLQUERY 式の値としても戻される出力シーケンスを戻します。 xquery-expression-constant の値は、空ストリングまたはブランク文字のストリングにすることはできません (SQLSTATE 10505)。

PASSING

入力値、およびそれらの値を xquery-expression-constant で指定された XQuery 式に渡す方法を指定します。 デフォルトでは、関数が呼び出された有効範囲内にあるすべての固有の列名が、 列の名前を変数名として使用して XQuery 式に暗黙的に渡されます。 指定の xquery-argument 内の identifier が有効範囲内の列名と一致する場合、 明示的な xquery-argument はその暗黙的な列をオーバーライドして XQuery 式に渡されます。

BY REF

デフォルトの受け渡しメカニズムを、データ・タイプ XML の任意の xquery-variable-expression または戻り値の参照によると指定します。 XML 値を参照で渡す場合、XQuery の評価は、入力ノード・ツリーがあればそれを使用します。その場合は指定された入力式から直接、元のノードの ID および文書順序を含めすべてのプロパティーを保持したまま使用します。 2 つの引数が同じ XML 値を渡す場合、その 2 つの入力引数の間に含まれている何らかのノードに関係するノード ID 比較および文書順序比較は、同じ XML ノード・ツリー内のノードを参照する場合があります。

この節は、非 XML 値の受け渡しには影響を与えません。 非 XML 値は、XML へのキャスト中に値の新規コピーを作成します。

xquery-argument

xquery-expression-constant により指定された XQuery 式に渡される引数を指定します。 引数は、値およびその値が渡される方法を指定します。 xquery-argument では、値とその値の受け渡し方法の両方を指定します。 PASSING 節の引数を XQuery 式で使用する方式は、引数が xquery-context-item-expression または xquery-variable-expression のどちらとして指定されているかによって異なります。 xquery-argument に含まれる SQL 式は、評価された後に、その結果が XQuery 式に渡されます。

• 結果の値は、XML 型である場合、input-xml-value になります。 NULL の XML 値は、XML の空シーケンスに変換されます。
• 結果の値は、XML 型でない場合、XML データ・タイプにキャスト可能でなければなりません。 NULL 値は、XML の空シーケンスに変換されます。 変換される値は、input-xml-value になります。

xquery-expression-constant が評価されるとき、XQuery 変数は input-xml-value と等しい値、および AS 節により指定された名前で示されます。

xquery-context-item-expression

xquery-context-item-expression は、xquery-expression-constant で指定した XQuery 式の初期コンテキスト項目を指定します。 初期コンテキスト項目の値は、XML への xquery-context-item-expression の結果です。 xquery-context-item-expression は、複数回指定してはなりません。 xquery-context-item-expression に一連の複数項目を指定してはなりません。

input-xml-value が XML 空ストリングの場合、XQuery 式は、初期コンテキスト項目に XML 空ストリングを設定して評価されます。 input-xml-value の値が NULL の場合、関数は NULL 値を返します。 xquery-context-item-expression が指定されていない場合、または空シーケンスである場合、XQuery 式の初期コンテキスト項目は未定義であり、XQuery 式は初期コンテキスト項目を参照してはなりません。

XQuery 変数はコンテキスト項目式に対しては作成されません。

xquery-variable-expression

実行中に xquery-expression-constant により指定された XQuery 式が使用できる値を持つ SQL 式を指定します。 式には、シーケンス参照 (SQLSTATE 428F9) または OLAP 関数 (SQLSTATE 42903) を含めることはできません。 式のデータ・タイプを DECFLOAT にすることはできません。

AS identifier

xquery-variable-expression により生成された値が、xquery-expression-constant に XQuery 変数として渡されることを指定します。 変数名は identifier になります。 XQuery 言語の変数名に先行する先頭のドル記号 ($) は、identifier には含められません。 identifier は有効な XQuery 変数名でなければならず、XML NCName に制限されます (SQLSTATE 42634)。 identifier は、長さが 128 バイトを超えてはなりません。 同じ PASSING 節内の 2 つの引数が同じ identifier を使用することはできません (SQLSTATE 42711)。

BY REF

XML 入力値が参照により渡されるように指示します。 XML 値を参照で渡す場合、XQuery の評価は、入力ノード・ツリーがあればそれを使用します。その場合は指定された入力式から直接、元のノードの ID および文書順序を含めすべてのプロパティーを保持したまま使用します。 2 つの引数が同じ XML 値を渡す場合、その 2 つの入力引数の間に含まれている何らかのノードに関係するノード ID 比較および文書順序比較は、同じ XML ノード・ツリー内のノードを参照する場合があります。 BY REF が xquery-variable-expression に続いて指定されない場合、XML 引数は、PASSING キーワードに続く構文により提供されるデフォルトの受け渡しメカニズムによって渡されます。 このオプションは、非 XML 値に指定することはできません。 非 XML 値が渡される場合、値は XML に変換されます。このプロセスによりコピーが作成されます。

RETURNING SEQUENCE

XMLQUERY 式がシーケンスを戻すことを指示します。

BY REF

XQuery 式の結果を参照により戻すことを指示します。 この値にノードが含まれる場合、XQuery 式の戻り値を使用する式は、元のノードの ID および文書順序を含めすべてのノードのプロパティーを保持したまま、ノード参照を直接受け取ります。 参照されるノードは、そのノード・ツリー内で接続されたままです。 BY REF 節が指定されず、PASSING が指定されている場合、デフォルトの受け渡しメカニズムが使用されます。 BY REF が指定されず、PASSING も指定されていない場合、デフォルトの受け渡しメカニズムは BY REF です。

EMPTY ON EMPTY

XQuery 式の処理による空のシーケンスの結果を、空のシーケンスとして戻すことを指定します。

結果のデータ・タイプは XML であり、NULL にはできません。

XQuery 式の評価の結果がエラーになる場合、XMLQUERY 関数は XQuery エラーを戻します (SQLSTATE クラス '10')。