サーバー上の出力のリダイレクトについて

Oracle JVMの出力先をさらに広範囲にわたって制御するために、SQL文にJava出力を渡すことができます。PL/SQLのパッケージDBMS_JAVAは次の新しいファンクションを追加することで拡張され、これにより、以前はDBMS_JAVA.SET_OUTPUTプロシージャでのみ使用可能であった機能が拡張されています。

set_output_to_sql

set_output_to_sqlは、デフォルトのSystem.outおよびSystem.errへの出力ストリームが発生すると、SQL文の実行命令で構成される指定の出力仕様を定義します。この仕様は、現在のセッションの期間内、またはremove_output_to_sqlファンクションがそのIDでコールされるまで定義されます。Java出力がある場合、仕様で規定されたSQLアクションが実行されます。これを停止するにはdisable_output_to_sqlファンクションをコールし、開始するにはenable_output_to_sqlファンクションをコールします。このファンクションの戻り値は、正常に実行された場合はNULL、それ以外はエラー・メッセージになります。

FUNCTION set_output_to_sql (id VARCHAR2,
stmt VARCHAR2,
bindings VARCHAR2,
no_newline_stmt VARCHAR2 default null,
no_newline_bindings VARCHAR2 default null,
newline_only_stmt VARCHAR2 default null,
newline_only_bindings VARCHAR2 default null,
maximum_line_segment_length NUMBER default 0,
allow_replace NUMBER default 1,
from_stdout NUMBER default 1,
from_stderr NUMBER default 1,
include_newlines NUMBER default 0,
eager NUMBER default 0) return VARCHAR2;

表3-2に、set_output_to_sqlファンクションが取る引数を示します。

表3-2 set_output_to_sqlの引数の概要

引数	説明
id	仕様の名前。同じセッションで複数の仕様を使用できますが、それぞれに個別のIDが必要です。このIDを使用して、`remove_output_to_sql、enable_output_to_sql、disable_output_to_sql`および`query_output_to_sql`の各ファンクションで仕様を識別します。
stmt	Java出力が発生した場合に実行するデフォルトのSQL文。
bindings	セットID、TEXT、LENGTH、LINENO、SEGNO、NLおよびERROUTからのトークンを含む文字列。この文字列は、SQL文`stmt`がバインドされる方法を定義します。bindings文字列でのトークンの位置は、SQL文でのバインドの位置に相当します。トークンの意味は次のとおりです。 IDは仕様のIDです。VARCHAR2でバインドされます。 TEXTは出力されるテキストです。VARCHAR2でバインドされます。 LENGTHはテキストの長さです。NUMBERでバインドされます。 LINENOは、セッション出力の開始以降の行番号です。NUMBERでバインドされます。 SEGNOは、複数の要素で出力される行内のセグメント番号です。NUMBERでバインドされます。 NLは、テキストが改行で終わるとみなされるかどうかを示すブール値です。NUMBERでバインドされます。引数`include_newlines`の値に応じて、改行が実際にテキストに含まれる場合と含まれない場合があります。 ERROUTは、出力が`System.out`または`System.err`のどちらからであるかを示すブール値です。NUMBERでバインドされます。`System.out`からの出力の場合、値は0です。
no_newline_stmt	出力が改行で終わらない場合に実行するオプションの代替SQL文。
no_newline_bindings	前述のbindings引数と同じ構文を使用する文字列。`no_newline_stmt`がバインドされる方法を示します。
newline_only_stmt	出力が1つの改行の場合に実行するオプションの代替SQL文。
newline_only_bindings	前述のbindings引数と同じ構文を使用する文字列。`newline_only_stmt`がバインドされる方法を示します。
maximum_line_segment_length	指定されたSQL文の実行でバインドされる最大文字数。出力シーケンスが長い場合、識別可能なSEGNO値によって個々のコールに分けられます。値0は`no maximum`を表します。
allow_replace	同じIDの仕様が以前に定義されている場合の動作を制御します。値1は、古い仕様を置き換えます。0は、古い仕様を変更せずにエラー・メッセージを戻します。
from_stdout	`System.out`からの出力によって、仕様で規定されたSQL文が実行されるかどうかを制御します。値0は、`System.out`からの出力であった場合、それ以外で仕様が有効であったとしても、文が実行されないことを示します。
from_stderr	`System.err`からの出力によって、仕様で規定されたSQL文が実行されるかどうかを制御します。値0は、`System.err`からの出力であった場合、それ以外で仕様が有効であったとしても、文が実行されないことを示します。
include_newlines	改行文字がテキストにバインドされる場合、それらの文字が出力に残るかどうかを制御します。値0は改行が含まれないことを示します。ただし、改行が存在するかどうかは、NLバインディングや`no_newline_stmt`が使用されていることからもわかります。
eager	改行で終了しない出力により、改行を受け取るたびにSQL文を実行するかどうかを制御するか、または、改行を受け取るまでこのような出力を蓄積します。値0は、終了しない出力が蓄積されることを示します。

