Documentation Oracle Cloud Infrastructure

Package DBMS_PIPE

Le package DBMS_PIPE permet à plusieurs sessions de la même instance de communiquer.

Oracle Autonomous Database prend en charge les fonctionnalités de base de DBMS_PIPE telles que disponibles dans Oracle Database 19c, ainsi que les extensions.

Pour plus d'informations sur la fonctionnalité de base DBMS_PIPE fournie dans Oracle Database, reportez-vous à DBMS_PIPE.

Rubrique parent : Référence de package fourni avec Autonomous Database

DBMS_PIPE Présentation des tubes simples

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

Sur Autonomous Database, le package DBMS_PIPE a des fonctionnalités étendues pour prendre en charge les canaux singleton.

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

  • Possibilité de mettre en cache et d'extraire un message personnalisé de 32 767 octets maximum dans la mémoire de base de données Oracle. La taille de message maximale de 32 767 octets est applicable à tous les tubes, y compris les tubes simples. Les versions précédentes de DBMS_PIPE avaient une taille de message maximale 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 de cache explicite 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 cache.

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

Un canal unique peut être l'un des types DBMS_PIPE pris en charge :

  • Tuyau implicite : créé automatiquement lorsqu'un message est envoyé avec un nom de tuyau 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 tuyau spécifié 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 pipe.

Rubrique parent : Package DBMS_PIPE

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

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

Tableau 6-1 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 tuyau nommé

Fonction RECEIVE_MESSAGE

Copie le message du canal nommé dans le tampon local

Procédure RESET_BUFFER

Purge le contenu du tampon local

Fonction REMOVE_PIPE

Supprime le tuyau nommé

Fonction SEND_MESSAGE

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

Fonction UNIQUE_SESSION_NAME

Renvoie un nom de session unique

UNPACK_MESSAGE Procédures

Accède à l'élément suivant dans le tampon
  • CREATE_PIPE Fonction
    Cette fonction crée explicitement un canal public ou privé. Si l'indicateur private est TRUE, le créateur de canal est affecté en tant que propriétaire du canal privé.
  • RECEIVE_MESSAGE Fonction
    Cette fonction copie le message dans le tampon de messages local.
  • SEND_MESSAGE Fonction
    Cette fonction envoie un message sur le canal nommé.

Rubrique parent : Package 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 canal est affecté en tant que propriétaire 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 singleton pipe, définissez le paramètre singleton sur TRUE. Les arguments suivants sont applicables aux tubes singleton :

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

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

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

Tableau 6-2 Paramètres de fonction CREATE_PIPE

Paramètre Description

pipename

Nom du pipeline 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$. 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 ne tient pas compte de 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 pipeline, en octets.

La taille totale de tous les messages sur le pipeline 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 de 66536 octets.

La valeur maxpipesize d'un tuyau devient une partie des caractéristiques du tuyau et persiste pendant toute sa durée de vie. Les appelants de SEND_MESSAGE avec des valeurs plus élevées augmentent la valeur de maxpipesize. Les appelants dont la valeur est inférieure utilisent la valeur supérieure existante.

La valeur par défaut maxpipesize (65536) est applicable à tous les tubes.

private

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

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

singleton

Utilisez TRUE pour créer un singleton pipe.

La valeur par défaut est FALSE

shelflife

Délai d'expiration en secondes d'un message mis en cache dans Singleton Pipe. Une fois l'heure shelflife indiquée dépassée, le message n'est plus accessible à partir du canal. Le paramètre shelflife ne s'applique qu'à un simple tube.

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

Valeurs renvoyées

Tableau 6-3 Valeurs renvoyées par la fonction CREATE_PIPE

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 renvoie 0, ce qui indique qu'il a réussi et toutes les données déjà présentes dans le canal restent.

6

Echec de la conversion du pipeline existant en pipeline singleton.

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

7

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

ORA-23322

Echec en raison d'un conflit de noms.

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

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

Tableau 6-5 Paramètres de fonction RECEIVE_MESSAGE

Paramètre Description

pipename

Nom du canal sur lequel 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. Un délai d'attente 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 : constante MAXWAIT, définie comme 86400000 (1000 jours).

