| Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス 11g リリース1（11.1） E05686-02 |
|
 戻る |
 次へ |
DBMS_XMLGENパッケージは、SQL問合せの結果を標準的なXML形式に変換します。このパッケージでは、入力された任意のSQL問合せをXML形式に変換し、その結果をCLOBとして戻します。 このパッケージは、Cで記述されてカーネルにコンパイルされる点を除き、DBMS_XMLQUERYパッケージに類似しています。このパッケージを実行できるのは、データベース上のみです。
この章では、次の項目について説明します。
|
関連項目: XMLサポートの詳細およびDBMS_XMLGENの使用例については、『Oracle XML DB開発者ガイド』を参照してください。 |
表156-1 DBMS_XMLGENパッケージのサブプログラムの要約
| サブプログラム | 説明 |
|---|---|
|
|
コンテキストをクローズし、リソースをすべて解放します。 |
|
|
XMLを、エスケープ済またはエスケープ解除済の同等のXMLに変換します。 |
|
GETXMLファンクションを最後にコールしたときに処理されたSQL行の数を取得します。 |
|
|
XML文書を取得します。 |
|
|
XML文書を取得し、 |
|
|
|
新しいコンテキスト・ハンドルを作成します。 |
|
|
問合せを再起動し、最初からフェッチを開始します。 |
|
|
XML文字ではない |
|
|
一度にフェッチされる行の最大数を設定します。 |
|
|
|
|
|
結果全体を囲む要素の名前を設定します。 |
|
|
結果の各行を囲む要素の名前を設定します。 |
|
|
XMLを生成する前に毎回スキップされる行数を設定します。 |
|
|
コレクション要素には、タグ |
|
USENULLATTRIBUTEINDICATORプロシージャ |
|
このプロシージャは、指定されたコンテキストをクローズし、そのコンテキストに関連付けられたすべてのリソース（SQLカーソル、バインド、定義バッファなど）を解放します。このプロシージャをコールした後はコンテキスト・ハンドルが無効になるため、後続のファンクション・コールではハンドルを使用できなくなります。
構文
DBMS_XMLGEN.CLOSECONTEXT ( ctx IN ctxHandle);
パラメータ
このファンクションは、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;
パラメータ
表156-3 CONVERTファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
エンコードまたはデコードするXML |
|
|
フラグ設定。エンコードの場合は |
使用上の注意
ENTITY_ENCODEを指定すると、XMLデータがエスケープされます。たとえば、<は<に変換されます。エスケープの解除では、これとは逆に変換されます。
このファンクションは、GETXMLファンクションをコールしてXML文書を生成するときに処理されたSQL行の数を取得します。この行数には、XML文書の生成前にスキップされた行は含まれません。 GETXMLファンクションは行がない場合でも、常にXML文書を生成します。
構文
DBMS_XMLGEN.GETNUMROWSPROCESSED ( ctx IN ctxHandle) RETURN NUMBER;
パラメータ
使用上の注意
このファンクションは、ループ内で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;
パラメータ
表156-5 GETXMLファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
ctx |
|
tmpclob |
XML文書が追加される |
|
|
SQL問合せ文字列。 |
|
|
DTDとスキーマのどちらを作成するのかを指定します。現在は |
使用上の注意
SETSKIPROWSプロシージャのコールで指定された行がスキップされた場合は、SETMAXROWSプロシージャのコールで指定された最大数の行（指定されていない場合は結果全体）がフェッチされ、XMLに変換されます。行が取り出されたかどうかをチェックするには、GETNUMROWSPROCESSEDファンクションを使用してください。
このファンクションは、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
パラメータ
表156-6 GETXMLTYPEファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
SQL問合せ文字列。 |
|
|
DTDとスキーマのどちらを作成するのかを指定します。現在は |
このファンクションは、新しいコンテキスト・ハンドルを生成して戻します。このコンテキスト・ハンドルは、結果からXMLを生成するために、GETXMLファンクションなどのファンクションで使用されます。このファンクションの指定方法は、次のとおりです。
構文
問合せから新しいコンテキスト・ハンドルを生成します。
DBMS_XMLGEN.NEWCONTEXT (
query IN VARCHAR2)
RETURN ctxHandle;
PL/SQL REFカーソル形式の問合せ文字列から、新しいコンテキスト・ハンドルを生成します。
DBMS_XMLGEN.NEWCONTEXT ( queryString IN SYS_REFCURSOR) RETURN ctxHandle;
パラメータ
表156-7 NEWCONTEXTファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
PL/SQL REFカーソル形式の問合せ文字列。結果はXMLに変換する必要があります。 |
このプロシージャは問合せを再起動し、最初の行からXMLを生成します。新しいコンテキストを作成せずに、問合せを再度実行する場合に使用できます。
構文
DBMS_XMLGEN.RESTARTQUERY ( ctx IN ctxHandle);
パラメータ
このプロシージャは、XMLデータ内の特殊文字を同等のエスケープXMLに変換するかどうかを設定します。たとえば、<符号は<.に変換されます。デフォルトでは、エスケープXMLへの変換が実行されます。 入力データに<、>、"、'などの特殊文字（エスケープが必要）を格納できない場合は、このプロシージャを使用するとXML処理のパフォーマンスが向上します。特にデータ量が多い場合、文字データをスキャンして特殊文字を置き換える作業は非効率的です。
構文
DBMS_XMLGEN.SETCONVERTSPECIALCHARS ( ctx IN ctxHandle, conv IN BOOLEAN);
パラメータ
表156-9 SETCONVERTSPECIALCHARSプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
いずれかのNEWCONTEXTファンクションをコールして取得したコンテキスト・ハンドル。 |
|
|
|
このプロシージャでは、GETXMLファンクションをコールするたびにSQLの問合せ結果からフェッチする行の最大数を設定します。このプロシージャは、ページ番号付きの結果を生成する場合に使用します。たとえば、XMLデータやHTMLデータのページの生成時に、このmaxRowsパラメータを設定して、XMLやHTMLに変換する行の数を抑制します。
構文
DBMS_XMLGEN.SETMAXROWS ( ctx IN ctxHandle, maxRows IN NUMBER);
パラメータ
表156-10 SETMAXROWSプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
実行した問合せに対応するコンテキスト・ハンドル。 |
|
|
GETXMLファンクションをコールするたびに取得する行の最大数。 |
このプロシージャでは、flagパラメータを指定することによって、NULLに対する処理オプションを設定します。
構文
DBMS_XMLGEN.SETNULLHANDLING( ctx IN ctx, flag IN NUMBER);
パラメータ
表156-11 SETNULLHANDLINGプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
実行した問合せに対応するコンテキスト・ハンドル。 |
|
|
|
このプロシージャは、ドキュメントのルート要素名を設定します。デフォルトの名前はROWSETです。
構文
DBMS_XMLGEN.SETROWSETTAG ( ctx IN ctxHandle, rowSetTagName IN VARCHAR2);
パラメータ
表156-12 SETROWSETTAGプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
ctx |
NEWCONTEXTファンクションをコールして取得したコンテキスト・ハンドル。 |
|
rowSetTagName |
ドキュメントの要素名。 |
使用上の注意
ユーザーは、rowSetTagをNULLに設定して、この要素の出力を抑制できます。ただし、行と行セットの両方がNULLで、出力に複数の列または行がある場合は、エラーが発生します。これは、生成されたXMLにトップレベルの囲みタグがないため、無効になるからです。
このプロシージャは、すべての行を分割する要素の名前を設定します。デフォルトの名前はROWです。
構文
DBMS_XMLGEN.SETROWTAG ( ctx IN ctxHandle, rowTagName IN VARCHAR2);
パラメータ
表156-13 SETROWTAGプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
NEWCONTEXTファンクションをコールして取得したコンテキスト・ハンドル。 |
|
|
|
使用上の注意
ユーザーは、要素の名前をNULLに設定して、ROW要素自体を抑制できます。ただし、行と行セットの両方がNULLで、出力に複数の列または行がある場合は、エラーが発生します。これは、生成されたXMLにトップレベルの囲みタグがないため、無効になるからです。
このプロシージャでは、GETXMLファンクションをコールするたびに、任意の行数をスキップしてからXML出力を生成します。このプロシージャは、ステートレスWebページ用にページ番号付きの結果を生成する場合に使用します。たとえば、XMLまたはHTMLデータの最初のページを生成する場合は、skipRowsを0（ゼロ）に設定します。2ページ以降の場合、skipRowsには最初のページで取得した行数を設定します。詳細は、GETNUMROWSPROCESSEDファンクションを参照してください。
構文
DBMS_XMLGEN.SETSKIPROWS ( ctx IN ctxHandle, skipRows IN NUMBER);
パラメータ
表156-14 SETSKIPROWSプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
実行した問合せに対応するコンテキスト・ハンドル。 |
|
|
|
このプロシージャは、コレクション要素のデフォルト名を上書きします。コレクション要素のデフォルト名は、そのタイプ名です。
構文
DBMS_XMLGEN.USEITEMTAGSFORCOLL ( ctx IN ctxHandle);
パラメータ
使用上の注意
このプロシージャを使用すると、デフォルトに上書きして_ITEMタグを追加した列名を使用できます。NUMBERのコレクションがある場合、コレクション要素のデフォルトのタグ名はNUMBERです。
このプロシージャでは、NULLを示すためにXML属性を使用するか、XML文書で特定のエンティティのインクルードを省略するかどうかを指定します。このプロシージャは、SETNULLHANDLINGプロシージャのショートカットとして使用します。
構文
DBMS_XMLGEN.USENULLATTRIBUTEINDICATOR( ctx IN ctxType, attrind IN BOOLEAN := TRUE);
パラメータ
