195 DBMS_XMLQUERY

DBMS_XMLQUERYは、データベースからXMLTypeへの変換機能を提供します。できるだけDBMS_XMLQUERYは使用せず、C言語の組込みパッケージであるDBMS_XMLGENを使用してください。

DBMS_XMLQUERYの使用方法

セキュリティ・モデル

定数

タイプ

セキュリティ・モデル

DBMS_XMLQUERYパッケージは、XDBが所有しているため、SYSまたはXDBによって作成される必要があります。EXECUTE権限は、PUBLICに付与されます。このパッケージ内のサブプログラムは、現行のユーザーの権限を使用して実行されます。

定数

表195-1 DBMS_XMLQUERYの定数

定数	説明
`DB_ENCODING`	DB文字エンコーディングの使用を示します。
`DEFAULT_ROWSETTAG`	結果セットから生成されたXMLを囲む要素のタグ名(ほとんどの場合、ルート・ノードのタグ名) -- `ROWSET`。
`DEFAULT_ERRORTAG`	発生したエラーを囲むデフォルトのタグ -- `ERROR`。
`DEFAULT_ROWIDATTR`	`db.records`に対応するXML要素のカーディナリティ属性のデフォルト名 -- `NUM`。
`DEFAULT_ROWTAG`	`db.records`に対応する要素のデフォルト・タグ名 -- `ROW`。
`DEFAULT_DATE_FORMAT`	デフォルトの日付マスク -- `'MM/dd/yyyy HH:mm:ss'`。
`ALL_ROWS`	出力にすべての行が必要であることを示します。
`NONE`	出力にXMLメタデータを含めない(DTDなどがない)ことを指定します。
`DTD`	DTDの生成が必要であることを指定します。
`SCHEMA`	XML Schemaの生成が必要であることを指定します。
`LOWER_CASE`	小文字のタグ名を使用します。
`UPPER_CASE`	大文字のタグ名を使用します。

タイプ

表195-2 DBMS_XMLQUERYのタイプ

タイプ	説明
`ctxType`	問合せコンテキスト・ハンドルのタイプ。NEWCONTEXTの戻りタイプです。

DBMS_XMLQUERYサブプログラムの要約

表195-3 DBMS_XMLQUERYパッケージのサブプログラム

メソッド	説明
CLOSECONTEXT	特定の問合せコンテキストのクローズまたは割当て解除を行います。
GETDTD	DTDを生成します。
GETEXCEPTIONCONTENT	スローされた例外のエラー・コードおよびエラー・メッセージを戻します。
GETNUMROWSPROCESSED	問合せで処理された行の数を戻します。
GETVERSION	使用中のXSUのバージョンを出力します。
GETXML	XML文書を生成します。
NEWCONTEXT	問合せコンテキストを作成し、コンテキスト・ハンドルを戻します。
PROPAGATEORIGINALEXCEPTION	例外が発生してスローされる場合、`OracleXMLSQLException`で例外をラップするのではなく、発生した例外自体をスローするようにXSUに指示します。
REMOVEXSLTPARAM	特定のトップレベルのスタイルシート・パラメータを削除します。
SETBINDVALUE	特定のバインド名の値を設定します。
SETCOLLIDATTRNAME	コレクション要素のセパレータ・タグのID属性名を設定します。
SETDATAHEADER	XMLデータ・ヘッダーを設定します。
SETDATEFORMAT	XML文書で生成された日付の書式を設定します。
SETENCODINGTAG	XML文書でのエンコーディング処理命令を設定します。
SETERRORTAG	XMLエラー・ドキュメントを囲むタグを設定します。
SETMAXROWS	XMLに変換される行の最大数を設定します。
SETMETAHEADER	XMLメタ・ヘッダーを設定します。
SETRAISEEXCEPTION	発生した例外をスローするようにXSUに指示します。
SETRAISENOROWSEXCEPTION	生成されたXML文書がなんらかの理由で空である場合、`OracleXMLNoRowsException`をスローするかどうかをXSUに指示します。
SETROWIDATTRNAME	タグを囲む行のID属性名を設定します。
SETROWIDATTRVALUE	タグを囲む行のID属性に値を割り当てるスカラー列を指定します。
SETROWSETTAG	XMLデータセットを囲むタグを設定します。
SETROWTAG	XML要素を囲むタグを設定します。
SETSKIPROWS	スキップする行数を設定します。
SETSQLTOXMLNAMEESCAPING	XML識別子にマップされたSQLオブジェクト名が有効なXML識別子でない場合、XMLタグのエスケープをオンまたはオフにします。
SETSTYLESHEETHEADER	スタイルシートのヘッダーを設定します。
SETTAGCASE	生成されたXMLタグの大文字または小文字を指定します。
SETXSLT	生成されたXMLに適用されるスタイルシートを登録します。
SETXSLTPARAM	トップレベルのスタイルシート・パラメータの値を設定します。
USENULLATTRIBUTEINDICATOR	`NULL`を示すためにXML属性を使用するかどうかを指定します。
USETYPEFORCOLLELEMTAG	コレクション要素のタグ名としてコレクション要素のタイプ名を使用することをXSUに指示します。

