1. Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス
  2. DBMS_XMLGEN

197 DBMS_XMLGEN

DBMS_XMLGENパッケージは、SQL問合せの結果を標準的なXML形式に変換します。

このパッケージでは、入力された任意のSQL問合せをXML形式に変換し、その結果をCLOBとして戻します。このパッケージは、Cで記述されてカーネルにコンパイルされる点を除き、DBMS_XMLQUERYパッケージに類似しています。このパッケージを実行できるのは、データベース上のみです。

この章では、次の項目について説明します。

参照:

XMLサポートの詳細およびDBMS_XMLGENの使用例については、『Oracle XML DB開発者ガイド』を参照してください。

197.1 DBMS_XMLGENのセキュリティ・モデル

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

197.2 DBMS_XMLGENサブプログラムの要約

この表は、DBMS_XMLGENサブプログラムを示し、簡単に説明しています。

表197-1 DBMS_XMLGENパッケージのサブプログラムの要約

サブプログラム 説明

CLOSECONTEXTプロシージャ

コンテキストをクローズし、リソースをすべて解放します。

CONVERTファンクション

XMLを、エスケープ済またはエスケープ解除済の同等のXMLに変換します。

GETNUMROWSPROCESSEDファンクション

GETXMLファンクションを最後にコールしたときに処理されたSQL行の数を取得します。

GETXMLファンクション

XML文書を取得します。

GETXMLTYPEファンクション

XML文書を取得し、XMLTypeとして戻します。

NEWCONTEXTファンクション

新しいコンテキスト・ハンドルを作成します。

NEWCONTEXTFROMHIERARCHYファンクション

結果から再帰的要素を含む階層XMLを生成するために、GETXMLファンクションなどのファンクションで使用されるハンドルを取得します。

RESTARTQUERYプロシージャ

問合せを再起動し、最初からフェッチを開始します。

SETCONVERTSPECIALCHARSプロシージャ

XML文字ではない$などの特殊文字をエスケープ表示に変換するかどうかを設定します。

SETMAXROWSプロシージャ

一度にフェッチされる行の最大数を設定します。

SETNULLHANDLINGプロシージャ

NULLの処理オプションを設定します。

SETROWSETTAGプロシージャ

結果全体を囲む要素の名前を設定します。

SETROWTAGプロシージャ

結果の各行を囲む要素の名前を設定します。

SETSKIPROWSプロシージャ

XMLを生成する前に毎回スキップされる行数を設定します。

USEITEMTAGSFORCOLLプロシージャ

コレクション要素には、タグ_ITEMを追加したコレクションの列名を使用するように強制できます。

USENULLATTRIBUTEINDICATORプロシージャ

NULLを示すためにXML属性を使用するか、XML文書で特定のエンティティのインクルードを省略するかを指定します。

197.2.1 CLOSECONTEXTプロシージャ

このプロシージャは、指定されたコンテキストをクローズし、そのコンテキストに関連付けられたすべてのリソース(SQLカーソル、バインド、定義バッファなど)を解放します。このプロシージャをコールした後はコンテキスト・ハンドルが無効になるため、後続のファンクション・コールではハンドルを使用できなくなります。

構文

DBMS_XMLGEN.CLOSECONTEXT (
   ctx  IN ctxHandle);

パラメータ

表197-2 CLOSECONTEXTプロシージャのパラメータ

パラメータ 説明

ctx

クローズするコンテキスト・ハンドル

197.2.2 CONVERTファンクション

このファンクションは、XMLデータを、エスケープ済またはエスケープ解除済の同等のXMLに変換し、XML CLOBデータをエンコードまたはデコードされた形式で戻します。このファンクションの指定方法は、次のとおりです。

構文

文字列形式(VARCHAR2)でXMLDATAを使用します。 

DBMS_XMLGEN.CONVERT (
   xmlData IN VARCHAR2,
   flag    IN NUMBER := ENTITY_ENCODE)
RETURN VARCHAR2;

CLOB形式でXMLDATAを使用します。 

DBMS_XMLGEN.CONVERT (
   xmlData IN CLOB,
   flag    IN NUMBER := ENTITY_ENCODE)
 RETURN CLOB;

パラメータ

表197-3 CONVERTファンクションのパラメータ

パラメータ 説明

xmlData

エンコードまたはデコードするXML CLOBデータ。

flag

フラグ設定。エンコードの場合はENTITY_ENCODE(デフォルト)、デコードの場合はENTITY_DECODEに設定します。

使用上のノート

