DBMS_PIPEパッケージ

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

Oracle Autonomous Databaseは、Oracle Database 19cで使用可能なコアDBMS_PIPE機能と拡張機能をサポートしています。

Oracle Databaseで提供されるコアDBMS_PIPE機能の詳細は、DBMS_PIPEを参照してください。

DBMS_PIPEシングルトン・パイプの概要
パイプ機能には、外部サービス・インタフェース、デバッグ、独立したトランザクションおよびアラートなど、いくつかの潜在的なアプリケーションがあります。
シングルトン・パイプのDBMS_PIPEサブプログラムの概要
この表では、DBMS_PIPEサブプログラムを示し、簡単に説明しています。
DBMS_PIPE永続メッセージング・パイプの概要
パイプ機能には、外部サービス・インタフェース、デバッグ、独立したトランザクションおよびアラートなど、いくつかの潜在的なアプリケーションがあります。
永続メッセージングのDBMS_PIPEサブプログラムの概要
この表では、DBMS_PIPEサブプログラムを示し、簡単に説明しています。

親トピック: Autonomous Database提供パッケージ・リファレンス

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

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

Autonomous Databaseでは、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サブプログラムを示し、簡単に説明しています。

表6-1 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の場合、パイプ作成者が、そのプライベート・パイプの所有者として割り当てられます。
RECEIVE_MESSAGEファンクション
このファンクションは、メッセージをローカル・メッセージ・バッファにコピーします。
SEND_MESSAGEファンクション
このファンクションは、メッセージを名前付きパイプに送信します。

親トピック: DBMS_PIPEパッケージ

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;

パラメータ

表6-2 CREATE_PIPEファンクションのパラメータ

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

戻り値

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

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

例外

表6-4 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;
/

親トピック: シングルトン・パイプのDBMS_PIPEサブプログラムの要約

RECEIVE_MESSAGEファンクション

このファンクションは、メッセージをローカル・メッセージ・バッファにコピーします。

構文

DBMS_PIPE.RECEIVE_MESSAGE (
   pipename      IN VARCHAR2,
   timeout       IN INTEGER      DEFAULT maxwait,
   cache_func    IN VARCHAR2     DEFAULT NULL)
RETURN INTEGER;

パラメータ

表6-5 RECEIVE_MESSAGEファンクションのパラメータ

パラメータ摘要

pipename

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

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

timeout

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

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

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

cache_func

シングルトン・パイプにメッセージを自動的にキャッシュするファンクション名をキャッシュします。

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

OWNER.FUNCTION_NAME
OWNER.PACKAGE.FUNCTION_NAME

デフォルト値: NULL

戻り値

表6-6 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をオプションに指定します)

例外

表6-7 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;
/

親トピック: シングルトン・パイプのDBMS_PIPEサブプログラムの要約

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;

パラメータ