cache_func

Cachez le nom de la fonction pour mettre automatiquement en cache un message dans un canal unique.

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

  • OWNER.FUNCTION_NAME
  • OWNER.PACKAGE.FUNCTION_NAME

La valeur par défaut est NULL

Valeurs renvoyées

Tableau 6-6 RECEIVE_MESSAGE Valeurs renvoyées par la fonction

Retour Description

0

Succès

1

Le délai a expiré. Si le tuyau a été implicitement créé et est vide, il est enlevé.

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 lorsque vous utilisez un canal unique.

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 retiré 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é une fois que le dernier enregistrement a été supprimé du tuyau.

Si le canal que vous indiquez 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 délai d'attente défini, l'appel revient et le canal est supprimé.

Une fois le message reçu, vous devez passer 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écompresser les éléments de type DATE, NUMBER, VARCHAR2. Il existe deux procédures supplémentaires pour décompresser 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

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

  • Singleton Pipe est vide.
  • Le message dans le canal unique n'est pas valide en raison d'un délai de 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 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 de la canalisation unique.
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 d'une fonction de cache sont les suivantes :

  • Créez un canal unique, pour un canal explicite, à l'aide de DBMS_PIPE.CREATE_PIPE.
  • Créez le message à mettre en cache dans le singleton pipe.
  • Envoyez un message à Singleton Pipe, en spécifiant éventuellement un 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 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 message local, qui a été rempli 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 unique implicite, définissez le paramètre singleton sur TRUE. Les arguments suivants sont applicables aux tubes singleton :

  • singleton : indique que le canal doit être créé en tant que canal unique (valeur par défaut : FALSE).
  • shelflife : indiquez éventuellement l'expiration de la durée de conservation du message mis en cache dans le singleton pipe. Il peut être utilisé pour l'invalidation implicite d'un message dans Singleton Pipe.

    Cet argument est applicable aux tubes 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 unique explicite dans la fonction CREATE_PIPE et sera la valeur par défaut pour tout nouveau message mis en cache dans le canal unique.

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 du canal sur lequel vous voulez placer le message.

Si vous utilisez un canal explicite, il s'agit du nom que vous avez indiqué lorsque vous avez appelé CREATE_PIPE.

Attention : n'utilisez pas de noms de pipe commençant par 'ORA$'. Ces noms sont réservés à l'usage des 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

Temps 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 sur le pipeline ne peut pas dépasser ce montant. Le message est bloqué s'il dépasse ce maximum. La longueur par défaut est de 65536 octets.

La valeur maxpipesize d'un tuyau devient une partie des caractéristiques du tuyau et persiste pendant toute sa durée de vie. Les appelants de SEND_MESSAGE avec des valeurs plus élevées augmentent la valeur de maxpipesize. Les appelants dont la valeur est inférieure utilisent simplement la valeur supérieure existante.

Si vous indiquez maxpipesize dans le cadre de la procédure SEND_MESSAGE, vous n'avez plus besoin d'un appel distinct pour ouvrir le canal. Si vous avez créé le canal de manière explicite, 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 (65536) est applicable à tous les tubes.

singleton

Utilisez TRUE pour créer un singleton pipe.

La valeur par défaut est FALSE

shelflife

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

Une fois l'heure shelflife indiquée dépassée, le message n'est plus accessible à partir du canal. Le paramètre shelflife ne s'applique qu'à un simple tube.

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

Valeurs renvoyées

Tableau 6-9 SEND_MESSAGE Valeurs renvoyées par la fonction

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 renvoie 0, ce qui indique qu'il a réussi 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 renvoie le statut 0, mais la propriété du canal reste inchangée.

1

Le délai a expiré.

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é implicitement créé et est vide, il est enlevé.

3

Une interruption s'est produite.

Si le tuyau a été implicitement créé et est vide, il est enlevé.

6

Echec de la conversion du pipeline existant en pipeline singleton.

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

7

Une valeur différente de zéro est indiquée pour le paramètre shelflife et le tube n'est pas un tube 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 de dénomination.

Exceptions

Tableau 6-10 Exception de fonction SEND_MESSAGE

Exception Description

Null pipe name

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

