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内の永続メッセージ:

DBMS_PIPEの制限

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

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

この表は、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の場合、パイプ作成者が、そのプライベート・パイプの所有者として割り当てられます。

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

構文

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

Parameters

パラメータ 説明
pipename

作成するパイプの名前。

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

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

maxpipesize

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

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

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

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

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

private

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

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

戻り値

戻り 説明
0

成功

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

命名競合のために失敗。

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

例外

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

例

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

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

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

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

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;

Parameters

表- 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権限が必要です。

location_uri

メッセージの格納に使用されるクラウド・ストアの場所URI。

location_uriは、デフォルトでNULLとして初期化されるグローバル変数です。

この値は、DBMS_PIPE.RECEIVE_MESSAGEをコールする前に設定できます。渡されたパラメータ値は、グローバル変数の値より優先されます。

戻り値

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

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

使用上のノート

例外

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

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

SEND_MESSAGEファンクション

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

PACK_MESSAGEへのコールで入力されたメッセージは、ローカル・メッセージ・バッファに格納されます。CREATE_PIPEを使用するとパイプを明示的に作成でき、それ以外の場合は暗黙的に作成されます。

構文

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

Parameters

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

パラメータ 説明
credential_name

メッセージの格納に使用するクラウド・ストアの資格証明名。

credential_nameは、デフォルトでNULLとして初期化されるパッケージ引数です。

この値は、DBMS_PIPE.SEND_MESSAGEをコールする前に設定できます。渡されたパラメータ値は、グローバル変数の値より優先されます。

資格証明オブジェクトには、DBMS_PIPE.SEND_MESSAGEを実行しているユーザーによるEXECUTEおよびREAD/WRITE権限が必要です。

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日)に定義されています。

戻り値

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

戻り 説明
0

成功

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

SYSDBS/SYSOPERとして接続したユーザーがパイプを再作成した場合、Oracleはステータス0(ゼロ)を戻しますが、そのパイプの所有者は変更されないままです。

1

タイムアウト

このプロシージャは、管でロックが取得できないか、またはパイプがいっぱいで使用できない理由でタイムアウトすることがあります。暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。
3

割込みが発生しました。

暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。
ORA-23322

権限が不十分です。

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

使用上のノート

例外

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

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

SET_CREDENTIAL_NAMEプロシージャ

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

構文

DBMS_PIPE.SET_CREDENTIAL_NAME (
   credential_name   IN VARCHAR2 );

Parameters

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

使用上のノート

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

例

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

SET_LOCATION_URIプロシージャ

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

構文

DBMS_PIPE.SET_LOCATION_URI (
   location_uri   IN VARCHAR2 );

パラメータ

パラメータ 説明
location_uri オブジェクトまたはファイルURI。URIのフォーマットは、使用しているクラウド・オブジェクト・ストレージ・サービスによって異なります。詳細は、クラウド・オブジェクト・ストレージのURIフォーマットを参照してください。

使用上のノート

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

例

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

関連コンテンツ