Ensemble DBMS_PIPE (Pipes de messagerie persistantes)

L'ensemble DBMS_PIPE permet à deux sessions ou plus dans la même instance de communiquer.

Oracle Autonomous AI Database sur une infrastructure Exadata dédiée prend en charge la fonctionnalité DBMS_PIPE de base disponible dans Oracle Database 19c, plus les extensions.

Voir DBMS_PIPE dans Informations de référence sur les ensembles et les types PL/SQL pour Oracle Database 19c ou Informations de référence sur les ensembles et les types PL/SQL pour Oracle Database 26ai pour plus de détails sur la fonctionnalité DBMS_PIPE de base fournie dans Oracle Database.

Aperçu DBMS_PIPE pour les pipelines de messagerie persistants

La fonctionnalité de canal comporte plusieurs applications potentielles : interface de service externe, débogage, transactions indépendantes et alertes.

Sur Autonomous AI Database, l'ensemble DBMS_PIPE offre des fonctionnalités étendues pour la prise en charge des canaux de messagerie persistants. Pour plus d'informations, voir DBMS_PIPE dans Informations de référence sur les ensembles et les types PL/SQL pour Oracle Database 19c ou Informations de référence sur les ensembles et les types PL/SQL pour Oracle Database 26ai.

Messages persistants dans DBMS_PIPE :

Limite DBMS_PIPE

L'ensemble DBMS_PIPE ne prend pas en charge l'envoi de messages entre des bases de données qui utilisent des jeux de caractères différents. Par exemple, si vous avez une instance de base de données d'IA autonome qui utilise AL32UTF8 et une autre qui utilise WE8MSWIN1252, vous ne pouvez pas envoyer de messages avec DBMS_PIPE entre ces deux bases de données. Dans ce cas, le système générera l'erreur ORA-12704 si vous tentez d'envoyer des messages avec DBMS_PIPE entre ces deux bases de données.

Sommaire des sous-programmes DBMS_PIPE pour la messagerie persistante

Ce tableau répertorie les sous-programmes DBMS_PIPE et les décrit brièvement.

Sous-programme Description
Fonction CREATE_PIPE Crée un tuyau (nécessaire pour les tuyaux privés).
Fonction GET_CREDENTIAL_NAME Retourne la valeur de variable credential_name globale.
Fonction GET_LOCATION_URI Retourne la valeur de la variable location_uri globale utilisée comme URI d'emplacement par défaut lorsqu'un message est stocké dans le magasin d'objets en nuage.

Fonction NEXT_ITEM_TYPE

Retourne le type de données de l'élément suivant dans la mémoire tampon.

Procédures PACK_MESSAGE

Crée le message dans la mémoire tampon locale.
Fonction RECEIVE_MESSAGE Copie le message du canal nommé dans la mémoire tampon locale.

Procédure RESET_BUFFER

Épure le contenu de la mémoire tampon locale.

Fonction REMOVE_PIPE

Supprime le tuyau nommé.
Fonction SEND_MESSAGE Envoie un message sur un tuyau nommé : Cela crée implicitement un tuyau public si le tuyau nommé n'existe pas.
Procédure SET_CREDENTIAL_NAME Définit la variable credential_name utilisée comme données d'identification par défaut pour les messages stockés dans le magasin d'objets en nuage.
Procédure SET_LOCATION_URI Définit la variable location_uri globale utilisée comme URI d'emplacement par défaut pour les messages stockés dans le magasin d'objets en nuage.

Fonction UNIQUE_SESSION_NAME

Retourne un nom de session unique.

Procédures UNPACK_MESSAGE

Permet d'accéder à l'élément suivant dans la mémoire tampon.

Fonction CREATE_PIPE

Cette fonction crée explicitement un canal public ou privé. Si l'indicateur private est TRUE, le créateur de la canalisation est affecté en tant que responsable de la canalisation privée.

Les canaux créés explicitement ne peuvent être supprimés qu'en appelant REMOVE_PIPE ou en arrêtant l'instance.

Syntaxe

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

Paramètres

Paramètre Description
pipename

Nom du canal que vous créez.

Vous devez utiliser ce nom lorsque vous appelez SEND_MESSAGE et RECEIVE_MESSAGE. Ce nom doit être unique dans l'instance.

**Attention :** N'utilisez pas de noms de canal commençant par ORA$. Elles sont réservées à l'utilisation par les procédures fournies par Oracle. Le nom de pipeline ne doit pas dépasser 128 octets et n'est pas sensible à la casse. Pour le moment, le nom ne peut pas contenir de caractères prenant en charge la globalisation.

maxpipesize

Taille maximale autorisée pour le tuyau, en octets.

La taille totale de tous les messages de la barre verticale ne peut pas dépasser ce montant. Le message est bloqué s'il dépasse ce maximum.

La valeur par défaut de maxpipesize est 66536 octets.

Le maxpipesize pour un tuyau devient une partie des caractéristiques du tuyau et persiste pendant la durée de vie du tuyau. Les appelants de SEND_MESSAGE avec des valeurs plus grandes entraînent l'augmentation de maxpipesize. Les appelants ayant une valeur plus petite utilisent la valeur plus grande existante.

