Paquete DBMS_PIPE (tuberías únicas)

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

Oracle Autonomous AI Database on Dedicated Exadata Infrastructure admite la funcionalidad principal DBMS_PIPE disponible en Oracle Database 19c, además de las extensiones.

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

Descripción general de DBMS_PIPE para tuberías únicas

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

En la base de datos de IA autónoma, el paquete DBMS_PIPE tiene una funcionalidad ampliada para admitir tuberías singleton. Consulte DBMS_PIPE en Oracle Database 19c PL/SQL Packages and Types Reference o Oracle Database 26ai PL/SQL Packages and Types Reference para obtener más información.

Las funciones de tubería Singleton en DBMS_PIPE proporcionan lo siguiente:

Capacidad para 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 de mensaje máximo de 32.767 bytes se aplica a todos los tubos, incluidos los tubos Singleton. Las versiones anteriores de DBMS_PIPE tenían un tamaño de mensaje máximo menor.
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 de caché explícita 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é.
Soporta bases de datos de solo lectura y de lectura y escritura.

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

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

Resumen de subprogramas DBMS_PIPE para tubos singleton

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

Subprograma	Descripción
Función CREATE_PIPE	Crea una tubería (necesaria para tuberías privadas)
Función NEXT_ITEM_TYPE Referencia de tipos y paquetes PL/SQL de Oracle Database 19c Referencia de tipos y paquetes PL/SQL de Oracle Database 26ai	Devuelve el tipo de dato del siguiente elemento del buffer
Procedimientos PACK_MESSAGE Referencia de tipos y paquetes PL/SQL de Oracle Database 19c Referencia de tipos y paquetes PL/SQL de Oracle Database 26ai	Crea un mensaje en el buffer local
Procedimiento de PURGE Referencia de tipos y paquetes PL/SQL de Oracle Database 19c Referencia de tipos y paquetes PL/SQL de Oracle Database 26ai	Purga el contenido de la tubería con nombre
Función RECEIVE_MESSAGE	Copia el mensaje del conducto con nombre en el buffer local
Procedimiento RESET_BUFFER Referencia de tipos y paquetes PL/SQL de Oracle Database 19c Referencia de tipos y paquetes PL/SQL de Oracle Database 26ai	Depura el contenido del buffer local
Función REMOVE_PIPE Referencia de tipos y paquetes PL/SQL de Oracle Database 19c Referencia de tipos y paquetes PL/SQL de Oracle Database 26ai	Elimina el conducto con nombre
Función SEND_MESSAGE	Envía un mensaje en una canalización con nombre: esto crea implícitamente una canalización pública si la canalización con nombre no existe
Función UNIQUE_SESSION_NAME Referencia de tipos y paquetes PL/SQL de Oracle Database 19c Referencia de tipos y paquetes PL/SQL de Oracle Database 26ai	Devuelve un nombre de sesión único
Procedimientos UNPACK_MESSAGE Referencia de tipos y paquetes PL/SQL de Oracle Database 19c Referencia de tipos y paquetes PL/SQL de Oracle Database 26ai	Accede al siguiente elemento del buffer

Función CREATE_PIPE

Esta función crea explícitamente un conducto público o privado. Si el indicador private es TRUE, el creador del canal se asigna como propietario del canal privado.

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

Para crear un tubo Singleton, defina el parámetro singleton en TRUE. Los siguientes argumentos son aplicables a Singleton Pipes:

singleton: indica que el conducto se debe crear como un conducto Singleton (valor por defecto: FALSE).
shelflife: si lo desea, especifique una caducidad (en segundos) del mensaje almacenado en caché en el tubo Singleton. 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 Función SEND_MESSAGE).

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

parámetro	Descripción
`pipename`	Nombre del conducto que está creando. Debe utilizar este nombre cuando llame 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 mediante los procedimientos proporcionados por Oracle. El nombre de pipeline no debe tener más de 128 bytes y no es sensible a mayúsculas/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 del conducto no puede superar esta cantidad. El mensaje se bloquea si supera este máximo. El valor por defecto de `maxpipesize` es 66536 bytes. El `maxpipesize` para una tubería se convierte en una 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 se aplica a todos los pipes.
`private`	Utiliza el valor por defecto, `TRUE`, para crear un conducto privado. Las tuberías públicas se pueden crear implícitamente al llamar a `SEND_MESSAGE`.
`singleton`	Utilice `TRUE` para crear un tubo Singleton. Valor por defecto: `FALSE`
`shelflife`	Tiempo de caducidad en segundos de un mensaje almacenado en caché en Singleton Pipe. Una vez que se supera el tiempo especificado de `shelflife`, ya no se puede acceder al mensaje desde la pleca. El parámetro `shelflife` solo se aplica a un tubo de Singleton. El valor por defecto es `0`, lo que implica que el mensaje nunca caduca.

Valores devueltos

Return	Descripción
`0`	Correcto. Si la canalizació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 cualquier dato que ya esté en la canalización permanece.
`6`	Error al convertir el conducto existente en conducto singleton. El conducto implícito con más de un mensaje existente no se puede convertir en un conducto singleton. Para un conducto explícito que no es 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`	Error debido a un conflicto de nomenclatura. Si existe un conducto con el mismo nombre y lo ha creado un usuario diferente, Oracle indica el error `ORA-23322`, que indica el conflicto de nomenclatura.

Excepciones

Excepción	Descripción
`Null pipe name`	Error de permiso: ya existe una pleca con el mismo nombre y no puede utilizarla.

Ejemplo

Cree una tubería 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

parámetro	Descripción
`pipename`	Nombre de la conducción en la que desea recibir un mensaje. Los nombres que empiecen por `ORA$` están reservados para uso de Oracle.
`timeout`	Tiempo para esperar un mensaje, en segundos. Un timeout de 0 le permite leer sin bloqueo. El timeout no incluye el tiempo empleado en la función de caché de ejecución especificada en el parámetro `cache_func`. Valor predeterminado: es la constante `MAXWAIT`, que se define como 86400000 (1000 días).
`cache_func`	Nombre de función de caché para almacenar automáticamente en caché un mensaje en una pleca 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`