DBMS_PIPE Présentation des pipelines de messagerie persistants

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

Sur Autonomous Database, le package DBMS_PIPE dispose de fonctionnalités étendues pour prendre en charge les canaux de messagerie persistants.

Messages persistants dans DBMS_PIPE :

  • Prendre en charge 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.

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

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

    La fonctionnalité de messagerie persistante permet à plusieurs sessions de base de données de communiquer avec les messages stockés dans la banque d'objets cloud. L'utilisation de ces messages de fonctionnalité dans un canal peut être mise à la disposition de la base de données en cours uniquement ou 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 :

    • Tuyau implicite : créé automatiquement lorsqu'un message est envoyé avec un nom de tuyau 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 tuyau spécifié par l'utilisateur.
    • Public Pipe : 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 pipe.
Remarque

Lorsque vous envoyez et recevez des messages dans différentes bases de données à l'aide de messages persistants, Oracle vous recommande d'appeler DBMS_PIPE.CREATE_PIPE avant d'envoyer ou de recevoir des messages. La création d'un canal explicite avec DBMS_PIPE.CREATE_PIPE garantit qu'un canal est créé avec les droits d'accès souhaités, publics ou privés (en définissant le paramètre PRIVATE sur FALSE ou en utilisant la valeur par défaut TRUE).

DBMS_PIPE Limitation

Le package DBMS_PIPE ne prend pas en charge l'envoi de messages entre les bases de données qui utilisent des jeux de caractères différents. Par exemple, si vous avez une instance Autonomous Database qui utilise AL32UTF8 et une autre instance qui utilise WE8MSWIN1252, vous ne pouvez pas envoyer de messages avec DBMS_PIPE entre ces deux bases de données. Dans ce cas, le système génère l'erreur ORA-12704 si vous tentez d'envoyer des messages avec DBMS_PIPE entre ces deux bases de données.

Pour plus d'informations, reportez-vous à Choix d'un jeu de caractères pour Autonomous Database.

Rubrique parent : Package DBMS_PIPE

Récapitulatif des sous-programmes DBMS_PIPE pour la messagerie persistante

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

Tableau 6-11 Sous-programmes du package DBMS_PIPE

Sous-programme Description

Fonction CREATE_PIPE

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

Fonction GET_CREDENTIAL_NAME

Renvoie la valeur globale de la variable credential_name.

Fonction GET_LOCATION_URI

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

Fonction NEXT_ITEM_TYPE

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

PACK_MESSAGE Procédures

Crée un message dans la mémoire tampon locale.

Fonction RECEIVE_MESSAGE

Copie le message du pipeline nommé dans le tampon local.

Procédure RESET_BUFFER

Purge le contenu du tampon local.

Fonction REMOVE_PIPE

Supprime le pipe nommé.

Fonction SEND_MESSAGE

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

Procédure SET_CREDENTIAL_NAME

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

Procédure SET_LOCATION_URI

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

Fonction UNIQUE_SESSION_NAME

Renvoie un nom de session unique.

UNPACK_MESSAGE Procédures

Permet d'accéder à l'élément suivant dans le tampon.
  • CREATE_PIPE Fonction
    Cette fonction crée explicitement un canal public ou privé. Si l'indicateur private est TRUE, le créateur de canal est affecté en tant que propriétaire du canal privé.
  • GET_CREDENTIAL_NAME Fonction
    Cette fonction renvoie la valeur de variable credential_name globale à utiliser lorsque les messages sont stockés dans la banque d'objets cloud.
  • GET_LOCATION_URI Fonction
    Cette fonction renvoie la valeur de variable location_uri globale qui peut être utilisée comme URI d'emplacement par défaut lorsque les messages de canal sont stockés dans la banque d'objets cloud.
  • RECEIVE_MESSAGE Fonction
    Cette fonction copie le message dans le tampon de messages local.
  • SEND_MESSAGE Fonction
    Cette fonction envoie un message sur le canal nommé.
  • Procédure SET_CREDENTIAL_NAME
    Cette procédure définit la variable credential_name qui est utilisée comme informations d'identification par défaut lorsque les messages de canal sont stockés dans la banque d'objets cloud.
  • Procédure SET_LOCATION_URI
    Cette procédure définit la variable location_uri globale.