La valeur par défaut maxpipesize de 65536 s'applique à tous les tuyaux.

private

Utilise la valeur par défaut, TRUE, pour créer un canal privé.

Les canaux publics peuvent être créés implicitement lorsque vous appelez SEND_MESSAGE.

Valeurs retournées

Retour Description
0

Réussite.

Si le canal existe déjà et que l'utilisateur qui tente de le créer est autorisé à l'utiliser, Oracle retourne 0, indiquant la réussite, et toutes les données déjà présentes dans le canal restent.

ORA-23322

Échec dû à un conflit d'attribution de nom.

Si un canal portant le même nom existe et a été créé par un autre utilisateur, Oracle signale l'erreur ORA-23322, indiquant le conflit d'attribution de nom.

Exceptions

Exception Description
Null pipe name Erreur d'autorisation : Un canal portant le même nom existe déjà et vous n'êtes pas autorisé à l'utiliser.

Exemple

Créer un privé explicite nommé MY_PIPE1

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

Fonction GET_CREDENTIAL_NAME

Cette fonction retourne la valeur de variable credential_name globale à utiliser lorsque les messages sont stockés dans le magasin d'objets en nuage.

Syntaxe

DBMS_PIPE.GET_CREDENTIAL_NAME
         RETURN VARCHAR2;

Valeurs retournées

Valeur de retour Description
credential_name Nom des données d'identification permettant d'accéder au service de stockage d'objets en nuage.

Exemple

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

Fonction GET_LOCATION_URI

Cette fonction retourne la valeur de variable location_uri globale qui peut être utilisée comme URI d'emplacement par défaut lorsque des messages de canal sont stockés dans le magasin d'objets en nuage.

Syntaxe

DBMS_PIPE.GET_LOCATION_URI
        RETURN VARCHAR2;

Valeur de retour

Valeur de retour Description
location_uri URI de l'objet.

Exemple

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

Fonction RECEIVE_MESSAGE

Cette fonction copie le message dans le tampon de messages local.

Syntaxe

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

Paramètres

Table - Paramètres de fonction RECEIVE_MESSAGE

Paramètre Description
pipename

Nom de la barre verticale sur laquelle vous souhaitez recevoir un message.

Les noms commençant par ORA$ sont réservés à Oracle.

timeout

Temps d'attente d'un message, en secondes. Une temporisation de 0 vous permet de lire sans blocage.

La temporisation n'inclut pas le temps passé à exécuter la fonction de mémoire cache spécifiée avec le paramètre cache_func.

Valeur par défaut : est la constante MAXWAIT, qui est définie comme 86400000 (1000 jours).

credential_name

Nom des données d'identification du magasin en nuage utilisé pour stocker les messages.

credential_name est un argument d'ensemble initialisé par défaut en tant que NULL.

Vous pouvez définir cette valeur avant d'appeler DBMS_PIPE.RECEIVE_MESSAGE. La valeur du paramètre transmis a priorité sur la valeur de la variable globale.

L'objet de données d'identification doit disposer des privilèges EXECUTE et READ/WRITE par l'utilisateur exécutant DBMS_PIPE.RECEIVE_MESSAGE.

location_uri

URI d'emplacement du magasin en nuage utilisé pour stocker les messages.

location_uri est une variable globale qui, par défaut, est initialisée en tant que NULL.

Vous pouvez définir cette valeur avant d'appeler DBMS_PIPE.RECEIVE_MESSAGE. La valeur du paramètre transmis a priorité sur la valeur de la variable globale.

Valeurs retournées

Table - Valeurs de retour de fonction RECEIVE_MESSAGE

Retour Description
0 Réussite
1 Temporisé. Si le tuyau a été créé implicitement et est vide, il est supprimé.
2 L'enregistrement dans le tuyau est trop volumineux pour le tampon.
3 Une interruption s'est produite.
ORA-23322 L'utilisateur ne dispose pas de privilèges suffisants pour lire à partir du canal.

Notes d'utilisation

Exceptions

Table - Exceptions de fonction RECEIVE_MESSAGE

Exception Description
Null pipe name Erreur d'autorisation. Privilège insuffisant pour supprimer l'enregistrement de la barre verticale. La pipe appartient à quelqu'un d'autre.

Fonction SEND_MESSAGE

Cette fonction envoie un message sur le canal nommé.

Le message est contenu dans la mémoire tampon du message local, qui a été remplie d'appels à PACK_MESSAGE. Vous pouvez créer un canal explicitement à l'aide de CREATE_PIPE, sinon il est créé implicitement.

Syntaxe

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

Paramètres

Table - Paramètres de fonction SEND_MESSAGE

Paramètre Description
credential_name

Nom des données d'identification du magasin en nuage utilisé pour stocker les messages.

credential_name est un argument d'ensemble initialisé par défaut en tant que NULL.

Vous pouvez définir cette valeur avant d'appeler DBMS_PIPE.SEND_MESSAGE. La valeur du paramètre transmis a priorité sur la valeur de la variable globale.

