89 DBMS_JOB
The DBMS_JOB
package schedules and manages jobs in the job queue.
Note:
The DBMS_JOB
package has been superseded by the DBMS_SCHEDULER
package, and support for DBMS_JOB
might be removed in future releases of Oracle Database. In particular, if you are administering jobs to manage system load, you are encouraged to disable DBMS_JOB
by revoking the package execution privilege for users.
For more information, see DBMS_SCHEDULER and "Moving from DBMS_JOB
to DBMS_SCHEDULER
" in the Oracle Database Administrator's Guide.
This chapter contains the following topics:
89.1 DBMS_JOB Security Model
No specific system privileges are required to use DBMS_JOB
. No system privileges are available to manage DBMS_JOB
. Jobs cannot be altered or deleted other than jobs owned by the user. This is true for all users including those users granted DBA privileges.
You can execute procedures that are owned by the user or for which the user is explicitly granted EXECUTE
. However, procedures for which the user is granted the execute privilege through roles cannot be executed.
Note that, once a job is started and running, there is no easy way to stop the job.
89.2 DBMS_JOB Operational Notes
These notes describe stopping a job, and working with Oracle Real Application Clusters.
Stopping a Job
Note that, once a job is started and running, there is no easy way to stop the job.
Working with Oracle Real Application Clusters
DBMS_JOB
supports multi-instance execution of jobs. By default jobs can be executed on any instance, but only one single instance will execute the job. In addition, you can force instance binding by binding the job to a particular instance. You implement instance binding by specifying an instance number to the instance affinity parameter. Note, however, that in Oracle Database 10g Release 1 (10.1) instance binding is not recommended. Service affinity is preferred. This concept is implemented in the DBMS_SCHEDULER package.
The following procedures can be used to create, alter or run jobs with instance affinity. Note that not specifying affinity means any instance can run the job.
-
DBMS_JOB.SUBMIT
-
DBMS_JOB.INSTANCE
-
DBMS_JOB.CHANGE
-
DBMS_JOB.RUN
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 DEFAULT SYSDATE, 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);
89.3 Summary of DBMS_JOB Subprograms
This table lists the DBMS_JOB
subprograms and briefly describes them.
Table 89-1 DBMS_JOB Package Subprograms
Subprogram | Description |
---|---|
Disables job execution |
|
Alters any of the user-definable parameters associated with a job |
|
Assigns a job to be run by a instance |
|
Alters the interval between executions for a specified job |
|
Alters the next execution time for a specified job |
|
Removes specified job from the job queue |
|
Forces a specified job to run |
|
Submits a new job to the job queue |
|
Re-creates a given job for export, or re-creates a given job for export with instance affinity |
|
Alters the job description for a specified job |
89.3.1 BROKEN Procedure
This procedure sets the broken flag. Broken jobs are never run.
Syntax
DBMS_JOB.BROKEN ( job IN BINARY_INTEGER, broken IN BOOLEAN, next_date IN DATE DEFAULT SYSDATE);
Parameters
Table 89-2 BROKEN Procedure Parameters
Parameter | Description |
---|---|
|
System-assigned ID of the job being run. To find this ID, query the |
|
Sets the job as broken or not broken. |
|
Next date when the job will be run. |
Note:
If you set job as broken while it is running, Oracle resets the job's status to normal after the job completes. Therefore, only execute this procedure for jobs that are not running.
Usage Notes
-
Your job will not be available for processing by the job queue in the background until it is committed.
-
If a job fails 16 times in a row, Oracle automatically sets it as broken and then stops trying to run it.
89.3.2 CHANGE Procedure
This procedure changes any of the fields a user can set in a job.
Syntax
DBMS_JOB.CHANGE ( job IN BINARY_INTEGER, what IN VARCHAR2, next_date IN DATE, interval IN VARCHAR2, instance IN BINARY_INTEGER DEFAULT NULL, force IN BOOLEAN DEFAULT FALSE);
Parameters
Table 89-3 CHANGE Procedure Parameters
Parameter | Description |
---|---|
|
System-assigned ID of the job being run. To find this ID, query the |
|
PL/SQL procedure to run. |
|
Next date when the job will be run. |
|
Date function; evaluated immediately before the job starts running. |
|
When a job is submitted, specifies which instance can run the job. This defaults to |
|
If this is If this is |
Usage Notes
-
Your job will not be available for processing by the job queue in the background until it is committed.
-
The parameters
instance
andforce
are added for job queue affinity. Job queue affinity gives users the ability to indicate whether a particular instance or any instance can run a submitted job. -
If the parameters
what
,next_date
, orinterval
areNULL
, then leave that value as it is.
Example
BEGIN DBMS_JOB.CHANGE(14144, null, null, 'sysdate+3'); COMMIT; END;
89.3.3 INSTANCE Procedure
This procedure changes job instance affinity.
Syntax
DBMS_JOB.INSTANCE ( job IN BINARY_INTEGER, instance IN BINARY_INTEGER, force IN BOOLEAN DEFAULT FALSE);
Parameters
Table 89-4 INSTANCE Procedure Parameters
Parameter | Description |
---|---|
|
System-assigned ID of the job being run. To find this ID, query the |
|
When a job is submitted, a user can specify which instance can run the job. |
|
If this is |
Usage Notes
Your job will not be available for processing by the job queue in the background until it is committed.
89.3.4 INTERVAL Procedure
This procedure changes how often a job runs.
Syntax
DBMS_JOB.INTERVAL ( job IN BINARY_INTEGER, interval IN VARCHAR2);
Parameters
Table 89-5 INTERVAL Procedure Parameters
Parameter | Description |
---|---|
|
System-assigned ID of the job being run. To find this ID, query the |
|
Date function, evaluated immediately before the job starts running. |
Usage Notes
-
If the job completes successfully, then this new date is placed in
next_date
.interval
is evaluated by plugging it into the statement selectinterval
intonext_date
from dual; -
The
interval
parameter must evaluate to a time in the future. Legal intervals include:Interval Description 'sysdate + 7'
Run once a week.
'next_day(sysdate,''TUESDAY'')'
Run once every Tuesday.
'null'
Run only once.
-
If
interval
evaluates toNULL
and if a job completes successfully, then the job is automatically deleted from the queue. -
Your job will not be available for processing by the job queue in the background until it is committed.
89.3.5 NEXT_DATE Procedure
This procedure changes when an existing job next runs.
Syntax
DBMS_JOB.NEXT_DATE ( job IN BINARY_INTEGER, next_date IN DATE);
Parameters
Table 89-6 NEXT_DATE Procedure Parameters
Parameter | Description |
---|---|
|
System-assigned ID of the job being run. To find this ID, query the |
|
Date of the next refresh: it is when the job will be automatically run, assuming there are background processes attempting to run it. |
Usage Notes
Your job will not be available for processing by the job queue in the background until it is committed.
89.3.6 REMOVE Procedure
This procedure removes an existing job from the job queue. This currently does not stop a running job.
Syntax
DBMS_JOB.REMOVE ( job IN BINARY_INTEGER );
Parameters
Table 89-7 REMOVE Procedure Parameters
Parameter | Description |
---|---|
|
System-assigned ID of the job being run. To find this ID, query the |
Usage Notes
Your job will not be available for processing by the job queue in the background until it is committed.
Example
BEGIN DBMS_JOB.REMOVE(14144); COMMIT; END;
89.3.7 RUN Procedure
This procedure runs job JOB
now. It runs it even if it is broken.
Running the job recomputes next_date
. See data dictionary view USER_JOBS
or DBA_JOBS
.
Syntax
DBMS_JOB.RUN ( job IN BINARY_INTEGER, force IN BOOLEAN DEFAULT FALSE);
Parameters
Table 89-8 RUN Procedure Parameters
Parameter | Description |
---|---|
|
System-assigned ID of the job being run. To find this ID, query the |
|
If this is |
Example
EXECUTE DBMS_JOB.RUN(14144);
WARNING:
This re-initializes the current session's packages.
Exceptions
An exception is raised if force
is FALSE
, and if the connected instance is the wrong one.
89.3.8 SUBMIT Procedure
This procedure submits a new job. It chooses the job from the sequence sys
.jobseq
.
Syntax
DBMS_JOB.SUBMIT ( job OUT BINARY_INTEGER, what IN VARCHAR2, next_date IN DATE DEFAULT SYSDATE, interval IN VARCHAR2 DEFAULT 'null', no_parse IN BOOLEAN DEFAULT FALSE, instance IN BINARY_INTEGER DEFAULT any_instance, force IN BOOLEAN DEFAULT FALSE);
Parameters
Table 89-9 SUBMIT Procedure Parameters
Parameter | Description |
---|---|
|
System-assigned ID of the job being run. To find this ID, query the |
|
PL/SQL text o the job to be run. This must be a valid PL/SQL statement or block of code. For example, to run a stored procedure DECLARE job BINARY_INTEGER := :job; next_date DATE := :mydate; broken BOOLEAN := FALSE; BEGIN WHAT :mydate := next_date; IF broken THEN :b := 1; ELSE :b := 0; END IF; END; Ensure that you include the |
|
Next date when the job will be run. |
|
Date function that calculates the next time to run the job. The default is |
|
A flag. The default is For example, if you want to submit a job before you have created the tables associated with the job, then set this to |
|
When a job is submitted, specifies which instance can run the job. |
|
If this is |
Usage Notes
-
Your job will not be available for processing by the job queue in the background until it is committed.
-
The parameters
instance
andforce
are added for job queue affinity. Job queue affinity gives users the ability to indicate whether a particular instance or any instance can run a submitted job.
Example
This submits a new job to the job queue. The job calls the procedure DBMS_DDL
.ANALYZE_OBJECT
to generate optimizer statistics for the table DQUON
.ACCOUNTS
. The statistics are based on a sample of half the rows of the ACCOUNTS
table. The job is run every 24 hours:
VARIABLE jobno number; BEGIN DBMS_JOB.SUBMIT(:jobno, 'dbms_ddl.analyze_object(''TABLE'', ''DQUON'', ''ACCOUNTS'', ''ESTIMATE'', NULL, 50);' SYSDATE, 'SYSDATE + 1'); COMMIT; END; / Statement processed. print jobno JOBNO ---------- 14144
89.3.9 USER_EXPORT Procedures
There are two overloaded procedures. The first produces the text of a call to re-create the given job. The second alters instance affinity (8i and after) and preserves the compatibility.
Syntax
DBMS_JOB.USER_EXPORT ( job IN BINARY_INTEGER, mycall IN OUT VARCHAR2); DBMS_JOB.USER_EXPORT ( job IN BINARY_INTEGER, mycall IN OUT VARCHAR2, myinst IN OUT VARCHAR2);
Parameters
Table 89-10 USER_EXPORT Procedure Parameter
Parameter | Description |
---|---|
|
System-assigned ID of the job being run. To find this ID, query the |
|
Text of a call to re-create the given job. |
|
Text of a call to alter instance affinity. |
89.3.10 WHAT Procedure
This procedure changes what an existing job does, and replaces its environment.
Syntax
DBMS_JOB.WHAT ( job IN BINARY_INTEGER, what IN VARCHAR2);
Parameters
Table 89-11 WHAT Procedure Parameters
Parameter | Description |
---|---|
|
System-assigned ID of the job being run. To find this ID, query the |
|
PL/SQL procedure to run. |
Usage Notes
-
Your job will not be available for processing by the job queue in the background until it is committed.
-
Some legal values of
what
(assuming the routines exist) are:-
'myproc(''10-JAN-82'', next_date, broken);'
-
'scott.emppackage.give_raise(''JENKINS'', 30000.00);'
-
'dbms_job.remove(job);'
-