Package DBMS_PIPE (pipes de messagerie persistantes)

Le package DBMS_PIPE permet à au moins deux sessions de la même instance de communiquer.

Oracle Autonomous Database on Dedicated Exadata Infrastructure prend en charge les fonctionnalités de base DBMS_PIPE telles qu'elles sont disponibles dans Oracle Database 19c, ainsi que les extensions.

Pour plus d'informations sur les fonctionnalités de base DBMS_PIPE fournies dans Oracle Database, reportez-vous à DBMS_PIPE dans Référence des types et des packages PL/SQL Oracle Database 19c ou Référence des types et des packages PL/SQL Oracle Database 23ai.

Rubriques connexes

DBMS_PIPE Présentation des tuyaux de messagerie persistants

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

Sur Autonomous Database, le package DBMS_PIPE dispose de fonctionnalités étendues pour prendre en charge les canaux de messagerie persistants. Pour plus d'informations, reportez-vous à DBMS_PIPE dans Référence des types et des packages PL/SQL Oracle Database 19c ou Référence des types et des packages PL/SQL Oracle Database 23ai.

Messages persistants dans DBMS_PIPE :

  • Permet d'envoyer et de récupérer des messages très volumineux.

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

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

  • Prise en charge de plusieurs canaux à l'aide du même URI d'emplacement de banque d'objets cloud.

    La fonctionnalité de messagerie persistante permet à deux sessions de base de données ou plus de communiquer avec les messages stockés dans la banque d'objets cloud. Les messages de cette fonctionnalité dans un canal peuvent être mis à la disposition de la base de données en cours uniquement ou de plusieurs bases de données de la même région ou de différentes régions.

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

    • Tuyau implicite : créé automatiquement lorsqu'un message est envoyé avec un nom de pipeline inconnu à l'aide de la fonction DBMS_PIPE.SEND_MESSAGE.
    • Tuyau explicite : créé à l'aide de la fonction DBMS_PIPE.CREATE_PIPE avec un nom de pipeline indiqué par l'utilisateur.
    • Tuyau public : accessible par tout utilisateur disposant du droit d'accès EXECUTE sur le package DBMS_PIPE.
    • Tuyau privé : accessible par les sessions avec le même utilisateur que le créateur de canal.

Remarques :

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 pipeline explicite avec DBMS_PIPE.CREATE_PIPE garantit qu'un pipeline est créé avec les droits d'accès de votre choix, publics ou privés (en définissant le paramètre PRIVATE sur FALSE ou en utilisant la valeur par défaut TRUE).

DBMS_PIPE Limitation

Le package 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 disposez d'une instance Autonomous Database qui utilise AL32UTF8 et d'une autre instance 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.

Récapitulatif 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 package DBMS_PIPE

Sous-programme Description

Fonction CREATE_PIPE

Crée un tuyau (nécessaire pour les tuyaux privés).

Fonction GET_CREDENTIAL_NAME

Renvoie la valeur globale de la variable credential_name.

Fonction GET_LOCATION_URI

Renvoie la valeur de variable location_uri globale utilisée comme URI d'emplacement par défaut à utiliser lorsqu'un message est stocké dans la banque d'objets cloud.

Fonction NEXT_ITEM_TYPE

Renvoie le type de données de l'élément suivant dans le tampon.
PACK_MESSAGE Procédures

Crée le message dans le tampon local.

Fonction RECEIVE_MESSAGE

Copie le message du pipeline nommé dans le tampon local.
RESET_BUFFER Procédure

Purge le contenu du tampon local.
Fonction REMOVE_PIPE

Supprime le canal nommé.

Fonction SEND_MESSAGE

Envoie un message sur un pipeline nommé : cela crée implicitement un pipeline public si le pipeline nommé n'existe pas.

SET_CREDENTIAL_NAME Procédure

Définit la variable credential_name utilisée comme informations d'identification par défaut pour les messages stockés dans la banque d'objets cloud.

SET_LOCATION_URI Procédure

Définit la variable globale location_uri utilisée comme URI d'emplacement par défaut pour les messages stockés dans la banque d'objets cloud.

Fonction UNIQUE_SESSION_NAME

Renvoie 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 pipeline public ou privé. Si l'indicateur private est TRUE, le créateur de pipeline est affecté en tant que propriétaire du pipeline privé.

Les canaux créés explicitement peuvent uniquement être enlevés 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

Table - 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'instance.

Attention : n'utilisez pas de noms de pipe commençant par ORA$. Ils 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 ne distingue pas les majuscules des minuscules. 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 pipeline, en octets.

La taille totale de tous les messages du canal ne peut pas dépasser cette quantité. Le message est bloqué s'il dépasse ce maximum.

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

Le maxpipesize d'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 élevées entraînent l'augmentation de maxpipesize. Les appelants dont la valeur est inférieure utilisent la valeur supérieure existante.

La valeur par défaut maxpipesize de 65536 est applicable à tous les tuyaux.

private

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

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

Valeurs retournées

Table - Valeurs renvoyées de la fonction CREATE_PIPE

Retour Description

0

Succès.

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

ORA-23322

Échec en raison d'un conflit de dénomination.

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 de dénomination.

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 instance 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 renvoie la valeur de variable credential_name globale à utiliser lorsque les messages sont stockés dans la banque d'objets cloud.

Syntaxe

DBMS_PIPE.GET_CREDENTIAL_NAME
         RETURN VARCHAR2;

Valeurs retournées

Valeur renvoyée Description

credential_name

Nom des informations d'identification permettant d'accéder au stockage d'objet cloud.

