Ensemble DBMS_PIPE (tuyaux simples)

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 canalisations Singleton

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 canalisations singleton. 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.

Les fonctions de canalisation singleton dans DBMS_PIPE fournissent les éléments suivants :

  • Possibilité de mettre en mémoire cache et d'extraire un message personnalisé, allant jusqu'à 32 767 octets, dans la mémoire de la base de données Oracle. La taille maximale du message de 32 767 octets est applicable à tous les tuyaux, y compris les tuyaux Singleton. Les versions précédentes de DBMS_PIPE avaient une taille de message maximale inférieure.

  • 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 (en secondes) d'un paramètre spécifié par l'utilisateur (shelflife).

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

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

Un canal Singleton 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.
  • Public Pipe : 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.

Résumé des sous-programmes DBMS_PIPE pour Singleton Pipes

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 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
Procédure d'ÉPURGATION

Épure le contenu du tuyau nommé

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

Pour créer un canal 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 mono-ton (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 canal Singleton. Il peut être utilisé pour l'invalidation implicite du message dans Singleton Pipe.

    Le message shelflife dans Singleton Pipe 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 - 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.

singleton

Utilisez TRUE pour créer un canal Singleton.

Valeur par défaut : FALSE

shelflife

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

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

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.

6

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

  • Impossible de convertir une canalisation implicite contenant plus d'un message existant en canalisation singleton.
  • Pour une barre verticale explicite qui n'est pas Singleton, DBMS_PIPE.SEND_MESSAGE ne peut pas envoyer de message avec l'argument singleton 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 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 un Singleton Pipe 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 message 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 - 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é 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

Nom de la fonction de mise en cache 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 - 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 lors de l'utilisation d'un canal Singleton.

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.

Paramètre de fonction de mémoire cache

Singleton Pipes prend en charge la fonction de cache pour mettre automatiquement en cache un message dans le tuyau dans le cas des deux scénarios suivants :

  • Le tuyau singleton est vide.
  • Le message dans le canal 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 mémoire cache, l'utilisateur de session courant qui appelle DBMS_PIPE.RECEIVE_MESSAGE doit disposer des privilèges requis pour exécuter la fonction de mémoire 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é à partir des sessions de lecteur de Singleton Pipe. Les opérations typiques d'une fonction de cache sont les suivantes :

  • Créez un canal Singleton, pour un canal 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 - 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.

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

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 mono-ton (valeur par défaut : FALSE).
  • shelflife : Facultativement, spécifiez l'expiration de la durée de conservation du message mis en cache dans le canal Singleton. Il peut être utilisé pour l'invalidation implicite du message dans Singleton Pipe.

    Cet argument s'applique aussi bien aux tubes Singleton implicites qu'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 mémoire 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 - 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 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).

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.

singleton

Utilisez TRUE pour créer un canal Singleton.

Valeur par défaut : FALSE

shelflife

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

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

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

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

6

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

  • Impossible de convertir une canalisation implicite contenant plus d'un message existant en canalisation singleton.
  • Pour une barre verticale explicite qui n'est pas Singleton, DBMS_PIPE.SEND_MESSAGE ne peut pas envoyer de message avec l'argument singleton 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

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.