DBMS_PIPEパッケージ(シングルトン・パイプ)

DBMS_PIPEパッケージによって、同じインスタンスにある複数のセッションの通信を行います。

Oracle Autonomous Database on Dedicated Exadata Infrastructureでは、Oracle Database 19cで使用可能なコアDBMS_PIPE機能と拡張機能がサポートされています。

Oracle Databaseで提供されるコアDBMS_PIPE機能の詳細は、『Oracle Database 19c PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』または『Oracle Database 23ai PL/SQLパッケージおよびタイプ・リファレンス』のDBMS_PIPEを参照してください。

関連項目

シングルトン・パイプを使用したメッセージのキャッシュ

DBMS_PIPEシングルトン・パイプの概要

パイプ機能には、複数の潜在的なアプリケーション(外部サービス・インタフェース、デバッグ、独立したトランザクションおよびアラート)があります。

Autonomous Databaseでは、DBMS_PIPEパッケージに、シングルトン・パイプをサポートするための拡張機能があります。詳細は、『Oracle Database 19c PL/SQLパッケージ・アンド・タイプ・リファレンス』のDBMS_PIPEまたは『Oracle Database 23ai 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サブプログラムを示し、簡単に説明しています。

表- DBMS_PIPEパッケージのサブプログラム

サブプログラム	説明
CREATE_PIPEファンクション	パイプを作成します(プライベート・パイプの場合は必須です)。
NEXT_ITEM_TYPEファンクション Oracle Database 19c PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス Oracle Database 23ai PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス	バッファにある次の項目のデータ・タイプを戻します。
PACK_MESSAGEプロシージャ Oracle Database 19c PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス Oracle Database 23ai PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス	ローカル・バッファにメッセージを作成します。
PURGEプロシージャ Oracle Database 19c PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス Oracle Database 23ai PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス	名前付きパイプの内容をパージします。
RECEIVE_MESSAGEファンクション	名前付きパイプからローカル・バッファにメッセージをコピーします。
RESET_BUFFERプロシージャ Oracle Database 19c PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス Oracle Database 23ai PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス	ローカル・バッファの内容をパージします。
REMOVE_PIPEファンクション Oracle Database 19c PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス Oracle Database 23ai PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス	名前付きパイプを削除します。
SEND_MESSAGEファンクション	メッセージを名前付きパイプに送信します。名前付きパイプが存在しない場合は、パブリック・パイプが暗黙的に作成されます。
UNIQUE_SESSION_NAMEファンクション Oracle Database 19c PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス Oracle Database 23ai PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス	一意のセッション名を戻します。
UNPACK_MESSAGEプロシージャ Oracle Database 19c PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス Oracle Database 23ai PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス	バッファにある次の項目にアクセスします。

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ファンクションのパラメータ

パラメータ	説明
`pipename`	作成するパイプの名前。 `SEND_MESSAGE`および`RECEIVE_MESSAGE`をコールするときは、この名前を使用する必要があります。この名前は、インスタンス間で一意である必要があります。注意: `ORA$`で始まるパイプ名を使用しないでください。これらは、Oracleが提供するプロシージャで使用するために予約されています。パイプ名は128バイト以下で指定し、大/小文字区別がありません。現時点では、名前にグローバリゼーション・サポート文字を含めることはできません。
`maxpipesize`	パイプの最大サイズ(バイト単位)。パイプ上のすべてのメッセージの合計サイズは、この数を超えることはできません。この最大値を超えると、そのメッセージはブロックされます。デフォルトの`maxpipesize`は66536バイトです。パイプの`maxpipesize`はパイプ特性の一部となり、パイプが存続するかぎり有効です。これより大きいパイプ・サイズで`SEND_MESSAGE`をコールすると、`maxpipesize`の値が大きくなります。これより小さいサイズでコールした場合は、より大きい既存の値を使用します。デフォルトの`maxpipesize` 65536は、すべてのパイプに適用できます。
`private`	デフォルトの`TRUE`を使用して、プライベート・パイプを作成します。パブリック・パイプは、`SEND_MESSAGE`をコールして、暗黙的に作成できます。
`singleton`	シングルトン・パイプを作成するには、`TRUE`を使用します。デフォルト値: `FALSE`
`shelflife`	シングルトン・パイプにキャッシュされるメッセージの失効時間(秒)。指定した`shelflife`時間が経過すると、メッセージはパイプからアクセスできなくなります。パラメータ`shelflife`は、シングルトン・パイプにのみ適用されます。デフォルトは`0`で、メッセージの有効期限がないことを示します。

戻り値

表- CREATE_PIPEファンクションの戻り値

戻り	説明
`0`	成功パイプがすでに存在し、パイプを作成しようとするユーザーにそのパイプの使用が認可されている場合、Oracleは0(ゼロ)を戻して成功であることを示し、パイプ内のデータはそのまま残ります。
`6`	既存のパイプをシングルトン・パイプに変換できませんでした。複数の既存のメッセージがある暗黙的パイプは、シングルトン・パイプに変換できません。シングルトンではない明示的なパイプの場合、`DBMS_PIPE.SEND_MESSAGE`ではsingleton引数を`TRUE`に設定したメッセージを送信できません。
`7`	`shelflife`パラメータに0以外の値が与えられ、パイプはシングルトン・パイプではありません。
`ORA-23322`	命名競合のために失敗。同じ名前のパイプが存在し、別のユーザーがそのパイプを作成した場合、Oracleではエラー`ORA-23322`を通知して命名競合であることを示しています。