ENTITY_ENCODEを指定すると、XMLデータがエスケープされます。たとえば、<は&lt;に変換されます。エスケープの解除では、これとは逆に変換されます。

197.2.3 GETNUMROWSPROCESSEDファンクション

このファンクションは、GETXMLファンクションをコールしてXML文書を生成するときに処理されたSQL行の数を取得します。この行数には、XML文書の生成前にスキップされた行は含まれません。

GETXMLファンクションは行がない場合でも、常にXML文書を生成します。

構文

DBMS_XMLGEN.GETNUMROWSPROCESSED (
   ctx     IN    ctxHandle)
RETURN NUMBER;

パラメータ

表197-4 GETNUMROWSPROCESSEDファンクションのパラメータ

パラメータ 説明

ctx

NEWCONTEXTファンクションをコールして取得したコンテキスト・ハンドル。

使用上のノート

このファンクションは、ループ内でGETXMLファンクションをコールしている場合に、ループ処理の終了条件を判断するために使用します。

関連項目

197.2.4 GETXMLファンクション

このファンクションはXML文書を取得します。このファンクションはオーバーロードされています。

構文

指定した最大行数まで行をフェッチすることによって、XML文書を取得します。また、そのXML文書を渡されたCLOBに追加します。CLOBの余分なコピーが作成されるのを回避し、後続のコールで同じCLOBを再利用する場合は、このバージョンのGETXMLファンクションを使用してください。CLOBが再利用できるため、このようにGETXMLファンクションをコールすると効果的です。 

DBMS_XMLGEN.GETXML (
   ctx          IN ctxHandle, 
   tmpclob      IN OUT NCOPY CLOB,
   dtdOrSchema  IN number := NONE)
 RETURN BOOLEAN;

次の例では、XML文書を生成し、一時CLOBとして戻します。このファンクションから取得した一時CLOBは、DBMS_LOB.FREETEMPORARYをコールして解放する必要があります。 

DBMS_XMLGEN.GETXML (
   ctx          IN ctxHandle,
   dtdOrSchema  IN number := NONE)
 RETURN CLOB;

次の例では、SQL問合せ文字列の実行結果をXML形式に変換し、そのXML文書を一時CLOBとして戻しますが、これについては、後でDBMS_LOB.FREETEMPORARYをコールして解放する必要があります。 

DBMS_XMLGEN.GETXML (
   sqlQuery     IN VARCHAR2,
   dtdOrSchema  IN number := NONE)
 RETURN CLOB;

パラメータ

表197-5 GETXMLファンクションのパラメータ

パラメータ 説明 
ctx

newContextをコールして取得したコンテキスト・ハンドル。 

tmpclob

XML文書が追加されるCLOB。

sqlQuery

SQL問合せ文字列。

dtdOrSchema

DTDとスキーマのどちらを作成するのかを指定します。現在はNONEのみがサポートされています。

使用上のノート

SETSKIPROWSプロシージャのコールで指定された行がスキップされた場合は、SETMAXROWSプロシージャのコールで指定された最大数の行(指定されていない場合は結果全体)がフェッチされ、XMLに変換されます。行が取り出されたかどうかをチェックするには、GETNUMROWSPROCESSEDファンクションを使用してください。

197.2.5 GETXMLTYPEファンクション

このファンクションは、XML文書を取得してその文書をXMLTYPEとして戻します。結果に対してXMLTYPE操作を実行できます。このファンクションはオーバーロードされています。

構文

次の例では、XML文書を生成し、sys.XMLType:として戻します。

DBMS_XMLGEN.GETXMLTYPE (
   ctx           IN ctxhandle,
   dtdOrSchema   IN number := NONE)
 RETURN sys.XMLType;

SQL問合せ文字列の実行結果をXML形式に変換し、そのXML文書をsys.XMLTypeとして戻します。 

DBMS_XMLGEN.GETXMLTYPE (
   sqlQuery     IN VARCHAR2,
   dtdOrSchema  IN number := NONE)
 RETURN sys.XMLType

パラメータ

表197-6 GETXMLTYPEファンクションのパラメータ

パラメータ 説明

ctx

newContextをコールして取得したコンテキスト・ハンドル。

sqlQuery

SQL問合せ文字列。

dtdOrSchema

DTDとスキーマのどちらを作成するのかを指定します。現在はNONEのみがサポートされています。

197.2.6 NEWCONTEXTファンクション

このファンクションは、新しいコンテキスト・ハンドルを生成して戻します。

このコンテキスト・ハンドルは、結果からXMLを生成するために、GETXMLファンクションなどのファンクションで使用されます。このファンクションの指定方法は、次のとおりです。

