Paquete DBMS

Paquete DBMS_PIPE

El paquete DBMS_PIPE permite la comunicación de dos o más sesiones en la misma instancia.

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

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

DBMS_PIPE Visión general de Singleton Pipes
La funcionalidad de Pipe tiene varias aplicaciones posibles: interfaz de servicio externo, depuración, transacciones independientes y alertas.
Resumen de los subprogramas DBMS_PIPE para pipas singleton
En esta tabla se muestran los subprogramas DBMS_PIPE y se describen brevemente.
DBMS_PIPE Visión general de pipas de mensajes persistentes
La funcionalidad de pipa tiene varias aplicaciones potenciales: interfaz de servicio externa, depuración, transacciones independientes y alertas.
Resumen de los subprogramas DBMS_PIPE para la mensajería persistente
En esta tabla se muestran los subprogramas DBMS_PIPE y se describen brevemente.

Tema principal: Referencia de paquete proporcionado por Autonomous Database

DBMS_PIPE Visión general de Singleton Pipes

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 canalización singleton en 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 de mensaje de 32.767 bytes es aplicable a todos los pipes, incluidos los pipes singleton. Las versiones anteriores de DBMS_PIPE tenían un tamaño de mensaje máximo 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 la caché:
- Invalidación explícita de caché controlada por el usuario.
- Invalidación de caché después de un intervalo de tiempo de parámetro especificado por el usuario (shelflife) (en segundos).
API PL/SQL declarativas y fáciles de utilizar para el almacenamiento en caché.
Soporta tanto bases de datos de sólo lectura como de lectura-escritura.

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

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.
Conducto público: accesible para cualquier usuario con permiso EXECUTE en el paquete DBMS_PIPE
Conducto privado: accesible por sesiones con el mismo usuario que el creador del conducto.

Tema principal: Paquete DBMS_PIPE

Resumen de subprogramas DBMS_PIPE para pipas singleton

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

Tabla 6-1 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	Genera un mensaje en el buffer local
Procedimiento de depuración	Depura el contenido del conducto 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 el conducto con nombre: crea implícitamente un conducto público si el conducto 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 canal público o privado. Si el indicador private es TRUE, el creador del conducto se asigna como propietario del conducto 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 canal público o privado. Si el indicador private es TRUE, el creador del conducto se asigna como propietario del conducto privado.

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

