Documentation sur Oracle Cloud Infrastructure

Ensemble DBMS_PIPE

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

Oracle Autonomous AI Database prend en charge la fonctionnalité DBMS_PIPE de base, disponible dans Oracle Database 19c, plus les extensions.

Voir DBMS_PIPE pour plus de détails sur la fonctionnalité DBMS_PIPE de base fournie dans Oracle Database.

Rubrique parent : Informations de référence sur les ensembles fournis avec Autonomous AI Database

DBMS_PIPE Aperçu pour Singleton Pipes

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

Dans Autonomous AI Database, l'ensemble DBMS_PIPE offre des fonctionnalités étendues pour la prise en charge des canalisations singleton.

Les fonctions de tuyau Singleton dans DBMS_PIPE fournissent les éléments suivants :

  • Possibilité de mettre en mémoire cache et d'extraire un message personnalisé d'un maximum de 32 767 octets dans la mémoire de la base de données Oracle. La taille maximale du message de 32 767 octets s'applique à tous les tuyaux, y compris les tuyaux Singleton. La taille maximale des messages des versions précédentes de DBMS_PIPE était plus petite.

  • Partagez le message mis en cache entre plusieurs sessions de base de données avec des lectures simultanées.

  • Méthodes d'invalidation du cache :

    • Invalidation explicite du cache contrôlée par l'utilisateur.
    • Invalidation du cache après l'intervalle de temps d'un paramètre spécifié par l'utilisateur (shelflife) (en secondes).

  • API PL/SQL déclaratives et faciles à utiliser pour la mise en cache.

  • Prend en charge les bases de données en lecture seule et en lecture-écriture.

Un tuyau Singleton peut être l'un des types DBMS_PIPE pris en charge :

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

Rubrique parent : Ensemble DBMS_PIPE

Sommaire des sous-programmes DBMS_PIPE pour Singleton Pipes

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

Tableau 6-1 Sous-programmes d'ensemble DBMS_PIPE

Sous-programme Description

Fonction CREATE_PIPE

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

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 le message dans la mémoire tampon locale

Procédure d'ÉPURGATION

Épure le contenu du tuyau nommé

Fonction RECEIVE_MESSAGE

Copie le message du tuyau 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 pipe nommée : Cela crée implicitement une pipe publique si la pipe nommée n'existe pas.

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 de la canalisation est affecté en tant que responsable de la canalisation privée.
  • Fonction RECEIVE_MESSAGE
    Cette fonction copie le message dans la mémoire tampon du message local.
  • Fonction SEND_MESSAGE
    Cette fonction envoie un message sur la barre verticale nommée.

Rubrique parent : Ensemble DBMS_PIPE

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.

Pour créer un tuyau Singleton, réglez le paramètre singleton à TRUE. Les arguments suivants s'appliquent à Singleton Pipes :

  • singleton : Indique que la barre verticale doit être créée en tant que barre verticale Singleton (valeur par défaut : FALSE).

  • shelflife : Facultativement, spécifiez l'expiration de la durée de conservation (en secondes) du message mis en cache dans le tuyau Singleton. Il peut être utilisé pour l'invalidation implicite du message dans Singleton Pipe.

    Le message shelflife dans le canal Singleton peut également être spécifié lorsque vous envoyez un message (voir Fonction SEND_MESSAGE).

Syntaxe 

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

Paramètres

Tableau 6-2 : 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 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.

singleton

Utilisez TRUE pour créer un tuyau Singleton.

Valeur par défaut : FALSE

shelflife

Délai d'expiration en secondes d'un message mis en cache dans Singleton Pipe. Une fois le temps shelflife spécifié dépassé, le message n'est plus accessible à partir du canal. Le paramètre shelflife ne s'applique qu'à un tuyau Singleton.

La valeur par défaut est 0, ce qui signifie que le message n'expire jamais.

Valeurs retournées

Tableau 6-3 : Valeurs de retour de fonction CREATE_PIPE

Retour Description

0

réussi.

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.

6

Échec de la conversion de la canalisation existante en canalisation singleton.

  • Une barre verticale implicite avec plusieurs messages existants ne peut pas être convertie en une barre verticale Singleton.
  • Pour une barre verticale explicite qui n'est pas Singleton, DBMS_PIPE.SEND_MESSAGE ne peut pas envoyer un message dont l'argument singleton est réglé à TRUE.

7

Une valeur différente de zéro est indiquée pour le paramètre shelflife et la canalisation n'est pas une canalisation singleton.

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

Tableau 6-4 : 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 un tuyau Singleton avec une durée de conservation de 1 heure.

DECLARE
  l_status INTEGER;
BEGIN
  l_status := DBMS_PIPE.create_pipe(pipename  => 'MY_PIPE1',
                                    private   => TRUE,
                                    singleton => TRUE,
                                    shelflife => 3600);
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,
   cache_func    IN VARCHAR2     DEFAULT NULL)
RETURN INTEGER;

Paramètres

