Paquete DBMS_PIPE (tubos de mensajes persistentes)

El paquete DBMS_PIPE permite que se comuniquen dos o más sesiones de la misma instancia.

Oracle Autonomous Database on Dedicated Exadata Infrastructure soporta la funcionalidad principal DBMS_PIPE, como está disponible en Oracle Database 19c, además de extensiones.

Consulte DBMS_PIPE en Oracle Database 19c PL/SQL Packages and Types Reference o Oracle Database 23ai PL/SQL Packages and Types Reference para obtener más información sobre la funcionalidad principal DBMS_PIPE proporcionada en Oracle Database.

Temas relacionados

DBMS_PIPE Visión General de Pipes de Mensajería Persistente

La funcionalidad de canalización tiene varias aplicaciones potenciales: interfaz de servicio externo, depuración, transacciones independientes y alertas.

En Autonomous Database, el paquete DBMS_PIPE tiene una funcionalidad ampliada para soportar pipes de mensajería persistentes. Consulte DBMS_PIPE en Oracle Database 19c PL/SQL Packages and Types Reference o Oracle Database 23ai PL/SQL Packages and Types Reference para obtener más información.

Mensajes persistentes en DBMS_PIPE:

  • Apoya la capacidad de enviar y recuperar mensajes muy grandes.

  • Soporta un gran número de mensajes de canal.

  • Admita el uso compartido de mensajes dentro de una única base de datos, entre varias bases de datos y entre bases de datos de diferentes regiones.

  • Soporta varios pipes con el mismo URI de ubicación del almacén de objetos en la nube.

    La funcionalidad de mensajería persistente permite que dos o más sesiones de base de datos se comuniquen con los mensajes almacenados en el almacén de objetos en la nube. El uso de estos mensajes de funcionalidad en un conducto solo puede estar disponible para la base de datos actual o puede estar disponible para varias bases de datos en la misma región o en diferentes regiones.

    Un tubo de mensajería persistente puede ser cualquiera de los tipos DBMS_PIPE soportados:

    • Conducta implícita: se crea automáticamente cuando se envía un mensaje con un nombre de conducto desconocido mediante la función DBMS_PIPE.SEND_MESSAGE.
    • Pipa explícita: se crea mediante la función DBMS_PIPE.CREATE_PIPE con un nombre de pipa especificado por el usuario.
    • Conducta pública: accesible para cualquier usuario con permiso EXECUTE en el paquete DBMS_PIPE.
    • Dirección privada: accesible para sesiones con el mismo usuario que el creador de la conducción.

Note:

Al enviar y recibir mensajes en distintas bases de datos mediante mensajes persistentes, Oracle recomienda llamar a DBMS_PIPE.CREATE_PIPE antes de enviar o recibir mensajes. La creación de una conducción explícita con DBMS_PIPE.CREATE_PIPE garantiza que se cree una conducción con los permisos de acceso que desee, ya sean públicos o privados (definiendo el parámetro PRIVATE en FALSE o utilizando el valor por defecto TRUE).

DBMS_PIPE Limitación

El paquete DBMS_PIPE no soporta el envío de mensajes entre bases de datos que utilizan diferentes juegos de caracteres. Por ejemplo, si tiene una instancia de Autonomous Database que utiliza AL32UTF8 y otra instancia que utiliza WE8MSWIN1252, no puede enviar mensajes con DBMS_PIPE entre estas dos bases de datos. En este caso, el sistema emitirá el error ORA-12704 si intenta enviar mensajes con DBMS_PIPE entre estas dos bases de datos.

Resumen de Subprogramas DBMS_PIPE para Mensajería Persistente

En esta tabla se muestran los subprogramas DBMS_PIPE y se describen brevemente.

Tabla: Subprogramas de Paquete DBMS_PIPE

Subprograma Descripción

Función CREATE_PIPE

Crea una tubería (necesaria para tuberías privadas).

Función GET_CREDENTIAL_NAME

Devuelve el valor de la variable credential_name global.

Función GET_LOCATION_URI

Devuelve el valor de variable location_uri global que se utiliza como URI de ubicación por defecto para su uso cuando se almacena un mensaje en el almacén de objetos en la nube.

Función NEXT_ITEM_TYPE

Devuelve el tipo de dato del siguiente elemento en el buffer.
PACK_MESSAGE Procedimientos

Crea el mensaje en el buffer local.

