Documentación de Oracle Cloud Infrastructure

Paquete DBMS_PIPE

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

Oracle Autonomous Database soporta la funcionalidad principal DBMS_PIPE según esté disponible en Oracle Database 19c, además de las extensiones.

Consulte DBMS_PIPE para obtener más información sobre la funcionalidad principal DBMS_PIPE proporcionada en Oracle Database.

Tema principal: Referencia de paquetes proporcionados por Autonomous Database

Visión general de DBMS_PIPE para tubos Singleton

La funcionalidad Pipe 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 pipas singleton.

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.

Una tubería 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: se crea 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: se puede acceder mediante sesiones con el mismo usuario que el creador del pipeline.

Tema principal: Paquete DBMS_PIPE

Resumen de los subprogramas de DBMS_PIPE para tubos singleton

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

Tabla 6-1 Subprogramas del 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 del buffer

PACK_MESSAGE Procedimientos

Crea un mensaje en el buffer local

Procedimiento de PURGE

Purga el contenido de la tubería con nombre

Función RECEIVE_MESSAGE

Copia el mensaje del conducto con nombre en el buffer local

RESET_BUFFER Procedimiento

Depura el contenido del buffer local

Función REMOVE_PIPE

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

Devuelve un nombre de sesión único

UNPACK_MESSAGE Procedimientos

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.
  • Función RECEIVE_MESSAGE
    Esta función copia el mensaje en el buffer de mensajes local.
  • Función SEND_MESSAGE
    Esta función envía un mensaje en el conducto con nombre.

Tema principal: Paquete DBMS_PIPE

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 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 6-2 Parámetros de función CREATE_PIPE

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 toda la instancia.

Precaución: No utilice nombres de conducción que empiecen 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 de Retorno

Tabla 6-3 Valores de retorno de función CREATE_PIPE

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

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

Tabla 6-4 Excepción de función CREATE_PIPE

Excepción Descripción

Null pipe name

Error de permiso: ya existe una pleca con el mismo nombre y no puede utilizarla.

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 6-5 Parámetros de función RECEIVE_MESSAGE

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 de espera para 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 de Retorno

Tabla 6-6 Valores de retorno de función RECEIVE_MESSAGE

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

Tabla 6-7 RECEIVE_MESSAGE Excepciones de función

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 SEND_MESSAGE Function sobrescribe el valor shelflife especificado para la pleca Singleton explícita en CREATE_PIPE Function 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 6-8 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 conducción 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 de Retorno

Tabla 6-9 Valores de retorno de función SEND_MESSAGE

Intro 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

Tabla 6-10 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.

Visión General de DBMS_PIPE para Pipes de Mensajes Persistentes

La funcionalidad Pipe 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 canales de mensajería persistentes.

Mensajes Persistentes en DBMS_PIPE:

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

  • Soporta un gran número de mensajes de conducción.

  • Compatibilidad con el uso compartido de mensajes en una única base de datos, en varias bases de datos y en distintas regiones.

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

    La funcionalidad de mensajes persistentes permite que dos o más sesiones de base de datos se comuniquen con mensajes que se almacenan en el almacén de objetos en la nube. El uso de esta funcionalidad de mensajes 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 conducto de mensajería persistente puede ser cualquiera de los tipos de 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: se crea 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: se puede acceder mediante sesiones con el mismo usuario que el creador del pipeline.
Nota