Tableau 6-5 : 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é dans la fonction de mémoire cache d'exécution spécifiée dans le paramètre cache_func.

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

cache_func

Mettre en cache le nom de la fonction pour mettre automatiquement en cache un message dans un canal Singleton.

Le nom de la fonction doit être entièrement qualifié avec le schéma propriétaire :

  • OWNER.FUNCTION_NAME
  • OWNER.PACKAGE.FUNCTION_NAME

Valeur par défaut : NULL

Valeurs retournées

Tableau 6-6 : 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.
8

La fonction Cache ne peut être spécifiée que lorsque vous utilisez un tuyau Singleton.

ORA-23322

L'utilisateur ne dispose pas de privilèges suffisants pour lire à partir du canal.

Notes d'utilisation

Pour recevoir un message d'un canal, appelez d'abord RECEIVE_MESSAGE. Lorsque vous recevez un message, il est supprimé 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 la suppression du dernier enregistrement 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 de recevoir le message. Si le message n'arrive pas dans un intervalle de temporisation désigné, l'appel retourne et le tuyau 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éballer, appelez NEXT_ITEM_TYPE pour déterminer le type de l'élément suivant dans la mémoire tampon.

Paramètre de fonction de mémoire cache

Singleton Pipes prend en charge la fonction cache pour mettre automatiquement en cache un message dans le tuyau dans les deux cas suivants :

  • Singleton Pipe est vide.
  • Le message dans la barre verticale Singleton n'est pas valide en raison du temps écoulé pour shelflife.

Le nom de la fonction doit être entièrement qualifié avec le schéma propriétaire :

  • OWNER.FUNCTION_NAME
  • OWNER.PACKAGE.FUNCTION_NAME

Pour utiliser une fonction de cache, l'utilisateur de session courant qui appelle DBMS_PIPE.RECEIVE_MESSAGE doit disposer des privilèges requis pour exécuter la fonction de cache.

Syntaxe de la fonction de mémoire cache

CREATE OR REPLACE FUNCTION cache_function_name (
       pipename  IN VARCHAR2
) RETURN INTEGER;
Paramètre Type de données Description

pipename

 VARCHAR2

Nom du tuyau Singleton.
Retour Description
0 Succès
Non nul Valeur d'échec retournée par DBMS_PIPE.RECEIVE_MESSAGE

Définissez une fonction de cache pour fournir l'encapsulation et l'abstraction de la complexité des sessions de lecture de Singleton Pipe. Les opérations typiques d'une fonction de cache sont les suivantes :

  • Créez un tuyau Singleton, pour un tuyau explicite, à l'aide de DBMS_PIPE.CREATE_PIPE.
  • Créez le message à mettre en cache dans le canal Singleton.
  • Envoyer un message à Singleton Pipe, en spécifiant éventuellement shelflife pour le message implicite.

Exceptions

Tableau 6-7 : 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.

Exemple 

DECLARE
  l_status INTEGER;
BEGIN
  l_status := DBMS_PIPE.receive_message(pipename   => 'MY_PIPE1',
                                        timeout    => 1,
                                        cache_func => 'MY_USER.MY_CACHE_FUNC');
END;
/

Fonction SEND_MESSAGE

Cette fonction envoie un message sur la canalisation nommée.

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.

Pour créer un canal Singleton implicite, réglez le paramètre singleton à TRUE. Les arguments suivants s'appliquent à Singleton Pipes :

  • singleton : Indique que la barre verticale doit être créée en tant que barre verticale Singleton (valeur par défaut : FALSE).
  • shelflife : Facultativement, spécifiez l'expiration de la durée de conservation du message mis en cache dans le tuyau Singleton. Il peut être utilisé pour l'invalidation implicite du message dans Singleton Pipe.

    Cet argument s'applique aux tuyaux Singleton implicites et explicites. Une valeur shelflife spécifiée dans la fonction SEND_MESSAGE remplace la valeur shelflife spécifiée pour le canal Singleton explicite dans la fonction CREATE_PIPE et sera la valeur par défaut pour tous les nouveaux messages mis en cache dans le canal Singleton.

Syntaxe 

DBMS_PIPE.SEND_MESSAGE (
    pipename     IN VARCHAR2,
    timeout      IN INTEGER DEFAULT MAXWAIT,
    maxpipesize  IN INTEGER DEFAULT 65536,
    singleton    IN BOOLEAN DEFAULT FALSE,
    shelflife    IN INTEGER DEFAULT 0)
RETURN INTEGER;

Paramètres

Tableau 6-8 : Paramètres de fonction SEND_MESSAGE

Paramètre Description

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).

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 de 655336 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.

singleton

Utilisez TRUE pour créer un tuyau Singleton.

Valeur par défaut : FALSE

shelflife

Délai d'expiration en secondes d'un message mis en cache dans Singleton Pipe.

Une fois le temps shelflife spécifié dépassé, le message n'est plus accessible à partir du canal. Le paramètre shelflife ne s'applique qu'à un tuyau Singleton.