Para crear una tubería 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: puede especificar una caducidad de vida útil (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 6-2 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 conducto que empiecen por `ORA$`. Estas están reservadas para ser utilizadas por 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 el conducto, en bytes. El tamaño total de todos los mensajes del canal no puede superar esta cantidad. El mensaje se bloquea si supera este máximo. El valor por defecto `maxpipesize` es 66536 bytes. El `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 pipes.
`private`	Utiliza el valor por defecto, `TRUE`, para crear un canal privado. Los pipes públicos se pueden crear implícitamente al llamar a `SEND_MESSAGE`.
`singleton`	Utilice `TRUE` para crear una tubería Singleton. Valor por defecto: `FALSE`}
`shelflife`	Tiempo de caducidad en segundos de un mensaje almacenado en caché en Singleton Pipe. Una vez que se ha excedido el tiempo `shelflife` especificado, ya no se puede acceder al mensaje desde el canal. El parámetro `shelflife` solo se aplica a una tubería 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

Volver	Descripción
`0`	correcto. Si el conducto ya existe y el usuario que intenta crearlo está autorizado a utilizarlo, Oracle devuelve 0, indicando que es correcto, y los datos que ya están en el conducto permanecen.
`6`	Fallo al convertir el canal existente en el único. El canal implícito con más de un mensaje existente no se puede convertir en un canal Singleton. Para un canal explícito que no es Singleton, `DBMS_PIPE.SEND_MESSAGE` no puede enviar un mensaje con un 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 único.
`ORA-23322`	Fallo debido a un conflicto de nomenclatura. Si existe un conducto con el mismo nombre y lo ha creado otro usuario, 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 un conducto con el mismo nombre y no se le permite utilizarlo.

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;
/

Tema principal: Resumen de los subprogramas DBMS_PIPE para pipas singleton

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 del conducto en el que desea recibir un mensaje.

Los nombres que empiezan por ORA$ están reservados para su uso por 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 por defecto: 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 un canal 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

Volver	Descripción
`0`	Correcta
`1`	Timeout. Si el conducto se ha creado implícitamente y está vacío, 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 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 de la tubería; 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 conducto que especifica al llamar a RECEIVE_MESSAGE aún no existe, Oracle crea el conducto de forma implícita y espera a recibir el mensaje. Si el mensaje no llega dentro de un intervalo de tiempo de espera designado, la llamada vuelve y se elimina el canal.

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

Los pipes singleton admiten la función de caché para almacenar automáticamente en caché un mensaje en el canal en caso de los dos escenarios siguientes:

Singleton Pipe está vacío.
El mensaje en Singleton Pipe no es válido debido al tiempo transcurrido de 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 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.

Volver	Descripción
0	Correcta
No es cero	Valor de fallo devuelto de `DBMS_PIPE.RECEIVE_MESSAGE`

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

Cree un conducto singleton, para un conducto explícito, mediante DBMS_PIPE.CREATE_PIPE.
Cree el mensaje que desea almacenar en caché en Singleton Pipe.
Enviar mensaje al canal Singleton, especificando opcionalmente shelflife para el mensaje implícito.

Excepciones

Tabla 6-7 Excepciones de función RECEIVE_MESSAGE

Excepción	Descripción
`Null pipe name`	Error de permiso. No dispone de privilegios suficientes para eliminar el registro del conducto. La tubería 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;
/

Tema principal: Resumen de los subprogramas DBMS_PIPE para pipas singleton

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 de forma implícita.

Para crear un canal 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: puede especificar una caducidad de vida útil 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 tanto a pipas Singleton implícitas como explícitas. Un valor shelflife especificado en la función SEND_MESSAGE sobrescribe el valor shelflife especificado para el conducto Singleton explícito en la función CREATE_PIPE y será el valor predeterminado para los mensajes nuevos almacenados en caché en el conducto 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 del conducto en el que desea colocar el mensaje. Si utiliza un conducto explícito, este es el nombre que ha especificado al llamar a `CREATE_PIPE`. Precaución: No utilice nombres de conducción que empiecen por '`ORA$`'. Estos nombres están reservados para ser utilizados por 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 canal, 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 del canal 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 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 más pequeño simplemente utilizan el valor más grande existente. La especificación de `maxpipesize` como parte del procedimiento `SEND_MESSAGE` elimina la necesidad de una llamada independiente para abrir el canal. 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 es aplicable a todos los pipes.
`singleton`	Utilice `TRUE` para crear una tubería Singleton. Valor por defecto: `FALSE`}
`shelflife`	Tiempo de caducidad en segundos de un mensaje almacenado en caché en Singleton Pipe. Una vez que se ha excedido el tiempo `shelflife` especificado, ya no se puede acceder al mensaje desde el canal. El parámetro `shelflife` solo se aplica a una tubería 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

Volver	Descripción
`0`	Correcta. Si el conducto ya existe y el usuario que intenta crearlo está autorizado a utilizarlo, Oracle devuelve 0, indicando que es correcto, y los datos que ya están en el conducto permanecen. Si un usuario conectado como `SYSDBS`/`SYSOPER` vuelve a crear un conducto, Oracle devuelve el estado 0, pero la propiedad del conducto permanece sin cambios.
`1`	Timeout. Este procedimiento puede agotarse porque no puede obtener un bloqueo en el conducto o porque el conducto permanece demasiado lleno para ser utilizado. Si el conducto se ha creado implícitamente y está vacío, se elimina.
`3`	Se ha producido una interrupción. Si el conducto se ha creado implícitamente y está vacío, se elimina.
`6`	Fallo al convertir el canal existente en el único. El canal implícito con más de un mensaje existente no se puede convertir en un canal Singleton. Para un canal explícito que no es Singleton, `DBMS_PIPE.SEND_MESSAGE` no puede enviar un mensaje con un 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 único.
`ORA-23322`	Los privilegios no son suficientes. Si existe un conducto con el mismo nombre y lo ha creado otro usuario, 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.

Tema principal: Resumen de los subprogramas DBMS_PIPE para pipas singleton

DBMS_PIPE Visión General de 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 pipas de mensajes persistentes.

Mensajes persistentes en DBMS_PIPE:

Admite la capacidad de enviar y recuperar mensajes muy grandes.
Admite un gran número de mensajes de canal.
Permita el uso compartido de mensajes en una sola base de datos, en 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. Al utilizar esta funcionalidad, los mensajes de un canal pueden estar disponibles solo para la base de datos actual o para varias bases de datos de la misma región o de distintas regiones.

Un conducto de mensajería persistente 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.
- Conducto público: accesible para cualquier usuario con permiso EXECUTE en el paquete DBMS_PIPE.
- Conducto privado: accesible por sesiones con el mismo usuario que el creador del conducto.

Nota

Al enviar y recibir 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 canal explícito con DBMS_PIPE.CREATE_PIPE garantiza que se cree un canal con los permisos de acceso que desee, ya sea público o privado (definiendo el parámetro PRIVATE en FALSE o utilizando el valor por defecto TRUE).

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 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 global `credential_name`.
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	Genera un 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 un canal con nombre: crea implícitamente un canal público si el canal 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 del buffer.

Función CREATE_PIPE
Esta función crea explícitamente un canal público o privado. Si el indicador private es TRUE, el creador del conducto se asigna como propietario del conducto privado.
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.
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.
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 conducción se almacenan en el almacén de objetos en la nube.
Procedimiento SET_LOCATION_URI
Este procedimiento define la variable location_uri global.

Tema principal: Paquete DBMS_PIPE

Función CREATE_PIPE

Esta función crea explícitamente un canal público o privado. Si el indicador private es TRUE, el creador del conducto se asigna como propietario del conducto 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 al llamar a SEND_MESSAGE y RECEIVE_MESSAGE. Este nombre debe ser único en la instancia.

Precaución: No utilice nombres de conducto que empiecen por ORA$. Estas están reservadas para ser utilizadas por 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 el conducto, en bytes.

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

El valor por defecto maxpipesize es 66536 bytes.

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

private

Utiliza el valor por defecto, TRUE, para crear un canal privado.

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

Valores de Retorno

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

Volver Descripción

0

correcto.

Si el conducto ya existe y el usuario que intenta crearlo está autorizado a utilizarlo, Oracle devuelve 0, indicando que es correcto, y los datos que ya están en el conducto permanecen.

ORA-23322

Fallo debido a un conflicto de nomenclatura.

Si existe un conducto con el mismo nombre y lo ha creado otro usuario, 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 un conducto con el mismo nombre y no se le permite 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;
/

Tema principal: Resumen de los subprogramas de DBMS_PIPE para mensajería persistente

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 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;
/

Tema principal: Resumen de los subprogramas de DBMS_PIPE para mensajería persistente

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

Ejemplo

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

Tema principal: Resumen de los subprogramas de DBMS_PIPE para mensajería persistente

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 del conducto en el que desea recibir un mensaje. Los nombres que empiezan por `ORA$` están reservados para su uso por 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 por defecto: 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, una entidad de servicio de Azure, un 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 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 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

Volver	Descripción
`0`	Correcta
`1`	Timeout. Si el conducto se ha creado implícitamente y está vacío, 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, primero llame a RECEIVE_MESSAGE. Cuando recibe un mensaje, se elimina de la tubería; 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 conducto que especifica al llamar a RECEIVE_MESSAGE aún no existe, Oracle crea el conducto de forma implícita y espera a recibir el mensaje. Si el mensaje no llega dentro de un intervalo de tiempo de espera designado, la llamada vuelve y se elimina el canal.
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 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 del contenido del mensaje debido a escrituras y lecturas simultáneas. Mediante un canal de mensajes persistente, DBMS_PIPE permite que solo una operación, el envío de un mensaje o un mensaje de recepción, esté activo en un momento determinado. Sin embargo, si una operación no es posible debido a una operación en curso, el proceso vuelve a intentarlo 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 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 6-17 Excepciones de función RECEIVE_MESSAGE

Excepción	Descripción
`Null pipe name`	Error de permiso. No dispone de privilegios suficientes para eliminar el registro del conducto. La tubería es propiedad de otra persona.

Tema principal: Resumen de los subprogramas de DBMS_PIPE para mensajería persistente

Función SEND_MESSAGE

Esta función envía un mensaje en el conducto con nombre.

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, una entidad de servicio de Azure, un 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 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 de 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 del canal 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 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 más pequeño simplemente utilizan el valor más grande existente. La especificación de `maxpipesize` como parte del procedimiento `SEND_MESSAGE` elimina la necesidad de una llamada independiente para abrir el canal. 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 es aplicable a todos los pipes.
`pipename`	Nombre del conducto en el que desea colocar el mensaje. Si utiliza un conducto explícito, este es el nombre que ha especificado al llamar a `CREATE_PIPE`. Precaución: No utilice nombres de conducción que empiecen por '`ORA$`'. Estos nombres están reservados para ser utilizados por 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 canal, 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

Volver	Descripción
`0`	Correcta. Si el conducto ya existe y el usuario que intenta crearlo está autorizado a utilizarlo, Oracle devuelve 0, indicando que es correcto, y los datos que ya están en el conducto permanecen. Si un usuario conectado como `SYSDBS`/`SYSOPER` vuelve a crear un conducto, Oracle devuelve el estado 0, pero la propiedad del conducto permanece sin cambios.
`1`	Timeout. Este procedimiento puede agotarse porque no puede obtener un bloqueo en el conducto o porque el conducto permanece demasiado lleno para ser utilizado. Si el conducto se ha creado implícitamente y está vacío, se elimina.
`3`	Se ha producido una interrupción. Si el conducto se ha creado implícitamente y está vacío, se elimina.
`ORA-23322`	Los privilegios no son suficientes. Si existe un conducto con el mismo nombre y lo ha creado otro usuario, 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 en un proceso. Esto evita la inconsistencia del contenido del mensaje debido a escrituras y lecturas simultáneas. Mediante un canal de mensajes persistente, DBMS_PIPE permite que solo una operación, el envío de un mensaje o un mensaje de recepción, esté activo en un momento determinado. Sin embargo, si una operación no es posible debido a una operación en curso, el proceso vuelve a intentarlo 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 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 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.

Tema principal: Resumen de los subprogramas de DBMS_PIPE para mensajería persistente

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

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, una entidad de servicio de Azure, un 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.

credential_name

Nombre de la credencial para acceder a Cloud Object Storage.

El valor credential_name puede ser una entidad de recurso de OCI, una entidad de servicio de Azure, un 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 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;
/

Tema principal: Resumen de los subprogramas de DBMS_PIPE para mensajería persistente

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 DBMS_CLOUD Formato de URI.

Nota de Uso

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 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;
/

Tema principal: Resumen de los subprogramas de DBMS_PIPE para mensajería persistente

Documentación de Oracle Cloud Infrastructure

DBMS_PIPE Visión general de Singleton Pipes

Resumen de subprogramas DBMS_PIPE para pipas singleton

Función CREATE_PIPE

Función RECEIVE_MESSAGE

Función SEND_MESSAGE

DBMS_PIPE Visión General de Pipes de Mensajes Persistentes

Resumen de Subprogramas DBMS_PIPE para Mensajería Persistente

Función CREATE_PIPE

Función GET_CREDENTIAL_NAME

Función GET_LOCATION_URI

Función RECEIVE_MESSAGE

Función SEND_MESSAGE

Procedimiento SET_CREDENTIAL_NAME

Procedimiento SET_LOCATION_URI