Exemple

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

Fonction GET_LOCATION_URI

Cette fonction renvoie 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 la banque d'objets cloud.

Syntaxe

DBMS_PIPE.GET_LOCATION_URI
        RETURN VARCHAR2;

Valeur renvoyée

Valeur renvoyé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 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 du canal sur lequel vous voulez recevoir un message.

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

timeout

Temps d'attente d'un message, en secondes. Un délai d'expiration de 0 vous permet de lire sans bloquer.

Le délai d'expiration n'inclut pas le temps passé à exécuter la fonction de cache indiquée avec le paramètre cache_func.

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

credential_name

Nom des informations d'identification de la banque cloud utilisée pour stocker les messages.

credential_name est un argument de package 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 est prioritaire sur la valeur de la variable globale.

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

location_uri

URI d'emplacement de la banque cloud utilisée 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 est prioritaire sur la valeur de la variable globale.

Valeurs retournées

Table - Valeurs renvoyées de la fonction RECEIVE_MESSAGE

Retour Description

0

Succès

1

Délai expiré. Si le pipeline 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.

Remarques sur l'utilisation

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

  • Si le pipeline que vous indiquez lors de l'appel de RECEIVE_MESSAGE n'existe pas encore, Oracle le crée implicitement et attend de recevoir le message. Si le message n'arrive pas dans un délai d'attente défini, l'appel est renvoyé et le canal est supprimé.

  • Après avoir reçu le message, vous devez effectuer des appels vers 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 le tampon.

  • Les messages persistants doivent être écrits ou lus par un seul processus. Cela évite les incohérences de contenu de message dues à des écritures et des lectures simultanées. A l'aide d'un canal de messages persistant, DBMS_PIPE n'autorise qu'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 régulièrement jusqu'à ce que la valeur timeout soit atteinte.

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

    • 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 d'informations 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 d'informations d'identification.

Exceptions

Table - Exceptions de fonction RECEIVE_MESSAGE

Exception Description

Null pipe name

Erreur de droit d'accès. Privilège insuffisant pour supprimer l'enregistrement du canal. Le tuyau appartient à quelqu'un d'autre.

Fonction SEND_MESSAGE

Cette fonction envoie un message sur le pipeline nommé.

Le message est contenu dans le tampon de messages local, qui a été rempli avec des appels vers PACK_MESSAGE. Vous pouvez créer un pipeline 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 informations d'identification de la banque cloud utilisée pour stocker les messages.

credential_name est un argument de package 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 est prioritaire sur la valeur de la variable globale.

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

location_uri

URI d'emplacement de la banque cloud utilisée 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 est prioritaire sur la valeur de la variable globale.

maxpipesize

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

La taille totale de tous les messages du canal ne peut pas dépasser cette quantité. Le message est bloqué s'il dépasse ce maximum. La longueur par défaut est de 65536 octets.

Le maxpipesize d'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 élevées entraînent l'augmentation de maxpipesize. Les appelants dont la valeur est inférieure utilisent simplement la valeur supérieure existante.

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 pipeline explicitement, vous pouvez utiliser le paramètre facultatif maxpipesize pour remplacer les spécifications de taille de pipeline de création.

La valeur par défaut maxpipesize de 65536 est applicable à tous les tuyaux.

pipename

Nom du canal sur lequel vous voulez placer le message.

Si vous utilisez un pipeline explicite, il s'agit du nom que vous avez indiqué lors de l'appel de CREATE_PIPE.

Attention : n'utilisez pas de noms de pipe 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 ne respecte pas la casse. Pour le moment, le nom ne peut pas contenir de caractères de prise en charge de la globalisation.

timeout

Délai d'attente lors de la tentative de placement d'un message sur un canal, en secondes.

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

Valeurs retournées

Table - Valeurs renvoyées de la fonction SEND_MESSAGE

Retour Description

0

Succès.

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

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

1

Délai expiré.

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

3

Une interruption s'est produite.

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

ORA-23322

Droits 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 de dénomination.

Remarques sur l'utilisation

  • Les messages persistants doivent être écrits ou lus par un seul processus. Cela évite les incohérences de contenu de message dues à des écritures et des lectures simultanées. A l'aide d'un canal de messages persistant, DBMS_PIPE n'autorise qu'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 régulièrement jusqu'à ce que la valeur timeout soit atteinte.

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

    • 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 d'informations 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 d'informations d'identification.

Exceptions

Table - Exception de fonction SEND_MESSAGE

Exception Description

Null pipe name

Erreur de droit d'accès. Privilège insuffisant pour écrire dans le pipe. Le tuyau est privé et appartient à quelqu'un d'autre.

SET_CREDENTIAL_NAME Procédure

Cette procédure définit la variable credential_name utilisée comme informations d'identification par défaut lorsque des messages de canal sont stockés dans la banque d'objets cloud.

Syntaxe

DBMS_PIPE.SET_CREDENTIAL_NAME (
   credential_name   IN VARCHAR2 );

Paramètres

Paramètre Description

credential_name

Nom des informations d'identification permettant d'accéder au stockage d'objet cloud.

Remarque sur l'utilisation

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

  • 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 d'informations 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 d'informations d'identification.

Exemple

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

SET_LOCATION_URI Procédure

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 de l'objet ou du fichier. Le format de l'URI dépend du service Cloud Object Storage que vous utilisez. Pour plus de détails, reportez-vous à Formats d'URI de stockage d'objet cloud.

Remarque sur l'utilisation

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

  • 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 d'informations 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 d'informations d'identification.

Exemple

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