L'objet de données d'identification doit disposer des privilèges EXECUTE et READ/WRITE par l'utilisateur exécutant DBMS_PIPE.SEND_MESSAGE.

location_uri

URI d'emplacement du magasin en nuage utilisé pour stocker les messages.

location_uri est une variable globale qui, par défaut, est initialisée en tant que NULL.

Vous pouvez définir cette valeur avant d'appeler DBMS_PIPE.SEND_MESSAGE. La valeur du paramètre transmis a priorité sur la valeur de la variable globale.

maxpipesize

Taille maximale autorisée pour le tuyau, en octets.

La taille totale de tous les messages de la barre verticale ne peut pas dépasser ce montant. Le message est bloqué s'il dépasse ce maximum. La valeur par défaut est 65536 octets.

Le maxpipesize pour un tuyau devient une partie des caractéristiques du tuyau et persiste pendant la durée de vie du tuyau. Les appelants de SEND_MESSAGE avec des valeurs plus grandes entraînent l'augmentation de maxpipesize. Les appelants avec une valeur plus petite utilisent simplement la valeur existante, plus grande.

La spécification de maxpipesize dans le cadre de la procédure SEND_MESSAGE élimine la nécessité d'un appel distinct pour ouvrir le canal. Si vous avez créé le canal explicitement, vous pouvez utiliser le paramètre facultatif maxpipesize pour remplacer les spécifications de taille de canal de création.

La valeur par défaut maxpipesize de 65536 s'applique à tous les tuyaux.

pipename

Nom de la barre verticale sur laquelle vous voulez placer le message.

Si vous utilisez une barre verticale explicite, il s'agit du nom que vous avez spécifié lorsque vous avez appelé CREATE_PIPE.

**Attention :** N'utilisez pas de noms de barre verticale commençant par 'ORA$'. Ces noms sont réservés à l'utilisation par les procédures fournies par Oracle. Le nom de pipeline ne doit pas dépasser 128 octets et n'est pas sensible à la casse. Pour le moment, le nom ne peut pas contenir de caractères prenant en charge la globalisation.

timeout

Temps d'attente en tentant de placer un message sur une barre verticale, en secondes.

La valeur par défaut est la constante MAXWAIT, qui est définie comme 86400000 (1000 jours).

Valeurs retournées

Table - Valeurs de retour de fonction SEND_MESSAGE

Retour Description
0

Succès.

Si le canal existe déjà et que l'utilisateur qui tente de le créer est autorisé à l'utiliser, Oracle retourne 0, indiquant la réussite, et toutes les données déjà présentes dans le canal restent.

Si un utilisateur connecté en tant que SYSDBS/SYSOPER recrée un canal, Oracle retourne le statut 0, mais la propriété du canal reste inchangée.

1

Temporisé.

Cette procédure peut expirer soit parce qu'elle ne peut pas obtenir un verrou sur le tuyau, soit parce que le tuyau reste trop plein pour être utilisé. Si le tuyau a été créé implicitement et est vide, il est supprimé.

3

Une interruption s'est produite.

Si le tuyau a été créé implicitement et est vide, il est supprimé.

ORA-23322

Privilèges insuffisants.

Si un canal portant le même nom existe et a été créé par un autre utilisateur, Oracle signale l'erreur ORA-23322, indiquant le conflit d'attribution de nom.

Notes d'utilisation

Exceptions

Table - Exception de fonction SEND_MESSAGE

Exception Description
Null pipe name Erreur d'autorisation. Privilège insuffisant pour écrire dans le canal. Le tuyau est privé et appartient à quelqu'un d'autre.

Procédure SET_CREDENTIAL_NAME

Cette procédure définit la variable credential_name qui est utilisée comme données d'identification par défaut lorsque des messages de canal sont stockés dans le magasin d'objets en nuage.

Syntaxe

DBMS_PIPE.SET_CREDENTIAL_NAME (
   credential_name   IN VARCHAR2 );

Paramètres

Paramètre Description
credential_name Nom des données d'identification permettant d'accéder au service de stockage d'objets en nuage.

Note d'utilisation

Si vous utilisez Oracle Cloud Infrastructure Object Storage pour stocker des messages, vous pouvez utiliser des URI natifs d'Oracle Cloud Infrastructure ou des URI Swift. Toutefois, l'URI d'emplacement et les données d'identification doivent correspondre au type suivant :

Exemple

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

Procédure SET_LOCATION_URI

Cette procédure définit la variable location_uri globale.

Syntaxe

DBMS_PIPE.SET_LOCATION_URI (
   location_uri   IN VARCHAR2 );

Paramètre

Paramètre Description
location_uri URI d'objet ou de fichier. Le format de l'URI dépend du service de stockage d'objets en nuage que vous utilisez. Pour plus de détails, voir Formats d'URI du service de stockage d'objets en nuage.

Note d'utilisation

Si vous utilisez Oracle Cloud Infrastructure Object Storage pour stocker des messages, vous pouvez utiliser des URI natifs d'Oracle Cloud Infrastructure ou des URI Swift. Toutefois, l'URI d'emplacement et les données d'identification doivent correspondre au type suivant :

Exemple

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

Contenu connexe