La valeur par défaut est 0, ce qui signifie que le message n'expire jamais.

Valeurs retournées

Tableau 6-9 : 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é.

6

Échec de la conversion de la canalisation existante en canalisation singleton.

  • Une barre verticale implicite avec plusieurs messages existants ne peut pas être convertie en une barre verticale Singleton.
  • Pour une barre verticale explicite qui n'est pas Singleton, DBMS_PIPE.SEND_MESSAGE ne peut pas envoyer un message dont l'argument singleton est réglé à TRUE.

7

Une valeur différente de zéro est indiquée pour le paramètre shelflife et la canalisation n'est pas une canalisation singleton.

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.

Exceptions

Tableau 6-10 : 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.

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.

Dans Autonomous AI Database, l'ensemble DBMS_PIPE offre des fonctionnalités étendues pour prendre en charge les canaux de messagerie persistants.

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 canal.

  • 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 du 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'aide de cette fonctionnalité, les messages d'un canal peuvent être mis à la disposition uniquement de la base de données courante ou ê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 :

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

Lors de l'envoi et de la réception de 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).

Limitation de 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'intelligence artificielle 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.

Pour plus d'informations, voir Sélectionner un jeu de caractères pour une base de données d'IA autonome.

Rubrique parent : Ensemble DBMS_PIPE

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 6-11 Sous-programmes d'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 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.

PACK_MESSAGE Procédures

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.

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 un tuyau nommé : Cela crée implicitement un tuyau public si le tuyau nommé n'existe pas.

SET_CREDENTIAL_NAME Procédure

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.

SET_LOCATION_URI Procédure

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.

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 de la canalisation est affecté en tant que responsable de la canalisation privée.
  • 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.
  • 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.
  • Fonction RECEIVE_MESSAGE
    Cette fonction copie le message dans la mémoire tampon du message local.
  • Fonction SEND_MESSAGE
    Cette fonction envoie un message sur la barre verticale nommée.
  • 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 canalisés sont stockés dans le magasin d'objets en nuage.
  • Procédure SET_LOCATION_URI
    Cette procédure définit la variable location_uri globale.

Rubrique parent : Ensemble DBMS_PIPE

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

Tableau 6-12 : 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 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

Tableau 6-13 : Valeurs de retour de fonction CREATE_PIPE

Retour Description

0

réussi.

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

Tableau 6-14 : 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é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 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 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

Tableau 6-15 : 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.

La valeur credential_name peut être un principal de ressource OCI, un principal de service Azure, un nom de ressource Amazon (ARN) ou un compte de service Google. Voir Configurer des politiques et des rôles pour accéder aux ressources pour plus d'informations sur l'authentification basée sur le principal de ressource.

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

Tableau 6-16 : 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 d'un canal, appelez d'abord RECEIVE_MESSAGE. Lorsque vous recevez un message, il est supprimé 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 la suppression du dernier enregistrement 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 de recevoir le message. Si le message n'arrive pas dans un intervalle de temporisation désigné, l'appel retourne et le tuyau 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éballer, appelez NEXT_ITEM_TYPE pour déterminer le type de l'élément suivant dans la mémoire tampon.

  • Les messages persistants sont garantis d'être écrits ou lus par un seul processus. Cela évite les incohérences dans le contenu des messages 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 tente de nouveau 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 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 :

    • Si vous utilisez un format d'URI natif pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser l'authentification native des clés de signature Oracle Cloud Infrastructure 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 6-17 : 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 la canalisation nommée.

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

Tableau 6-18 : 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.

La valeur credential_name peut être un principal de ressource OCI, un principal de service Azure, un nom de ressource Amazon (ARN) ou un compte de service Google. Voir Configurer des politiques et des rôles pour accéder aux ressources pour plus d'informations sur l'authentification basée sur le principal de ressource.

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 de 655336 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

Tableau 6-19 : 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

  • Les messages persistants sont garantis d'être écrits ou lus par un seul processus. Cela évite les incohérences dans le contenu des messages 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 tente de nouveau 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 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 :

    • Si vous utilisez un format d'URI natif pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser l'authentification native des clés de signature Oracle Cloud Infrastructure 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 6-20 : 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.

SET_CREDENTIAL_NAME Procédure

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.

La valeur credential_name peut être un principal de ressource OCI, un principal de service Azure, un nom de ressource Amazon (ARN) ou un compte de service Google. Voir Configurer des politiques et des rôles pour accéder aux ressources pour plus d'informations sur l'authentification basée sur le principal de ressource.

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 :

  • Si vous utilisez un format d'URI natif pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser l'authentification native des clés de signature Oracle Cloud Infrastructure 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;
/

SET_LOCATION_URI Procédure

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 des détails, voir Formats d'URI DBMS_CLOUD.

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 :

  • Si vous utilisez un format d'URI natif pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser l'authentification native des clés de signature Oracle Cloud Infrastructure 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;
/