DBMS_PIPE Paquete (tubos singleton)

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 los tubos Singleton

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

Las funciones de conducto singleton de DBMS_PIPE proporcionan lo siguiente:

  • Capacidad de almacenar en caché y recuperar un mensaje personalizado, de hasta 32.767 bytes, en la memoria de la base de datos Oracle. El tamaño máximo del mensaje de 32.767 bytes es aplicable a todas las tuberías, incluidas las tuberías Singleton. Las versiones anteriores de DBMS_PIPE tenían un tamaño máximo de mensaje más pequeño.

  • Comparta el mensaje almacenado en caché en varias sesiones de base de datos con lecturas simultáneas.

  • Métodos de invalidación de la caché:

    • Invalidación explícita de caché controlada por el usuario.
    • Invalidación de caché después de un intervalo de tiempo del parámetro especificado por el usuario (shelflife) (en segundos).

  • API PL/SQL declarativas y fáciles de utilizar para el almacenamiento en caché.

  • Admite bases de datos de solo lectura y de lectura y escritura.

Un tubo Singleton puede ser cualquiera de los tipos DBMS_PIPE admitidos:

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

Resumen de Subprogramas DBMS_PIPE para Pipes Singleton

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 NEXT_ITEM_TYPE

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

Crea un mensaje en el buffer local
Procedimiento PURGE

Depura el contenido de la conducción con nombre

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 la conducción con nombre: esto crea implícitamente una conducción pública si la conducción con nombre no existe
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.

Para crear una canalización Singleton, defina el parámetro singleton en TRUE. Los siguientes argumentos son aplicables a las tuberías Singleton:

  • singleton: indica que el conducto se debe crear como un conducto Singleton (valor por defecto: FALSE).

  • shelflife: si lo desea, especifique una caducidad de caducidad (en segundos) del mensaje almacenado en caché en Singleton Pipe. Se puede utilizar para la invalidación implícita del mensaje en Singleton Pipe.

    El mensaje shelflife en Singleton Pipe también se puede especificar al enviar un mensaje (consulte SEND_MESSAGE Function).

Sintaxis

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;

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.

singleton

Utilice TRUE para crear una pipa Singleton.

Valor por defecto: FALSE

shelflife

Tiempo de caducidad en segundos de un mensaje almacenado en caché en Singleton Pipe. Una vez superado el tiempo de shelflife especificado, ya no se podrá acceder al mensaje desde la pipa. El parámetro shelflife solo se aplica a un tubo Singleton.

El valor por defecto es 0, lo que implica que el mensaje nunca caduca.

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.

6

Fallo al convertir el canal existente en canal singleton.

  • El conducto implícito con más de un mensaje existente no se puede convertir en un conducto Singleton.
  • Para una conducción explícita que no sea Singleton, DBMS_PIPE.SEND_MESSAGE no puede enviar un mensaje con el argumento singleton definido en TRUE.

7

Se proporciona un valor distinto de cero para el parámetro shelflife y el conducto no es un conducto singleton.

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

Cree un tubo Singleton con una vida útil de 1 hora.

DECLARE
  l_status INTEGER;
BEGIN
  l_status := DBMS_PIPE.create_pipe(pipename  => 'MY_PIPE1',
                                    private   => TRUE,
                                    singleton => TRUE,
                                    shelflife => 3600);
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,
   cache_func    IN VARCHAR2     DEFAULT NULL)
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 la función de caché de ejecución especificada en el parámetro cache_func.

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

cache_func

Almacenar en caché el nombre de la función para almacenar automáticamente en caché un mensaje en una pipa Singleton.

El nombre de la función debe estar totalmente cualificado con el esquema de propietario:

  • OWNER.FUNCTION_NAME
  • OWNER.PACKAGE.FUNCTION_NAME

Valor por defecto: NULL

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

La función de caché solo se puede especificar al utilizar una pipa Singleton.

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.

Parámetro de Función de Caché

Singleton Pipes soporta la función de caché para almacenar automáticamente en caché un mensaje en el canal en el caso de los dos escenarios siguientes:

  • Singleton Pipe está vacío.
  • El mensaje de Singleton Pipe no es válido debido al tiempo transcurrido shelflife.

El nombre de la función debe estar totalmente cualificado con el esquema de propietario:

  • OWNER.FUNCTION_NAME
  • OWNER.PACKAGE.FUNCTION_NAME

Para utilizar una función de caché, el usuario de la sesión actual que llama a DBMS_PIPE.RECEIVE_MESSAGE debe tener los privilegios necesarios para ejecutar la función de caché.

Sintaxis de Función de Caché

CREATE OR REPLACE FUNCTION cache_function_name (
       pipename  IN VARCHAR2
) RETURN INTEGER;
parámetro Tipo de dato Descripción

pipename

 VARCHAR2

Nombre del Singleton Pipe.
Return Descripción
0 Correcto
No cero Valor de fallo devuelto de DBMS_PIPE.RECEIVE_MESSAGE

Defina una función de caché para proporcionar encapsulación y abstracción de la complejidad de las sesiones de lectura de Singleton Pipe. Las operaciones típicas dentro de una función de caché serían:

  • Cree una pipa Singleton para una pipa explícita mediante DBMS_PIPE.CREATE_PIPE.
  • Cree el mensaje para almacenar en caché en Singleton Pipe.
  • Enviar mensaje a Singleton Pipe, especificando opcionalmente un shelflife para el mensaje implícito.

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.

Ejemplo

DECLARE
  l_status INTEGER;
BEGIN
  l_status := DBMS_PIPE.receive_message(pipename   => 'MY_PIPE1',
                                        timeout    => 1,
                                        cache_func => 'MY_USER.MY_CACHE_FUNC');
END;
/

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.

Para crear una conducción Singleton implícita, defina el parámetro singleton en TRUE. Los siguientes argumentos son aplicables a las tuberías Singleton:

  • singleton: indica que el conducto se debe crear como un conducto Singleton (valor por defecto: FALSE).
  • shelflife: si lo desea, especifique una caducidad de caducidad del mensaje almacenado en caché en Singleton Pipe. Se puede utilizar para la invalidación implícita del mensaje en Singleton Pipe.

    Este argumento es aplicable para pipas Singleton implícitas y explícitas. Un valor shelflife especificado en SEND_MESSAGE Function sobrescribe el valor shelflife especificado para la pipa Singleton explícita en CREATE_PIPE Function y será el valor por defecto para los mensajes nuevos almacenados en caché en la pipa Singleton.

Sintaxis

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;

Parámetros

Tabla - Parámetros de función SEND_MESSAGE

parámetro Descripción

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

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.

singleton

Utilice TRUE para crear una pipa Singleton.

Valor por defecto: FALSE

shelflife

Tiempo de caducidad en segundos de un mensaje almacenado en caché en Singleton Pipe.

Una vez superado el tiempo de shelflife especificado, ya no se podrá acceder al mensaje desde la pipa. El parámetro shelflife solo se aplica a un tubo Singleton.

El valor por defecto es 0, lo que implica que el mensaje nunca caduca.

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.

6

Fallo al convertir el canal existente en canal singleton.

  • El conducto implícito con más de un mensaje existente no se puede convertir en un conducto Singleton.
  • Para una conducción explícita que no sea Singleton, DBMS_PIPE.SEND_MESSAGE no puede enviar un mensaje con el argumento singleton definido en TRUE.

7

Se proporciona un valor distinto de cero para el parámetro shelflife y el conducto no es un conducto singleton.

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.

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.