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パッケージおよびタイプ・リファレンス』または『Oracle Database 26ai PL/SQLパッケージおよびタイプ・リファレンス』のDBMS_PIPEを参照してください。
DBMS_PIPEシングルトン・パイプの概要
パイプ機能には、複数の潜在的なアプリケーション(外部サービス・インタフェース、デバッグ、独立したトランザクションおよびアラート)があります。
Autonomous AI Databaseでは、DBMS_PIPEパッケージにシングルトン・パイプをサポートする拡張機能があります。詳細は、『Oracle Database 19c PL/SQLパッケージおよびタイプ・リファレンス』または『Oracle Database 26ai PL/SQLパッケージおよびタイプ・リファレンス』のDBMS_PIPEを参照してください。
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サブプログラムを示し、簡単に説明しています。
表- DBMS_PIPEパッケージのサブプログラム
| サブプログラム | 説明 |
|---|---|
|
パイプを作成します(プライベート・パイプの場合は必須です)。 |
|
|
バッファにある次の項目のデータ・タイプを戻します。 |
|
|
ローカル・バッファにメッセージを作成します。 |
|
|
名前付きパイプの内容をパージします。 |
|
|
名前付きパイプからローカル・バッファにメッセージをコピーします。 |
|
|
ローカル・バッファの内容をパージします。 |
|
|
名前付きパイプを削除します。 |
|
|
メッセージを名前付きパイプに送信します。名前付きパイプが存在しない場合は、パブリック・パイプが暗黙的に作成されます。 |
|
|
UNIQUE_SESSION_NAMEファンクション
|
一意のセッション名を戻します。 |
|
バッファにある次の項目にアクセスします。 |
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
表- CREATE_PIPEファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
作成するパイプの名前。
注意: |
|
|
パイプの最大サイズ(バイト単位)。 パイプ上のすべてのメッセージの合計サイズは、この数を超えることはできません。この最大値を超えると、そのメッセージはブロックされます。 デフォルトの パイプの デフォルトの |
|
|
デフォルトの パブリック・パイプは、 |
|
|
シングルトン・パイプを作成するには、 デフォルト値: |
|
|
シングルトン・パイプにキャッシュされるメッセージの失効時間(秒)。指定した デフォルトは |
戻り値
表- CREATE_PIPEファンクションの戻り値
| 戻り | 説明 |
|---|---|
|
|
成功 パイプがすでに存在し、パイプを作成しようとするユーザーにそのパイプの使用が認可されている場合、Oracleは0(ゼロ)を戻して成功であることを示し、パイプ内のデータはそのまま残ります。 |
|
|
既存のパイプをシングルトン・パイプに変換できませんでした。
|
|
|
|
|
|
命名競合のために失敗。 同じ名前のパイプが存在し、別のユーザーがそのパイプを作成した場合、Oracleではエラー |
例外
表- CREATE_PIPEファンクションの例外
| 例外 | 説明 |
|---|---|
|
|
アクセス権エラー: 同名のパイプが存在するため使用できません。 |
例
シェルフが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ファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
メッセージを受信するパイプ名。
|
|
|
メッセージを待つ時間(秒単位)。タイムアウトを0(ゼロ)に指定すると、ブロックされずに読み込むことができます。 タイムアウトには、 デフォルト値: 定数 |
|
|
シングルトンパイプにメッセージを自動的にキャッシュするためのキャッシュ関数名。 ファンクションの名前は、所有者スキーマで完全修飾されている必要があります:
デフォルト値: |
戻り値
表- RECEIVE_MESSAGEファンクションの戻り値
| 戻り | 説明 |
|---|---|
|
|
成功 |
|
|
タイムアウト暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。 |
|
|
パイプにあるレコードが、バッファに対して大きすぎます。 |
|
|
割込みが発生しました |
8 |
キャッシュ関数は、シングルトンパイプを使用している場合にのみ指定できます。 |
|
|
パイプから読み込むための十分な権限がユーザーにありません。 |
使用上のノート
パイプからメッセージを受信するには、最初にRECEIVE_MESSAGEをコールします。メッセージを受信すると、メッセージはパイプから削除されるため、メッセージは1回しか受信できません。暗黙的に作成されたパイプは、最後のレコードがそのパイプから削除された後で削除されます。
RECEIVE_MESSAGEのコール時に指定したパイプがすでに存在しない場合、Oracleはパイプを暗黙的に作成してメッセージの受信を待ちます。メッセージが指定したタイムアウト時間内に着信しなかった場合、そのコールは戻され、パイプは削除されます。
メッセージの受信後、1つ以上のUNPACK_MESSAGEをコールして、メッセージ内の個別の項目にアクセスする必要があります。UNPACK_MESSAGEプロシージャは、DATE、NUMBER、VARCHAR2タイプの項目をアンパックするためにオーバーロードされ、さらに、RAWおよびROWID項目をアンパックするための2つのプロシージャがあります。アンパックするデータのタイプが不明の場合は、NEXT_ITEM_TYPEをコールして、バッファ内にある次の項目のタイプを判別します。
キャッシュ関数パラメータ
シングルトン・パイプは、次の2つのシナリオの場合に、パイプにメッセージを自動的にキャッシュするキャッシュ機能をサポートしています。
- シングルトン・パイプが空
shelflife時間が経過したため、シングルトン・パイプのメッセージが無効です。
ファンクションの名前は、所有者スキーマで完全修飾されている必要があります:
OWNER.FUNCTION_NAMEOWNER.PACKAGE.FUNCTION_NAME
キャッシュ・ファンクションを使用するには、DBMS_PIPE.RECEIVE_MESSAGEを起動する現在のセッション・ユーザーに、キャッシュ・ファンクションの実行に必要な権限が必要です。
キャッシュ関数の構文
CREATE OR REPLACE FUNCTION cache_function_name (
pipename IN VARCHAR2
) RETURN INTEGER;| パラメータ | データ型 | 説明 |
|---|---|---|
|
|
VARCHAR2 |
シングルトンパイプの名前。 |
| 戻り | 説明 |
|---|---|
| 0 | 成功 |
| 0以外 | DBMS_PIPE.RECEIVE_MESSAGEから返される失敗値 |
シングルトンパイプのリーダセッションからの複雑なカプセル化と抽象化を提供するキャッシュ関数を定義します。キャッシュ・ファンクションの一般的な操作は次のとおりです。
DBMS_PIPE.CREATE_PIPEを使用して、明示パイプ用のシングルトン・パイプを作成します。- シングルトンパイプにキャッシュするメッセージを作成します。
- メッセージをシングルトン・パイプに送信します。オプションで、暗黙的メッセージに
shelflifeを指定します。
例外
表- RECEIVE_MESSAGEファンクションの例外
| 例外 | 説明 |
|---|---|
|
|
権限エラーパイプからレコードを削除するための権限がありません。パイプは別のユーザーが所有しています。 |
例
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値は、CREATE_PIPEファンクションの明示的シングルトン・パイプに指定されたshelflifeを上書きし、シングルトン・パイプにキャッシュされる新しいメッセージのデフォルトになります。
構文
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ファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
メッセージを設定するパイプの名前。 明示的なパイプを使用している場合、この名前は、 注意: |
|
|
パイプにメッセージを設定する間の待機時間(秒単位)。 デフォルト値は定数 |
|
|
パイプの最大サイズ(バイト単位)。 パイプ上のすべてのメッセージの合計サイズは、この数を超えることはできません。この最大値を超えると、そのメッセージはブロックされます。デフォルトは65536バイトです。 パイプの
デフォルトの |
|
|
シングルトン・パイプを作成するには、 デフォルト値: |
|
|
シングルトン・パイプにキャッシュされるメッセージの失効時間(秒)。 指定した デフォルトは |
戻り値
表- SEND_MESSAGEファンクションの戻り値
| 戻り | 説明 |
|---|---|
|
|
成功 パイプがすでに存在し、パイプを作成しようとするユーザーにそのパイプの使用が認可されている場合、Oracleは0(ゼロ)を戻して成功であることを示し、パイプ内のデータはそのまま残ります。
|
|
|
タイムアウト このプロシージャは、パイプでロックが取得できないか、またはパイプがいっぱいで使用できない理由でタイムアウトできます。暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。 |
|
|
割込みが発生しました 暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。 |
|
|
既存のパイプをシングルトン・パイプに変換できませんでした。
|
|
|
|
|
|
権限がありません 同じ名前のパイプが存在し、別のユーザーがそのパイプを作成した場合、Oracleではエラー |
例外
表- SEND_MESSAGEファンクションの例外
| 例外 | 説明 |
|---|---|
|
|
権限エラーパイプに書込みを行うための権限が不十分です。パイプはプライベートで、別のユーザーが所有しています。 |