表6-8 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`で、メッセージが失効しないことを意味します。

戻り値

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

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

例外

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

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

親トピック: シングルトン・パイプのDBMS_PIPEサブプログラムの要約

DBMS_PIPE永続メッセージング・パイプの概要

Autonomous Databaseでは、DBMS_PIPEパッケージに、永続メッセージング・パイプをサポートするための拡張機能があります。

DBMS_PIPEの永続メッセージ:

非常に大きなメッセージを送信および取得する機能をサポートします。
多数のパイプメッセージをサポートします。
単一のデータベース内、複数のデータベース間、および異なるリージョン内のデータベース間でのメッセージの共有をサポートします。
同じクラウド・オブジェクト・ストアの場所URIを使用する複数のパイプをサポートします。

永続メッセージング機能を使用すると、2つ以上のデータベース・セッションで、クラウド・オブジェクト・ストアに格納されているメッセージと通信できます。パイプでこの機能メッセージを使用すると、現在のデータベースのみが使用できるようにしたり、同じリージョンまたは異なるリージョンの複数のデータベースでメッセージを使用できるようにすることができます。

永続メッセージング・パイプには、サポートされているDBMS_PIPEタイプのいずれかを指定できます。
- 暗黙的パイプ: DBMS_PIPE.SEND_MESSAGE関数を使用して不明なパイプ名でメッセージを送信すると、自動的に作成されます。
- 明示的パイプ:ユーザー指定のパイプ名を持つDBMS_PIPE.CREATE_PIPE関数を使用して作成されます。
- パブリック・パイプ: DBMS_PIPEパッケージに対するEXECUTE権限を持つユーザーがアクセスできます。
- プライベート・パイプ:パイプ作成者と同じユーザーを持つセッションからアクセスできます。

ノート

永続メッセージを使用して異なるデータベース間でメッセージを送受信する場合、Oracleでは、メッセージを送信または受信する前にDBMS_PIPE.CREATE_PIPEをコールすることをお薦めします。DBMS_PIPE.CREATE_PIPEを使用して明示的なパイプを作成すると、(PRIVATEパラメータをFALSEに設定するか、デフォルト値TRUEを使用して)必要なアクセス権限でパイプが作成されるようになります。

DBMS_PIPE制限

DBMS_PIPEパッケージでは、異なる文字セットを使用するデータベース間でのメッセージの送信はサポートされていません。たとえば、AL32UTF8を使用する1つのAutonomous Databaseインスタンスと、WE8MSWIN1252を使用する別のインスタンスがある場合、これら2つのデータベース間でDBMS_PIPEを含むメッセージを送信することはできません。この場合、これらの2つのデータベース間でDBMS_PIPEを含むメッセージを送信しようとすると、エラーORA-12704が発生します。

詳細は、Autonomous Databaseの文字セットの選択を参照してください。

親トピック: DBMS_PIPEパッケージ

永続メッセージングのDBMS_PIPEサブプログラムの要約

この表は、DBMS_PIPEサブプログラムを示し、簡単に説明しています。

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

サブプログラム	摘要
CREATE_PIPEファンクション	パイプを作成します(プライベート・パイプには必須です)。
GET_CREDENTIAL_NAMEファンクション	グローバル`credential_name`変数値を返します。
GET_LOCATION_URIファンクション	メッセージがクラウド・オブジェクト・ストアに格納されるときに使用するデフォルトの場所URIとして使用されるグローバル`location_uri` 変数値を返します。
NEXT_ITEM_TYPEファンクション	バッファにある次の項目のデータ型を戻します。
PACK_MESSAGEプロシージャ	ローカル・バッファにメッセージを生成します。
RECEIVE_MESSAGEファンクション	名前付きパイプからローカル・バッファにメッセージをコピーします。
RESET_BUFFERプロシージャ	ローカル・バッファの内容を消去します。
REMOVE_PIPEファンクション	名前付きパイプを削除します。
SEND_MESSAGEファンクション	名前付きパイプにメッセージを送信します。名前付きパイプが存在しない場合は、パブリック・パイプが暗黙的に作成されます。
SET_CREDENTIAL_NAMEプロシージャ	クラウド・オブジェクト・ストアに格納されているメッセージのデフォルトの資格証明として使用される`credential_name`変数を設定します。
SET_LOCATION_URIプロシージャ	クラウド・オブジェクト・ストアに格納されているメッセージのデフォルトの場所URIとして使用されるグローバル`location_uri`変数を設定します。
UNIQUE_SESSION_NAMEファンクション	一意セッション名を戻します。
UNPACK_MESSAGEプロシージャ	バッファ内の次の項目にアクセスします。

CREATE_PIPEファンクション
このファンクションは、パブリック・パイプまたはプライベート・パイプは明示的に作成します。privateフラグがTRUEの場合、パイプ作成者が、そのプライベート・パイプの所有者として割り当てられます。
GET_CREDENTIAL_NAMEファンクション
このファンクションは、メッセージがクラウド・オブジェクト・ストアに格納されるときに使用するグローバルなcredential_name変数値を返します。
GET_LOCATION_URIファンクション
このファンクションは、パイプ・メッセージがクラウド・オブジェクト・ストアに格納されるときにデフォルトの場所URIとして使用できるグローバルなlocation_uri変数値を返します。
RECEIVE_MESSAGEファンクション
このファンクションは、メッセージをローカル・メッセージ・バッファにコピーします。
SEND_MESSAGEファンクション
このファンクションは、メッセージを名前付きパイプに送信します。
SET_CREDENTIAL_NAMEプロシージャ
このプロシージャは、パイプ・メッセージがクラウド・オブジェクト・ストアに格納されるときにデフォルトの資格証明として使用されるcredential_name変数を設定します。
SET_LOCATION_URIプロシージャ
このプロシージャは、グローバルlocation_uri変数を設定します。

親トピック: DBMS_PIPEパッケージ

CREATE_PIPEファンクション

明示的に作成されたパイプは、REMOVE_PIPEをコールするか、またはインスタンスをシャットダウンすることによってのみ削除できます。

構文

DBMS_PIPE.CREATE_PIPE (
   pipename     IN VARCHAR2,
   maxpipesize  IN INTEGER DEFAULT 66536,
   private      IN BOOLEAN DEFAULT TRUE)
RETURN INTEGER;

パラメータ

表6-12 CREATE_PIPEファンクションのパラメータ

パラメータ摘要

pipename

作成するパイプの名前。

SEND_MESSAGEおよびRECEIVE_MESSAGEをコールするときは、この名前を使用する必要があります。この名前は、インスタンス間で一意である必要があります。

注意: ORA$で始まるパイプ名を使用しないでください。これは、オラクル社が提供する製品用に予約されています。パイプ名は128バイト以下で指定し、大/小文字区別がありません。現時点では、名前にグローバリゼーション・サポート文字を含めることはできません。

maxpipesize

パイプの最大サイズ(バイト単位)。

パイプ上のすべてのメッセージの合計サイズは、この数を超えることはできません。この最大値を超えると、そのメッセージはブロックされます。

デフォルトのmaxpipesizeは66536バイトです。

パイプのmaxpipesizeはパイプ特性の一部となり、パイプが存続するかぎり有効です。これより大きいパイプ・サイズでSEND_MESSAGEをコールすると、maxpipesizeの値が大きくなります。これより小さいサイズでコールした場合は、より大きい既存の値を使用します。

デフォルトのmaxpipesizeである65536は、すべてのパイプに適用できます。

private

デフォルトのTRUEを使用して、プライベート・パイプを作成します。

パブリック・パイプは、SEND_MESSAGEをコールして、暗黙的に作成できます。

戻り値

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

返品摘要

0

成功しました。

パイプが存在し、パイプを作成するユーザーにそのパイプの使用が認可されている場合、Oracleは0(ゼロ)を戻して成功であることを示し、パイプ内のデータはそのまま残ります。

ORA-23322

命名競合のために失敗。

同じ名前のパイプが存在し、別のユーザーがそのパイプを作成した場合、OracleではエラーORA-23322を通知して命名競合であることを示しています。

例外

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

例外	摘要
`Null pipe name`	アクセス権エラー: 同名のパイプが存在するため使用できません。

例

MY_PIPE1という名前の明示的なプライベートを作成します。

DECLARE
  l_status INTEGER;
BEGIN
  l_status := DBMS_PIPE.create_pipe(
      pipename  => 'MY_PIPE1',
      private   => TRUE);
END;
/

親トピック: 永続メッセージングのDBMS_PIPEサブプログラムの要約

GET_CREDENTIAL_NAMEファンクション

このファンクションは、メッセージがクラウド・オブジェクト・ストアに格納されるときに使用するグローバルなcredential_name変数値を返します。

構文

DBMS_PIPE.GET_CREDENTIAL_NAME
         RETURN VARCHAR2;

戻り値

戻り値	摘要
`credential_name`	クラウド・オブジェクト・ストレージにアクセスするための資格証明の名前。

例

DECLARE
  credential_name     VARCHAR2(400)
BEGIN
  credential_name := DBMS_PIPE.GET_CREDENTIAL_NAME;
END;
/

親トピック: 永続メッセージングのDBMS_PIPEサブプログラムの要約

GET_LOCATION_URIファンクション

このファンクションは、パイプ・メッセージがクラウド・オブジェクト・ストアに格納されるときにデフォルトの場所URIとして使用できるグローバルなlocation_uri変数値を返します。

構文

DBMS_PIPE.GET_LOCATION_URI
        RETURN VARCHAR2;

戻り値

戻り値	摘要
`location_uri`	オブジェクトURI。

例

DECLARE
  location_uri     VARCHAR2(400)
BEGIN
  location_uri := DBMS_PIPE.GET_LOCATION_URI;
END;
/

親トピック: 永続メッセージングのDBMS_PIPEサブプログラムの要約

RECEIVE_MESSAGEファンクション

このファンクションは、メッセージをローカル・メッセージ・バッファにコピーします。

構文

DBMS_PIPE.RECEIVE_MESSAGE (
   pipename          IN VARCHAR2,
   timeout           IN INTEGER  DEFAULT maxwait,
   credential_name   IN VARCHAR2 DEFAULT null,
   location_uri      IN VARCHAR2)
RETURN INTEGER;

パラメータ

表6-15 RECEIVE_MESSAGEファンクションのパラメータ

パラメータ	摘要
`pipename`	メッセージを受信するパイプ名。 `ORA$`で始まる名前は、Oracleで使用するために予約されています。
`timeout`	メッセージを待つ時間(秒単位)。タイムアウトを0(ゼロ)に指定すると、ブロックされずに読み込むことができます。タイムアウトには、`cache_func`パラメータで指定されたキャッシュ関数の実行に要した時間は含まれません。デフォルト値は定数`MAXWAIT`で、86400000(1000日)に定義されています。
`credential_name`	メッセージの格納に使用するクラウド・ストアの資格証明名。 `credential_name`は、デフォルトで`NULL`として初期化されるパッケージ引数です。この値は、`DBMS_PIPE.RECEIVE_MESSAGE`をコールする前に設定できます。渡されたパラメータ値は、グローバル変数の値よりも優先されます。資格証明オブジェクトには、`DBMS_PIPE.RECEIVE_MESSAGE`を実行しているユーザーによる`EXECUTE`および`READ/WRITE`権限が必要です。 `credential_name`値は、OCIリソース・プリンシパル、Azureサービス・プリンシパル、Amazonリソース名(ARN)またはGoogleサービス・アカウントです。リソース・プリンシパル・ベースの認証の詳細は、リソースにアクセスするためのポリシーおよびロールの構成を参照してください。
`location_uri`	メッセージの格納に使用されるクラウド・ストアの場所URI。 `location_uri`は、デフォルトで`NULL`として初期化されるグローバル変数です。この値は、`DBMS_PIPE.RECEIVE_MESSAGE`をコールする前に設定できます。渡されたパラメータ値は、グローバル変数の値よりも優先されます。

戻り値

表6-16 RECEIVE_MESSAGEファンクションの戻り値

返品	摘要
`0`	成功
`1`	タイムアウト。暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。
`2`	パイプにあるレコードが、バッファに対して大きすぎます。
`3`	割込みが発生しました。
`ORA-23322`	パイプから読み込むための十分な権限がユーザーにありません。

使用上のノート

パイプからメッセージを受信するには、最初にRECEIVE_MESSAGEをコールします。メッセージを受信すると、パイプから削除されます。したがって、メッセージは1回しか受信できません。暗黙的に作成されたパイプは、最後のレコードがそのパイプから削除された後、削除されます。
RECEIVE_MESSAGEのコール時に指定したパイプがすでに存在しない場合、Oracleはパイプを暗黙的に作成してメッセージの受信を待ちます。メッセージが指定したタイムアウト時間の間に着信しなかった場合、そのコールが戻され、パイプは削除されます。
メッセージの受信後、1つ以上のUNPACK_MESSAGEをコールして、メッセージ内の個別の項目にアクセスする必要があります。UNPACK_MESSAGEプロシージャは、DATE、NUMBER、VARCHAR2タイプの項目をアンパックするためにオーバーロードされ、さらに、RAWおよびROWID項目をアンパックするための2つのプロシージャがあります。アンパックするデータのタイプが不明の場合は、NEXT_ITEM_TYPEをコールして、バッファ内にある次の項目のタイプを判別します。
永続メッセージは、確実に1つのプロセスによって書込みまたは読取りされることが保証されています。これにより、同時書込みと同時読取りによるメッセージ内容の不整合が回避されます。永続的なメッセージング・パイプを使用すると、DBMS_PIPEは、同時にアクティブにすることができる操作がメッセージの送信またはメッセージの受信が1つのみになります。ただし、進行中の操作のために操作が不可能な場合、そのプロセスはtimeout値に達するまで定期的に再試行します。
メッセージの格納にOracle Cloud Infrastructure Object Storageを使用している場合は、Oracle Cloud InfrastructureのネイティブURIまたはSwift URIを使用できます。ただし、ロケーションURIと資格証明は、次のようにタイプが一致している必要があります:
- ネイティブURI形式を使用してOracle Cloud Infrastructure Object Storageにアクセスする場合は、資格証明オブジェクトでネイティブOracle Cloud Infrastructure署名キー認証を使用する必要があります。
- Swift URI形式を使用してOracle Cloud Infrastructure Object Storageにアクセスする場合は、資格証明オブジェクトで認証トークン認証を使用する必要があります。

例外

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

例外	摘要
`Null pipe name`	権限エラーが発生しました。パイプからレコードを削除するための権限が不十分です。パイプは別のユーザーが所有しています。

親トピック: 永続メッセージングのDBMS_PIPEサブプログラムの要約

SEND_MESSAGEファンクション

このファンクションは、メッセージを名前付きパイプに送信します。

構文

DBMS_PIPE.SEND_MESSAGE (
    pipename          IN VARCHAR2,
    timeout           IN INTEGER DEFAULT MAXWAIT,
    credential_name   IN VARCHAR2 DEFAULT null,
    location_uri      IN VARCHAR2 )
RETURN INTEGER;

パラメータ

表6-18 SEND_MESSAGEファンクションのパラメータ

パラメータ	摘要
`credential_name`	メッセージの格納に使用するクラウド・ストアの資格証明名。 `credential_name`は、デフォルトで`NULL`として初期化されるパッケージ引数です。この値は、`DBMS_PIPE.SEND_MESSAGE`をコールする前に設定できます。渡されたパラメータ値は、グローバル変数の値よりも優先されます。資格証明オブジェクトには、`DBMS_PIPE.SEND_MESSAGE`を実行しているユーザーによる`EXECUTE`および`READ/WRITE`権限が必要です。 `credential_name`値は、OCIリソース・プリンシパル、Azureサービス・プリンシパル、Amazonリソース名(ARN)またはGoogleサービス・アカウントです。リソース・プリンシパル・ベースの認証の詳細は、リソースにアクセスするためのポリシーおよびロールの構成を参照してください。
`location_uri`	メッセージの格納に使用されるクラウド・ストアの場所URI。 `location_uri`は、デフォルトで`NULL`として初期化されるグローバル変数です。この値は、`DBMS_PIPE.SEND_MESSAGE`をコールする前に設定できます。渡されたパラメータ値は、グローバル変数の値よりも優先されます。
`maxpipesize`	パイプの最大サイズ(バイト単位)。パイプ上のすべてのメッセージの合計サイズは、この数を超えることはできません。この最大値を超えると、そのメッセージはブロックされます。デフォルトは65536バイトになります。パイプの`maxpipesize`はパイプ特性の一部となり、パイプが存続するかぎり有効です。これより大きいパイプ・サイズで`SEND_MESSAGE`をコールすると、`maxpipesize`の値が大きくなります。これより小さいサイズでコールした場合は、より大きい既存の値を使用します。 `SEND_MESSAGE`プロシージャの一部として`maxpipesize`を指定すると、別のコールでパイプをオープンする必要がなくなります。明示的にパイプを作成した場合は、オプションの`maxpipesize`パラメータを使用して、作成したパイプのサイズを上書きできます。デフォルトの`maxpipesize`である65536は、すべてのパイプに適用できます。
`pipename`	メッセージを設定するパイプの名前。明示的なパイプを使用している場合、この名前は、`CREATE_PIPE`をコールしたときに指定した名前です。注意: `ORA$`で始まるパイプ名を使用しないでください。これは、オラクル社が提供する製品用に予約されています。パイプ名は128バイト以下で指定し、大/小文字は区別されません。現時点では、名前にグローバリゼーション・サポート文字を含めることはできません。
`timeout`	パイプにメッセージを設定する間の待機時間(秒単位)。デフォルト値は定数`MAXWAIT`で、86400000(1000日)に定義されています。

戻り値

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

返品	摘要
`0`	成功。パイプが存在し、パイプを作成するユーザーにそのパイプの使用が認可されている場合、Oracleは0(ゼロ)を戻して成功であることを示し、パイプ内のデータはそのまま残ります。 `SYSDBS`/`SYSOPER`として接続したユーザーがパイプを再作成した場合、Oracleはステータス0(ゼロ)を戻しますが、そのパイプの所有者は変更されないままです。
`1`	タイムアウト。このプロシージャは、管でロックが取得できないか、またはパイプがいっぱいで使用できない理由でタイムアウトする可能性があります。暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。
`3`	割込みが発生しました。暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。
`ORA-23322`	権限が不十分です。同じ名前のパイプが存在し、別のユーザーがそのパイプを作成した場合、Oracleではエラー`ORA-23322`を通知して命名競合であることを示しています。

使用上のノート

永続メッセージは、確実に1つのプロセスによって書込みまたは読取りされることが保証されています。これにより、同時書込みと同時読取りによるメッセージ内容の不整合が回避されます。永続的なメッセージング・パイプを使用すると、DBMS_PIPEは、同時にアクティブにすることができる操作がメッセージの送信またはメッセージの受信が1つのみになります。ただし、進行中の操作のために操作が不可能な場合、そのプロセスはtimeout値に達するまで定期的に再試行します。
メッセージの格納にOracle Cloud Infrastructure Object Storageを使用している場合は、Oracle Cloud InfrastructureのネイティブURIまたはSwift URIを使用できます。ただし、ロケーションURIと資格証明は、次のようにタイプが一致している必要があります:
- ネイティブURI形式を使用してOracle Cloud Infrastructure Object Storageにアクセスする場合は、資格証明オブジェクトでネイティブOracle Cloud Infrastructure署名キー認証を使用する必要があります。
- Swift URI形式を使用してOracle Cloud Infrastructure Object Storageにアクセスする場合は、資格証明オブジェクトで認証トークン認証を使用する必要があります。

例外

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

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

親トピック: 永続メッセージングのDBMS_PIPEサブプログラムの要約

SET_CREDENTIAL_NAMEプロシージャ

このプロシージャは、パイプ・メッセージがクラウド・オブジェクト・ストアに格納されるときにデフォルト資格証明として使用されるcredential_name変数を設定します。

構文

DBMS_PIPE.SET_CREDENTIAL_NAME (
   credential_name   IN VARCHAR2 );

パラメータ

パラメータ摘要

パラメータ	摘要
`credential_name`	クラウド・オブジェクト・ストレージにアクセスするための資格証明の名前。 `credential_name`値は、OCIリソース・プリンシパル、Azureサービス・プリンシパル、Amazonリソース名(ARN)またはGoogleサービス・アカウントです。リソース・プリンシパル・ベースの認証の詳細は、リソースにアクセスするためのポリシーおよびロールの構成を参照してください。

credential_name

クラウド・オブジェクト・ストレージにアクセスするための資格証明の名前。

credential_name値は、OCIリソース・プリンシパル、Azureサービス・プリンシパル、Amazonリソース名(ARN)またはGoogleサービス・アカウントです。リソース・プリンシパル・ベースの認証の詳細は、リソースにアクセスするためのポリシーおよびロールの構成を参照してください。

使用上のノート

メッセージの格納にOracle Cloud Infrastructure Object Storageを使用している場合は、Oracle Cloud InfrastructureのネイティブURIまたはSwift URIを使用できます。ただし、ロケーションURIと資格証明は、次のようにタイプが一致している必要があります:

ネイティブURI形式を使用してOracle Cloud Infrastructure Object Storageにアクセスする場合は、資格証明オブジェクトでネイティブOracle Cloud Infrastructure署名キー認証を使用する必要があります。
Swift URI形式を使用してOracle Cloud Infrastructure Object Storageにアクセスする場合は、資格証明オブジェクトで認証トークン認証を使用する必要があります。

例

BEGIN
     DBMS_PIPE.SET_CREDENTIAL_NAME(
       credential_name =>  'my_cred1');
END;
/

親トピック: 永続メッセージングのDBMS_PIPEサブプログラムの要約

SET_LOCATION_URIプロシージャ

このプロシージャは、グローバルlocation_uri変数を設定します。

構文

DBMS_PIPE.SET_LOCATION_URI (
   location_uri   IN VARCHAR2 );

パラメータ

パラメータ	摘要
`location_uri`	オブジェクトまたはファイルURI。URIの形式は、使用しているクラウド・オブジェクト・ストレージ・サービスによって異なります。詳細は、DBMS_CLOUD URIの形式に関する項を参照してください。

使用上のノート

ネイティブURI形式を使用してOracle Cloud Infrastructure Object Storageにアクセスする場合は、資格証明オブジェクトでネイティブOracle Cloud Infrastructure署名キー認証を使用する必要があります。
Swift URI形式を使用してOracle Cloud Infrastructure Object Storageにアクセスする場合は、資格証明オブジェクトで認証トークン認証を使用する必要があります。

例

BEGIN
  DBMS_PIPE.GET_LOCATION_URI(
      location_uri  => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/');
END;
/

親トピック: 永続メッセージングのDBMS_PIPEサブプログラムの要約

Oracle Cloud Infrastructureドキュメント