Ensemble DBMS_PIPE (Singleton Pipes)

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

Oracle Autonomous AI Database sur une infrastructure Exadata dédiée 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 pour Oracle Database 19c ou Informations de référence sur les ensembles et les types PL/SQL pour Oracle Database 26ai pour plus de détails sur la fonctionnalité DBMS_PIPE de base fournie dans Oracle Database.

Aperçu DBMS_PIPE pour les pipelines Singleton

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

Sur Autonomous AI Database, l'ensemble DBMS_PIPE offre des fonctionnalités étendues pour la prise en charge des canaux 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 26ai.

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.

Sommaire des sous-programmes DBMS_PIPE pour Singleton Pipes

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

Sous-programme	Description
Fonction CREATE_PIPE	Crée un tuyau (nécessaire pour les tuyaux privés)
Fonction NEXT_ITEM_TYPE Informations de référence sur les ensembles et types PL/SQL d'Oracle Database 19c Informations de référence sur les ensembles et types PL/SQL d'Oracle Database 26ai	Retourne le type de données de l'élément suivant dans la mémoire tampon
Procédures PACK_MESSAGE Informations de référence sur les ensembles et types PL/SQL d'Oracle Database 19c Informations de référence sur les ensembles et types PL/SQL d'Oracle Database 26ai	Crée le message dans la mémoire tampon locale
Procédure d'ÉPURGATION Informations de référence sur les ensembles et types PL/SQL d'Oracle Database 19c Informations de référence sur les ensembles et types PL/SQL d'Oracle Database 26ai	Épure le contenu du tuyau nommé
Fonction RECEIVE_MESSAGE	Copie le message du tuyau nommé dans la mémoire tampon locale
Procédure RESET_BUFFER Informations de référence sur les ensembles et types PL/SQL d'Oracle Database 19c Informations de référence sur les ensembles et types PL/SQL d'Oracle Database 26ai	Épure le contenu de la mémoire tampon locale
Fonction REMOVE_PIPE Informations de référence sur les ensembles et types PL/SQL d'Oracle Database 19c Informations de référence sur les ensembles et types PL/SQL d'Oracle Database 26ai	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 Informations de référence sur les ensembles et types PL/SQL d'Oracle Database 19c Informations de référence sur les ensembles et types PL/SQL d'Oracle Database 26ai	Retourne un nom de session unique
Procédures UNPACK_MESSAGE Informations de référence sur les ensembles et types PL/SQL d'Oracle Database 19c Informations de référence sur les ensembles et types PL/SQL d'Oracle Database 26ai	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.

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

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 barre verticale 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

Retour	Description
`0`	Réussite. 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

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

Table - Paramètres de fonction RECEIVE_MESSAGE

Paramètre Description

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`

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

Table - Valeurs de retour de fonction RECEIVE_MESSAGE

Retour	Description
`0`	Réussite
`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	Réussite
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

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 le canal nommé.

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

Fonction CREATE_PIPE et sera la valeur par défaut pour tous les nouveaux messages mis en cache dans la barre verticale 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 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 65536 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

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

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.

Contenu connexe

Mettre en cache des messages à l'aide de canaux singletons