quotes around the literal. The length of the what parameter is limited to 2000 bytes under Oracle 7.3 and 4000 bytes under Oracle 8.0. These limits should be more than sufficient for all practical purposes. The value of the parameter is normally a call to a stored PL/SQL program. It is best to avoid using large anonymous PL/SQL blocks, although these are legal values. Another good tip is to always wrap stored procedure invocations in an anonymous block, as some subtle difficulties are possible otherwise. Thus, instead of: what => 'my_proc(parm1);' it is safer to use: what => 'begin my_proc(parm1); end;' Whenever the what parameter is modified to change the job to execute, the user's current session settings are recorded and become part of the job's execution environment. This could alter the expected execution behavior of the job if the session settings were different from those in place when the job was originally submitted. It is important to be aware of this potential side effect and be sure that session settings are correct whenever the what parameter is used in a DBMS_JOB procedure call. See the Section 13.2" section for more discussion of the job execution environment. Jobs that reference database links will fail if the database link is not fully qualified with the username and password. This is another subtle consequence of the execution environment of jobs. The job definition specified by the what parameter can also reference the following "special" job parameter values: Parameter Mode job IN next_date IN/OUT broken IN/OUT When the job definition references these job parameters in its own parameter list, their values are assigned to the parameters in the job definition when the job executes. For example, suppose that a procedure called proc1 has the following specification: PROCEDURE proc1 (my_job_number IN INTEGER); Suppose also that we submit proc1 to be executed by the job queue as follows: DECLARE jobno INTEGER; BEGIN DBMS_JOB.SUBMIT(jobno,`proc1(my_job_number=>job);'); END; / When proc1 is executed by the queue, the my_job_number parameter is assigned the job's job number, and thus proc1 will "know" what job number it is. The ability to reference and modify job parameters from within the job itself enables the creation of self−modifying and self−aware jobs. See the Section 13.4, "DBMS_JOB Examples"" section for an example of a job that demonstrates these powerful characteristics. [Appendix A] What's on the Companion Disk? 13.1.2 Job Definition Parameters 576 13.1.2.3 The next_date parameter The next_date parameter tells the job queue when a job should be executed next. This parameter defaults to SYSDATE in both the DBMS_JOB.SUBMIT and BROKEN procedures, indicating that the job should be run immediately. Whenever 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. The next_date parameter can be set to a time in the past. Jobs are chosen for execution in order of their next execution dates, so setting a job's next_date back can effectively move the job ahead in the queue. This can be useful in systems where the job queue processes are not keeping up with jobs to be executed, and a specific job needs to be executed as soon as possible. 13.1.2.4 The interval parameter The interval parameter is a character string representing a valid Oracle date expression. This date expression is evaluated each time the job begins execution. When a job completes successfully, this date becomes the next execution date for the job. It is important to remember that interval evaluation and updating the job's next execution date happen at different times. For instance, a job that takes one hour to complete and has interval set to SYSDATE+1/48 (every 30 minutes) will constantly execute, because each time it completes, it will already be 30 minutes late to execute again. The interval expression must evaluate to either a NULL value or a time in the future. When interval evaluates to a NULL value, the job will not be re−executed after the next execution and will be automatically removed from the job queue. Thus, to execute a job one time only, pass a NULL value for the interval parameter. Jobs may have complex execution schedules, requiring complex date arithmetic expressions for the interval parameter. The interval parameter can contain a call to a PL/SQL function with a return datatype of DATE, suggesting a nice way to encapsulate complex execution schedules within simple interval parameter values. However, experimentation with using function calls for interval resulted in erratic job execution behavior. Thus, unfortunately, a useful alternative to embedding complex date arithmetic into the interval parameter does not appear to be currently available. 13.1.2.5 The broken parameter The broken parameter is a BOOLEAN flag used to indicate that the job is to be marked as broken (TRUE) or unbroken (FALSE). The job queue processes will not attempt to execute jobs marked as broken. 12.2 DBMS_SHARED_POOL: Pinning Objects 13.2 Job Queue Architecture Copyright (c) 2000 O'Reilly & Associates. All rights reserved. [Appendix A] What's on the Companion Disk? 13.1.2 Job Definition Parameters 577 Chapter 13 Job Scheduling in the Database 13.2 Job Queue Architecture The job queue is really a subsystem within an Oracle database, which uses dedicated background processes and catalog tables to execute user PL/SQL procedures automatically without user intervention. It is useful to get a good conceptual understanding of the job queue, because some of the behavior of this queue is not obvious. Figure Figure 13.1 shows a schematic of the job queue architecture. Figure 13.1: . Schematic of job queue architecture 13.2.1 INIT.ORA Parameters and Background Processes These three INIT.ORA parameters are instrumental in controlling the job queue: JOB_QUEUE_PROCESSES JOB_QUEUE_INTERVAL JOB_QUEUE_KEEP_CONNECTIONS 13.2.1.1 JOB_QUEUE_PROCESSES The job queue (or SNP[1]) background processes are started when the Oracle instance is started. There are as many SNP processes started as specified in the INIT.ORA parameter JOB_QUEUE_PROCESSES. The range of valid values is from 0 to 36, so there can be a maximum of 36 SNP processes per Oracle instance. Under most operating systems, the characters SNP will appear as part of the process name. For example, under UNIX, an Oracle instance called DEV with three job queue processes would show the following process 578 names: [1] The SNP acronym results from the fact that these special background processes were originally developed to refresh Oracle snapshots. ora_DEV_snp0 ora_DEV_snp1 ora_DEV_snp2 One significant difference between the SNP background processes and other Oracle background processes is that killing an SNP process will not crash the instance. While you're not likely to want to do this very often, this behavior is useful to know in case a job queue process "runs away" and consumes excessive resources. When an SNP process is killed or fails on its own, Oracle automatically starts a new one to replace it. 13.2.1.2 JOB_QUEUE_INTERVAL The job queue processes "wake up" periodically and check the job queue catalog to see if any jobs are due to execute. The INIT.ORA parameter JOB_QUEUE_INTERVAL controls how long the SNP processes "sleep" (in seconds) between catalog checks. Setting the interval too low can cause unnecessary overhead as SNP processes constantly check the catalog. Setting the interval too high can keep jobs from executing at the expected time if an SNP process does not awaken promptly enough. The proper balance will depend on the specific mix of jobs in a given environment. For most purposes, the default setting of 60 seconds is adequate. 13.2.1.3 JOB_QUEUE_KEEP_CONNECTIONS The third INIT.ORA parameter that supposedly affects the behavior of the SNP processes is JOB_QUEUE_KEEP_CONNECTIONS. This parameter has been made obsolete in Oracle8i. In fact, it apparently never actually had any effect under previous releases, although it has been documented as having various effects. Some sources say that it controlled the database sessions held by the SNP background processes; others say that it controlled the sessions in remote databases for jobs using database links. Although setting this parameter appears to do no harm, it is best to leave it alone. 13.2.2 Job Execution and the Job Execution Environment When an SNP process wakes up, it looks in the catalog to see if the current date exceeds the next execution date for any jobs in the queue. If a job is due to execute, the SNP process will dynamically do the following: • Become a database session with the username of the job's owner • Alter session NLS (National Language Support) settings to match those in place when the job was submitted or last modified • Calculate the next execution date by applying the interval date expression to SYSDATE • Execute the PL/SQL job definition • If execution succeeds, upate next_date for the job with the previously calculated next execution date; otherwise, increment the number of failures • [Appendix A] What's on the Companion Disk? 13.2.1 INIT.ORA Parameters and Background Processes 579 Repeat if another job is due to run or sleep for JOB_QUEUE_INTERVAL seconds In the first two steps, the SNP process creates a job execution environment that mimics that of a real user session that is executing the job definition's PL/SQL. This includes setting the following NLS settings: NLS_LANGUAGE NLS_TERRITORY NLS_CURRENCY NLS_ISO_CURRENCY NLS_NUMERIC_CHARACTERS NLS_DATE_FORMAT NLS_DATE_LANGUAGE NLS_SORT In Trusted Oracle databases, the session also sets the session label and high/low clearances. The execution environment does not exactly mimic a user session, and this has some consequences worth noting. First, any nondefault roles that were enabled when the job was submitted will not be enabled in the job execution environment. Therefore, jobs that rely on privileges obtained through nondefault roles should not be submitted, and modification of user default roles can compromise the future execution of existing jobs. Also, any database links used in the job definition itself, or the procedures executed by it, must be fully qualified with a remote username and password. The SNP process is not able to initiate a remote session without an explicit password. Apparently, it does not assume the local user's password as part of the execution environment session settings. When job execution fails, the SNP processes attempts to rerun the job one minute later. If this run fails, another attempt is made in two minutes and another in four minutes. The job queue doubles the retry interval until it exceeds the normal execution interval, which is then used. After 16 consecutive failures, the job is flagged as broken and will not be re−executed by the job queue without user intervention. 13.2.3 Miscellaneous Notes The Oracle export and import utilities preserve job numbers. Therefore, when you are importing into a database with jobs in the job queue, job number conflicts are possible. The same consideration applies when using DBMS_JOB.USER_EXPORT to transfer jobs from one database to another. The job queue is not designed to function well under Oracle Parallel Server configurations. In particular, here are two significant limitations: • Jobs cannot be specified to run in a specific Oracle instance. • The SYS.JOB$ catalog table is not partitioned by instance and will be subject to "pinging" by job queue processes from different instances. The workaround to these problems is to only run the job queue in a single instance of an OPS environment. This is done by setting JOB_QUEUE_PROCESSES to zero in all but one of the Oracle instances. 13.2.4 DBMS_JOB Interface This section describes the programs available in the DBMS_JOB package. [Appendix A] What's on the Companion Disk? 13.2.3 Miscellaneous Notes 580 . around the literal. The length of the what parameter is limited to 2000 bytes under Oracle 7.3 and 4000 bytes under Oracle 8.0. These limits should be more than sufficient for all practical purposes maximum of 36 SNP processes per Oracle instance. Under most operating systems, the characters SNP will appear as part of the process name. For example, under UNIX, an Oracle instance called DEV with. were originally developed to refresh Oracle snapshots. ora_DEV_snp0 ora_DEV_snp1 ora_DEV_snp2 One significant difference between the SNP background processes and other Oracle background processes is that