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 Database on Dedicated Exadata Infrastructure 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 Oracle Database 19c ou Informations de référence sur les ensembles et les types PL/SQL Oracle Database 23ai pour plus de détails sur la fonctionnalité DBMS_PIPE de base fournie dans Oracle Database.

Rubriques connexes

DBMS_PIPE Aperçu des pipelines de messagerie persistants

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

Sur Autonomous Database, l'ensemble DBMS_PIPE offre des fonctionnalités étendues pour prendre en charge les 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 23ai.

Messages persistants dans DBMS_PIPE :

  • Prise en charge de la possibilité d'envoyer et de récupérer des messages très volumineux.

  • Prise en charge d'un grand nombre de messages de canalisation.

  • Prenez en charge le partage de messages au sein d'une seule base de données, entre plusieurs bases de données et entre des bases de données de différentes régions.

  • Prendre en charge plusieurs canaux à l'aide du même URI d'emplacement de magasin d'objets en nuage.

    La fonctionnalité de messagerie persistante permet à deux sessions de base de données ou plus de communiquer avec les messages stockés dans le magasin d'objets en nuage. L'utilisation de ces messages de fonctionnalité dans une barre verticale peut être mise à la disposition de la base de données courante seulement ou ils peuvent être mis à la disposition de plusieurs bases de données dans la même région ou dans différentes régions.

    Un canal de messagerie persistant peut être l'un des types DBMS_PIPE pris en charge :

    • Conduit implicite : Créé automatiquement lorsqu'un message est envoyé avec un nom de canal inconnu à l'aide de la fonction DBMS_PIPE.SEND_MESSAGE.
    • Converbe explicite : Créé à l'aide de la fonction DBMS_PIPE.CREATE_PIPE avec un nom de canal spécifié par l'utilisateur.
    • Conseil public : Accessible par tout utilisateur disposant de l'autorisation EXECUTE sur l'ensemble DBMS_PIPE.
    • Converbe privé : Accessible par les sessions avec le même utilisateur que le créateur du canal.

Note :

Lorsque vous envoyez et recevez des messages dans différentes bases de données à l'aide de messages persistants, Oracle vous recommande d'appeler DBMS_PIPE.CREATE_PIPE avant d'envoyer ou de recevoir des messages. La création d'un canal explicite avec DBMS_PIPE.CREATE_PIPE garantit qu'un canal est créé avec les autorisations d'accès voulues, publiques ou privées (en réglant le paramètre PRIVATE à FALSE ou en utilisant la valeur par défaut TRUE).

DBMS_PIPE Limite

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 Autonomous Database 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ère 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.

Tableau - Sous-programmes de l'ensemble DBMS_PIPE

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 la variable credential_name globale.

Fonction GET_LOCATION_URI

Retourne la valeur de la variable location_uri globale qui est utilisée comme URI d'emplacement par défaut à utiliser 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.
PACK_MESSAGE Procédures

Crée un message dans la mémoire tampon locale.

Fonction RECEIVE_MESSAGE

Copie le message du canal nommé dans la mémoire tampon locale.
RESET_BUFFER Procédure

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

Supprime le tuyau nommé.

Fonction SEND_MESSAGE

Envoie un message sur une canalisation nommée : Cela crée implicitement une canalisation publique si la canalisation nommée 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 en tant qu'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.
UNPACK_MESSAGE Procédures

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 du canal est affecté en tant que responsable du canal privé.

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

Tableau - Paramètres de fonction CREATE_PIPE

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'ensemble de l'instance.

Attention : N'utilisez pas de nom 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 de prise en charge de 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 toute 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 la valeur existante plus grande.

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

Tableau - Valeurs de retour de fonction CREATE_PIPE

Retour Description

0

réussi.

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

ORA-23322

Échec en raison 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

Table - Exception de fonction CREATE_PIPE

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éez une adresse privée explicite nommée 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 retournée 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 retournée

Valeur retournée 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 message 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

Tableau - 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 bloquer.

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 pour le magasin en nuage utilisé pour stocker les messages.

credential_name est un argument de paquetage initialisé par défaut en tant que NULL.

Vous pouvez définir cette valeur avant d'appeler DBMS_PIPE.RECEIVE_MESSAGE. La valeur de paramètre transmise 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 est initialisée par défaut en tant que NULL.

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

Valeurs retournées

Tableau - Valeurs de retour de fonction RECEIVE_MESSAGE

Retour Description

0