構文

問合せから新しいコンテキスト・ハンドルを生成します。

DBMS_XMLGEN.NEWCONTEXT ( 
      query     IN VARCHAR2) 
 RETURN ctxHandle;

PL/SQL REFカーソル形式の問合せ文字列から、新しいコンテキスト・ハンドルを生成します。

DBMS_XMLGEN.NEWCONTEXT (
   queryString  IN SYS_REFCURSOR)
 RETURN ctxHandle;

パラメータ

表197-7 NEWCONTEXTファンクションのパラメータ

パラメータ 説明

query

VARCHAR形式の問合せ。結果はXMLに変換する必要があります。

queryString

PL/SQL REFカーソル形式の問合せ文字列。結果はXMLに変換する必要があります。

197.2.7 NEWCONTEXTFROMHIERARCHYファンクション

このファンクションは、結果から再帰的要素を含む階層XMLを生成するために、GETXMLファンクションなどのファンクションで使用されるハンドルを取得します。

構文

DBMS_XMLGEN.NEWCONTEXTFROMHIERARCHY ( 
   queryString IN VARCHAR2) 
 RETURN ctxHandle;

パラメータ

表197-8 NEWCONTEXTFROMHIERARCHYファンクションのパラメータ

パラメータ 説明

queryString

結果をXMLに変換する必要がある問合せ文字列。この問合せは、通常、CONNECT BY句を使用して構成された階層問合せであり、CONNECT BY問合せによって生成された結果セットと同じプロパティを持つ必要があります。結果セットの列は、レベル数およびXML値の2つのみである必要があります。レベル数は、結果のXML文書内でのXML値の階層位置を判断するために使用されます。

関連項目

197.2.8 RESTARTQUERYプロシージャ

このプロシージャは問合せを再起動し、最初の行からXMLを生成します。

新しいコンテキストを作成せずに、問合せを再度実行する場合に使用できます。

構文

DBMS_XMLGEN.RESTARTQUERY (
ctx  IN ctxHandle);

パラメータ

表197-9 RESTARTQUERYプロシージャのパラメータ

パラメータ 説明

ctx

現行の問合せに対応するコンテキスト・ハンドル。

197.2.9 SETCONVERTSPECIALCHARSプロシージャ

このプロシージャは、XMLデータ内の特殊文字を同等のエスケープXMLに変換するかどうかを設定します。たとえば、<符号は&lt;に変換されます。

デフォルトでは、変換が実行されます。

入力データに<、>、"、'などの特殊文字(エスケープが必要)を格納できない場合は、このプロシージャを使用するとXML処理のパフォーマンスが向上します。特にデータ量が多い場合、文字データをスキャンして特殊文字を置き換える作業は非効率的です。

構文

DBMS_XMLGEN.SETCONVERTSPECIALCHARS (
ctx   IN ctxHandle,
conv  IN BOOLEAN);

パラメータ

表197-10 SETCONVERTSPECIALCHARSプロシージャのパラメータ

パラメータ 説明

ctx

いずれかのNEWCONTEXTファンクションをコールして取得したコンテキスト・ハンドル。

conv

TRUEは、変換が必要であることを示します。

197.2.10 SETMAXROWSプロシージャ

このプロシージャでは、GETXMLファンクションをコールするたびにSQLの問合せ結果からフェッチする行の最大数を設定します。

このプロシージャは、ページ番号付きの結果を生成する場合に使用します。たとえば、XMLデータやHTMLデータのページの生成時に、このmaxrowsパラメータを設定して、XMLやHTMLに変換する行の数を抑制します。

構文

DBMS_XMLGEN.SETMAXROWS (
ctx      IN ctxHandle,
maxRows  IN NUMBER);

パラメータ

表197-11 SETMAXROWSプロシージャのパラメータ

パラメータ 説明

ctx

実行した問合せに対応するコンテキスト・ハンドル。

maxRows

GETXMLファンクションをコールするたびに取得する行の最大数。

関連項目

197.2.11 SETNULLHANDLINGプロシージャ

このプロシージャでは、flagパラメータを指定することによって、NULLに対する処理オプションを設定します。

構文

DBMS_XMLGEN.SETNULLHANDLING(
ctx  IN ctx,
flag IN NUMBER);

パラメータ

表197-12 SETNULLHANDLINGプロシージャのパラメータ

パラメータ 説明

ctx

実行した問合せに対応するコンテキスト・ハンドル。

flag

