Package DBMS_PIPE
DBMS_PIPE
permet à deux sessions ou plus de la même instance de communiquer.
Oracle Autonomous Database prend en charge les fonctionnalités de base DBMS_PIPE
telles qu'elles sont disponibles dans Oracle Database 19c, ainsi que les extensions.
Reportez-vous à DBMS_PIPE pour plus de détails sur la fonctionnalité DBMS_PIPE
de base fournie dans Oracle Database.
- DBMS_PIPE Présentation de Singleton Pipes
La fonctionnalité de pipe peut être utilisée dans plusieurs applications : interface de service externe, débogage, transactions indépendantes et alertes. - Récapitulatif des sous-programmes DBMS_PIPE pour les pipes simples
Ce tableau répertorie les sous-programmesDBMS_PIPE
et les décrit brièvement. - DBMS_PIPE Présentation des pipes de messagerie persistantes
La fonctionnalité de pipe peut être utilisée dans plusieurs applications : interface de service externe, débogage, transactions indépendantes et alertes. - Récapitulatif des sous-programmes DBMS_PIPE pour la messagerie persistante
Ce tableau répertorie les sous-programmesDBMS_PIPE
et les décrit brièvement.
Rubrique parent : Référence de package fourni avec Autonomous Database
Présentation de DBMS_PIPE pour les tuyaux simples
La fonctionnalité de tuyau peut être utilisée dans plusieurs applications : 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.
Les fonctionnalités de canalisation unique dans 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 tuyaux, y compris les tuyaux simples. La taille maximale des messages des versions précédentes de
DBMS_PIPE
était 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 de cache explicite contrôlée par l'utilisateur.
- Invalidation du cache après un intervalle de temps (en secondes) spécifié par l'utilisateur pour le paramètre (
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 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. - Pipe publique : accessible par tout utilisateur disposant du droit d'accès
EXECUTE
sur le packageDBMS_PIPE
- Pipe privée : 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 pipes simples
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 |
---|---|
Crée un tuyau (nécessaire pour les tuyaux privés) |
|
Renvoie le type de données de l'élément suivant dans le tampon |
|
Crée un message dans le tampon local |
|
Purge le contenu du pipeline nommé |
|
Copie le message du pipeline nommé dans le tampon local |
|
Purge le contenu du tampon local |
|
Supprime le canal nommé |
|
Envoie un message sur le pipeline nommé : crée implicitement un pipeline public si le pipeline nommé n'existe pas |
|
Renvoie un nom de session unique |
|
Permet d'accéder à l'élément suivant dans le tampon |
- Fonction CREATE_PIPE
Cette fonction crée explicitement un pipeline public ou privé. Si l'indicateurprivate
estTRUE
, le créateur du pipeline est affecté en tant que propriétaire du pipeline privé. - Fonction RECEIVE_MESSAGE
Cette fonction copie le message dans le tampon de messages local. - Fonction SEND_MESSAGE
Cette fonction envoie un message sur le pipeline 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 du 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 tuyau unique, définissez le paramètre singleton
sur TRUE
. Les arguments suivants s'appliquent aux singleton pipes :
-
singleton
: indique que la canalisation doit être créée en tant que canalisation unique (valeur par défaut :FALSE
). -
shelflife
: indiquez éventuellement une expiration de délai d'attente (en secondes) du message mis en cache dans le tuyau singleton. Il peut être utilisé pour l'invalidation implicite d'un message dans un tuyau singleton.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 |
---|---|
|
Nom du pipeline que vous créez. Vous devez utiliser ce nom lorsque vous appelez Attention : n'utilisez pas de noms de barre verticale commençant par |
|
Taille maximale autorisée pour le pipeline, en octets. La taille totale de tous les messages sur la canalisation ne peut pas dépasser cette valeur. Le message est bloqué s'il dépasse ce maximum. La valeur par défaut de Le La valeur par défaut |
|
Utilise la valeur par défaut, Les canaux publics peuvent être créés implicitement lorsque vous appelez |
|
Utilisez Valeur par défaut : |
|
Délai d'expiration, en secondes, d'un message mis en cache dans un tuyau unique. Une fois le délai La valeur par défaut est |
Valeurs renvoyées
Tableau 6-3 Valeurs renvoyées par la fonction CREATE_PIPE
Renvoyer | Description |
---|---|
|
Opération effectuée. 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 toutes les données qui y figurent restent. |
|
Échec de conversion du canal existant en canal singleton.
|
|
Une valeur différente de zéro est indiquée pour le paramètre |
|
É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 |
Exceptions
Tableau 6-4 Exception de fonction CREATE_PIPE
Exception | Description |
---|---|
|
Erreur d'autorisation : un tuyau 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 vie de 1 heure.
DECLARE
l_status INTEGER;
BEGIN
l_status := DBMS_PIPE.create_pipe(pipename => 'MY_PIPE1',
private => TRUE,
singleton => TRUE,
shelflife => 3600);
END;
/
Rubrique parent : Récapitulatif des sous-programmes DBMS_PIPE pour les singleton Pipes
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 |
---|---|
|
Nom du canal sur lequel vous voulez recevoir un message. Les noms commençant par |
|
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 Valeur par défaut : est la constante |
|
Nom de la fonction de mise en cache pour mettre automatiquement en cache un message dans un tuyau unique. Le nom de la fonction doit être entièrement qualifié avec le schéma propriétaire :
Valeur par défaut : |
Valeurs renvoyées
Tableau 6-6 Valeurs renvoyées par la fonction RECEIVE_MESSAGE
Renvoyer | Description |
---|---|
|
succès |
|
Expiration. Si le tuyau a été créé implicitement et qu'il est vide, il est enlevé. |
|
L'enregistrement dans la canalisation est trop volumineux pour le tampon. |
|
Une interruption s'est produite. |
8 |
La fonction de cache ne peut être spécifiée que lors de l'utilisation d'un tuyau unique. |
|
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é de la canalisation ; par conséquent, un message ne peut être reçu qu'une seule fois. Pour les canalisations créées implicitement, la canalisation est supprimée après le retrait du dernier enregistrement de la canalisation.
Si le pipeline que vous indiquez lorsque vous appelez RECEIVE_MESSAGE
n'existe pas déjà, Oracle le crée implicitement et attend la réception du message. Si le message n'arrive pas dans un intervalle d'expiration désigné, l'appel revient et la canalisation est supprimée.
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écompresser les éléments de type DATE
, NUMBER
, VARCHAR2
. Il existe également 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
Les singleton Pipes prennent en charge la fonction de cache pour mettre automatiquement en cache un message dans le pipeline dans les deux scénarios suivants :
- Le tuyau singleton est vide.
- Le message dans le tuyau 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 |
---|---|---|
|
VARCHAR2 |
Nom du canal unique. |
Renvoyer | Description |
---|---|
0 | succès |
Non nul | Valeur d'échec renvoyée par DBMS_PIPE.RECEIVE_MESSAGE |
Définissez une fonction de cache pour fournir une encapsulation et une 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 tuyau singleton pour un tuyau explicite à l'aide de
DBMS_PIPE.CREATE_PIPE
. - Créez le message à mettre en cache dans le singleton Pipe.
- Envoyer un message au tuyau singleton, en spécifiant éventuellement un
shelflife
pour le message implicite.
Exceptions
Tableau 6-7 Exceptions de fonction RECEIVE_MESSAGE
Exception | Description |
---|---|
|
Erreur de droit d'accès. Privilège insuffisant pour supprimer l'enregistrement de la canalisation. 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;
/
Rubrique parent : Récapitulatif des sous-programmes DBMS_PIPE pour les singleton Pipes
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 d'appels à PACK_MESSAGE
. Vous pouvez créer un pipeline explicitement à l'aide de CREATE_PIPE
, sinon il est créé implicitement.
Pour créer un pipeline singleton implicite, définissez le paramètre singleton
sur TRUE
. Les arguments suivants s'appliquent aux singleton pipes :
singleton
: indique que la canalisation doit être créée en tant que canalisation unique (valeur par défaut :FALSE
).shelflife
: indiquez éventuellement l'expiration du délai d'attente du message mis en cache dans le tuyau singleton. Il peut être utilisé pour l'invalidation implicite d'un message dans un tuyau singleton.Cet argument s'applique aux tubes Singleton implicites et explicites. Une valeur
shelflife
spécifiée dans la fonction SEND_MESSAGE remplace la valeurshelflife
spécifiée pour le tuyau singleton explicite dans la fonction CREATE_PIPE et sera la valeur par défaut pour tous les nouveaux messages mis en cache dans le tuyau singleton.
Syntaxe
DBMS_PIPE.SEND_MESSAGE ( pipename IN VARCHAR2, timeout IN INTEGER DEFAULT MAXWAIT, maxpipesize IN INTEGER DEFAULT 65536, singleton IN BOOLEAN DEFAULT FALSE, shelflife IN INTEGER DEFAULT 0) RETURN INTEGER;
Paramètres
Tableau 6-8 Paramètres de fonction SEND_MESSAGE
Paramètre | Description |
---|---|
|
Nom de la canalisation sur laquelle vous voulez placer le message. Si vous utilisez une barre verticale explicite, il s'agit du nom que vous avez indiqué lorsque vous avez appelé Attention : n'utilisez pas de noms de barre verticale commençant par ' |
|
Temps d'attente pendant la tentative de placement d'un message sur un canal, en secondes. La valeur par défaut est la constante |
|
Taille maximale autorisée pour le pipeline, en octets. La taille totale de tous les messages sur la canalisation ne peut pas dépasser cette valeur. Le message est bloqué s'il dépasse ce maximum. La longueur par défaut est de 65536 octets. Le La spécification de La valeur par défaut |
|
Utilisez Valeur par défaut : |
|
Délai d'expiration, en secondes, d'un message mis en cache dans un tuyau unique. Une fois le délai La valeur par défaut est |
Valeurs renvoyées
Tableau 6-9 Valeurs renvoyées par la fonction SEND_MESSAGE
Renvoyer | Description |
---|---|
|
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 toutes les données qui y figurent restent. Si un utilisateur connecté en tant que |
|
Expiration. 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 qu'il est vide, il est enlevé. |
|
Une interruption s'est produite. Si le tuyau a été créé implicitement et qu'il est vide, il est enlevé. |
|
Échec de conversion du canal existant en canal singleton.
|
|
Une valeur différente de zéro est indiquée pour le paramètre |
|
Droits insuffisants. Si un canal portant le même nom existe et a été créé par un autre utilisateur, Oracle signale l'erreur |
Exceptions
Tableau 6-10 Exception de fonction SEND_MESSAGE
Exception | Description |
---|---|
|
Erreur de droit d'accès. Privilège insuffisant pour écrire dans le pipeline. Le tuyau est privé et appartient à quelqu'un d'autre. |
Rubrique parent : Récapitulatif des sous-programmes DBMS_PIPE pour les singleton Pipes
Présentation de DBMS_PIPE pour les pipelines de messagerie persistante
La fonctionnalité de tuyau peut être utilisée dans plusieurs applications : 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.
-
Prendre en charge un grand nombre de messages de canalisation.
-
Prendre en charge le partage des messages au sein d'une seule base de données, entre plusieurs bases de données et entre des bases de données de différentes régions.
-
Prendre en charge plusieurs canaux à l'aide du même URI d'emplacement de banque d'objets cloud.
La fonctionnalité de messagerie persistante permet à deux sessions de base de données ou plus de communiquer avec des messages stockés dans la banque d'objets cloud. L'utilisation de ces messages de fonctionnalité dans un pipeline peut être rendue disponible uniquement pour la base de données en cours ou pour plusieurs bases de données de la même région ou de différentes régions.
Un tuyau de messagerie persistante 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. - Pipe publique : accessible par tout utilisateur disposant du droit d'accès
EXECUTE
sur le packageDBMS_PIPE
. - Pipe privée : accessible par les sessions avec le même utilisateur que le créateur de pipe.
- Canal implicite : créé automatiquement lorsqu'un message est envoyé avec un nom de canal inconnu à l'aide de la fonction
Lorsque vous envoyez et recevez des messages sur 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 des bases de données qui utilisent des jeux de caractères différents. Par exemple, si vous disposez d'une instance Autonomous Database qui utilise AL32UTF8 et d'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 sur le 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 de package DBMS_PIPE
Sous-programme | Description |
---|---|
Crée un tuyau (nécessaire pour les tuyaux privés). |
|
Renvoie la valeur de variable |
|
Renvoie la valeur de variable |
|
Renvoie le type de données de l'élément suivant dans le tampon. |
|
Crée un message dans le tampon local. |
|
Copie le message du pipeline nommé dans le tampon local. |
|
Purge le contenu du tampon local. |
|
Supprime le canal nommé. |
|
Envoie un message sur un canal nommé : crée implicitement un canal public si le canal nommé n'existe pas. |
|
Définit la variable |
|
Définit la variable |
|
Renvoie un nom de session unique. |
|
Permet d'accéder à l'élément suivant dans le tampon. |
- Fonction CREATE_PIPE
Cette fonction crée explicitement un pipeline public ou privé. Si l'indicateurprivate
estTRUE
, le créateur du pipeline est affecté en tant que propriétaire du pipeline privé. - Fonction GET_CREDENTIAL_NAME
Cette fonction renvoie la valeur de variablecredential_name
globale à utiliser lorsque les messages sont stockés dans la banque d'objets cloud. - Fonction GET_LOCATION_URI
Cette fonction renvoie la valeur de variablelocation_uri
globale qui peut être utilisée comme URI d'emplacement par défaut lorsque les messages pipe sont stockés dans la banque d'objets cloud. - Fonction RECEIVE_MESSAGE
Cette fonction copie le message dans le tampon de messages local. - Fonction SEND_MESSAGE
Cette fonction envoie un message sur le pipeline nommé. - Procédure SET_CREDENTIAL_NAME
Cette procédure définit la variablecredential_name
utilisée comme informations d'identification par défaut lorsque les messages de pipeline sont stockés dans la banque d'objets cloud. - Procédure SET_LOCATION_URI
Cette procédure définit la variablelocation_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 du 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.
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 |
---|---|
|
Nom du pipeline que vous créez. Vous devez utiliser ce nom lorsque vous appelez Attention : n'utilisez pas de noms de barre verticale commençant par |
|
Taille maximale autorisée pour le pipeline, en octets. La taille totale de tous les messages sur la canalisation ne peut pas dépasser cette valeur. Le message est bloqué s'il dépasse ce maximum. La valeur par défaut de Le La valeur par défaut |
|
Utilise la valeur par défaut, Les canaux publics peuvent être créés implicitement lorsque vous appelez |
Valeurs renvoyées
Tableau 6-13 Valeurs renvoyées par la fonction CREATE_PIPE
Renvoyer | Description |
---|---|
|
Opération effectuée. 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 toutes les données qui y figurent restent. |
|
É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 |
Exceptions
Tableau 6-14 Exception de fonction CREATE_PIPE
Exception | Description |
---|---|
|
Erreur d'autorisation : un tuyau portant le même nom existe déjà et vous n'êtes pas autorisé à l'utiliser. |
Exemple
Créez une instance 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 renvoyée | Description |
---|---|
|
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 des messages de pipeline sont stockés dans la banque d'objets cloud.
Syntaxe
DBMS_PIPE.GET_LOCATION_URI RETURN VARCHAR2;
Valeur renvoyée
Valeur renvoyée | Description |
---|---|
location_uri |
URI de l'objet. |
Exemple
DECLARE
location_uri VARCHAR2(400)
BEGIN
location_uri := DBMS_PIPE.GET_LOCATION_URI;
END;
/
Fonction RECEIVE_MESSAGE
Cette fonction copie le message dans le tampon de messages local.
Syntaxe
DBMS_PIPE.RECEIVE_MESSAGE ( pipename IN VARCHAR2, timeout IN INTEGER DEFAULT maxwait, credential_name IN VARCHAR2 DEFAULT null, location_uri IN VARCHAR2) RETURN INTEGER;
Paramètres
Tableau 6-15 Paramètres de fonction RECEIVE_MESSAGE
Paramètre | Description |
---|---|
|
Nom du canal sur lequel vous voulez recevoir un message. Les noms commençant par |
|
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é à exécuter la fonction de cache indiquée avec le paramètre Valeur par défaut : est la constante |
|
Nom des informations d'identification de la banque cloud utilisée pour stocker les messages.
Vous pouvez définir cette valeur avant d'appeler L'utilisateur exécutant La valeur |
|
URI d'emplacement de la banque cloud utilisée pour stocker les messages.
Vous pouvez définir cette valeur avant d'appeler |
Valeurs renvoyées
Tableau 6-16 Valeurs renvoyées par la fonction RECEIVE_MESSAGE
Renvoyer | Description |
---|---|
|
succès |
|
Expiration. Si le tuyau a été créé implicitement et qu'il est vide, il est enlevé. |
|
L'enregistrement dans la canalisation est trop volumineux pour le tampon. |
|
Une interruption s'est produite. |
|
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é de la canalisation ; par conséquent, un message ne peut être reçu qu'une seule fois. Pour les canalisations créées implicitement, la canalisation est supprimée après le retrait du dernier enregistrement de la canalisation. -
Si le pipeline que vous indiquez lorsque vous appelez
RECEIVE_MESSAGE
n'existe pas déjà, Oracle le crée implicitement et attend la réception du message. Si le message n'arrive pas dans un intervalle d'expiration désigné, l'appel revient et la canalisation est supprimée. -
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édureUNPACK_MESSAGE
est surchargée pour décompresser les éléments de typeDATE
,NUMBER
,VARCHAR2
. Il existe également deux procédures supplémentaires pour décompresser les élémentsRAW
etROWID
. Si vous ne connaissez pas le type de données que vous tentez de décompresser, appelezNEXT_ITEM_TYPE
pour déterminer le type de l'élément suivant dans le tampon. -
Les messages persistants doivent être é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 messages persistant,
DBMS_PIPE
n'autorise qu'une seule opération, l'envoi d'un message ou d'un message de réception à être actif à un moment donné. Toutefois, si une opération n'est pas possible en raison d'une opération en cours, le processus réessaie régulièrement jusqu'à ce que la valeurtimeout
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 |
---|---|
|
Erreur de droit d'accès. Privilège insuffisant pour supprimer l'enregistrement de la canalisation. 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 messages local, qui a été rempli d'appels à PACK_MESSAGE
. Vous pouvez créer un pipeline 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.
Vous pouvez définir cette valeur avant d'appeler L'utilisateur exécutant La valeur |
location_uri |
URI d'emplacement de la banque cloud utilisée pour stocker les messages.
Vous pouvez définir cette valeur avant d'appeler |
|
Taille maximale autorisée pour le pipeline, en octets. La taille totale de tous les messages sur la canalisation ne peut pas dépasser cette valeur. Le message est bloqué s'il dépasse ce maximum. La longueur par défaut est de 65536 octets. Le La spécification de La valeur par défaut |
|
Nom de la canalisation sur laquelle vous voulez placer le message. Si vous utilisez une barre verticale explicite, il s'agit du nom que vous avez indiqué lorsque vous avez appelé Attention : n'utilisez pas de noms de barre verticale commençant par ' |
|
Temps d'attente pendant la tentative de placement d'un message sur un canal, en secondes. La valeur par défaut est la constante |
Valeurs renvoyées
Tableau 6-19 Valeurs renvoyées par la fonction SEND_MESSAGE
Renvoyer | Description |
---|---|
|
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 toutes les données qui y figurent restent. Si un utilisateur connecté en tant que |
|
Expiration. 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 qu'il est vide, il est enlevé. |
|
Une interruption s'est produite. Si le tuyau a été créé implicitement et qu'il est vide, il est enlevé. |
|
Droits insuffisants. Si un canal portant le même nom existe et a été créé par un autre utilisateur, Oracle signale l'erreur |
Notes d'utilisation
-
Les messages persistants doivent être é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 messages persistant,
DBMS_PIPE
n'autorise qu'une seule opération, l'envoi d'un message ou d'un message de réception à être actif à un moment donné. Toutefois, si une opération n'est pas possible en raison d'une opération en cours, le processus réessaie régulièrement jusqu'à ce que la valeurtimeout
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 |
---|---|
|
Erreur de droit d'accès. Privilège insuffisant pour écrire dans le pipeline. Le tuyau est privé et appartient à quelqu'un d'autre. |
SET_CREDENTIAL_NAME Procédure
Cette procédure définit la variable credential_name
utilisée comme informations d'identification par défaut lorsque les messages de pipeline sont stockés dans la banque d'objets cloud.
Syntaxe
DBMS_PIPE.SET_CREDENTIAL_NAME ( credential_name IN VARCHAR2 );
Paramètres
Paramètre | Description |
---|---|
|
Nom des informations d'identification permettant d'accéder au stockage d'objet cloud. La valeur |
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;
/
SET_LOCATION_URI Procédure
Cette procédure définit la variable location_uri
globale.
Syntaxe
DBMS_PIPE.SET_LOCATION_URI ( location_uri IN VARCHAR2 );
Paramètre
Paramètre | Description |
---|---|
location_uri |
URI de l'objet ou du fichier. Le format de l'URI dépend du service Cloud Object Storage que vous utilisez. Pour 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;
/