Función RECEIVE_MESSAGE

Copia el mensaje del conducto con nombre en el buffer local.
Procedimiento RESET_BUFFER

Depura el contenido del buffer local.
Función REMOVE_PIPE

Elimina la conducción con nombre.

Función SEND_MESSAGE

Envía un mensaje en una conducción con nombre: esto crea implícitamente una conducción pública si la conducción con nombre no existe.

Procedimiento SET_CREDENTIAL_NAME

Define la variable credential_name que se utiliza como credencial por defecto para los mensajes almacenados en el almacén de objetos en la nube.

Procedimiento SET_LOCATION_URI

Define la variable location_uri global que se utiliza como URI de ubicación por defecto para los mensajes almacenados en el almacén de objetos en la nube.

Función UNIQUE_SESSION_NAME

Devuelve un nombre de sesión único.
UNPACK_MESSAGE Procedimientos

Accede al siguiente elemento en el buffer.

Función CREATE_PIPE

Esta función crea explícitamente una conducción pública o privada. Si el indicador private es TRUE, el creador de la conducción se asigna como propietario de la conducción privada.

Los pipes creados explícitamente solo se pueden eliminar llamando a REMOVE_PIPE o cerrando la instancia.

Sintaxis

DBMS_PIPE.CREATE_PIPE (
   pipename     IN VARCHAR2,
   maxpipesize  IN INTEGER DEFAULT 66536,
   private      IN BOOLEAN DEFAULT TRUE)
RETURN INTEGER;

Parámetros

Tabla - Parámetros de función CREATE_PIPE

parámetro Descripción

pipename

Nombre del conducto que está creando.

Debe utilizar este nombre al llamar a SEND_MESSAGE y RECEIVE_MESSAGE. Este nombre debe ser único en la instancia.

Precaución: No utilice nombres de conducción que comiencen por ORA$. Se reservan para el uso de los procedimientos que proporciona Oracle. El nombre de pipeline no debe superar los 128 bytes y no distingue entre mayúsculas y minúsculas. En este momento, el nombre no puede contener caracteres de soporte de globalización.

maxpipesize

Tamaño máximo permitido para la conducción, en bytes.

El tamaño total de todos los mensajes de la conducción no puede superar esta cantidad. El mensaje se bloquea si supera este máximo.

El valor por defecto maxpipesize es de 66536 bytes.

maxpipesize para una tubería se convierte en parte de las características de la tubería y persiste durante la vida útil de la tubería. Los emisores de llamadas de SEND_MESSAGE con valores más grandes hacen que se aumente maxpipesize. Los emisores de llamadas con un valor menor utilizan el valor mayor existente.

El valor por defecto maxpipesize de 65536 es aplicable a todos los tubos.

private

Utiliza el valor por defecto, TRUE, para crear una conducción privada.

Los pipes públicos se pueden crear implícitamente al llamar a SEND_MESSAGE.

Valores devueltos

Tabla: Valores de Retorno de Función CREATE_PIPE

Return Descripción

0

Correcto.

Si la conducción ya existe y el usuario que intenta crearla está autorizado a utilizarla, Oracle devuelve 0, lo que indica que se ha realizado correctamente, y los datos que ya estén en la conducción permanecen.

ORA-23322

Fallo debido a un conflicto de nombres.

Si existe una conducción con el mismo nombre y la ha creado un usuario diferente, Oracle señala el error ORA-23322, que indica el conflicto de nomenclatura.

Excepciones

Tabla - Excepción de función CREATE_PIPE

Excepción Descripción

Null pipe name

Error de permiso: Ya existe un conducto con el mismo nombre y no puede utilizarlo.

Ejemplo

Crear un privado explícito denominado MY_PIPE1

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

Función GET_CREDENTIAL_NAME

Esta función devuelve el valor de variable credential_name global para su uso cuando los mensajes se almacenan en el almacén de objetos en la nube.

Sintaxis

DBMS_PIPE.GET_CREDENTIAL_NAME
         RETURN VARCHAR2;

Valores devueltos

Valor devuelto Descripción

credential_name

Nombre de la credencial para acceder a Cloud Object Storage.

Ejemplo

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

Función GET_LOCATION_URI

Esta función devuelve el valor de variable location_uri global que se puede utilizar como URI de ubicación por defecto cuando los mensajes de conducción se almacenan en el almacén de objetos en la nube.

Sintaxis