Rubrique parent : Package 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 canal est affecté en tant que propriétaire du canal privé.

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 pipeline 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$. 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 ne tient pas compte de 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 pipeline, en octets.

La taille totale de tous les messages sur le pipeline 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 de 66536 octets.

La valeur maxpipesize d'un tuyau devient une partie des caractéristiques du tuyau et persiste pendant toute sa durée de vie. Les appelants de SEND_MESSAGE avec des valeurs plus élevées augmentent la valeur de maxpipesize. Les appelants dont la valeur est inférieure utilisent la valeur supérieure existante.

La valeur par défaut maxpipesize (65536) est applicable à tous les tubes.

private

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

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

Valeurs renvoyées

Tableau 6-13 Valeurs renvoyées par la fonction CREATE_PIPE

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 renvoie 0, ce qui indique qu'il a réussi et toutes les données déjà présentes dans le canal restent.

ORA-23322

Echec en raison d'un conflit de noms.

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

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 une valeur privée explicite nommée MY_PIPE1

DECLARE
  l_status INTEGER;
BEGIN
  l_status := DBMS_PIPE.create_pipe(
      pipename  => 'MY_PIPE1',
      private   => TRUE);
END;
/

Fonction GET_CREDENTIAL_NAME

Cette fonction renvoie la valeur de variable credential_name globale à utiliser lorsque les messages sont stockés dans la banque d'objets cloud.

Syntaxe

DBMS_PIPE.GET_CREDENTIAL_NAME
         RETURN VARCHAR2;

Valeurs renvoyées

Valeur de retour Description

credential_name

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

Exemple

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

Fonction GET_LOCATION_URI

Cette fonction renvoie la valeur de variable location_uri globale qui peut être utilisée comme URI d'emplacement par défaut lorsque les messages de canal sont stockés dans la banque d'objets cloud.

Syntaxe

DBMS_PIPE.GET_LOCATION_URI
        RETURN VARCHAR2;

Valeur de retour

Valeur de retour Description
location_uri

URI d'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 du canal sur lequel 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. Un délai d'attente de 0 vous permet de lire sans bloquer.

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

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

credential_name

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

credential_name est un argument de package initialisé par défaut en tant que NULL.

Vous pouvez définir cette valeur avant d'appeler DBMS_PIPE.RECEIVE_MESSAGE. La valeur de paramètre transmise est prioritaire sur la valeur de la variable globale.

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

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. Pour plus d'informations sur l'authentification basée sur le principal de ressource, reportez-vous à Configuration de stratégies et de rôles pour accéder aux ressources.

location_uri

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

Valeurs renvoyées

Tableau 6-16 Valeurs renvoyées par la fonction RECEIVE_MESSAGE

Retour Description

0

Succès

1

Le délai a expiré. Si le tuyau a été implicitement créé et est vide, il est enlevé.

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 retiré 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é une fois que le dernier enregistrement a été supprimé du tuyau.

  • Si le canal que vous indiquez 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 délai d'attente défini, l'appel revient et le canal est supprimé.

  • Une fois le message reçu, vous devez passer 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écompresser les éléments de type DATE, NUMBER, VARCHAR2. Il existe deux procédures supplémentaires pour décompresser 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.

  • Il est garanti que les messages persistants sont écrits ou lus par un seul processus. Cela évite les incohérences de contenu de message dues à des écritures et des lectures simultanées. A l'aide d'un canal de messagerie persistant, DBMS_PIPE permet qu'une seule opération, l'envoi d'un message ou un message de réception, soit active à 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 régulièrement jusqu'à ce que la valeur timeout soit atteinte.

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

    • Si vous utilisez un format d'URI natif pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser l'authentification des clés de signature Oracle Cloud Infrastructure natives dans l'objet d'informations d'identification.

    • Si vous utilisez le format d'URI Swift pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser une authentification par jeton d'authentification dans l'objet d'informations d'identification.

Exceptions

Tableau 6-17 Exceptions de fonction RECEIVE_MESSAGE

Exception Description

Null pipe name

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

Fonction SEND_MESSAGE

