DBMS_PIPE-Package (Persistente Messaging-Pipes)

Mit dem Package DBMS_PIPE können zwei oder mehr Sessions in derselben Instanz kommunizieren.

Oracle Autonomous AI Database on Dedicated Exadata Infrastructure unterstützt die Kernfunktionalität DBMS_PIPE, wie in Oracle Database 19c verfügbar, sowie Erweiterungen.

Weitere Informationen zur in Oracle Database bereitgestellten Core-Funktionalität DBMS_PIPE finden Sie unter DBMS_PIPE in Oracle Database 19c PL/SQL-Packages und Typenreferenz oder Oracle Database 26ai PL/SQL-Packages und Typenreferenz.

DBMS_PIPE - Überblick für persistente Messaging-Pipes

Pipe-Funktionalität hat mehrere potenzielle Anwendungen: externe Serviceschnittstelle, Debugging, unabhängige Transaktionen und Warnungen.

In einer autonomen KI-Datenbank verfügt das DBMS_PIPE-Package über erweiterte Funktionen zur Unterstützung persistenter Messaging-Pipes. Weitere Informationen finden Sie unter DBMS_PIPE in Oracle Database 19c PL/SQL-Packages and Types Reference oder Oracle Database 26ai PL/SQL Packages and Types Reference.

Persistente Nachrichten in DBMS_PIPE:

DBMS_PIPE-Beschränkung

Das Package DBMS_PIPE unterstützt das Senden von Nachrichten zwischen Datenbanken, die unterschiedliche Zeichensätze verwenden, nicht. Beispiel: Wenn eine autonome KI-Datenbankinstanz AL32UTF8 und eine andere Instanz WE8MSWIN1252 verwendet, können Sie keine Nachrichten mit DBMS_PIPE zwischen diesen beiden Datenbanken senden. In diesem Fall löst das System den Fehler ORA-12704 aus, wenn Sie versuchen, Nachrichten mit DBMS_PIPE zwischen diesen beiden Datenbanken zu senden.

Zusammenfassung der DBMS_PIPE-Unterprogramme für persistentes Messaging

In dieser Tabelle werden die Unterprogramme DBMS_PIPE aufgeführt und kurz beschrieben.

Unterprogramm Beschreibung
CREATE_PIPE-Funktion Erstellt eine Pipe (für private Pipes erforderlich).
Funktion GET_CREDENTIAL_NAME Gibt den globalen Variablenwert credential_name zurück.
Funktion GET_LOCATION_URI Gibt den globalen Variablenwert location_uri zurück, der als Standard-Speicherort-URI verwendet wird, wenn eine Nachricht im Cloud-Objektspeicher gespeichert wird.

NEXT_ITEM_TYPE (Funktion)

 Gibt den Datentyp des nächsten Elements im Puffer zurück.

PACK_MESSAGE-Verfahren

 Erstellt Meldung im lokalen Puffer.
RECEIVE_MESSAGE-Funktion Kopiert die Nachricht aus der benannten Pipe in den lokalen Puffer.

Prozedur RESET_BUFFER

 Löscht den Inhalt des lokalen Puffers.

REMOVE_PIPE-Funktion

 Entfernt die benannte Pipe.
SEND_MESSAGE-Funktion Sendet eine Nachricht an eine benannte Pipe: Dadurch wird implizit eine öffentliche Pipe erstellt, wenn die benannte Pipe nicht existiert.
Prozedur SET_CREDENTIAL_NAME Legt die Variable credential_name fest, die als Standardzugangsdaten für Nachrichten verwendet wird, die im Cloud-Objektspeicher gespeichert sind.
SET_LOCATION_URI - Prozedur Legt die globale location_uri-Variable fest, die als Standardverzeichnis-URI für Nachrichten verwendet wird, die im Cloud-Objektspeicher gespeichert sind.

UNIQUE_SESSION_NAME-Funktion

 Gibt einen eindeutigen Sessionnamen zurück.

UNPACK_MESSAGE-Verfahren

 Greift auf das nächste Element im Puffer zu.

CREATE_PIPE-Funktion

Diese Funktion erstellt explizit eine öffentliche oder private Pipe. Wenn das Flag private TRUE ist, wird der Pipe-Ersteller als Eigentümer der privaten Pipe zugewiesen.

Explizit erstellte Pipes können nur entfernt werden, indem REMOVE_PIPE aufgerufen oder die Instanz heruntergefahren wird.