Succès

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

  • Pour recevoir un message à partir d'une barre verticale, appelez d'abord RECEIVE_MESSAGE. Lorsque vous recevez un message, il est retiré du tuyau; par conséquent, un message ne peut être reçu qu'une seule fois. Pour les tuyaux créés implicitement, le tuyau est retiré après que le dernier enregistrement a été retiré du tuyau.

  • Si le canal que vous spécifiez lorsque vous appelez RECEIVE_MESSAGE n'existe pas déjà, Oracle crée implicitement le canal et attend la réception du message. Si le message n'arrive pas dans un intervalle de temporisation désigné, l'appel retourne et le canal est supprimé.

  • Après avoir reçu le message, vous devez effectuer un ou plusieurs appels à UNPACK_MESSAGE pour accéder aux éléments individuels du message. La procédure UNPACK_MESSAGE est surchargée pour déballer les éléments de type DATE, NUMBER, VARCHAR2 et il existe deux procédures supplémentaires pour déballer les éléments RAW et ROWID. Si vous ne connaissez pas le type de données que vous tentez de décompresser, appelez NEXT_ITEM_TYPE pour déterminer le type de l'élément suivant dans la mémoire tampon.

  • Les messages persistants sont garantis pour être écrits ou lus par un seul processus. Cela évite l'incohérence du contenu du message en raison d'écritures et de lectures simultanées. À l'aide d'un canal de messagerie persistant, DBMS_PIPE autorise une seule opération, l'envoi d'un message ou d'un message de réception à être actif à un moment donné. Toutefois, si une opération n'est pas possible en raison d'une opération en cours, le processus réessaie périodiquement jusqu'à ce que la valeur timeout soit atteinte.

  • Si vous utilisez Oracle Cloud Infrastructure Object Storage pour stocker des messages, vous pouvez utiliser les URI natifs d'Oracle Cloud Infrastructure ou des URI Swift. Toutefois, le type de l'URI d'emplacement et des données d'identification doit correspondre comme suit :

    • Si vous utilisez un format d'URI natif pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser l'authentification des clés de signature Oracle Cloud Infrastructure natives dans l'objet de données d'identification.

    • Si vous utilisez le format d'URI Swift pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser une authentification par jeton d'authentification dans l'objet de données d'identification.

Exceptions

Tableau - Exceptions de fonction RECEIVE_MESSAGE

Exception Description

Null pipe name

Erreur d'autorisation. Privilège insuffisant pour supprimer l'enregistrement du canal. La pipe appartient à quelqu'un d'autre.

Fonction SEND_MESSAGE

Cette fonction envoie un message sur le tuyau nommé.

Le message est contenu dans le tampon de message local, qui a été rempli d'appels à PACK_MESSAGE. Vous pouvez créer une barre verticale explicitement à l'aide de CREATE_PIPE, sinon elle est créée 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

Tableau - Paramètres de fonction SEND_MESSAGE

Paramètre Description
credential_name

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

credential_name est un argument de paquetage initialisé par défaut en tant que NULL.

Vous pouvez définir cette valeur avant d'appeler DBMS_PIPE.SEND_MESSAGE. La valeur de paramètre transmise 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 est initialisée par défaut en tant que NULL.

Vous pouvez définir cette valeur avant d'appeler DBMS_PIPE.SEND_MESSAGE. La valeur de paramètre transmise 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. Par défaut, la taille est de 65536 octets.

Le maxpipesize pour un tuyau devient une partie des caractéristiques du tuyau et persiste pendant toute 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 le besoin d'un appel distinct pour ouvrir le canal. Si vous avez créé la canalisation explicitement, vous pouvez utiliser le paramètre facultatif maxpipesize pour remplacer les spécifications de taille de canalisation 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 nom de canal commençant par 'ORA$'. Ces noms sont réservés aux 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 de prise en charge de la globalisation.

timeout

Temps d'attente pendant la tentative de placement d'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

Tableau - Valeurs de retour de fonction SEND_MESSAGE

Retour Description

0

Succès.

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

Si un utilisateur connecté en tant que SYSDBS/SYSOPER recrée une barre verticale, Oracle retourne le statut 0, mais la propriété de la barre verticale 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

  • Les messages persistants sont garantis pour être écrits ou lus par un seul processus. Cela évite l'incohérence du contenu du message en raison d'écritures et de lectures simultanées. À l'aide d'un canal de messagerie persistant, DBMS_PIPE autorise une seule opération, l'envoi d'un message ou d'un message de réception à être actif à un moment donné. Toutefois, si une opération n'est pas possible en raison d'une opération en cours, le processus réessaie périodiquement jusqu'à ce que la valeur timeout soit atteinte.

  • Si vous utilisez Oracle Cloud Infrastructure Object Storage pour stocker des messages, vous pouvez utiliser les URI natifs d'Oracle Cloud Infrastructure ou des URI Swift. Toutefois, le type de l'URI d'emplacement et des données d'identification doit correspondre comme suit :

    • Si vous utilisez un format d'URI natif pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser l'authentification des clés de signature Oracle Cloud Infrastructure natives dans l'objet de données d'identification.

    • Si vous utilisez le format d'URI Swift pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser une authentification par jeton d'authentification dans l'objet de données d'identification.

Exceptions

Table - Exception de fonction SEND_MESSAGE

Exception Description

Null pipe name

Erreur d'autorisation. Privilège insuffisant pour écrire dans la barre verticale. La pipe est privée 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 les URI natifs d'Oracle Cloud Infrastructure ou des URI Swift. Toutefois, le type de l'URI d'emplacement et des données d'identification doit correspondre comme suit :

  • Si vous utilisez un format d'URI natif pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser l'authentification des clés de signature Oracle Cloud Infrastructure natives dans l'objet de données d'identification.

  • Si vous utilisez le format d'URI Swift pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser une authentification par jeton d'authentification dans l'objet de données d'identification.

Exemple

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

Procédure SET_LOCATION_URI

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

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 les URI natifs d'Oracle Cloud Infrastructure ou des URI Swift. Toutefois, le type de l'URI d'emplacement et des données d'identification doit correspondre comme suit :

  • Si vous utilisez un format d'URI natif pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser l'authentification des clés de signature Oracle Cloud Infrastructure natives dans l'objet de données d'identification.

  • Si vous utilisez le format d'URI Swift pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser une authentification par jeton d'authentification dans l'objet de données d'identification.

Exemple

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