Cette fonction envoie un message sur le pipeline nommé.

Le message est contenu dans le tampon de message local, qui a été rempli 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 informations d'identification de la banque cloud utilisée pour stocker les messages.

credential_name est un argument de package initialisé par défaut en tant que NULL.

Vous pouvez définir cette valeur avant d'appeler DBMS_PIPE.SEND_MESSAGE. La valeur de paramètre transmise est prioritaire sur la valeur de la variable globale.

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

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. Pour plus d'informations sur l'authentification basée sur le principal de ressource, reportez-vous à Configuration de stratégies et de rôles pour accéder aux ressources.

location_uri

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

maxpipesize

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

La taille totale de tous les messages sur le pipeline ne peut pas dépasser ce montant. Le message est bloqué s'il dépasse ce maximum. La longueur par défaut est de 65536 octets.

La valeur maxpipesize d'un tuyau devient une partie des caractéristiques du tuyau et persiste pendant toute sa durée de vie. Les appelants de SEND_MESSAGE avec des valeurs plus élevées augmentent la valeur de maxpipesize. Les appelants dont la valeur est inférieure utilisent simplement la valeur supérieure existante.

Si vous indiquez maxpipesize dans le cadre de la procédure SEND_MESSAGE, vous n'avez plus besoin d'un appel distinct pour ouvrir le canal. Si vous avez créé le canal de manière explicite, 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 (65536) est applicable à tous les tubes.

pipename

Nom du canal sur lequel vous voulez placer le message.

Si vous utilisez un canal explicite, il s'agit du nom que vous avez indiqué lorsque vous avez appelé CREATE_PIPE.

Attention : n'utilisez pas de noms de pipe commençant par 'ORA$'. Ces noms sont réservés à l'usage des 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

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

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

Valeurs renvoyées

Tableau 6-19 Valeurs renvoyées par la 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 renvoie 0, ce qui indique qu'il a réussi 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 renvoie le statut 0, mais la propriété du canal reste inchangée.

1

Le délai a expiré.

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é implicitement créé et est vide, il est enlevé.

3

Une interruption s'est produite.

Si le tuyau a été implicitement créé et est vide, il est enlevé.

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

Notes d'utilisation

  • Il est garanti que les messages persistants sont écrits ou lus par un seul processus. Cela évite les incohérences de contenu de message dues à des écritures et des lectures simultanées. A l'aide d'un canal de messagerie persistant, DBMS_PIPE permet qu'une seule opération, l'envoi d'un message ou un message de réception, soit active à 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 régulièrement jusqu'à ce que la valeur timeout soit atteinte.

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

    • Si vous utilisez un format d'URI natif pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser l'authentification des clés de signature Oracle Cloud Infrastructure natives dans l'objet d'informations d'identification.

    • Si vous utilisez le format d'URI Swift pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser une authentification par jeton d'authentification dans l'objet d'informations d'identification.

Exceptions

Tableau 6-20 Exception de fonction SEND_MESSAGE

Exception Description

Null pipe name

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

Procédure SET_CREDENTIAL_NAME

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

Syntaxe

DBMS_PIPE.SET_CREDENTIAL_NAME (
   credential_name   IN VARCHAR2 );

Paramètres

Paramètre Description

credential_name

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

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. Pour plus d'informations sur l'authentification basée sur le principal de ressource, reportez-vous à Configuration de stratégies et de rôles pour accéder aux ressources.

Remarque sur l'utilisation

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

  • Si vous utilisez un format d'URI natif pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser l'authentification des clés de signature Oracle Cloud Infrastructure natives dans l'objet d'informations d'identification.

  • Si vous utilisez le format d'URI Swift pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser une authentification par jeton d'authentification dans l'objet d'informations d'identification.

Exemple

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

Procédure SET_LOCATION_URI

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

Remarque sur l'utilisation

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

  • Si vous utilisez un format d'URI natif pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser l'authentification des clés de signature Oracle Cloud Infrastructure natives dans l'objet d'informations d'identification.

  • Si vous utilisez le format d'URI Swift pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser une authentification par jeton d'authentification dans l'objet d'informations d'identification.

Exemple

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