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);
パラメータ