13.2.6.4 The DBMS_JOB.WHAT procedure The WHAT procedure changes the PL/SQL call that comprises the job's PL/SQL definition. Here's the header for this program: PROCEDURE DBMS_JOB.WHAT (job IN BINARY_INTEGER ,what IN VARCHAR2); Parameters are summarized in the following table. Parameter Description job Unique identifier of the job what PL/SQL code to execute as a job 13.2.6.4.1 Restrictions The WHAT 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.4.2 Example In this example, job 100 is modified to execute a procedure called my_package.proc1. When the job is run by the job queue, it will run in a session that has NLS_DATE_FORMAT set as in the ALTER SESSION command. SQL> ALTER SESSION SET NLS_DATE_FORMAT='YYYY:MM:DD:HH24:MI:SS'; SQL> execute dbms_job.what(100,'my_package.proc1;'); 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. The what parameter must be enclosed in single quotes and the PL/SQL call must be terminated with a semicolon. To embed literal strings in the PL/SQL call, use two single quotes around the literal. 13.2.7 Removing Jobs and Changing Job Execution Status The REMOVE, BROKEN, and RUN procedures let you remove jobs from the job queue and change the execution status of jobs. 13.2.7.1 The DBMS_JOB.REMOVE procedure The REMOVE procedure removes an existing job from the job queue. If the job is currently executing, it will run to normal completion, but will not be rescheduled. The header for this procedure is: PROCEDURE DBMS_JOB.REMOVE (job IN BINARY_INTEGER); where job is the unique identifier of the job. This program does not raise any package exceptions. 13.2.7.1.1 Restrictions The REMOVE 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 [Appendix A] What's on the Companion Disk? 13.2.6 Modifying Job Characteristics 586 discussed in the Section 13.3" section. 13.2.7.1.2 Example To remove job number 100 from the job queue in SQL*Plus, specify the following: SQL> execute DBMS_JOB.REMOVE(100); When REMOVE is executed for a job that is currently executing, the job is removed from the job queue, but the current execution is allowed to complete. Terminating a running job and removing it from the job queue is described in the Section 13.3" section later in this chapter. 13.2.7.2 The DBMS_JOB.BROKEN procedure The BROKEN procedure is used to set or unset the broken flag for a job. Jobs flagged as broken are not automatically re−executed. Here's the header for this program: PROCEDURE DBMS_JOB.BROKEN (job IN BINARY_INTEGER ,broken IN BOOLEAN ,next_date IN DATE DEFAULT SYSDATE); Parameters are summarized in the following table. Parameter Description job Unique identifier of the job broken Flag indicating job is broken (TRUE) or not broken (FALSE) next_date Next execution date of the job The program does not raise any package exceptions. 13.2.7.2.1 Restrictions The BROKEN 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.7.2.2 Example All jobs owned by the current user are set to broken by this PL/SQL block: BEGIN FOR job_rec IN (SELECT job FROM user_jobs) LOOP DBMS_JOB.BROKEN(job_rec.job,TRUE); END LOOP; END; / Jobs are marked as broken by passing TRUE for the broken parameter. In this case, the next execution for the job date is automatically set to January 1, 4000, regardless of the value of the next_date parameter passed. Although it looks strange, this is not a problem and is merely another safeguard preventing the job queue processes from executing broken jobs. When marking jobs as not broken by passing the value FALSE for the broken parameter, the value of next_date becomes the next execution date for the job. Since next_date has a default value of SYSDATE, [Appendix A] What's on the Companion Disk? 13.2.7 Removing Jobs and Changing Job Execution Status 587 marking a job as unbroken without specifying next_date explicitly indicates that the job should execute immediately. Be careful to pass an explicit value for next_date if immediate execution is not the desired behavior. Note also that DBMS_JOB.BROKEN (job,FALSE) will always modify the next execution date of the job, regardless of whether it was marked broken. 13.2.7.3 The DBMS_JOB.RUN procedure The RUN procedure immediately executes the job in the current session. The header for this program follows: PROCEDURE DBMS_JOB.RUN (job IN BINARY_INTEGER); The job parameter is the unique identifier for the job. The program does not raise any package exceptions. 13.2.7.3.1 Restrictions The RUN 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.7.3.2 Example To run job number 100 immediately in the current session, specify the following: SQL> execute DBMS_JOB.RUN(100); The RUN procedure performs an implicit COMMIT in the current session. It runs the job with the current session's settings and privileges as the execution environment. Be aware that these could be different from the execution environment settings specified for the job and used by the job queue when it runs the job. This could cause unexpected results, so it is best to execute RUN from a session with the same environment as the job. Also, issuing the RUN procedure computes the next execution date for the job using the current SYSDATE as the seed value. This could throw off the execution schedule of some jobs, depending on how the interval is defined. See Section 13.3" for a discussion of job intervals and date arithmetic. 13.2.8 Transferring Jobs The USER_EXPORT procedure lets you export jobs in the job queue to a file for re−creation or transfer to another database. 13.2.8.1 The DBMS_JOB.USER_EXPORT procedure The USER_EXPORT procedure produces a character string that can be used to re−create an existing job in the job queue. The string contains a call to the ISUBMIT procedure for the job, which specifies the current values for the job definition parameters. Here's the header for the program: PROCEDURE DBMS_JOB.USER_EXPORT (job IN BINARY_INTEGER ,mycall IN OUT VARCHAR2); Parameters are summarized in the following table. Parameter Description job Unique identifier of the job [Appendix A] What's on the Companion Disk? 13.2.7 Removing Jobs and Changing Job Execution Status 588 mycall String containing call to the ISUBMIT procedure to re−create job The program does not raise any package exceptions. 13.2.8.1.1 Example. This SQL*Plus script shows that current settings for the job definition parameters are placed into the mycall parameter of USER_EXPORT: /* Filename on companion disk: job1.sql */* set array 1 var job number var jobstring VARCHAR2(2000) col jobstring format a50 word_wrap col what format a25 word_wrap col interval format a20 ALTER SESSION SET NLS_DATE_FORMAT='YYYY:MM:DD:HH24:MI:SS'; BEGIN /* submit no−op job to execute every 30 seconds */ DBMS_JOB.SUBMIT(:job,'begin null;end;',SYSDATE,'SYSDATE+1/2880'); /* commit to make sure the submit "takes" */ COMMIT; /* sleep for two minutes to let job execute a few times */ DBMS_LOCK.SLEEP(120); END; / SELECT job,what,next_date,interval FROM dba_jobs WHERE job = :job; BEGIN /* export the job */ DBMS_JOB.USER_EXPORT(:job,:jobstring); END; / print jobstring The following output was generated by the script. Notice that the current value of NEXT_DATE (as shown by querying DBA_JOBS) is extracted and placed into the string value returned in the mycall parameter as the value for next_date in the call to ISUBMIT. Session altered. PL/SQL procedure successfully completed. JOB WHAT NEXT_DATE INTERVAL −−−−−− −−−−−−−−−−−−−−−−−−−−−−−−− −−−−−−−−−−−−−−−−−−− −−−−−−−−−−−−−− 175 begin null;end; 1997:11:16:16:22:59 SYSDATE+1/2880 PL/SQL procedure successfully completed. JOBSTRING −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−− dbms_job.isubmit(job=>175,what=>'begin null;end;',next_date=>to_date('1997−11−16:16:22:59 [Appendix A] What's on the Companion Disk? 13.2.8 Transferring Jobs 589 ','YYYY−MM−DD:HH24:MI:SS'),interval=>'SYSDATE+1/28 80',no_parse=>TRUE); 13.1 Getting Started with DBMS_ JOB 13.3 Tips on Using DBMS_JOB Copyright (c) 2000 O'Reilly & Associates. All rights reserved. [Appendix A] What's on the Companion Disk? 13.2.8 Transferring Jobs 590