572  Chapter 12  n  Using the Scheduler to Automate Tasks

To remove the end date from a schedule, the SET_ATTRIBUTE_NULL procedure can be used to set the attribute to NULL, as shown here:

4attribute => ‘END_DATE’);

PL/SQL procedure successfully completed.

Using Scheduler Jobs

A Scheduler job defines a specific program to be executed, the arguments (or parameters) to be passed to the program, and the schedule defining when the program should be executed. It also specifies other characteristics, such as logging options, job priority, and so on.

Many of these characteristics are explicitly set at job-creation time through the CREATE_ JOB procedure. However, others are inherited from the job class to which the job is assigned. If a job is not explicitly assigned to a job class, these characteristics will be inherited from a job class named DEFAULT_JOB_CLASS.

In the following sections, you will learn how to administer the various aspects of Scheduler jobs. You will learn to create, copy, and alter jobs to achieve your scheduling needs. You will learn how to run jobs and how to stop jobs that are running. You will learn how to enable and disable jobs and, finally, how to drop jobs that are no longer needed.

Creating Jobs

Scheduler jobs can be created by using the DBMS_SCHEDULER.CREATE_JOB procedure. As you will recall, a job combines a program and a schedule for execution of that program. Therefore, these are the elements that you must define when creating a new job.

Depending on the program that the job uses, you may also need to set job arguments. These are parameters that will be passed to the program at execution time. Job arguments can be set by using the SET_JOB_ARGUMENT and/or SET_JOB_ANYDATA_VALUE procedures in the DBMS_SCHEDULER package.

Jobs also have job attributes that control certain behaviors of the job. Many of these can be set through the CREATE_JOB procedure, while others are inherited from the job class to which the job is assigned (or from the DEFAULT_JOB_CLASS class, as mentioned previously).

For example, job attributes such as JOB_TYPE, JOB_ACTION, and REPEAT_INTERVAL can all be defined at job-creation time. Other attributes, such as MAX_FAILURES, LOGGING_LEVEL, and JOB_PRIORITY, are inherited from the job class.

574  Chapter 12  n  Using the Scheduler to Automate Tasks

For an executable, the value is the name of the executable, including the full path name and applicable command-line arguments. If environment variables are required, we suggest that the executable be wrapped in a shell script that defines the environment before executing the program.

For example, specifying‘/prod/bin/big_load.sh full’would execute the big_load.sh script and pass in one argument with the value of full.

NUMBER_OF_ARGUMENTS  The NUMBER_OF_ARGUMENTS parameter specifies the number of arguments that the job accepts. The range is 0 (default) to 255.

PROGRAM_NAME  The PROGRAM_NAME parameter specifies the name of the program associated with this job. The program name must be the name of an existing program object.

START_DATE  The START_DATE parameter specifies the first date that the job should be run. If both the START_DATE and REPEAT_INTERVAL parameters are NULL, the job will be run as soon as it is enabled.

The START_DATE parameter is used as a reference date when the REPEAT_INTERVAL parameter uses a calendaring expression. In this situation, the job will run on the first date that matches the calendaring expression and is on or after the date specified in the START_DATE parameter.

The Scheduler cannot guarantee that a job will execute at an exact time because the system may be overloaded and thus resources may be unavailable.

REPEAT_INTERVAL  The REPEAT_INTERVAL parameter specifies how often the job should be repeated. This parameter can be specified using either a calendaring or a PL/SQL expression. If this parameter is NULL, the job will run only once (at the scheduled start time).

SCHEDULE_NAME  The SCHEDULE_NAME parameter specifies the name of the schedule associated with this job. It can optionally specify a window or window group associated with the job.

END_DATE  The END_DATE parameter specifies the date when the job will expire. After the date specified, the job will no longer be executed; the STATE of the job will be set to COMPLETED, and the ENABLED flag will be set to FALSE.

If this parameter is set to NULL, the job will repeat forever. However, if the MAX_RUNS or MAX_FAILURES parameters are set, the job will stop if either of these thresholds is met.

COMMENTS  The COMMENTS parameter allows the entry of a comment to document the job.

