19
DBMS_JOB

DBMS_JOB subprograms schedule and manage jobs in the job queue.

For more information on the DBMS_JOB package and the job queue, see Oracle9i Database Administrator's Guide.

This chapter discusses the following topics:

Requirements

There are no database privileges associated with jobs. DBMS_JOB does not allow a user to touch any jobs except their own.

Using the DBMS_JOB Package with Oracle Real Application Clusters

For this example, a constant in DBMS_JOB indicates "no mapping" among jobs and instances, that is, jobs can be executed by any instance.

DBMS_JOB.SUBMIT

To submit a job to the job queue, use the following syntax:

   DBMS_JOB.SUBMIT( JOB OUT BINARY_INTEGER,
   WHAT IN VARCHAR2, NEXT_DATE IN DATE DEFAULTSYSDATE, 
   INTERVAL IN VARCHAR2 DEFAULT 'NULL',
   NO_PARSE IN BOOLEAN DEFAULT FALSE,
   INSTANCE IN BINARY_INTEGER DEFAULT ANY_INSTANCE,
   FORCE IN BOOLEAN DEFAULT FALSE)

Use the parameters INSTANCE and FORCE to control job and instance affinity. The default value of INSTANCE is 0 (zero) to indicate that any instance can execute the job. To run the job on a certain instance, specify the INSTANCE value. Oracle displays error ORA-23319 if the INSTANCE value is a negative number or NULL.

The FORCE parameter defaults to FALSE. If force is TRUE, any positive integer is acceptable as the job instance. If FORCE is FALSE, the specified instance must be running, or Oracle displays error number ORA-23428.

DBMS_JOB.INSTANCE

To assign a particular instance to execute a job, use the following syntax:

   DBMS_JOB.INSTANCE(  JOB IN BINARY_INTEGER,
   INSTANCE IN BINARY_INTEGER, 
   FORCE IN BOOLEAN DEFAULT FALSE)

The FORCE parameter in this example defaults to FALSE. If the instance value is 0 (zero), job affinity is altered and any available instance can execute the job despite the value of force. If the INSTANCE value is positive and the FORCE parameter is FALSE, job affinity is altered only if the specified instance is running, or Oracle displays error ORA-23428.

If the FORCE parameter is TRUE, any positive integer is acceptable as the job instance and the job affinity is altered. Oracle displays error ORA-23319 if the INSTANCE value is negative or NULL.

DBMS_JOB.CHANGE

To alter user-definable parameters associated with a job, use the following syntax:

   DBMS_JOB.CHANGE(  JOB IN BINARY_INTEGER,
   WHAT IN VARCHAR2 DEFAULT NULL,
   NEXT_DATE IN DATE DEFAULT NULL,
   INTERVAL IN VARCHAR2 DEFAULT NULL,
   INSTANCE IN BINARY_INTEGER DEFAULT NULL,
    FORCE IN BOOLEAN DEFAULT FALSE )

Two parameters, INSTANCE and FORCE, appear in this example. The default value of INSTANCE is NULL indicating that job affinity will not change.

The default value of FORCE is FALSE. Oracle displays error ORA-23428 if the specified instance is not running and error ORA-23319 if the INSTANCE number is negative.

DBMS_JOB.RUN

The FORCE parameter for DBMS_JOB.RUN defaults to FALSE. If force is TRUE, instance affinity is irrelevant for running jobs in the foreground process. If force is FALSE, the job can run in the foreground only in the specified instance. Oracle displays error ORA-23428 if force is FALSE and the connected instance is the incorrect instance.

   DBMS_JOB.RUN( JOB IN BINARY_INTEGER,
   FORCE IN BOOLEAN DEFAULT FALSE)

Summary of DBMS_JOB Subprograms

Table 19-1 DBMS_JOB Package Subprograms

Subprogram	Description
"SUBMIT Procedure"	Submits a new job to the job queue.
"REMOVE Procedure"	Removes specified job from the job queue.
"CHANGE Procedure"	Alters any of the user-definable parameters associated with a job.
"WHAT Procedure"	Alters the job description for a specified job.
"NEXT_DATE Procedure"	Alters the next execution time for a specified job.
"INSTANCE Procedure"	Assigns a job to be run by a instance.
"INTERVAL Procedure"	Alters the interval between executions for a specified job.
"BROKEN Procedure"	Disables job execution.
"RUN Procedure"	Forces a specified job to run.
"USER_EXPORT Procedure"	Recreates a given job for export.
"USER_EXPORT Procedure"	Recreates a given job for export with instance affinity.

19 DBMS_JOB