Cuando se envían y reciben mensajes en diferentes bases de datos mediante mensajes persistentes, Oracle recomienda llamar a DBMS_PIPE.CREATE_PIPE antes de enviar o recibir mensajes. La creación de un conducto explícito con DBMS_PIPE.CREATE_PIPE garantiza que se cree un conducto con los permisos de acceso que desee, ya sean públicos o privados (mediante la definición del parámetro PRIVATE en FALSE o el uso del 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.

Consulte Selección de un juego de caracteres para Autonomous Database para obtener más información.

Tema principal: Paquete DBMS_PIPE

Resumen de Subprogramas DBMS_PIPE para Mensajería Persistente

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

Tabla 6-11 Subprogramas del 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 variable global credential_name.

Función GET_LOCATION_URI

Devuelve el valor de variable global location_uri 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 del buffer.

PACK_MESSAGE Procedimientos

Crea un mensaje en el buffer local.

Función RECEIVE_MESSAGE

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

RESET_BUFFER Procedimiento

Depura el contenido del buffer local.

Función REMOVE_PIPE

Elimina el conducto con nombre.

Función SEND_MESSAGE

Envía un mensaje en un conducto con nombre: esto crea implícitamente un conducto público si el conducto con nombre no existe.

SET_CREDENTIAL_NAME Procedimiento

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.

SET_LOCATION_URI Procedimiento

Define la variable global location_uri 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 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.
  • Función GET_CREDENTIAL_NAME
    Esta función devuelve el valor de variable global credential_name para su uso cuando los mensajes se almacenan en el almacén de objetos en la nube.
  • Función GET_LOCATION_URI
    Esta función devuelve el valor de variable global location_uri que se puede utilizar como URI de ubicación por defecto cuando se almacenan mensajes de canal en el almacén de objetos en la nube.
  • Función RECEIVE_MESSAGE
    Esta función copia el mensaje en el buffer de mensajes local.
  • Función SEND_MESSAGE
    Esta función envía un mensaje en el conducto con nombre.
  • Procedimiento SET_CREDENTIAL_NAME
    Este procedimiento define la variable credential_name que se utiliza como credencial por defecto cuando los mensajes de canal se almacenan en el almacén de objetos en la nube.
  • Procedimiento SET_LOCATION_URI
    Este procedimiento define la variable global location_uri.

Tema principal: Paquete DBMS_PIPE

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.

Sintaxis

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

Parámetros

Tabla 6-12 Parámetros de función CREATE_PIPE

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

Valores de Retorno

Tabla 6-13 Valores de retorno de función CREATE_PIPE

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

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

Tabla 6-14 Excepción de función CREATE_PIPE

Excepción Descripción

Null pipe name

Error de permiso: ya existe una pleca con el mismo nombre y no puede utilizarla.

Ejemplo

Crear una privada explícita denominada 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 global credential_name 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 de Retorno

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 global location_uri que se puede utilizar como URI de ubicación por defecto cuando los mensajes de canal 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 6-15 Parámetros de función RECEIVE_MESSAGE

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 de espera para un mensaje, en segundos. Un timeout de 0 le permite leer sin bloqueo.

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

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

credential_name

Nombre de credencial del 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 de 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.

El valor credential_name puede ser una entidad de recurso de OCI, entidad de servicio de Azure, nombre de recurso de Amazon (ARN) o una cuenta de servicio de Google. Consulte Configuración de políticas y roles para acceder a recursos para obtener más información sobre la autenticación basada en entidad de recurso.

location_uri

URI de ubicación del almacén en la nube que se utiliza para almacenar mensajes.

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

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

Valores de Retorno

Tabla 6-16 Valores de retorno de función RECEIVE_MESSAGE

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

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.

  • Se garantiza que los mensajes persistentes se escriban o lean exactamente mediante un proceso. Esto evita la inconsistencia del contenido del mensaje debido a escrituras y lecturas simultáneas. Mediante un conducto de mensajería persistente, DBMS_PIPE solo permite una operación, ya que el envío de un mensaje o un mensaje de recepción está activo en un momento determinado. Sin embargo, si no se puede realizar una operación 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 nativas de Oracle Cloud Infrastructure en el objeto de credencial.

    • Si utiliza el formato 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 6-17 RECEIVE_MESSAGE Excepciones de función

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

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 6-18 Parámetros de función SEND_MESSAGE

Parámetro Descripción
credential_name

Nombre de credencial del 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 de 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.

El valor credential_name puede ser una entidad de recurso de OCI, entidad de servicio de Azure, nombre de recurso de Amazon (ARN) o una cuenta de servicio de Google. Consulte Configuración de políticas y roles para acceder a recursos para obtener más información sobre la autenticación basada en entidad de recurso.

location_uri

URI de ubicación del almacén en la nube que se utiliza para almacenar mensajes.

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

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

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.

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 conducción 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).

Valores de Retorno

Tabla 6-19 Valores de retorno de función SEND_MESSAGE

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

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.

Notas de uso

  • Se garantiza que los mensajes persistentes se escriban o lean exactamente mediante un proceso. Esto evita la inconsistencia del contenido del mensaje debido a escrituras y lecturas simultáneas. Mediante un conducto de mensajería persistente, DBMS_PIPE solo permite una operación, ya que el envío de un mensaje o un mensaje de recepción está activo en un momento determinado. Sin embargo, si no se puede realizar una operación 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 nativas de Oracle Cloud Infrastructure en el objeto de credencial.

    • Si utiliza el formato 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 6-20 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.

SET_CREDENTIAL_NAME Procedimiento

Este procedimiento define la variable credential_name que se utiliza como credencial por defecto cuando los mensajes de canal 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.

El valor credential_name puede ser una entidad de recurso de OCI, entidad de servicio de Azure, nombre de recurso de Amazon (ARN) o una cuenta de servicio de Google. Consulte Configuración de políticas y roles para acceder a recursos para obtener más información sobre la autenticación basada en entidad de recurso.

Nota 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 nativas de Oracle Cloud Infrastructure en el objeto de credencial.

  • Si utiliza el formato 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;
/

SET_LOCATION_URI Procedimiento

Este procedimiento define la variable global location_uri.

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 Cloud Object Storage que utilice; para obtener información, consulte Formatos del URI de DBMS_CLOUD.

Nota 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 nativas de Oracle Cloud Infrastructure en el objeto de credencial.

  • Si utiliza el formato 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;
/