ENABLED  The ENABLED parameter specifies whether the job is created in an enabled state. A value of TRUE means the job will be enabled. By default, all jobs are created disabled, so the default value for this parameter is FALSE. A disabled job will exist as an object in the database, but it will never be processed by the job coordinator.

AUTO_DROP  The AUTO_DROP parameter specifies whether the job will be automatically dropped once it has been executed (for nonrepeating jobs) or when its status is changed to COMPLETED (for repeating jobs).

The default value for this parameter is TRUE, meaning the job will be dropped from the database. If it is set to FALSE, the jobs are not dropped and their metadata is retained in the database until they are explicitly dropped using the DBMS_SCHEDULER.DROP_JOB procedure.

Identifying the CREATE_JOB Procedure Options

Jobs are created by using the DBMS_SCHEDULER.CREATE_JOB procedure. The CREATE_JOB procedure is an overloaded procedure. If you are not familiar with procedure overloading, it simply means that the procedure can accept a variety of different parameter combinations. Oracle will execute the version of the procedure that matches the parameter list that is passed in. For a more thorough explanation, see the sidebar “Overloading Procedures and Functions.”

Overloading Procedures and Functions

Overloading allows you to create multiple versions of a procedure or function. Each version has the same name but a different parameter list. When an overloaded procedure or function is called, Oracle will execute the version with the parameter list matching the parameters that have been passed in.

The power of overloading lies in the ability to make a single function or procedure that will work with differing datatypes or data elements. For example, if you want to create a function that returns a date in DD-MM-YYYY format, you could overload the function to accept date, string, or numeric datatypes. The function could be defined as shown here:

FUNCTION conv_date (dt IN DATE) <CODE GOES HERE>

RETURN VARCHAR2;

FUNCTION conv_date (dt IN VARCHAR2) <CODE GOES HERE>

RETURN VARCHAR2;

FUNCTION conv_date ( mon IN NUMBER, day IN NUMBER, year IN NUMBER

)

<CODE GOES HERE> RETURN VARCHAR2;

By overloading the function, you can use the same function name regardless of how the date is passed in.

576  Chapter 12  n  Using the Scheduler to Automate Tasks

Using the CREATE_JOB Procedure

Now that you have been introduced to the options available with the CREATE_JOB procedure, you should have a feel for how Scheduler jobs are created. The following example creates a job that will run once every year to enact cost-of-living adjustments for all employees:

SQL> begin

2 dbms_scheduler.create_job (

3job_name => ‘LNE_job’,

4job_type => ‘PLSQL_BLOCK’,

5 job_action => ‘update employee set salary = salary*1.05;’, 6 start_date => ‘10-OCT-2008 06:00:00 AM’,

7repeat_interval => ‘FREQ=YEARLY’,

8 comments => ‘Cost of living adjustment’);

9 end;

10 /

PL/SQL procedure successfully completed.

To verify that the job was created, you can query the DBA|ALL|USER_SCHEDULER_JOBS view, as shown here:

SQL> select job_name, enabled, run_count from user_scheduler_jobs;

As you can see from the results, the job was indeed created, but it’s not enabled because the ENABLE attribute was not explicitly set in the CREATE_JOB procedure.

By default, jobs are created disabled. You must explicitly enable a job before it will become active and scheduled.

Copying Jobs

Jobs can be copied by using the DBMS_SCHEDULER.COPY_JOB procedure. This procedure accepts only two parameters: OLD_JOB and NEW_JOB. These parameters represent the name of the source and destination job names, respectively.

A copied job will be identical to the original job, with the following exceptions:

The COPY_JOB procedure can be used as shown in the following example:

SQL> begin

2dbms_scheduler.copy_job(‘LNE_JOB’,’RAISE_JOB’);

3 end;

4/

PL/SQL procedure successfully completed.

In the example, a new job named RAISE_JOB was created as a copy of the LNE_JOB job. To verify, the USER_SCHEDULER_JOBS view can be queried, as shown here:

SQL> select job_name, enabled

As you can see, the job was indeed created, and even though the LNE_JOB job is enabled, the RAISE_JOB job is disabled.

