13.2.5 Submitting Jobs to the Job Queue Use the SUBMIT and ISUBMIT procedures to submit jobs to the job queue. 13.2.5.1 The DBMS_JOB.SUBMIT procedure The SUBMIT procedure submits a new job to the job queue. The job number is obtained from the sequence SYS.JOBSEQ and returned as an OUT parameter. Here's the header for this program: PROCEDURE 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); Parameters are summarized in the following table. Parameter Description job Unique identifier of the job what PL/SQL code to execute as a job next_date Next execution date of the job interval Date expression to compute next execution date of job no_parse Flag indicating whether to parse job PL/SQL at time of submission (FALSE) or execution (TRUE) 13.2.5.1.1 Exceptions. The program does not raise any package exceptions. The interval date expression must evaluate to a future date or the following Oracle exception will be raised: ORA−23420 Interval must evaluate to a time in the future. 13.2.5.1.2 Example. This SQL*Plus script submits a job that uses DBMS_DDL.ANALYZE_OBJECT to analyze a particular table every day at midnight: var jobno NUMBER BEGIN DBMS_JOB.SUBMIT (job => :jobno ,what => 'DBMS_DDL.ANALYZE_OBJECT(''TABLE'',''LOAD1'',''TENK'', ''ESTIMATE'',null,estimate_percent=>50);' ,next_date => TRUNC(SYSDATE+1) ,interval => 'TRUNC(SYSDATE+1)' ); END; / print jobno The what parameter must be enclosed in single quotes and the PL/SQL call terminated with a semicolon. To embed literal strings in the PL/SQL call, use two single quotes around the literal. [Appendix A] What's on the Companion Disk? 13.2.5 Submitting Jobs to the Job Queue 581 The no_parse parameter controls when the job's PL/SQL definition is actually parsed. The default value of FALSE specifies that the PL/SQL is parsed immediately when the job is submitted. Alternatively, if you specify TRUE, parsing can be deferred until the first execution of the job. This allows jobs to be submitted into the queue for future execution where objects necessary for execution (tables, packages, etc.) are not in place at the time of submission. TIP: On some platforms and versions of Oracle, a COMMIT is required for the job to be picked up by the job queue for execution. If submitted jobs do not seem to be executing at all, this may be the cause. The workaround for this problem is to always COMMIT immediately after calling SUBMIT. To execute a job one time only, pass a NULL value for the interval parameter. 13.2.5.2 The DBMS_JOB.ISUBMIT procedure The ISUBMIT procedure submits a new job to the job queue with the specified job number. Here's the header for this program: PROCEDURE DBMS_JOB.ISUBMIT (job IN BINARY_INTEGER ,what IN VARCHAR2 ,next_date IN VARCHAR2 ,interval IN VARCHAR2 DEFAULT 'null' ,no_parse IN BOOLEAN DEFAULT FALSE); Parameters are summarized in the following table. Parameter Description job Unique identifier of the job what PL/SQL code to execute as a job next_date Next execution date of the job interval Date expression to compute next execution date of job no_parse Flag indicating whether to parse job PL/SQL at time of submission (FALSE) or execution (TRUE) 13.2.5.2.1 Exceptions The program does not raise any packaged exceptions. The interval date expression must evaluate to a future date or the following Oracle exception will be raised: ORA−23420 Interval must evaluate to a time in the future. The catalog table that records job queue entries is protected by a unique constraint on the job number. Therefore, using the ISUBMIT procedure to submit a job number that already exists results in the following error: ORA−00001 Unique constraint (SYS.I_JOB_JOB) violated. 13.2.5.2.2 Example The following example submits three jobs to the job queue, numbered 1, 2, and 3. Job 1 passes a string and number into procedure my_job1, runs it in one hour, and executes it every day thereafter. Job 2 passes a date [Appendix A] What's on the Companion Disk? 13.2.5 Submitting Jobs to the Job Queue 582 into procedure my_job2, executes for the first time tomorrow, and execute it every 10 minutes thereafter. Job 3 is a PL/SQL block that does nothing, executes immediately, and will be removed from the queue automatically. BEGIN DBMS_JOB.ISUBMIT (job => 1 ,what => 'my_job1(''string_parm_value'',120);' ,next_date => SYSDATE + 1/24 ,interval => 'SYSDATE +1'); DBMS_JOB.ISUBMIT (2, 'my_job2(date_IN=>SYSDATE);' ,SYSDATE+1,'SYSDATE+10/1440'); DBMS_JOB.ISUBMIT(3,'BEGIN null; END;',SYSDATE,null); END; The ISUBMIT procedure allows the calling user or application to decide the job identification number. Collisions in job numbers will result in the unique constraint violation noted earlier. Therefore, it is probably better not to embed fixed job numbers into applications (as this will increase the chances for collisions) and to use SUBMIT instead of ISUBMIT. If specific job numbering is required, then you can minimize job number collisions by pushing the SYS.JOBSEQ sequence out to a number greater than those used in calls to ISUBMIT. This can be accomplished by consuming sequence numbers as follows: SELECT SYS.JOBSEQ.NEXTVAL FROM dictionary WHERE rownum < 101; After issuing the previous command, DBMS_JOB.SUBMIT will always return job numbers higher than 100. Note that in this command, the dictionary view is not special, but is used because it is publicly accessible and contains more than 100 rows. You can substitute any table or view accessible to the user. WARNING: When you are using the ISUBMIT procedure, a subtle problem can arise from the fact that next_date has datatype VARCHAR2 instead of DATE (as in SUBMIT). When DATE values are assigned to next_date in calls to ISUBMIT, an implicit conversion to VARCHAR2 is done using the session's current NLS_DATE_FORMAT as the date mask. This can result in unexpected truncation of next_date. For instance, if the session NLS_DATE_FORMAT is `YY−MM−DD', dates assigned to next_date will be truncated to 12:00 a.m. To avoid this problem, either make sure that the session NLS_DATE_FORMAT includes all date components or supply next_date as a fully specified VARCHAR2. 13.2.6 Modifying Job Characteristics This section describes the procedures you use to modify job characteristics: CHANGE, INTERVAL, NEXT_DATE, and WHAT. 13.2.6.1 The DBMS_JOB.CHANGE procedure The CHANGE procedure alters one or more of the user−definable parameters of a job. When a null value is passed for any of these parameters (what, next_date, or interval) the current setting is not modified. Here's the header for this program: PROCEDURE DBMS_JOB.CHANGE (job IN BINARY_INTEGER ,what IN VARCHAR2 ,next_date IN DATE ,interval IN VARCHAR2); [Appendix A] What's on the Companion Disk? 13.2.6 Modifying Job Characteristics 583 Parameters are summarized in the following table. Parameter Description job Unique identifier of the job what PL/SQL code to execute as a job next_date Next execution date of the job interval Date expression to compute next execution date of job 13.2.6.1.1 Exceptions The program does not raise any packaged exceptions. The interval date function must evaluate to a future date or the following Oracle exception will be raised: ORA−23420 Interval must evaluate to a time in the future. 13.2.6.1.2 Restrictions The CHANGE procedure can be executed only for jobs owned by the username to which the session is connected. These jobs are visible in the dictionary view USER_JOBS. The USER_JOBS dictionary view is discussed in the Section 13.3, "Tips on Using DBMS_JOB"" section. 13.2.6.1.3 Example The execution schedule of job 100 can be changed to next execute tomorrow at 6:00 a.m. and every two hours after that, as follows: BEGIN DBMS_JOB.CHANGE(100,null,TRUNC(SYSDATE+1)+6/24,'SYSDATE+2/24'); END; / When the what parameter is changed to modify the actual job to execute, the user's current session NLS settings are also recorded and become part of the job's execution environment. 13.2.6.2 The DBMS_JOB.INTERVAL procedure The INTERVAL procedure changes the date expression, which is used to determine the next execution date of a job. Here's the header for this program: PROCEDURE DBMS_JOB.INTERVAL (job IN BINARY_INTEGER ,interval IN VARCHAR2); Parameters are summarized in the following table. Parameter Description job Unique identifier of the job interval Date expression to compute next execution date of job 13.2.6.2.1 Exceptions The program does not raise any package exceptions. The interval date expression must evaluate to a future date or the following Oracle exception will be raised: [Appendix A] What's on the Companion Disk? 13.2.6 Modifying Job Characteristics 584 ORA−23420 Interval must evaluate to a time in the future. 13.2.6.2.2 Restrictions The INTERVAL procedure can be executed only for jobs owned by the username to which the session is connected. These jobs are visible in the dictionary view USER_JOBS. The USER_JOBS dictionary view is discussed in the Section 13.3" section. 13.2.6.2.3 Example The following SQL*Plus command will modify job 100 to execute every day at 6:00 a.m.: SQL> execute DBMS_JOB.INTERVAL(100, 'TRUNC(SYSDATE+1)+6/24'); The date expression must be specified as a string literal or a VARCHAR2 variable containing a string literal. Literals that evaluate to PL/SQL functions are accepted by DBMS_JOB, but have been observed to cause erratic job execution behavior. A job can be removed automatically from the job queue after its next execution by passing NULL for the interval parameter. 13.2.6.3 The DBMS_JOB.NEXT_DATE procedure The NEXT_DATE procedure changes the job's next scheduled date of execution. Here's the header for this program: PROCEDURE DBMS_JOB.NEXT_DATE (job IN BINARY_INTEGER ,next_date IN DATE); Parameters are summarized in the following table. Parameter Description job Unique identifier of the job next_date Next execution date of the job The program does not raise any named exceptions. 13.2.6.3.1 Restrictions The NEXT_DATE procedure can be executed only for jobs owned by the username to which the session is connected. These jobs are visible in the dictionary view USER_JOBS. The USER_JOBS dictionary view is discussed in the Section 13.3" section. 13.2.6.3.2 Example This example shows a SQL*Plus example of how to schedule the next execution of job 100 for next Monday: SQL> execute DBMS_JOB.NEXT_DATE(100, NEXT_DAY(SYSDATE,'MONDAY')); When a NULL value is passed for the next_date parameter, the next execution date for the job is set to January 1, 4000. This effectively keeps the job from being executed without removing it from the job queue. [Appendix A] What's on the Companion Disk? 13.2.6 Modifying Job Characteristics 585 . package exceptions. The interval date expression must evaluate to a future date or the following Oracle exception will be raised: ORA−23420 Interval must evaluate to a time in the future. 13.2.5.1.2. packages, etc.) are not in place at the time of submission. TIP: On some platforms and versions of Oracle, a COMMIT is required for the job to be picked up by the job queue for execution. If submitted. packaged exceptions. The interval date expression must evaluate to a future date or the following Oracle exception will be raised: ORA−23420 Interval must evaluate to a time in the future. The catalog