NULLの処理オプションの設定。

  • DROP_NULLS CONSTANT NUMBER:= 0;(デフォルト)の場合は、NULL要素のタグを削除します。

  • NULL_ATTR CONSTANT NUMBER:= 1;の場合はxsi:nil="true"と設定します。

  • EMPTY_TAG CONSTANT NUMBER:= 2;の場合は、たとえば<foo/>のように設定します。

197.2.12 SETROWSETTAGプロシージャ

このプロシージャは、ドキュメントのルート要素名を設定します。デフォルトの名前はROWSETです。

構文

DBMS_XMLGEN.SETROWSETTAG ( 
ctx            IN ctxHandle,  
rowSetTagName  IN VARCHAR2);

パラメータ

表197-13 SETROWSETTAGプロシージャのパラメータ

パラメータ 説明

ctx

NEWCONTEXTファンクションをコールして取得したコンテキスト・ハンドル。

rowSetTagName

ドキュメントの要素名。NULLを渡すと、ROWSET要素を表示しないことを示します。

使用上のノート

ユーザーは、rowSetTagをNULLに設定して、この要素の出力を抑制できます。ただし、行と行セットの両方がNULLで、出力に複数の列または行がある場合は、エラーが発生します。これは、生成されたXMLにトップレベルの囲みタグがないため、無効になるからです。

197.2.13 SETROWTAGプロシージャ

このプロシージャは、すべての行を分割する要素の名前を設定します。デフォルトの名前はROWです。

構文

DBMS_XMLGEN.SETROWTAG (
ctx         IN ctxHandle,
rowTagName  IN VARCHAR2);

パラメータ

表197-14 SETROWTAGプロシージャのパラメータ

パラメータ 説明

ctx

NEWCONTEXTファンクションをコールして取得したコンテキスト・ハンドル。

rowTagName

ROW要素の名前。NULLを渡すと、ROW要素を表示しないことを示します。

使用上のノート

ユーザーは、要素の名前をNULLに設定して、ROW要素自体を抑制できます。ただし、行と行セットの両方がNULLで、出力に複数の列または行がある場合は、エラーが発生します。これは、生成されたXMLにトップレベルの囲みタグがないため、無効になるからです。

197.2.14 SETSKIPROWSプロシージャ

このプロシージャでは、GETXMLファンクションをコールするたびに、任意の行数をスキップしてからXML出力を生成します。このプロシージャは、ステートレスWebページ用にページ番号付きの結果を生成する場合に使用します。

たとえば、XMLまたはHTMLデータの最初のページを生成する場合は、skiprowsを0 (ゼロ)に設定します。次ページ以降の場合、skiprowsには最初のページで取得した行数を設定します。「GETNUMROWSPROCESSEDファンクション」を参照してください。

構文

DBMS_XMLGEN.SETSKIPROWS (
ctx       IN ctxHandle,
skipRows  IN NUMBER);

パラメータ

表197-15 SETSKIPROWSプロシージャのパラメータ

パラメータ 説明

ctx

実行した問合せに対応するコンテキスト・ハンドル。

skipRows

getXMLをコールするたびにスキップする行数。

関連項目

197.2.15 USEITEMTAGSFORCOLLプロシージャ

このプロシージャは、コレクション要素のデフォルト名を上書きします。コレクション要素のデフォルト名は、そのタイプ名です。

構文

DBMS_XMLGEN.USEITEMTAGSFORCOLL (
   ctx  IN ctxHandle);

パラメータ

表197-16 USEITEMTAGSFORCOLLプロシージャのパラメータ

パラメータ 説明

ctx

コンテキスト・ハンドル。

使用上のノート

このプロシージャを使用すると、デフォルトに上書きして_ITEMタグを追加した列名を使用できます。NUMBERのコレクションがある場合、コレクション要素のデフォルトのタグ名はNUMBERです。

197.2.16 USENULLATTRIBUTEINDICATORプロシージャ

このプロシージャでは、NULLを示すためにXML属性を使用するか、XML文書で特定のエンティティのインクルードを省略するかどうかを指定します。

このプロシージャは、SETNULLHANDLINGプロシージャのショートカットとして使用します。

構文

DBMS_XMLGEN.USENULLATTRIBUTEINDICATOR(
ctx       IN   ctxType,
attrind   IN   BOOLEAN := TRUE);

パラメータ

表197-17 USENULLATTRIBUTEINDICATORプロシージャのパラメータ

パラメータ 説明

ctx

コンテキスト・ハンドル。

attrind

NULLを示すために属性を使用するかどうか。