Running Jobs

The Scheduler allows scheduled jobs to be run outside of their normal schedule through the DBMS_SCHEDULER.RUN_JOB procedure. This procedure is useful for testing a newly created job or for re-executing a job that failed previously. It doesn’t affect the existing schedule of the job, nor does it require the creation of a separate, one-time-only job.

The RUN_JOB procedure accepts the JOB_NAME and USE_CURRENT_SESSION parameters. The USE_CURRENT_SESSION parameter is a Boolean (TRUE or FALSE) value that determines the method in which the job will be run. If this parameter is set to FALSE (the default value),

the job will be submitted to the job Scheduler for normal asynchronous execution.

If the parameter is set to TRUE, the job will be executed synchronously using the current user session. This means that as soon as the procedure is executed, the job will run. Therefore, control will not be returned to your user session until the job execution is complete, as you can see here:

SQL> begin

2dbms_scheduler.run_job(‘DAILY_ETL’,TRUE);

3 end;

4/

<JOB RUNS HERE>

578  Chapter 12  n  Using the Scheduler to Automate Tasks

PL/SQL procedure successfully completed.

SQL>

Keep in mind that only an enabled job may be run using the RUN_JOB procedure.

Stopping Jobs

A running job can be stopped by using the DBMS_SCHEDULER.STOP_JOB procedure. When a job is stopped in this manner, the Scheduler attempts to stop the job in a graceful manner by means of an interrupt mechanism. When that’s successful, control is returned to the slave process running the job, which will set the status of the job to STOPPED.

Optionally, a user with the MANAGE_SCHEDULER privilege can set the FORCE parameter to TRUE. This causes Oracle to terminate the process running the job and stops the job much faster, in most cases.

The STOP_JOB procedure can be called as follows:

SQL> begin

2 dbms_scheduler.stop_job(job_name => ‘LNE_JOB’,

3force => TRUE);

4 end;

5/

PL/SQL procedure successfully completed.

When a job is stopped using the STOP_JOB procedure, only the most recent transaction is rolled back. If the job has performed any commits prior to the time when it is stopped, data inconsistency may result.

Dropping Jobs

Jobs can be dropped by using the DBMS_SCHEDULER.DROP_JOB procedure. This procedure removes the job object completely from the database. If an instance of the job is running when you issue the DROP_JOB procedure, an error will result. If you set the FORCE option to TRUE, Oracle will issue an implicit STOP_JOB procedure to kill the current instance and then drop the job.

The DROP_JOB procedure can be called as follows:

SQL> begin

2 dbms_scheduler.drop_job(job_name => ‘LNE_JOB’,

3force => TRUE);

4 end;

5/

PL/SQL procedure successfully completed.

In Exercise 12.1, you’ll create a job, copy it, run it, stop it, and then drop it.

E x e r c i s e 12 .1

Getting Comfortable with Jobs

For this exercise, we’ll create a job, copy it, run it, stop it, then drop it.

1.Create a table, and then create a job using dbms_scheduler.create_job.

create table LNE_TEST (x DATE); begin

dbms_scheduler.create_job ( job_name => ‘LNE_job’, job_type => ‘PLSQL_BLOCK’,

job_action => ‘insert into LNE_TEST select sysdate from dual;’, start_date => ‘30-NOV-2008 10:05:00 PM’,

repeat_interval => ‘FREQ=YEARLY’, comments => ‘Cost of living adjustment’);

end;

/

2.Copy the newly created job using dbms_scheduler.copy_job.

begin dbms_scheduler.copy_job(‘LNE_JOB’,’CSTAY_JOB’);

end;

/

3.Now run the job using dbms_scheduler.run_job.

begin dbms_scheduler.run_job(‘LNE_JOB’,TRUE);

end;

/

4.Try stopping the job using dbms_scheduler.stop_job. If the job already finished, modify the program so that the job will run longer so that you have the opportunity to stop it. (Hint, modify the program to loop, so that you have a chance to stop it).

begin

dbms_scheduler.stop_job(job_name => ‘LNE_JOB’, force => TRUE);

end;

/