DBMS_PIPE.GET_LOCATION_URI
        RETURN VARCHAR2;

Valor devuelto

Valor devuelto Descripción
location_uri

URI del objeto.

Ejemplo

DECLARE
  location_uri     VARCHAR2(400)
BEGIN
  location_uri := DBMS_PIPE.GET_LOCATION_URI;
END;
/

Función RECEIVE_MESSAGE

Esta función copia el mensaje en el buffer de mensajes local.

Sintaxis

DBMS_PIPE.RECEIVE_MESSAGE (
   pipename          IN VARCHAR2,
   timeout           IN INTEGER  DEFAULT maxwait,
   credential_name   IN VARCHAR2 DEFAULT null,
   location_uri      IN VARCHAR2)
RETURN INTEGER;

Parámetros

Tabla - Parámetros de función RECEIVE_MESSAGE

parámetro Descripción

pipename

Nombre del conducto en el que desea recibir un mensaje.

Los nombres que empiezan por ORA$ están reservados para Oracle.

timeout

Tiempo de espera de un mensaje, en segundos. Un timeout de 0 le permite leer sin bloqueos.

El timeout no incluye el tiempo empleado en ejecutar la función de caché especificada con el parámetro cache_func.

Valor por defecto: es la constante MAXWAIT, que se define como 86400000 (1000 días).

credential_name

Nombre de credencial para el almacén en la nube utilizado para almacenar mensajes.

credential_name es un argumento de paquete que se inicializa por defecto como NULL.

Puede definir este valor antes de llamar a DBMS_PIPE.RECEIVE_MESSAGE. El valor del parámetro transferido tiene prioridad sobre el valor de la variable global.

El objeto de credencial debe tener privilegios EXECUTE y READ/WRITE por parte del usuario que ejecuta DBMS_PIPE.RECEIVE_MESSAGE.

location_uri

URI de ubicación del almacén en la nube utilizado para almacenar mensajes.

location_uri es una variable global que, por defecto, se inicializa como NULL.

Puede definir este valor antes de llamar a DBMS_PIPE.RECEIVE_MESSAGE. El valor del parámetro transferido tiene prioridad sobre el valor de la variable global.

Valores devueltos

Tabla: Valores de Retorno de Función RECEIVE_MESSAGE

Return Descripción

0

Correcto

1

Timeout. Si la conducción se ha creado implícitamente y está vacía, se elimina.

2

El registro en el conducto es demasiado grande para el buffer.

3

Se ha producido una interrupción.

ORA-23322

El usuario no tiene suficientes privilegios para leer desde el conducto.

Notas de uso

  • Para recibir un mensaje de un conducto, llame primero a RECEIVE_MESSAGE. Cuando recibe un mensaje, se elimina de la conducción; por lo tanto, un mensaje solo se puede recibir una vez. Para las tuberías creadas implícitamente, la tubería se elimina después de que se elimina el último registro de la tubería.

  • Si la conducción que especifique al llamar a RECEIVE_MESSAGE aún no existe, Oracle crea implícitamente la conducción y espera a recibir el mensaje. Si el mensaje no llega dentro de un intervalo de timeout designado, la llamada vuelve y se elimina la conducción.

  • Después de recibir el mensaje, debe realizar una o más llamadas a UNPACK_MESSAGE para acceder a los elementos individuales del mensaje. El procedimiento UNPACK_MESSAGE está sobrecargado para desempaquetar elementos de tipo DATE, NUMBER, VARCHAR2 y hay dos procedimientos adicionales para desempaquetar elementos RAW y ROWID. Si no conoce el tipo de datos que está intentando desempaquetar, llame a NEXT_ITEM_TYPE para determinar el tipo del siguiente elemento en el buffer.

  • Se garantiza que los mensajes persistentes se escriban o lean exactamente en un proceso. Esto evita la inconsistencia de contenido del mensaje debido a escrituras y lecturas simultáneas. Mediante un conducto de mensajes persistente, DBMS_PIPE solo permite que una operación, el envío de un mensaje o un mensaje de recepción estén activos en un momento determinado. Sin embargo, si una operación no es posible debido a una operación en curso, el proceso se reintenta periódicamente hasta que se alcanza el valor timeout.

  • Si utiliza Oracle Cloud Infrastructure Object Storage para almacenar mensajes, puede utilizar los URI nativos de Oracle Cloud Infrastructure o los URI de Swift. Sin embargo, el URI de ubicación y la credencial deben coincidir en el tipo de la siguiente manera:

    • Si utiliza un formato de URI nativo para acceder a Oracle Cloud Infrastructure Object Storage, debe utilizar la autenticación de claves de firma de Oracle Cloud Infrastructure nativa en el objeto de credencial.

    • Si utiliza el formato de URI de Swift para acceder a Oracle Cloud Infrastructure Object Storage, debe utilizar una autenticación de token de autenticación en el objeto de credencial.