Syntax

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

Parameter

Parameter Beschreibung
pipename

Name der Pipe, die Sie erstellen.

Sie müssen diesen Namen verwenden, wenn Sie SEND_MESSAGE und RECEIVE_MESSAGE aufrufen. Dieser Name muss instanzübergreifend eindeutig sein.

**Achtung:** Verwenden Sie keine Pipe-Namen, die mit ORA$ beginnen. Diese sind für die von Oracle bereitgestellten Verfahren reserviert. Pipename darf nicht länger als 128 Byte sein und die Groß-/Kleinschreibung wird nicht beachtet. Der Name darf derzeit keine Zeichen für die Globalisierungsunterstützung enthalten.

maxpipesize

Die maximal zulässige Größe für die Pipe in Byte.

Die Gesamtgröße aller Nachrichten in der Pipe darf diesen Betrag nicht überschreiten. Die Nachricht wird blockiert, wenn sie dieses Maximum überschreitet.

Der Standardwert für maxpipesize ist 66536 Byte.

Die maxpipesize für ein Rohr wird Teil der Eigenschaften des Rohres und bleibt für die Lebensdauer des Rohres bestehen. Aufrufer von SEND_MESSAGE mit größeren Werten führen dazu, dass maxpipesize erhöht wird. Anrufer mit einem kleineren Wert verwenden den vorhandenen, größeren Wert.

Der Standardwert maxpipesize von 65536 gilt für alle Pipes.

private

Verwendet den Standardwert TRUE, um eine private Pipe zu erstellen.

Öffentliche Pipes können implizit erstellt werden, wenn Sie SEND_MESSAGE aufrufen.

Rückgabewerte

Return Beschreibung
0

Erfolgreich.

Wenn die Pipe bereits vorhanden ist und der Benutzer, der sie zu erstellen versucht, zur Verwendung autorisiert ist, gibt Oracle 0 zurück, was den Erfolg anzeigt, und alle Daten, die sich bereits in der Pipe befinden, bleiben erhalten.
ORA-23322

Fehler aufgrund eines Namenskonflikts.

Wenn eine Pipe mit demselben Namen vorhanden ist und von einem anderen Benutzer erstellt wurde, gibt Oracle den Fehler ORA-23322 an, der auf den Namenskonflikt hinweist.

Exceptions

Ausnahme Beschreibung
Null pipe name Berechtigungsfehler: Pipe mit demselben Namen ist bereits vorhanden, und Sie dürfen ihn nicht verwenden.

Beispiel

Erstellen Sie einen expliziten privaten Namen namens MY_PIPE1.

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

Funktion GET_CREDENTIAL_NAME

Diese Funktion gibt den globalen Variablenwert credential_name zurück, der verwendet wird, wenn Nachrichten im Cloud-Objektspeicher gespeichert werden.

Syntax

DBMS_PIPE.GET_CREDENTIAL_NAME
         RETURN VARCHAR2;

Rückgabewerte

Rückgabewert Beschreibung
credential_name Der Name der Zugangsdaten für den Zugriff auf den Cloud-Objektspeicher.

Beispiel

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

Funktion GET_LOCATION_URI

Diese Funktion gibt den globalen Variablenwert location_uri zurück, der als Standardstandort-URI verwendet werden kann, wenn Pipe-Nachrichten im Cloud-Objektspeicher gespeichert werden.

Syntax

DBMS_PIPE.GET_LOCATION_URI
        RETURN VARCHAR2;

Rückgabewert

Rückgabewert Beschreibung
location_uri Die Objekt-URI.

Beispiel

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

RECEIVE_MESSAGE-Funktion

Diese Funktion kopiert die Nachricht in den lokalen Nachrichtenpuffer.

Syntax

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

Parameter

Tabelle - RECEIVE_MESSAGE-Funktionsparameter

Parameter Beschreibung
pipename

Name der Pipe, auf der eine Nachricht empfangen werden soll.

Namen, die mit ORA$ beginnen, sind für die Verwendung durch Oracle reserviert.

timeout

Wartezeit für eine Nachricht in Sekunden. Mit einem Timeout von 0 können Sie lesen, ohne zu blockieren.

Der Timeout enthält nicht die Zeit, die für die Ausführung der mit dem Parameter cache_func angegebenen Cachefunktion aufgewendet wurde.

Standardwert: Die Konstante MAXWAIT, die als 86400000 (1000 Tage) definiert ist.

