Referencia de paquete DBMS_DATA_TOOLS_JOBS

En este capítulo, se proporciona información sobre los paquetes que utiliza con la función Trabajos en Data Studio. El tema Summary of DBMS_DATA_TOOLS_JOBS Subprograms (Resumen de subprogramas) también abarca los procedimientos incluidos en el paquete DBMS_DATA_TOOLS_JOBS.

Temas:

Resumen de subprogramas DBMS_DATA_TOOLS_JOB

• Procedimientos DBMS_DATA_TOOLS_JOB

• Resumen de subprogramas DBMS_DATA_TOOLS_JOB
  El paquete DBMS_DATA_TOOLS_JOB proporciona una recopilación de funciones y procedimientos de programación que se utilizan con la función Trabajos en el conjunto de herramientas de Data Studio.

Resumen de subprogramas DBMS_DATA_TOOLS_JOB

El paquete DBMS_DATA_TOOLS_JOB proporciona una recopilación de funciones y procedimientos de programación que utiliza con la función Trabajos en el conjunto de herramientas de Data Studio.

Subprogramas de paquete DBMS_DATA_TOOLS_JOB

En la siguiente tabla, se muestran los subprogramas DBMS_DATA_TOOLS_JOB y se describen brevemente.

Tabla 22-2 Nombres y descripción de DBMS_DATA_TOOLS_JOB para los subprogramas DBMS_DATA_TOOLS_JOB

Subprograma	Descripción
Crear procedimiento de trabajo	Este procedimiento crea un nuevo trabajo.
Suprimir procedimiento de trabajo	Suprime el trabajo del programador.
Cambiar nombre de procedimiento de trabajo	Cambia el nombre del trabajo por el nombre deseado.
Procedimiento Actualizar trabajo	Modifica los atributos de un trabajo existente.
Ejecutar Procedimiento	Ejecuta un trabajo inmediatamente independientemente del programa que defina.
Detener procedimiento de trabajo	Detiene una tarea en ejecución. Esto termina un trabajo correctamente y, si es necesario, lo detiene por la fuerza.

Consideraciones de seguridad

No coloque datos confidenciales, como secretos, tokens de portador, contraseñas, claves privadas, URL firmadas u otras credenciales, directamente en las URL de paso de trabajo, los cuerpos de solicitud o la configuración de informes. Estos valores se pueden almacenar con la definición del trabajo y recuperarlos posteriormente. Utilice credenciales de base de datos o credenciales con nombre para la autenticación.

Procedimiento CREATE_JOB

Este procedimiento crea un único trabajo. Si crea el trabajo como activado definiendo el atributo activado en TRUE, el programador ejecuta automáticamente el trabajo según su programación. Si crea el trabajo desactivado, el trabajo no se ejecuta hasta que lo active con la función Activar trabajo.

Sintaxis

dbms_data_tools_job.create_job(
                       job_name        in varchar2,
                       description     in varchar2,
                       steps           in clob,
                       owner           in varchar2 default null,
                       start_date      IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
                       repeat_interval IN VARCHAR2                 DEFAULT NULL,
                       end_date        IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
                       job_class       IN VARCHAR2                 DEFAULT NULL,
                       enabled         IN BOOLEAN                  DEFAULT FALSE,
                       reporting       in clob default null);

Parámetros de Procedimiento CREATE_JOB

Tabla 22-3 Parámetros de Procedimiento CREATE_JOB

