Oracle8i Supplied Packages Reference
Release 8.1.5
A68001-01

Library
Product
Contents
Index

Prev Next

16
DBMS_JOB

DBMS_JOB subprograms schedule and manage jobs in the job queue.

See Also:

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

Requirements

There are no database privileges associated with jobs. The right to execute DBMS_JOB or takes the place. DBMS_JOB does not allow a user to touch any jobs except their own.

Summary of Subprograms

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

SUBMIT procedure

This procedure submits a new job. It chooses 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 16-2 SUBMIT Procedure Parameters
Parameter  Description  
job
 

Number of the job being run.  

 
what
 

PL/SQL procedure to run.  

 
next_date
 

Next date when the job will be run.  

 
interval
 

Date function that calculates the next time to run the job. The default is NULL. This must evaluate to a either a future point in time or NULL.  

 
no_parse
 

A flag. The default is FALSE. If this is set to FALSE, then Oracle parses the procedure associated with the job. If this is set to TRUE, then Oracle parses the procedure associated with the job the first time that the job is run.

For example, if you want to submit a job before you have created the tables associated with the job, then set this to TRUE.  

 
instance
 

When a job is submitted, specifies which instance can run the job.  

 
force
 

If this is TRUE, then any positive integer is acceptable as the job instance. If this is FALSE (the default), then the specified instance must be running; otherwise the routine raises an exception.  

Usage Notes

The parameters instance and force 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

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 16-3 REMOVE Procedure Parameters
Parameter  Description  
job
 

Number of the job being run.  

Example

EXECUTE DBMS_JOB.REMOVE(14144);

CHANGE procedure

This procedure changes any of the user-settable fields 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 16-4 CHANGE Procedure Parameters
Parameter  Description  
job
 

Number of the job being run.  

 
what
 

PL/SQL procedure to run.  

 
next_date
 

Date of the next refresh.  

 
interval
 

Date function; evaluated immediately before the job starts running.  

 
instance
 

When a job is submitted, specifies which instance can run the job. This defaults to NULL, which indicates that instance affinity is not changed.  

 
force
 

If this is FALSE, then the specified instance (to which the instance number change) must be running. Otherwise, the routine raises an exception.

If this is TRUE, then any positive integer is acceptable as the job instance.  

Usage Notes

The parameters instance and force 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, or interval are NULL, then leave that value as it is.

Example

EXECUTE DBMS_JOB.CHANGE(14144, null, null, 'sysdate+3');

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 16-5 WHAT Procedure Parameters
Parameter  Description  
job
 

Number of the job being run.  

 
what
 

PL/SQL procedure to run.  

Some legal values of what (assuming the routines exist) are:

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 16-6 NEXT_DATE Procedure Parameters
Parameter  Description  
job
 

Number of the job being run.  

 
next_date
 

Date of the next refresh: it is when the job will be automatically run, assuming there are background processes attempting to run it.  

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 16-7 INSTANCE Procedure Parameters
Parameter  Description  
job
 

Number of the job being run.  

 
instance
 

When a job is submitted, a user can specify which instance can run the job.  

 
force
 

If this is TRUE, then any positive integer is acceptable as the job instance. If this is FALSE (the default), then the specified instance must be running; otherwise the routine raises an exception.  

INTERVAL procedure

This procedure changes how often a job runs.

Syntax

DBMS_JOB.INTERVAL ( 
   job       IN  BINARY_INTEGER,
   interval  IN  VARCHAR2);

Parameters

Table 16-8 INTERVAL Procedure Parameters
Parameter  Description  
job
 

Number of the job being run.  

 
interval
 

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 select interval into next_date from dual;

The interval parameter must evaluate to a time in the future. Legal intervals include:

'sysdate + 7'  

Run once a week.  

'next_day(sysdate,''TUESDAY'')'  

Run once every Tuesday.  

'null'  

Run only once.  

If interval evaluates to NULL and if a job completes successfully, then the job is automatically deleted from the queue.

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 16-9 Broken Procedure Parameters
Parameter  Description  
job
 

Number of the job being run.  

 
broken
 

Job broken: IN value is FALSE.  

 
next_data
 

Date of the next refresh.  

RUN procedure

This procedure runs job JOB now. It runs it even if it is broken.

Running the job recomputes next_date. See view user_jobs.

Syntax

DBMS_JOB.RUN ( 
   job       IN  BINARY_INTEGER,
   force     IN  BOOLEAN DEFAULT FALSE);

Parameters

Table 16-10 Run Procedure Parameters
Parameter  Description  
job
 

Number of the job being run.  

 
force
 

If this is TRUE, then instance affinity is irrelevant for running jobs in the foreground process. If this is FALSE, then the job can be run in the foreground only in the specified instance.  

Example

EXECUTE DBMS_JOB.RUN(14144);

Caution:

This reinitializes the current session's packages.  

Exceptions

An exception is raised if force is FALSE, and if the connected instance is the wrong one.

USER_EXPORT procedure

This procedure produces the text of a call to recreate the given job.

Syntax

DBMS_JOB.USER_EXPORT ( 
   job    IN     BINARY_INTEGER,
   mycall IN OUT VARCHAR2);

Parameters

Table 16-11 USER_EXPORT Procedure Parameter
Parameter  Description  
job
 

Number of the job being run.  

 
mycall
 

Text of a call to recreate the given job.  

USER_EXPORT procedure

This procedure alters instance affinity (8i and above) and preserves the compatibility.

Syntax

DBMS_JOB.USER_EXPORT ( 
   job      IN     BINARY_INTEGER,
   mycall   IN OUT VARCHAR2,
   myinst   IN OUT VARCHAR2);

Parameters

Table 16-12 USER_EXPORT Procedure Parameters
Parameter  Description  
job
 

Number of the job being run.  

 
mycall
 

Text of a call to recreate a given job.  

 
myinst
 

Text of a call to alter instance affinity.  


Prev
Next
Oracle
Copyright © 1999 Oracle Corporation.
All Rights Reserved.

Library
Product
Contents
Index