CLOSECONTEXT

特定の問合せコンテキストのクローズまたは割当て解除を行います。

構文

PROCEDURE CLOSECONTEXT(
ctxHdl IN ctxType);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。

GETDTD

コンテキストの初期化に使用するSQL問合せに基づいてDTDを生成して戻します。指定できるオプションは、次の表のとおりです。

構文説明

構文	説明
`FUNCTION GETDTD(` `ctxHdl IN ctxType,` `withVer IN BOOLEAN := false)` `RETURN CLOB;`	コンテキストの初期化に使用するSQL問合せに基づいてDTDを生成するファンクション。
`PROCEDURE GETDTD(` `ctxHdl IN ctxType,` `xDoc IN CLOB,` `withVer IN BOOLEAN := false);`	コンテキストの初期化に使用するSQL問合せに基づいてDTDを生成するプロシージャ。XML文書の結果に対する出力`CLOB`を指定します。

FUNCTION GETDTD(

ctxHdl IN ctxType,

withVer IN BOOLEAN := false)

RETURN CLOB;

コンテキストの初期化に使用するSQL問合せに基づいてDTDを生成するファンクション。

PROCEDURE GETDTD(

ctxHdl IN ctxType,

xDoc IN CLOB,

withVer IN BOOLEAN := false);

コンテキストの初期化に使用するSQL問合せに基づいてDTDを生成するプロシージャ。XML文書の結果に対する出力CLOBを指定します。

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`withVer`	`(IN)`	バージョン情報を生成するかどうか。生成する場合は`TRUE`を設定します。
`xDoc`	`(IN)`	生成されたXML文書の書込み先`CLOB`。

GETEXCEPTIONCONTENT

スローされた例外のSQLエラー・コードとエラー・メッセージを、プロシージャのOUTパラメータを使用して戻します。このプロシージャでは、元の例外を独自の例外で隠すというJVMの機能を実行し、その結果、PL/SQLは元の例外の内容にアクセスできなくなります。

構文

PROCEDURE GETEXCEPTIONCONTENT(
ctxHdl IN ctxType,
errNo OUT NUMBER,
errMsg OUT VARCHAR2);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`errNo`	`(OUT)`	エラー番号。
`errMsg`	`(OUT)`	エラー・メッセージ。

GETNUMROWSPROCESSED

問合せで処理された行の数を戻します。

構文

FUNCTION GETNUMROWSPROCESSED(
ctxHdl IN ctxType)
RETURN NUMBER;

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。

GETVERSION

使用中のXSUのバージョンを出力します。

構文

PROCEDURE GETVERSION();

GETXML

新規コンテキストを作成して問合せを実行し、XMLを戻してコンテキストをクローズします。これは便利なファンクションです。コンテキストは、明示的にオープンまたはクローズする必要はありません。指定できるオプションは、次の表のとおりです。