credential_name

Der Zugangsdatenname für den Cloud-Speicher, der zum Speichern von Nachrichten verwendet wird.

credential_name ist ein Packageargument, das standardmäßig als NULL initialisiert wird.

Sie können diesen Wert festlegen, bevor Sie DBMS_PIPE.RECEIVE_MESSAGE aufrufen. Der übergebene Parameterwert hat Vorrang vor dem Wert der globalen Variable.

Das Zugangsdatenobjekt muss über die Berechtigungen EXECUTE und READ/WRITE des Benutzers verfügen, der DBMS_PIPE.RECEIVE_MESSAGE ausführt.

location_uri

Die Standort-URI für den Cloud-Speicher, der zum Speichern von Nachrichten verwendet wird.

Die location_uri ist eine globale Variable, die standardmäßig als NULL initialisiert wird.

Sie können diesen Wert festlegen, bevor Sie DBMS_PIPE.RECEIVE_MESSAGE aufrufen. Der übergebene Parameterwert hat Vorrang vor dem Wert der globalen Variable.

Rückgabewerte

Tabelle - Rückgabewerte der Funktion RECEIVE_MESSAGE

Return Beschreibung
0 Erfolgreich
1 Wegen Timeout abgebrochen. Wenn die Pipe implizit erstellt wurde und leer ist, wird sie entfernt.
2 Datensatz in der Pipe ist zu groß für den Puffer.
3 Eine Unterbrechung ist aufgetreten.
ORA-23322 Der Benutzer hat keine ausreichenden Berechtigungen zum Lesen aus der Pipe.

Verwendungshinweise

Exceptions

Tabelle - RECEIVE_MESSAGE-Funktionsausnahmen

Ausnahme Beschreibung
Null pipe name Berechtigungsfehler. Unzureichende Berechtigung zum Entfernen des Datensatzes aus der Pipe. Die Pipe gehört einer anderen Person.

SEND_MESSAGE-Funktion

Diese Funktion sendet eine Nachricht an die benannte Pipe.

Die Nachricht ist im lokalen Nachrichtenpuffer enthalten, der mit Aufrufen an PACK_MESSAGE gefüllt wurde. Sie können eine Pipe explizit mit CREATE_PIPE erstellen. Andernfalls wird sie implizit erstellt.

Syntax

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

Parameter

Tabelle - Parameter der Funktion SEND_MESSAGE

Parameter Beschreibung
credential_name

Der Zugangsdatenname für den Cloud-Speicher, der zum Speichern von Nachrichten verwendet wird.

credential_name ist ein Packageargument, das standardmäßig als NULL initialisiert wird.

Sie können diesen Wert festlegen, bevor Sie DBMS_PIPE.SEND_MESSAGE aufrufen. Der übergebene Parameterwert hat Vorrang vor dem Wert der globalen Variable.

Das Zugangsdatenobjekt muss über die Berechtigungen EXECUTE und READ/WRITE des Benutzers verfügen, der DBMS_PIPE.SEND_MESSAGE ausführt.

location_uri

Die Standort-URI für den Cloud-Speicher, der zum Speichern von Nachrichten verwendet wird.

Die location_uri ist eine globale Variable, die standardmäßig als NULL initialisiert wird.

Sie können diesen Wert festlegen, bevor Sie DBMS_PIPE.SEND_MESSAGE aufrufen. Der übergebene Parameterwert hat Vorrang vor dem Wert der globalen Variable.

maxpipesize

Maximal zulässige Größe für die Pipe in Byte.

Die Gesamtgröße aller Nachrichten in der Pipe darf diesen Betrag nicht überschreiten. Die Nachricht wird blockiert, wenn sie dieses Maximum überschreitet. Der Standardwert beträgt 65536 Byte.

Die maxpipesize für ein Rohr wird Teil der Eigenschaften des Rohres und bleibt für die Lebensdauer des Rohres bestehen. Aufrufer von SEND_MESSAGE mit größeren Werten führen dazu, dass maxpipesize erhöht wird. Anrufer mit einem kleineren Wert verwenden einfach den vorhandenen, größeren Wert.

Wenn Sie maxpipesize als Teil der Prozedur SEND_MESSAGE angeben, ist kein separater Aufruf zum Öffnen der Pipe erforderlich. Wenn Sie die Pipe explizit erstellt haben, können Sie den optionalen Parameter maxpipesize verwenden, um die Spezifikationen für die Erstellungs-Pipe-Größe außer Kraft zu setzen.