remove_output_to_sql

remove_output_to_sqlは、set_output_to_sqlで作成された仕様を削除します。このような仕様がない場合は、エラー・メッセージが戻されます。

FUNCTION remove_output_to_sql (id VARCHAR2) return VARCHAR2;

enable_output_to_sql

enable_output_to_sqlは、set_output_to_sqlで作成された後、disable_output_to_sqlで無効化された仕様を再度有効にします。このような仕様がない場合は、エラー・メッセージが戻されます。現在、仕様が無効ではない場合、変更はありません。

FUNCTION enable_output_to_sql (id VARCHAR2) return VARCHAR2;

disable_output_to_sql

disable_output_to_sqlは、set_output_to_sqlで作成された仕様を無効にします。仕様を有効にするには、enable_output_to_sqlをコールします。無効になっている間、仕様で規定されたSQL文は実行されません。このような仕様がない場合は、エラー・メッセージが戻されます。仕様がすでに無効の場合、変更はありません。

FUNCTION disable_output_to_sql (id VARCHAR2) return VARCHAR2;

query_output_to_sql

query_output_to_sqlは、set_output_to_sqlで作成された仕様を説明するメッセージを戻します。このような仕様がない場合は、エラー・メッセージが戻されます。このファンクションにnullを渡すと、既存のすべての仕様が表示されます。

FUNCTION query_output_to_sql (id VARCHAR2) return VARCHAR2;

Oracle JVMからの出力先を制御するには、自律型JavaセッションにJava出力を渡す方法もあります。これは、ディスク・ファイル、ソケットおよびURLなどの各種ターゲットに出力を伝播する一般的なメカニズムを提供します。ただし、出力を処理するJavaセッションはメイン・セッションとは論理的に異なるため、セッション間でその他の不要な相互作用はない点に注意する必要があります。これを実行するために、PL/SQLのパッケージDBMS_JAVAには次のファンクションが用意されています。

set_output_to_java

set_output_to_javaは、デフォルトのSystem.outおよびSystem.errへの出力ストリームが発生すると、Javaメソッドを実行する命令を与える指定の出力仕様を定義します。仕様で規定されたJavaメソッドは、セッションの残りの部分とは別のJavaセッションの状態を持つ別のVMコンテキストで実行されます。

FUNCTION set_output_to_java (id VARCHAR2,
class_name VARCHAR2,
class_schema VARCHAR2,
method VARCHAR2,
bindings VARCHAR2,
no_newline_method VARCHAR2 default null,
no_newline_bindings VARCHAR2 default null,
newline_only_method VARCHAR2 default null,
newline_only_bindings VARCHAR2 default null,
maximum_line_segment_length NUMBER default 0,
allow_replace NUMBER default 1,
from_stdout NUMBER default 1,
from_stderr NUMBER default 1,
include_newlines NUMBER default 0,
eager NUMBER default 0,
initialization_statement VARCHAR2 default null,
finalization_statement VARCHAR2 default null)return VARCHAR2;

表3-3に、set_output_to_javaメソッドが取る引数を示します。

表3-3 set_output_to_javaの引数の概要

引数	説明
class_name	1つ以上のメソッドを定義するクラスの名前。
class_schema	クラスが定義されるスキーマ。NULL値は、現行スキーマまたはPUBLICでクラスが定義されることを示します。
method	メソッドの名前。
bindings	メソッドの引数がバインドされる方法を定義する文字列。これは、`set_output_to_sql`と同じ構文を使用するトークンの文字列です。文字列内のトークンの位置によって、そのトークンが表す引数の位置が決まります。`java.lang.String`型であるIDまたはTEXTのトークンに相当する引数を除き、すべての引数はINT型です。
no_newline_method	出力が改行で終わらない場合に実行するオプションの代替メソッド。
newline_only_method	出力が1つの改行の場合に実行するオプションの代替メソッド。
initialization_statement	出力を受け取るメソッドを最初に実行する前に、Javaセッションごとに1回実行されるオプションのSQL文。この文は、出力メソッドが実行されるのと同じJava VMコンテキストで実行されます。通常、このような文は、出力を受け取るメソッドが予定どおりに機能するように、別のVMコンテキストで条件を初期化するJavaストアド・プロシージャを実行する際に使用します。たとえば、このようなプロシージャは、出力メソッドによって書き込まれるストリームを開きます。
finalization_statement	出力仕様が削除される直前、またはセッションが終了するときに1回実行されるオプションのSQL文。`initialization_statement`と同様、出力を受け取るメソッドと同じJVMコンテキストで実行されます。初期化メソッドを実行した場合のみ、または初期化メソッドがない場合に実行されます。

