DBMS_PIPEパッケージ(シングルトン・パイプ)
DBMS_PIPEパッケージによって、同じインスタンスにある複数のセッションの通信を行います。
Oracle Autonomous AI Database on Dedicated Exadata Infrastructureは、Oracle Database 19cで使用可能なコアDBMS_PIPE機能と拡張機能をサポートしています。
Oracle Databaseで提供されるDBMS_PIPEのコア機能の詳細は、『Oracle Database 19c PL/SQLパッケージおよびタイプ・リファレンス』のDBMS_PIPEに関する項または『Oracle Database 26ai PL/SQLパッケージおよびタイプ・リファレンス』を参照してください。
シングルトン・パイプのDBMS_PIPEの概要
パイプ機能には、外部サービス・インタフェース、デバッグ、独立したトランザクションおよびアラートなど、いくつかの潜在的なアプリケーションがあります。
Autonomous AI Databaseでは、DBMS_PIPEパッケージにシングルトン・パイプをサポートする拡張機能があります。詳細は、『Oracle Database 19c PL/SQLパッケージおよびタイプ・リファレンス』のDBMS_PIPEに関する項または『Oracle Database 26ai PL/SQLパッケージおよびタイプ・リファレンス』を参照してください。
DBMS_PIPEのシングルトン・パイプ機能には、次のものがあります。
-
Oracleデータベース・メモリーで最大32,767バイトのカスタム・メッセージをキャッシュおよび取得する機能。メッセージ・サイズの最大値は32,767バイトで、シングルトン・パイプを含むすべてのパイプに適用できます。以前のバージョンの
DBMS_PIPEでは、最大メッセージ・サイズが小さくなりました。 -
キャッシュされたメッセージを複数のデータベース・セッション間で同時読取りで共有します。
-
キャッシュ無効化メソッド:
-
ユーザーが制御する明示的なキャッシュ無効化。
-
ユーザー指定のパラメータ(
shelflife)の時間間隔(秒)後のキャッシュ無効化。
-
-
キャッシュ用に宣言的で使いやすいPL/SQL API。
-
読取り専用データベースと読取り/書込みデータベースの両方をサポートします。
シングルトン・パイプは、サポートされているDBMS_PIPEタイプのいずれかです。
-
暗黙的パイプ:
DBMS_PIPE.SEND_MESSAGE関数を使用して不明なパイプ名でメッセージが送信されると、自動的に作成されます。 -
明示パイプ:ユーザー指定のパイプ名を持つ
DBMS_PIPE.CREATE_PIPEファンクションを使用して作成されます。 -
パブリック・パイプ:
DBMS_PIPEパッケージに対するEXECUTE権限を持つすべてのユーザーがアクセスできます -
プライベート・パイプ:パイプ作成者と同じユーザーを持つセッションからアクセスできます。
シングルトン・パイプのDBMS_PIPEサブプログラムの要約
この表は、DBMS_PIPEサブプログラムを示し、簡単に説明しています。
| サブプログラム | 説明 |
|---|---|
| CREATE_PIPEファンクション | パイプを作成します(プライベート・パイプの場合は必須です) |
| NEXT_ITEM_TYPEファンクション |
バッファにある次の項目のデータ型を戻します。 |
| PACK_MESSAGEプロシージャ |
ローカル・バッファにメッセージを作成します。 |
| PURGEプロシージャ |
名前付きパイプの内容をパージします。 |
| RECEIVE_MESSAGEファンクション | 名前付きパイプからローカル・バッファにメッセージをコピーします。 |
| RESET_BUFFERプロシージャ |
ローカル・バッファの内容をパージします。 |
| REMOVE_PIPEファンクション |
名前付きパイプを削除します。 |
| SEND_MESSAGEファンクション | メッセージを名前付きパイプに送信します。名前付きパイプが存在しない場合は、パブリック・パイプが暗黙的に作成されます。 |
| UNIQUE_SESSION_NAMEファンクション |
一意のセッション名を戻します。 |
| UNPACK_MESSAGEプロシージャ |
バッファにある次の項目にアクセスします。 |
CREATE_PIPEファンクション
このファンクションは、パブリック・パイプまたはプライベート・パイプを明示的に作成します。privateフラグがTRUEの場合、パイプ作成者が、そのプライベート・パイプの所有者として割り当てられます。
明示的に作成されたパイプは、REMOVE_PIPEをコールするか、またはインスタンスをシャットダウンすることによってのみ削除できます。
シングルトン・パイプを作成するには、singletonパラメータをTRUEに設定します。シングルトン·パイプには、次の引数を適用できます。
-
singleton: パイプをシングルトン・パイプとして作成する必要があることを示します(デフォルト:FALSE)。 -
shelflife: オプションで、シングトン・パイプ内にキャッシュされたメッセージのシェルフ有効期限(秒単位)を指定します。シングトン・パイプ内のメッセージの暗黙的な無効化に使用できます。メッセージ・メッセージを送信する場合は、シングルトン・パイプのメッセージ
shelflifeも指定できます(「SEND_MESSAGEファンクション」を参照)。
構文
DBMS_PIPE.CREATE_PIPE (
pipename IN VARCHAR2,
maxpipesize IN INTEGER DEFAULT 66536,
private IN BOOLEAN DEFAULT TRUE,
singleton IN BOOLEAN DEFAULT FALSE,
shelflife IN INTEGER DEFAULT 0)
RETURN INTEGER;Parameters
| パラメータ | 説明 |
|---|---|
pipename |
作成するパイプの名前。
注意: |
maxpipesize |
パイプの最大サイズ(バイト単位)。 パイプ上のすべてのメッセージの合計サイズは、この数を超えることはできません。この最大値を超えると、そのメッセージはブロックされます。 デフォルトの パイプの デフォルトの |
private |
デフォルトの パブリック・パイプは、 |
singleton |
シングルトン・パイプを作成するには、 デフォルト値: |
shelflife |
シングルトン・パイプにキャッシュされるメッセージの失効時間(秒)。指定された デフォルト値は |
戻り値
| 戻り | 説明 |
|---|---|
0 |
成功 パイプが存在し、パイプを作成するユーザーにそのパイプの使用が認可されている場合、Oracleは0(ゼロ)を戻して成功であることを示し、パイプ内のデータはそのまま残ります。 |
6 |
既存のパイプをシングルトン・パイプに変換できませんでした。
|
7 |
shelflifeパラメータに0以外の値が指定されており、パイプはシングルトン・パイプではありません。 |
ORA-23322 |
命名競合のために失敗。 同じ名前のパイプが存在し、別のユーザーがそのパイプを作成した場合、Oracleではエラー |
例外
| 例外 | 説明 |
|---|---|
Null pipe name |
アクセス権エラー: 同名のパイプが存在するため使用できません。 |
例
シェルフが1時間であるシングルトンパイプを作成します。
DECLARE
l_status INTEGER;
BEGIN
l_status := DBMS_PIPE.create_pipe(pipename => 'MY_PIPE1',
private => TRUE,
singleton => TRUE,
shelflife => 3600);
END;
/RECEIVE_MESSAGEファンクション
このファンクションは、メッセージをローカル・メッセージ・バッファにコピーします。
構文
DBMS_PIPE.RECEIVE_MESSAGE (
pipename IN VARCHAR2,
timeout IN INTEGER DEFAULT maxwait,
cache_func IN VARCHAR2 DEFAULT NULL)
RETURN INTEGER;Parameters
表- RECEIVE_MESSAGEファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
pipename |
メッセージを受信するパイプ名。
|
timeout |
メッセージを待つ時間(秒単位)。タイムアウトを0(ゼロ)に指定すると、ブロックされずに読み込むことができます。 タイムアウトには、 デフォルト値: 定数 |
cache_func |
関数名をキャッシュして、メッセージをシングルトン・パイプに自動的にキャッシュします。 ファンクションの名前は、所有者スキーマで完全修飾されている必要があります:
デフォルト値: |
戻り値
表- RECEIVE_MESSAGEファンクションの戻り値
| 戻り | 説明 |
|---|---|
0 |
成功 |
1 |
タイムアウト暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。 |
2 |
パイプにあるレコードが、バッファに対して大きすぎます。 |
3 |
割込みが発生しました。 |
8 |
キャッシュ関数は、シングルトンパイプを使用している場合にのみ指定できます。 |
ORA-23322 |
パイプから読み込むための十分な権限がユーザーにありません。 |
使用上のノート
-
パイプからメッセージを受信するには、最初に
RECEIVE_MESSAGEをコールします。メッセージを受信すると、メッセージはパイプから削除されます。したがって、メッセージは1回しか受信できません。暗黙的に作成されたパイプは、最後のレコードがパイプから削除された後、パイプが削除されます。 -
RECEIVE_MESSAGEのコール時に指定したパイプがすでに存在しない場合、Oracleはパイプを暗黙的に作成してメッセージの受信を待ちます。メッセージが指定したタイムアウト間隔内に到着しなかった場合、そのコールが戻され、パイプは削除されます。 -
メッセージの受信後、1つ以上の
UNPACK_MESSAGEをコールして、メッセージ内の個別の項目にアクセスする必要があります。UNPACK_MESSAGEプロシージャは、DATE、NUMBER、VARCHAR2タイプの項目をアンパックするためにオーバーロードされ、さらに、RAWおよびROWID項目をアンパックするための2つのプロシージャがあります。アンパックするデータのタイプが不明の場合は、NEXT_ITEM_TYPEをコールして、バッファ内にある次の項目のタイプを判別します。
キャッシュ・ファンクションのパラメータ
シングルトン・パイプでは、次の2つのシナリオの場合に、メッセージをパイプに自動的にキャッシュできます。
-
シングルトン・パイプラインが空です。
-
shelflife時間が経過したため、シングルトン・パイプのメッセージが無効です。
ファンクションの名前は、所有者スキーマで完全修飾されている必要があります:
-
OWNER.FUNCTION_NAME -
OWNER.PACKAGE.FUNCTION_NAME
キャッシュ・ファンクションを使用するには、DBMS_PIPE.RECEIVE_MESSAGEを起動する現在のセッション・ユーザーに、キャッシュ・ファンクションの実行に必須の権限が必要です。
キャッシュ・ファンクションの構文
CREATE OR REPLACE FUNCTION *cache_function_name* (
pipename IN VARCHAR2
) RETURN INTEGER;| パラメータ | データ型 | 説明 |
|---|---|---|
pipename |
VARCHAR2 |
シングトン・パイプの名前。 |
| 戻り | 説明 |
|---|---|
| 0 | 成功 |
| 0 以外 | DBMS_PIPE.RECEIVE_MESSAGEから返される失敗値 |
キャッシュ・ファンクションを定義して、シングルトンのパイプ・リーダー・セッションからの複雑性をカプセル化および抽象化します。キャッシュ・ファンクションでの一般的な操作は次のとおりです:
-
DBMS_PIPE.CREATE_PIPEを使用して、明示的なパイプ用のシングルトン・パイプを作成します。 -
シングルトン・パイプラインにキャッシュするメッセージの作成。
-
シングルトン・パイプへのメッセージ送信(暗黙的メッセージには、
shelflifeをオプションで指定します)
例外
| 例外 | 説明 |
|---|---|
Null pipe name |
権限エラーが発生しました。パイプからレコードを削除するための権限が不十分です。パイプは別のユーザーが所有しています。 |
例
DECLARE
l_status INTEGER;
BEGIN
l_status := DBMS_PIPE.receive_message(pipename => 'MY_PIPE1',
timeout => 1,
cache_func => 'MY_USER.MY_CACHE_FUNC');
END;
/SEND_MESSAGEファンクション
このファンクションは、メッセージを名前付きパイプに送信します。
PACK_MESSAGEへのコールで入力されたメッセージは、ローカル・メッセージ・バッファに格納されます。CREATE_PIPEを使用するとパイプを明示的に作成でき、それ以外の場合は暗黙的に作成されます。
暗黙的シングルトン・パイプを作成するには、singletonパラメータをTRUEに設定します。シングルトン·パイプには、次の引数を適用できます。
-
singleton: パイプをシングルトン・パイプとして作成する必要があることを示します(デフォルト:FALSE)。 -
shelflife: オプションで、シングトン・パイプ内にキャッシュされたメッセージのシェルフ有効期限を指定します。シングトン・パイプ内のメッセージの暗黙的な無効化に使用できます。この引数は、暗黙的および明示的なシングルトン・パイプにも適用できます。SEND_MESSAGEファンクションで指定した
shelflife値は、次の明示的なシングルトン・パイプに指定されたshelflifeを上書きします。
CREATE_PIPEファンクション。シングルトン・パイプにキャッシュされる新しいメッセージのデフォルトになります。
構文
DBMS_PIPE.SEND_MESSAGE (
pipename IN VARCHAR2,
timeout IN INTEGER DEFAULT MAXWAIT,
maxpipesize IN INTEGER DEFAULT 65536,
singleton IN BOOLEAN DEFAULT FALSE,
shelflife IN INTEGER DEFAULT 0)
RETURN INTEGER;Parameters
表- SEND_MESSAGEファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
pipename |
メッセージを設定するパイプの名前。 明示的なパイプを使用している場合、この名前は、 **注意:** ' |
timeout |
パイプにメッセージを設定する間の待機時間(秒単位)。 デフォルト値は定数 |
maxpipesize |
パイプの最大サイズ(バイト単位)。 パイプ上のすべてのメッセージの合計サイズは、この数を超えることはできません。この最大値を超えると、そのメッセージはブロックされます。デフォルトは65536バイト。 パイプの
デフォルトの |
singleton |
シングルトン・パイプを作成するには、 デフォルト値: |
shelflife |
シングルトン・パイプにキャッシュされるメッセージの失効時間(秒)。 指定された デフォルト値は |
戻り値
| 戻り | 説明 |
|---|---|
0 |
成功 パイプが存在し、パイプを作成するユーザーにそのパイプの使用が認可されている場合、Oracleは0(ゼロ)を戻して成功であることを示し、パイプ内のデータはそのまま残ります。
|
1 |
タイムアウト このプロシージャは、管でロックが取得できないか、またはパイプがいっぱいで使用できない理由でタイムアウトすることがあります。暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。 |
3 |
割込みが発生しました。 暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。 |
6 |
既存のパイプをシングルトン・パイプに変換できませんでした。
|
7 |
shelflifeパラメータに0以外の値が指定されており、パイプはシングルトン・パイプではありません。 |
ORA-23322 |
権限が不十分です。 同じ名前のパイプが存在し、別のユーザーがそのパイプを作成した場合、Oracleではエラー |
例外
| 例外 | 説明 |
|---|---|
Null pipe name |
権限エラーが発生しました。パイプに書込みを行うための権限が不十分です。パイプはプライベートで、別のユーザーが所有しています。 |