構文	説明
`FUNCTION GETXML(` `sqlQuery IN VARCHAR2,` `metaType IN NUMBER := NONE)` `RETURN CLOB;`	このファンクションは、文字列形式のSQL問合せを使用します。
`FUNCTION GETXML(` `sqlQuery IN CLOB,` `metaType IN NUMBER := NONE)` `RETURN CLOB;`	このファンクションは、`CLOB`形式のSQL問合せを使用します。
`FUNCTION GETXML(` `ctxHdl IN ctxType,` `metaType IN NUMBER := NONE)` `RETURN CLOB;`	このファンクションは、コンテキストの初期化に使用するSQL問合せに基づいてXML文書を生成します。
`PROCEDURE GETXML(` `ctxHdl IN ctxType,` `xDoc IN CLOB,` `metaType IN NUMBER := NONE);`	このプロシージャは、コンテキストの初期化に使用するSQL問合せに基づいてXML文書を生成します。

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`metaType`	`(IN)`	XMLメタデータ・タイプ(`NONE`、`DTD`、または`SCHEMA`)。
`sqlQuery`	`(IN)`	SQL問合せ。
`xDoc`	`(IN)`	生成されたXML文書の書込み先`CLOB`。

NEWCONTEXT

問合せコンテキストを作成し、コンテキスト・ハンドルを戻します。指定できるオプションは、次の表のとおりです。

構文説明

構文	説明
`FUNCTION NEWCONTEXT(` `sqlQuery IN VARCHAR2)` `RETURN ctxType;`	文字列から問合せコンテキストを作成します。
`FUNCTION NEWCONTEXT(` `sqlQuery IN CLOB)` `RETURN ctxType;`	`CLOB`から問合せコンテキストを作成します。

FUNCTION NEWCONTEXT(

sqlQuery IN VARCHAR2)

RETURN ctxType;

文字列から問合せコンテキストを作成します。

FUNCTION NEWCONTEXT(

sqlQuery IN CLOB)

RETURN ctxType;

CLOBから問合せコンテキストを作成します。

パラメータ	IN / OUT	説明
`sqlQuery`	`(IN)`	SQL問合せ。結果はXMLに変換する必要があります。

PROPAGATEORIGINALEXCEPTION

発生した元の例外すべてをスローするか、OracleXMLSQLExceptionでラップするかどうかを指定します。

構文

PROCEDURE PROPAGATEORIGINALEXCEPTION(
ctxHdl IN ctxType,
flag IN BOOLEAN);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`flag`	`(IN)`	元の例外を伝播するには`TRUE`、`OracleXMLException`でラップするには`FALSE`を設定します。

REMOVEXSLTPARAM

トップレベルのスタイルシート・パラメータの値を削除します。登録されているスタイルシートがない場合、このメソッドは操作できません。

構文

PROCEDURE REMOVEXSLTPARAM(
ctxHdl IN ctxType,
name IN VARCHAR2);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`name`	`(IN)`	トップレベルのスタイルシート・パラメータの名前。

SETBINDVALUE

特定のバインド名の値を設定します。

構文

PROCEDURE SETBINDVALUE(
ctxHdl IN ctxType,
bindName IN VARCHAR2,
bindValue IN VARCHAR2);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`bindName`	`(IN)`	バインド名。
`bindValue`	`(IN)`	バインド値。

SETCOLLIDATTRNAME

コレクション要素のセパレータ・タグのID属性名を設定します。NULLまたは空の文字列をタグに渡すと、行のID属性が省略されます。

構文

PROCEDURE SETCOLLIDATTRNAME(
ctxHdl IN ctxType,
attrName IN VARCHAR2);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`attrName`	`(IN)`	属性名。

SETDATAHEADER

XMLデータ・ヘッダーを設定します。データ・ヘッダーとは、問合せにより生成されたXMLエンティティ(rowset)の始めに追加されるXMLエンティティです。これら2つのエンティティをdocTag引数で囲みます。最後に指定したデータ・ヘッダーが使用されます。headerパラメータにNULLを渡すと、データ・ヘッダーの設定が解除されます。

構文

PROCEDURE SETDATAHEADER(
ctxHdl IN ctxType,
header IN CLOB := null,
tag IN VARCHAR2 := null);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`header`	`(IN)`	ヘッダー。
`tag`	`(IN)`	データ・ヘッダーおよび行セットを囲むタグ。

SETDATEFORMAT

XML文書で生成された日付の書式を設定します。日付書式パターン(日付マスク)の構文は、java.text.SimpleDateFormatクラスの要件に従う必要があります。マスクをNULLまたは空の文字列に設定すると、デフォルトのマスクであるDEFAULT_DATE_FORMATが設定されます。

構文

PROCEDURE SETDATEFORMAT(
ctxHdl IN ctxType,
mask IN VARCHAR2);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`mask`	`(IN)`	日付マスク。