例外

表- CREATE_PIPEファンクションの例外

例外	説明
`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`	メッセージを受信するパイプ名。 `ORA$`で始まる名前は、Oracleで使用するために予約されています。
`timeout`	メッセージを待つ時間(秒単位)。タイムアウトを0(ゼロ)に指定すると、ブロックされずに読み込むことができます。タイムアウトには、`cache_func`パラメータで指定された実行キャッシュ関数に費やされた時間は含まれません。デフォルト値: 定数`MAXWAIT`で、8640000000(1000日)に定義されています。
`cache_func`	シングルトンパイプにメッセージを自動的にキャッシュするためのキャッシュ関数名。ファンクションの名前は、所有者スキーマで完全修飾されている必要があります: `OWNER.FUNCTION_NAME` `OWNER.PACKAGE.FUNCTION_NAME` デフォルト値: `NULL`

pipename

メッセージを受信するパイプ名。

ORA$で始まる名前は、Oracleで使用するために予約されています。

timeout

メッセージを待つ時間(秒単位)。タイムアウトを0(ゼロ)に指定すると、ブロックされずに読み込むことができます。

タイムアウトには、cache_funcパラメータで指定された実行キャッシュ関数に費やされた時間は含まれません。

デフォルト値: 定数MAXWAITで、8640000000(1000日)に定義されています。

cache_func

シングルトンパイプにメッセージを自動的にキャッシュするためのキャッシュ関数名。

ファンクションの名前は、所有者スキーマで完全修飾されている必要があります:

OWNER.FUNCTION_NAME
OWNER.PACKAGE.FUNCTION_NAME

デフォルト値: NULL

戻り値

表- 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を指定します。

例外

表- RECEIVE_MESSAGEファンクションの例外

例外	説明
`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値は、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ファンクションのパラメータ

パラメータ	説明
`pipename`	メッセージを設定するパイプの名前。明示的なパイプを使用している場合、この名前は、`CREATE_PIPE`をコールしたときに指定した名前です。注意: `ORA$`で始まるパイプ名を使用しないでください。これは、オラクル社が提供する製品用に予約されています。パイプ名は128バイト以下で指定し、大/小文字は区別されません。現時点では、名前にグローバリゼーション・サポート文字を含めることはできません。
`timeout`	パイプにメッセージを設定する間の待機時間(秒単位)。デフォルト値は定数`MAXWAIT`で、86400000(1000日)に定義されています。
`maxpipesize`	パイプの最大サイズ(バイト単位)。パイプ上のすべてのメッセージの合計サイズは、この数を超えることはできません。この最大値を超えると、そのメッセージはブロックされます。デフォルトは65536バイトです。パイプの`maxpipesize`はパイプ特性の一部となり、パイプが存続するかぎり有効です。これより大きいパイプ・サイズで`SEND_MESSAGE`をコールすると、`maxpipesize`の値が大きくなります。これより小さいサイズでコールした場合は、より大きい既存の値を使用します。 `SEND_MESSAGE`プロシージャの一部として`maxpipesize`を指定すると、別のコールでパイプをオープンする必要がなくなります。明示的にパイプを作成した場合は、オプションの`maxpipesize`パラメータを使用して、作成したパイプのサイズを上書きできます。デフォルトの`maxpipesize` 65536は、すべてのパイプに適用できます。
`singleton`	シングルトン・パイプを作成するには、`TRUE`を使用します。デフォルト値: `FALSE`
`shelflife`	シングルトン・パイプにキャッシュされるメッセージの失効時間(秒)。指定した`shelflife`時間が経過すると、メッセージはパイプからアクセスできなくなります。パラメータ`shelflife`は、シングルトン・パイプにのみ適用されます。デフォルトは`0`で、メッセージの有効期限がないことを示します。

戻り値

表- SEND_MESSAGEファンクションの戻り値

戻り	説明
`0`	成功パイプがすでに存在し、パイプを作成しようとするユーザーにそのパイプの使用が認可されている場合、Oracleは0(ゼロ)を戻して成功であることを示し、パイプ内のデータはそのまま残ります。 `SYSDBS`/`SYSOPER`として接続したユーザーがパイプを再作成した場合、Oracleはステータス0(ゼロ)を戻しますが、そのパイプの所有者は変更されないままです。
`1`	タイムアウトこのプロシージャは、パイプでロックが取得できないか、またはパイプがいっぱいで使用できない理由でタイムアウトできます。暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。
`3`	割込みが発生しました暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。
`6`	既存のパイプをシングルトン・パイプに変換できませんでした。複数の既存のメッセージがある暗黙的パイプは、シングルトン・パイプに変換できません。シングルトンではない明示的なパイプの場合、`DBMS_PIPE.SEND_MESSAGE`ではsingleton引数を`TRUE`に設定したメッセージを送信できません。
`7`	`shelflife`パラメータに0以外の値が与えられ、パイプはシングルトン・パイプではありません。
`ORA-23322`	権限がありません同じ名前のパイプが存在し、別のユーザーがそのパイプを作成した場合、Oracleではエラー`ORA-23322`を通知して命名競合であることを示しています。

例外

表- SEND_MESSAGEファンクションの例外

例外	説明
`Null pipe name`	権限エラーパイプに書込みを行うための権限が不十分です。パイプはプライベートで、別のユーザーが所有しています。

タイトルおよび著作権情報

Oracle and/or its affiliates.