Der Standardwert maxpipesize von 65536 gilt für alle Pipes.

pipename

Name der Pipe, auf der die Nachricht abgelegt werden soll.

Wenn Sie eine explizite Pipe verwenden, ist dies der Name, den Sie beim Aufruf von CREATE_PIPE angegeben haben.

**Achtung:** Verwenden Sie keine Pipe-Namen, die mit "ORA$" beginnen. Diese Namen sind für die Verwendung durch von Oracle bereitgestellte Prozeduren reserviert. Pipename darf nicht länger als 128 Byte sein und die Groß-/Kleinschreibung wird nicht beachtet. Derzeit darf der Name keine Zeichen für die Globalisierungsunterstützung enthalten.

timeout

Wartezeit beim Versuch, eine Nachricht in einer Pipe zu platzieren, in Sekunden.

Der Standardwert ist die Konstante MAXWAIT, die als 86400000 (1000 Tage) definiert ist.

Rückgabewerte

Tabelle - Rückgabewerte der Funktion SEND_MESSAGE

Return Beschreibung
0

Erfolgreich.

Wenn die Pipe bereits vorhanden ist und der Benutzer, der sie zu erstellen versucht, zur Verwendung autorisiert ist, gibt Oracle 0 zurück, was den Erfolg anzeigt, und alle Daten, die sich bereits in der Pipe befinden, bleiben erhalten.

Wenn ein als SYSDBS/SYSOPER verbundener Benutzer eine Pipe neu erstellt, gibt Oracle den Status 0 zurück, der Eigentümer der Pipe bleibt jedoch unverändert.

1

Wegen Timeout abgebrochen.

Bei diesem Verfahren kann ein Timeout auftreten, weil es keine Sperre für das Rohr erhalten kann oder weil das Rohr zu voll ist, um verwendet zu werden. Wenn die Pipe implizit erstellt wurde und leer ist, wird sie entfernt.
3

Eine Unterbrechung ist aufgetreten.

Wenn die Pipe implizit erstellt wurde und leer ist, wird sie entfernt.
ORA-23322

Unzureichende Berechtigungen.

Wenn eine Pipe mit demselben Namen vorhanden ist und von einem anderen Benutzer erstellt wurde, gibt Oracle den Fehler ORA-23322 an, der auf den Namenskonflikt hinweist.

Verwendungshinweise

Exceptions

Tabelle - Ausnahme für SEND_MESSAGE-Funktion

Ausnahme Beschreibung
Null pipe name Berechtigungsfehler. Unzureichende Berechtigung zum Schreiben in die Pipe. Die Pfeife ist privat und gehört jemand anderem.

Prozedur SET_CREDENTIAL_NAME

Diese Prozedur legt die Variable credential_name fest, die als Standardzugangsdaten verwendet wird, wenn Pipe-Nachrichten im Cloud-Objektspeicher gespeichert werden.

Syntax

DBMS_PIPE.SET_CREDENTIAL_NAME (
   credential_name   IN VARCHAR2 );

Parameter

Parameter Beschreibung
credential_name Der Name der Zugangsdaten für den Zugriff auf den Cloud-Objektspeicher.

Hinweis zur Verwendung

Wenn Sie Nachrichten in Oracle Cloud Infrastructure Object Storage speichern, können Sie native Oracle Cloud Infrastructure-URIs oder Swift-URIs verwenden. Der Speicherort-URI und die Zugangsdaten müssen jedoch wie folgt mit dem Typ übereinstimmen:

Beispiel

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

SET_LOCATION_URI - Prozedur

Diese Prozedur legt die globale Variable location_uri fest.

Syntax

DBMS_PIPE.SET_LOCATION_URI (
   location_uri   IN VARCHAR2 );

Parameter

Parameter Beschreibung
location_uri Objekt- oder Datei-URI. Das Format der URI ist vom verwendeten Cloud-Objektspeicherservice abhängig. Weitere Einzelheiten finden Sie unter URI-Formate für Cloud-Objektspeicher.

Hinweis zur Verwendung

Wenn Sie Nachrichten in Oracle Cloud Infrastructure Object Storage speichern, können Sie native Oracle Cloud Infrastructure-URIs oder Swift-URIs verwenden. Der Speicherort-URI und die Zugangsdaten müssen jedoch wie folgt mit dem Typ übereinstimmen:

Beispiel

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

Verwandte Inhalte