Package DBMS_PIPE (tubes singleton)

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

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

Les fonctionnalités de canalisation singleton de DBMS_PIPE fournissent les éléments suivants :

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

  • Partagez le message mis en cache sur 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 un intervalle de temps défini 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 canal singleton peut être de n'importe quel type 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.

Récapitulatif des sous-programmes DBMS_PIPE pour les pipes singleton

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 NEXT_ITEM_TYPE

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

Crée un message dans la mémoire tampon locale
Procédure PURGE

Purge le contenu du pipeline nommé

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

Enlève le canal nommé

Fonction SEND_MESSAGE

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

Renvoie un nom de session unique
UNPACK_MESSAGE Procédures

Accès à 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.

Pour créer un canal singleton, définissez le paramètre singleton sur TRUE. Les arguments suivants sont applicables aux canalisations singleton :

  • singleton : indique que le canal doit être créé en tant que canal unique (valeur par défaut : FALSE).

  • shelflife : spécifiez éventuellement l'expiration d'un délai d'attente (en secondes) du message mis en cache dans le canal singleton. Il peut être utilisé pour l'invalidation implicite d'un message dans un canal singleton.

    Le message shelflife dans le canal singleton peut également être spécifié lorsque vous envoyez un message (reportez-vous à 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

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.

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 mémoire cache dans un canal singleton. Une fois l'heure shelflife indiquée dépassée, 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 implique que le message n'arrive jamais à expiration.

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.

6

Echec de la conversion du canal existant en canal singleton.

  • Un pipe implicite comportant plusieurs messages existants ne peut pas être converti en un pipe singleton.
  • Pour un canal explicite qui n'est pas Singleton, DBMS_PIPE.SEND_MESSAGE ne peut pas envoyer un message dont l'argument singleton est défini sur TRUE.

7

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

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 un tuyau singleton avec un abri 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

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é dans la fonction de cache d'exécution indiquée dans le paramètre cache_func.

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

cache_func

Cachez 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

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

La fonction de 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.

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.

Paramètre de fonction de cache

Les canaux simples prennent en charge la fonction de mise en cache pour mettre automatiquement en cache un message dans le canal dans le cas des deux scénarios suivants :

  • Le canal singleton est vide.
  • Le message dans le canal singleton n'est pas valide en raison du temps shelflife écoulé.

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 en cours qui appelle DBMS_PIPE.RECEIVE_MESSAGE doit disposer des privilèges requis pour exécuter la fonction de cache.

Syntaxe de la fonction de cache

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

pipename

 VARCHAR2

Nom du canal singleton.
Retour Description
0 Succès
Non nul Valeur d'échec renvoyé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 standard au sein 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 au canal singleton, en indiquant éventuellement shelflife pour le message implicite.

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.

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

Pour créer un canal Singleton implicite, définissez le paramètre singleton sur TRUE. Les arguments suivants sont applicables aux canalisations singleton :

  • singleton : indique que le canal doit être créé en tant que canal unique (valeur par défaut : FALSE).
  • shelflife : spécifiez éventuellement une expiration de délai d'attente du message mis en cache dans le canal singleton. Il peut être utilisé pour l'invalidation implicite d'un message dans un canal singleton.

    Cet argument est applicable aux tubes Singleton implicites et explicites. La valeur shelflife indiquée dans Fonction SEND_MESSAGE écrase la valeur shelflife indiquée pour le canal singleton explicite dans 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

Table - Paramètres de fonction SEND_MESSAGE

Paramètre Description

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

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.

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 mémoire cache dans un canal singleton.

Une fois l'heure shelflife indiquée dépassée, 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 implique que le message n'arrive jamais à expiration.

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

6

Echec de la conversion du canal existant en canal singleton.

  • Un pipe implicite comportant plusieurs messages existants ne peut pas être converti en un pipe singleton.
  • Pour un canal explicite qui n'est pas Singleton, DBMS_PIPE.SEND_MESSAGE ne peut pas envoyer un message dont l'argument singleton est défini sur TRUE.

7

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

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.

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.