Oracle Built−in Packages- P118 doc

Thus, instead of: what => 'my_procparm1;' it is safer to use: what => 'begin my_procparm1; end;' Whenever the what parameter is modified to change the job to execute, the user's current

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

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

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

[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?

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