parámetro	Descripción
Nombre de trabajo	El nombre que desea asignar al trabajo. Si no se especifica job_name, se genera un error.
Descripción	Esto hace referencia a información adicional que se define para los trabajos.
Pasos	Esto hace referencia a varias tareas que realiza la herramienta Data Studio que consta de un trabajo. Steps es una matriz de JSON. Cada elemento de matriz es un objeto JSON. Estos son los elementos JSON que se aplican a todos los objetos: type: cadena, declara el tipo de paso que se realiza: data_load, smart_table, procedimiento, http. on_errors- cadena stop: si se encuentra un error, el trabajo se detiene y se emite el error. continue: el error se registra, pero el procesamiento continúa con el siguiente paso del trabajo. step_name: nombre descriptivo del paso que aparecerá en los logs Cada tipo de objeto tiene algunos elementos adicionales según el tipo. data_load: data_load_name: (obligatorio) nombre de una carga de datos creada previamente para su ejecución smart_table: recipe_name: (obligatorio) nombre de una receta de tabla inteligente creada anteriormente para ejecutar. url: URL de REST (obligatoria) a la que conectarse. method: GET (valor por defecto), POST, PUT, DELETE o algún otro verbo HTTP procedure: procedure: nombre (obligatorio) del procedimiento que se va a ejecutar. Opcionalmente, puede estar calificado para esquema y puede ser un procedimiento simple o un método de paquete. arguments: matriz de argumentos de cadena, número o booleanos para proporcionar al procedimiento. Atención: Para los pasos HTTP, no coloque datos confidenciales en la URL ni en el cuerpo de la solicitud. Utilice credenciales de base de datos o credenciales con nombre para la autenticación.
Propietario	Es el esquema en el que se crea el trabajo. Si crea un trabajo sin especificar un esquema, el propietario será el usuario que ejecuta el procedimiento CREATE_JOB.
Fecha de inicio	Este atributo especifica la primera fecha y hora en la que está programado el inicio de este trabajo. Si start_date y repeat_interval se dejan nulos, el trabajo se programa para que se ejecute tan pronto como se active el trabajo. Para los trabajos de repetición que utilizan una expresión de calendario para especificar el intervalo de repetición, start_date se utiliza como fecha de referencia. La primera vez que se ejecuta el trabajo es la primera coincidencia de la expresión de calendario que es igual o posterior a la fecha y hora actuales. El planificador no puede garantizar que un trabajo se ejecute a una hora exacta porque el sistema puede estar sobrecargado y, por lo tanto, los recursos no están disponibles.
Intervalo de Repetición	Este atributo especifica la frecuencia con la que se repite la ventana. Se expresa mediante la sintaxis de calendario del programador. Consulte "Sintaxis de calendario" para obtener más información. No se puede utilizar una expresión PL/SQL para especificar el intervalo de repetición de una ventana. La expresión especificada se evalúa para determinar la siguiente vez que se abre la ventana. Si no se especifica repeat_interval, la ventana solo se abre una vez en la fecha de inicio especificada.
Fecha de finalización	Este atributo especifica la fecha y hora después de la cual caduca el trabajo y ya no se ejecuta. El valor de end_date debe ser posterior al valor de start_date. Si end_date es menor que start_date, se generará un error. Si end_date es igual que start_date, el trabajo no se ejecutará y no se generará ningún error. Si no se especifica ningún valor para end_date, el trabajo se repite para siempre a menos que stop job.
Clase de Trabajo	Clase a la que está asociado este trabajo.
Activado	Este atributo especifica si el trabajo se ha creado activado o no. Los parámetros posibles son TRUE o FALSE. Por defecto, este atributo se define en FALSE y, por lo tanto, el trabajo se crea como desactivado. Un trabajo desactivado significa que los metadatos sobre el trabajo se han capturado y que el trabajo existe como objeto de base de datos. Sin embargo, el programador ignora el trabajo y el coordinador de trabajos no lo selecciona para su procesamiento. Para que el coordinador de puestos procese el puesto, éste debe estar activado. Puede activar un trabajo seleccionando el icono Enable Job.
Generación de Informes	Este atributo especifica los detalles de ejecución del trabajo mediante el botón Report de la función Jobs. Se trata de un objeto JSON similar al argumento de informe para dbms_live_feed. Puede tener los siguientes elementos: completed: destinos a los que notificar cuando finaliza un trabajo. errors: destinos a los que notificar cuando algún paso de un trabajo ha encontrado errores. failed: destinos para notificar cuando un trabajo ha tenido algún error fatal fuera del contexto de un paso. long: destinos a los que notificar cuándo se ha ejecutado un trabajo durante mucho tiempo. Cada uno de estos cuatro elementos puede especificar una matriz de direcciones de correo electrónico en el elemento smtp o canales flojos en el elemento slack. El elemento long puede tener un elemento max_runtime_seconds que determine cuánto tiempo se debe ejecutar un trabajo antes de que se considere que se ha ejecutado demasiado long. Atención: No incluya datos confidenciales en la configuración de informes.

Procedimiento DELETE_JOB

Este procedimiento suprime un trabajo.

Sintaxis

dbms_data_tools_job.delete_job(
                     job_name in varchar2, 
                     owner    in varchar2 default null);

Parámetros de Procedimiento DELETE_JOB

Tabla 22-4 Parámetros de procedimiento DELETE_JOB

parámetro	Descripción
Nombre de trabajo	El nombre que se va a asignar al trabajo. Si no se especifica job_name, se genera un error.
Propietario	Es el esquema en el que se crea el trabajo. Si crea un trabajo sin especificar un esquema, el propietario será el usuario que ejecuta el procedimiento CREATE_JOB.

Procedimiento RENAME_JOB

Este procedimiento cambia el nombre de un trabajo.

Sintaxis

dbms_data_tools_job.rename_job(
                       old_job_name in varchar2,
                       new_job_name in varchar2,
                       owner        in varchar2 default null);

Parámetros de Procedimiento RENAME_JOB

Tabla 22-5 Parámetros de procedimiento RENAME_JOB

parámetro	Descripción
Nombre de Trabajo Antiguo	Nombre del trabajo existente.
Nuevo nombre de trabajo	Nombre del nuevo trabajo.
Propietario	Es el esquema en el que se crea el trabajo.