SETENCODINGTAG

XML文書でのエンコーディング処理命令を設定します。

構文

PROCEDURE SETENCODINGTAG(
ctxHdl IN ctxType,
enc IN VARCHAR2 := DB_ENCODING);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`enc`	`(IN)`	使用するエンコーディング。

SETERRORTAG

XMLエラー・ドキュメントを囲むタグを設定します。

構文

PROCEDURE SETERRORTAG(
ctxHdl IN ctxType,
tag IN VARCHAR2);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`tag`	`(IN)`	タグ名。

SETMAXROWS

XMLに変換される行の最大数を設定します。デフォルトでは、最大数は設定されていません。

構文

PROCEDURE SETMAXROWS (
ctxHdl IN ctxType,
rows IN NUMBER);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`rows`	`(IN)`	生成する行の最大数。

SETMETAHEADER

XMLメタ・ヘッダーを設定します。設定すると、このオブジェクトにより生成された各XML文書のメタデータ・パート(DTDまたはXMLSchema)の最初の部分にヘッダーが挿入されます。最後に指定したメタ・ヘッダーが使用されます。headerパラメータにNULLを渡すと、メタ・ヘッダーの設定が解除されます。

構文

PROCEDURE SETMETAHEADER(
ctxHdl IN ctxType, 
header IN CLOB := null);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`Header`	`(IN)`	ヘッダー。

SETRAISEEXCEPTION

発生した例外をスローするかどうかを指定します。このコールが行われない場合またはflag引数にFALSEが渡された場合は、XSUによってSQL例外が捕捉され、例外メッセージからXML文書が生成されます。

構文

PROCEDURE SETRAISEEXCEPTION(
ctxHdl IN ctxType,
flag IN BOOLEAN:=true);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`flag`	`(IN)`	発生した例外をスローするかどうか。する場合は`TRUE`、しない場合は`FALSE`を設定します。

SETRAISENOROWSEXCEPTION

生成されたXML文書が空だった場合にOracleXMLNoRowsExceptionをスローするかどうかを指定します。デフォルトでは、例外はスローされません。

構文

PROCEDURE SETRAISENOROWSEXCEPTION(
ctxHdl IN ctxType,
flag IN BOOLEAN:=false);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`flag`	`(IN)`	`TRUE`が設定された場合は`OracleXMLNoRowsException`をスローします。

SETROWIDATTRNAME

タグを囲む行のID属性名を設定します。NULLまたは空の文字列をタグに渡すと、行のID属性が省略されます。

構文

PROCEDURE SETROWIDATTRNAME(
ctxHdl IN ctxType,
attrName IN VARCHAR2);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`attrName`	`(IN)`	属性名。

SETROWIDATTRVALUE

タグを囲む行のID属性に値を割り当てるスカラー列を指定します。colNameにNULLまたは空の文字列を渡すと、行のID属性に行のカウント値(0、1、2など)が割り当てられます。

構文

PROCEDURE SETROWIDATTRVALUE(
ctxHdl IN ctxType,
colName IN VARCHAR2);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`colName`	`(IN)`	値が行のID属性に割り当てられる列。

SETROWSETTAG

XMLデータセットを囲むタグを設定します。

構文

PROCEDURE SETROWSETTAG(
ctxHdl IN ctxType,
tag IN VARCHAR2);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`tag`	`(IN)`	タグ名。

SETROWTAG

db.recordに対応するXML要素を囲むタグを設定します。

構文

PROCEDURE SETROWTAG(
ctxHdl IN ctxType,
tag IN VARCHAR2);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`tag`	`(IN)`	タグ名。

SETSKIPROWS

スキップする行数を設定します。デフォルトでは、スキップされる行はありません。

構文

PROCEDURE SETSKIPROWS(
ctxHdl IN ctxType,
rows IN NUMBER);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`rows`	`(IN)`	スキップする行の最大数。

SETSQLTOXMLNAMEESCAPING

XML識別子にマップされたSQLオブジェクト名が有効なXML識別子でない場合、XMLタグのエスケープをオンまたはオフにします。

構文

PROCEDURE SETSQLTOXMLNAMEESCAPING(
ctxHdl IN ctxType,
flag IN BOOLEAN := true);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`flag`	`(IN)`	エスケープをオンにするかどうか。する場合は`TRUE`、しない場合は`FALSE`を設定します。