Excepciones

Tabla: excepciones de función RECEIVE_MESSAGE

Excepción Descripción

Null pipe name

Error de permiso. Privilegio insuficiente para eliminar el registro de la conducción. La pipa es propiedad de otra persona.

Función SEND_MESSAGE

Esta función envía un mensaje en la conducción con nombre.

El mensaje está incluido en el buffer de mensajes local, que se ha rellenado con llamadas a PACK_MESSAGE. Puede crear un conducto explícitamente mediante CREATE_PIPE; de lo contrario, se crea implícitamente.

Sintaxis

DBMS_PIPE.SEND_MESSAGE (
    pipename          IN VARCHAR2,
    timeout           IN INTEGER DEFAULT MAXWAIT,
    credential_name   IN VARCHAR2 DEFAULT null,
    location_uri      IN VARCHAR2 )
RETURN INTEGER;

Parámetros

Tabla - Parámetros de función SEND_MESSAGE

parámetro Descripción
credential_name

Nombre de credencial para el almacén en la nube utilizado para almacenar mensajes.

credential_name es un argumento de paquete que se inicializa por defecto como NULL.

Puede definir este valor antes de llamar a DBMS_PIPE.SEND_MESSAGE. El valor del parámetro transferido tiene prioridad sobre el valor de la variable global.

El objeto de credencial debe tener privilegios EXECUTE y READ/WRITE por parte del usuario que ejecuta DBMS_PIPE.SEND_MESSAGE.

location_uri

URI de ubicación del almacén en la nube utilizado para almacenar mensajes.

location_uri es una variable global que, por defecto, se inicializa como NULL.

Puede definir este valor antes de llamar a DBMS_PIPE.SEND_MESSAGE. El valor del parámetro transferido tiene prioridad sobre el valor de la variable global.

maxpipesize

Tamaño máximo permitido para el conducto, en bytes.

El tamaño total de todos los mensajes de la conducción no puede superar esta cantidad. El mensaje se bloquea si supera este máximo. El valor por defecto es 65536 bytes.

maxpipesize para una tubería se convierte en parte de las características de la tubería y persiste durante la vida útil de la tubería. Los emisores de llamadas de SEND_MESSAGE con valores más grandes hacen que se aumente maxpipesize. Las personas que llaman con un valor más pequeño simplemente usan el valor existente, más grande.

La especificación de maxpipesize como parte del procedimiento SEND_MESSAGE elimina la necesidad de una llamada independiente para abrir el conducto. Si ha creado el conducto explícitamente, puede utilizar el parámetro opcional maxpipesize para sustituir las especificaciones de tamaño del conducto de creación.

El valor por defecto maxpipesize de 65536 es aplicable a todos los tubos.

pipename

Nombre del conducto en el que desea colocar el mensaje.

Si está utilizando una conducción explícita, este es el nombre que especificó al llamar a CREATE_PIPE.

Precaución: No utilice nombres de conducción que comiencen por 'ORA$'. Estos nombres están reservados para los procedimientos que proporciona Oracle. El nombre de pipeline no debe superar los 128 bytes y no distingue entre mayúsculas y minúsculas. En este momento, el nombre no puede contener caracteres de soporte de globalización.

timeout

Tiempo de espera al intentar colocar un mensaje en una conducción, en segundos.

El valor por defecto es la constante MAXWAIT, que se define como 86400000 (1000 días).

Valores devueltos

Tabla: Valores de Retorno de Función SEND_MESSAGE

Return Descripción

0

Correcto.

Si la conducción ya existe y el usuario que intenta crearla está autorizado a utilizarla, Oracle devuelve 0, lo que indica que se ha realizado correctamente, y los datos que ya estén en la conducción permanecen.

Si un usuario conectado como SYSDBS/SYSOPER vuelve a crear una conducción, Oracle devuelve el estado 0, pero la propiedad de la conducción permanece sin cambios.