Procedimiento UPDATE_JOB

Este procedimiento actualiza cualquiera de los atributos de trabajo existentes.

Sintaxis

dbms_data_tools_job.update_job(
                       job_name        IN VARCHAR2,
                       owner           IN VARCHAR2 DEFAULT NULL,
                       description     IN VARCHAR2 DEFAULT NULL,
                       steps           IN clob DEFAULT NULL,
                       start_date      IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
                       repeat_interval IN VARCHAR2                 DEFAULT NULL,
                       end_date        IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
                       job_class       IN VARCHAR2                 DEFAULT NULL,
                       enabled         IN BOOLEAN                  DEFAULT NULL,
                       reporting       IN clob DEFAULT NULL);

Parámetros de Procedimiento UPDATE_JOB

Tabla 22-6 Parámetros de Procedimiento UPDATE_JOB

parámetro	Descripción
Nombre de trabajo	Nombre del Trabajo que se va a actualizar.
Propietario	Es el esquema en el que se va a actualizar el trabajo.
Descripción	La descripción actualizada que se aplicará.
Pasos	Los nuevos pasos a los que actualizar. Atención: Para los pasos HTTP, no coloque datos confidenciales en la URL ni en el cuerpo de la solicitud. Utilice credenciales de base de datos o credenciales con nombre para la autenticación.
Fecha de inicio	La nueva fecha de inicio.
Intervalo de Repetición	Intervalo de repetición actualizado.
Fecha de finalización	La fecha de finalización actualizada.
Clase de Trabajo	Clase de trabajo actualizada.
Activado	Podría activarse o desactivarse.
Generación de Informes	Atributo de informe actualizado. Atención: No incluya datos confidenciales en la configuración de informes.

Ejecutar Procedimiento

Este procedimiento ejecuta un trabajo inmediatamente.

Si se activa un trabajo, el programador lo ejecuta automáticamente. No es necesario llamar a RUN_JOB para ejecutar un trabajo según su programa. Utilice RUN_JOB para ejecutar un trabajo fuera de su programa normal.

Sintaxis

dbms_data_tools_job.run(
                job_name            in varchar2,
                owner               in varchar2 default null,
                use_current_session in number   default null,
                options             in clob     default null);

Ejecutar parámetros de procedimiento

Tabla 22-7 Parámetros de Procedimiento RUN

parámetro	Descripción
Nombre de trabajo	Un nombre de trabajo o una lista de entradas separada por comas, donde cada uno es el nombre de un trabajo existente, precedido opcionalmente por un nombre de esquema y un separador de puntos. Si especifica un trabajo de varios destinos, el trabajo se ejecuta en todos los destinos. En este caso, el argumento use_current_session debe ser FALSE.
Propietario	Es el esquema en el que se ejecuta el trabajo.
Usar sesión actual	Especifica si la ejecución del trabajo debe producirse o no en la misma sesión desde la que se ha llamado al procedimiento. Cuando use_current_session se define en TRUE: Puede probar un trabajo y ver los posibles errores en la línea de comandos. RUN se puede ejecutar en paralelo con una ejecución de trabajo programada regularmente. Cuando use_current_session está definido en FALSE: Debe comprobar el log de trabajos para buscar información de error. Se actualizan todos los campos relevantes de scheduler_jobs. RUN falla si se está ejecutando un trabajo programado regularmente.
Options

Procedimiento STOP_JOB

Este procedimiento para los trabajos en ejecución o todos los trabajos de una clase de trabajo.

Después de parar el trabajo, el estado de un trabajo puntual se define en STOPPED, mientras que el estado de un trabajo repetitivo se define en SCHEDULED o COMPLETED, según si se ha programado la siguiente ejecución del trabajo.

Sintaxis

dbms_data_tools_job.stop_job(
                     job_name in varchar2,
                     owner    in varchar2 default null,
                     force    in boolean  default false);

Parámetros de procedimiento STOP_JOB

Tabla 22-8 Parámetros de procedimiento STOP_JOB

parámetro	Descripción
Nombre de trabajo	Nombre del trabajo que se va a parar. Es el nombre de un trabajo existente, precedido opcionalmente por un nombre de esquema y un separador de puntos.
Propietario	Es el esquema en el que se va a parar el trabajo.
Forzado	Si force está definido en FALSE, el programador intenta parar correctamente el trabajo mediante un mecanismo de interrupción. Este método devuelve el control al proceso esclavo, que puede actualizar el estado del trabajo en la cola de trabajos a parado. Si esto falla, se devuelve un error. Si force se define en TRUE, el programador termina inmediatamente el trabajo esclavo. Oracle recomienda que STOP_JOB con forzado definido en TRUE se utilice solo después de que se haya producido un fallo en STOP_JOB con force definido en FALSE. El uso de la opción force requiere el privilegio del sistema MANAGE SCHEDULER.