SETSTYLESHEETHEADER

生成されたXML文書のスタイルシートのヘッダー(スタイルシート処理命令)を設定します。uri引数にNULLを渡すと、スタイルシート・ヘッダーおよびスタイルシート・タイプの設定が解除されます。

構文

PROCEDURE SETSTYLESHEETHEADER(
ctxHdl IN ctxType,
uri IN VARCHAR2,
type IN VARCHAR2 := 'text/xsl');

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`uri`	`(IN)`	スタイルシートのURI。
`type`	`(IN)`	スタイルシート・タイプ。デフォルトは、`text/xsl`です。

SETTAGCASE

生成されたXMLタグの大文字または小文字を指定します。

構文

PROCEDURE SETTAGCASE(
ctxHdl IN ctxType,
tCase IN NUMBER);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`tCase`	`(IN)`	タグに大文字と小文字のどちらを使用するか。 0は元の文字をそのまま使用します。 1は小文字を使用します。 2は大文字を使用します。

SETXSLT

生成されたXMLに適用されるスタイルシートを登録します。スタイルシートがすでに登録されている場合は、新しいものに置換されます。指定できるオプションは、次の表のとおりです。uri引数にNULLを渡すか、stylesheet引数に空の文字列を渡すと、スタイルシート・ヘッダーおよびスタイルシート・タイプの設定が解除されます。

構文説明

構文	説明
`PROCEDURE SETXSLT(` `ctxHdl IN ctxType,` `uri IN VARCHAR2,` `ref IN VARCHAR2 := null);`	スタイルシートを登録解除するには、URIにNULLを渡します。
`PROCEDURE SETXSLT(` `ctxHdl IN ctxType,` `stylesheet CLOB,` `ref IN VARCHAR2 := null);`	スタイルシートを登録解除するには、スタイルシートにNULLまたは空の文字列を渡します。

PROCEDURE SETXSLT(

ctxHdl IN ctxType,

uri IN VARCHAR2,

ref IN VARCHAR2 := null);

スタイルシートを登録解除するには、URIにNULLを渡します。

PROCEDURE SETXSLT(

ctxHdl IN ctxType,

stylesheet CLOB,

ref IN VARCHAR2 := null);

スタイルシートを登録解除するには、スタイルシートにNULLまたは空の文字列を渡します。

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`uri`	`(IN)`	スタイルシートのURI。
`stylesheet`	`(IN)`	スタイルシート。
`ref`	`(IN)`	エンティティに含めたりインポートする他、外部エンティティのURL。

SETXSLTPARAM

トップレベルのスタイルシート・パラメータの値を設定します。パラメータ値には、有効なXPath式を指定します(このため、文字列リテラル値は明示的に引用されることが必要です)。登録されているスタイルシートがない場合、このメソッドは操作できません。

構文

PROCEDURE SETXSLTPARAM(
ctxHdl IN ctxType,
name IN VARCHAR2,
value IN VARCHAR2);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`name`	`(IN)`	トップレベルのスタイルシート・パラメータの名前。
`value`	`(IN)`	スタイルシート・パラメータに割り当てられる値。

USENULLATTRIBUTEINDICATOR

NULLであることを示すために、XML属性を使用するか、XML文書で特定のエンティティを省略するかどうかを指定します。

構文

PROCEDURE SETNULLATTRIBUTEINDICATOR(
ctxHdl IN ctxType, 
flag IN BOOLEAN);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`flag`	`(IN)`	`TRUE`の場合、属性が`NULL`に設定されます。`FALSE`の場合、XML文書では省略されます。

USETYPEFORCOLLELEMTAG

コレクション要素のタイプ名をその要素のタグ名として使用するかどうかを指定します。デフォルトでは、コレクション要素のタグ名は、コレクションのタグ名の後に_itemを付けた名前です。

構文

PROCEDURE USETYPEFORCOLLELEMTAG(
ctxHdl IN ctxType,
flag IN BOOLEAN := true);

パラメータ	IN / OUT	説明
`ctxHdl`	`(IN)`	コンテキスト・ハンドル。
`flag`	`(IN)`	タイプ名の使用をオンにするかどうか。