1

Timeout.

Este procedimiento puede agotar el tiempo de espera ya sea porque no puede obtener un bloqueo en el conducto o porque el conducto permanece demasiado lleno para ser utilizado. Si la conducción se ha creado implícitamente y está vacía, se elimina.

3

Se ha producido una interrupción.

Si la conducción se ha creado implícitamente y está vacía, se elimina.

ORA-23322

Privilegios insuficientes.

Si existe una conducción con el mismo nombre y la ha creado un usuario diferente, Oracle señala el error ORA-23322, que indica el conflicto de nomenclatura.

Notas de uso

  • Se garantiza que los mensajes persistentes se escriban o lean exactamente en un proceso. Esto evita la inconsistencia de contenido del mensaje debido a escrituras y lecturas simultáneas. Mediante un conducto de mensajes persistente, DBMS_PIPE solo permite que una operación, el envío de un mensaje o un mensaje de recepción estén activos en un momento determinado. Sin embargo, si una operación no es posible debido a una operación en curso, el proceso se reintenta periódicamente hasta que se alcanza el valor timeout.

  • Si utiliza Oracle Cloud Infrastructure Object Storage para almacenar mensajes, puede utilizar los URI nativos de Oracle Cloud Infrastructure o los URI de Swift. Sin embargo, el URI de ubicación y la credencial deben coincidir en el tipo de la siguiente manera:

    • Si utiliza un formato de URI nativo para acceder a Oracle Cloud Infrastructure Object Storage, debe utilizar la autenticación de claves de firma de Oracle Cloud Infrastructure nativa en el objeto de credencial.

    • Si utiliza el formato de URI de Swift para acceder a Oracle Cloud Infrastructure Object Storage, debe utilizar una autenticación de token de autenticación en el objeto de credencial.

Excepciones

Tabla - Excepción de función SEND_MESSAGE

Excepción Descripción

Null pipe name

Error de permiso. Privilegio insuficiente para escribir en el conducto. La tubería es privada y propiedad de otra persona.

Procedimiento SET_CREDENTIAL_NAME

Este procedimiento define la variable credential_name que se utiliza como credencial por defecto cuando los mensajes de conducción se almacenan en el almacén de objetos en la nube.

Sintaxis

DBMS_PIPE.SET_CREDENTIAL_NAME (
   credential_name   IN VARCHAR2 );

Parámetros

parámetro Descripción

credential_name

Nombre de la credencial para acceder a Cloud Object Storage.

Notas de uso

Si utiliza Oracle Cloud Infrastructure Object Storage para almacenar mensajes, puede utilizar los URI nativos de Oracle Cloud Infrastructure o los URI de Swift. Sin embargo, el URI de ubicación y la credencial deben coincidir en el tipo de la siguiente manera:

  • Si utiliza un formato de URI nativo para acceder a Oracle Cloud Infrastructure Object Storage, debe utilizar la autenticación de claves de firma de Oracle Cloud Infrastructure nativa en el objeto de credencial.

  • Si utiliza el formato de URI de Swift para acceder a Oracle Cloud Infrastructure Object Storage, debe utilizar una autenticación de token de autenticación en el objeto de credencial.

Ejemplo

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

Procedimiento SET_LOCATION_URI

Este procedimiento define la variable location_uri global.

Sintaxis

DBMS_PIPE.SET_LOCATION_URI (
   location_uri   IN VARCHAR2 );

parámetro

parámetro Descripción
location_uri

URI de archivo o de objeto. El formato del URI depende del servicio de Cloud Object Storage que utilice. Para obtener más información, consulte Formatos de URI de almacenamiento de objetos en la nube.

Notas de uso

Si utiliza Oracle Cloud Infrastructure Object Storage para almacenar mensajes, puede utilizar los URI nativos de Oracle Cloud Infrastructure o los URI de Swift. Sin embargo, el URI de ubicación y la credencial deben coincidir en el tipo de la siguiente manera:

  • Si utiliza un formato de URI nativo para acceder a Oracle Cloud Infrastructure Object Storage, debe utilizar la autenticación de claves de firma de Oracle Cloud Infrastructure nativa en el objeto de credencial.

  • Si utiliza el formato de URI de Swift para acceder a Oracle Cloud Infrastructure Object Storage, debe utilizar una autenticación de token de autenticación en el objeto de credencial.

Ejemplo

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