pipename

Nombre de la conducción en la que desea recibir un mensaje.

Los nombres que empiecen por ORA$ están reservados para uso de Oracle.

timeout

Tiempo para esperar un mensaje, en segundos. Un timeout de 0 le permite leer sin bloqueo.

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

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

cache_func

Nombre de función de caché para almacenar automáticamente en caché un mensaje en una pleca 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 tubería se creó implícitamente y está vacía, se elimina.
`2`	El registro en el conducto es demasiado grande para el buffer.
`3`	Se produjo una interrupción.
`8`	La función de caché solo se puede especificar cuando se utiliza un tubo Singleton.
`ORA-23322`	El usuario no tiene suficientes privilegios para leer desde el conducto.

Notas de uso

Para recibir un mensaje de un conducto, primero llame a RECEIVE_MESSAGE. Cuando recibe un mensaje, se elimina del conducto; 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 eliminar el último registro de la tubería.
Si el canal que especifique al llamar a RECEIVE_MESSAGE no existe, Oracle crea el canal de forma implícita y espera a recibir el mensaje. Si el mensaje no llega dentro de un intervalo de tiempo de espera designado, se devuelve la llamada 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 se sobrecarga para desempaquetar artículos de tipo DATE, NUMBER, VARCHAR2 y hay dos procedimientos adicionales para desempaquetar artículos 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 un mensaje en la canalización en caso de los dos escenarios siguientes:

El tubo Singleton está vacío.
El mensaje en la tubería Singleton 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 de la tubería Singleton.

Return	Descripción
0	Correcto
No cero	Valor de fallo devuelto de `DBMS_PIPE.RECEIVE_MESSAGE`

Definir 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 un tubo singleton, para un tubo explícito, mediante DBMS_PIPE.CREATE_PIPE.
Cree el mensaje que desea almacenar en caché en la pleca Singleton.
Enviar mensaje a una pleca Singleton, si lo desea, especificando shelflife para el mensaje implícito.

Excepciones

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 el conducto 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 un conducto Singleton implícito, defina el parámetro singleton en TRUE. Los siguientes argumentos son aplicables a Singleton Pipes:

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

Este argumento es aplicable tanto a las tuberías Singleton implícitas como explícitas. Un valor shelflife especificado en la función SEND_MESSAGE sobrescribe el valor shelflife especificado para el tubo Singleton explícito en

Función CREATE_PIPE y será el valor por defecto para cualquier mensaje nuevo almacenado en caché en la pleca 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 de la conducción en la que desea colocar el mensaje. Si utiliza un conducto explícito, este es el nombre que especificó al llamar a `CREATE_PIPE`. Precaución: No utilice nombres de conductos que empiecen por '`ORA$`'. Estos nombres están reservados para los procedimientos proporcionados por Oracle. El nombre de pipeline no debe tener más de 128 bytes y no es sensible a mayúsculas/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 un conducto, 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 la conducción, en bytes. El tamaño total de todos los mensajes del conducto no puede superar esta cantidad. El mensaje se bloquea si supera este máximo. El valor por defecto es 65536 bytes. El `maxpipesize` para una tubería se convierte en una 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. Al especificar `maxpipesize` como parte del procedimiento `SEND_MESSAGE`, se elimina la necesidad de una llamada independiente para abrir el conducto. Si ha creado el conducto de forma explícita, 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 se aplica a todos los pipes.
`singleton`	Utilice `TRUE` para crear un tubo Singleton. Valor por defecto: `FALSE`
`shelflife`	Tiempo de caducidad en segundos de un mensaje almacenado en caché en Singleton Pipe. Una vez que se supera el tiempo especificado de `shelflife`, ya no se puede acceder al mensaje desde la pleca. El parámetro `shelflife` solo se aplica a un tubo de Singleton. El valor por defecto es `0`, lo que implica que el mensaje nunca caduca.

Valores devueltos

Return	Descripción
`0`	Correcto. Si el conducto ya existe y el usuario que intenta crearlo está autorizado a utilizarlo, Oracle devuelve 0, lo que indica que se ha realizado correctamente, y cualquier dato que ya esté en el conducto permanece. Si un usuario conectado como `SYSDBS`/`SYSOPER` vuelve a crear un canal, Oracle devuelve el estado 0, pero la propiedad del canal no cambia.
`1`	Timeout. Este procedimiento puede agotar el tiempo de espera porque no puede obtener un bloqueo en el conducto o porque el conducto permanece demasiado lleno para ser utilizado. Si la tubería se creó implícitamente y está vacía, se elimina.
`3`	Se produjo una interrupción. Si el conducto se creó implícitamente y está vacío, se elimina.
`6`	Error al convertir el conducto existente en conducto singleton. El conducto implícito con más de un mensaje existente no se puede convertir en un conducto singleton. Para un conducto explícito que no es 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`	No dispone de privilegios suficientes. Si existe un conducto con el mismo nombre y lo ha creado un usuario diferente, Oracle indica el error `ORA-23322`, que indica el conflicto de nomenclatura.

Excepciones

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.

Contenido relacionado

Mensajes en caché con canalizaciones Singleton