remove_output_to_java

remove_output_to_javaは、set_output_to_javaで作成された仕様を削除します。このような仕様がない場合、エラー・メッセージが戻されます。

FUNCTION remove_output_to_java (id VARCHAR2) return VARCHAR2;

enable_output_to_java

enable_output_to_javaは、set_output_to_javaで作成された後、disable_output_to_javaで無効化された仕様を再度有効にします。このような仕様がない場合は、エラー・メッセージが戻されます。現在、仕様が無効ではない場合、変更はありません。

FUNCTION enable_output_to_java (id VARCHAR2) return VARCHAR2;

disable_output_to_java

disable_output_to_javaは、set_output_to_javaで作成された仕様を無効にします。仕様は、enable_output_to_javaで再度有効にできます。無効になっている間、仕様で規定されたSQL文は実行されません。このような仕様がない場合は、エラー・メッセージが戻されます。仕様がすでに無効の場合、変更はありません。

FUNCTION disable_output_to_java (id VARCHAR2) return VARCHAR2;

query_output_to_java

query_output_to_javaは、set_output_to_javaで作成された仕様を説明するメッセージを戻します。このような仕様がない場合は、エラー・メッセージが戻されます。このファンクションにnullを渡すと、既存のすべての仕様が表示されます。

FUNCTION query_output_to_java (id VARCHAR2) return VARCHAR2;

set_output_to_file

set_output_to_fileは、デフォルトのSystem.outおよびSystem.errに送信された出力ストリームを捕捉し、これを特定のファイルに追加する命令で構成された指定の出力仕様を定義します。これを実装するには、特殊なset_output_to_javaを使用します。引数file_pathは、出力の追加先のファイルのパスを指定します。引数allow_replace、from_stdoutおよびfrom_stderrは、set_output_to_sqlの同じ名前の引数と類似しています。

FUNCTION set_output_to_file (id VARCHAR2,
file_path VARCHAR2,
allow_replace NUMBER default 1,
from_stdout NUMBER default 1,
from_stderr NUMBER default 1) return VARCHAR2;

remove_output_to_file

このファンクションは、remove_output_to_javaと似ています。

FUNCTION remove_output_to_file (id VARCHAR2) return VARCHAR2;

enable_output_to_file

このファンクションは、enable_output_to_javaと似ています。

FUNCTION enable_output_to_file (id VARCHAR2) return VARCHAR2;

disable_output_to_file

このファンクションは、disable_output_to_javaと似ています。

FUNCTION disable_output_to_file (id VARCHAR2) return VARCHAR2;

query_output_to_file

このファンクションは、query_output_to_javaと似ています。

FUNCTION query_output_to_file (id VARCHAR2) return VARCHAR2;

次のDBMS_JAVAファンクションは、.trcファイルにJava出力が表示されるかどうかを制御します。

PROCEDURE enable_output_to_trc;
PROCEDURE disable_output_to_trc;
FUNCTION query_output_to_trc return VARCHAR2;

注意:

11gリリース1 (11.1)以前は、.trcファイルに表示されるJava出力は変更できませんでした。

SQL*Plusテキスト・バッファへの出力のリダイレクト

以前のリリースと同様、DBMS_JAVAパッケージのプロシージャSET_OUTPUTを使用して、SQL*Plusテキスト・バッファに出力をリダイレクトできます。

SQL> SET SERVEROUTPUT ON
SQL> CALL dbms_java.set_output(2000);

最小(デフォルト)バッファ・サイズは2,000バイトで、最大サイズは1,000,000バイトです。次の例では、バッファ・サイズを5,000バイトに増やしています。

SQL> SET SERVEROUTPUT ON SIZE 5000
SQL> CALL dbms_java.set_output(5000);

出力は、コール終了時に表示されます。