580  Chapter 12  n  Using the Scheduler to Automate Tasks

E x e r c i s e 12 .1   ( c o n t i n u e d )

5.Now drop the job using dbms_scheduler.drop_job.

begin

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

end;

/

Using Scheduler Programs

A program defines the action that will occur when a job runs. It can be a PL/SQL block, a stored procedure, or an operating-system executable. In the previous section, you learned to define a program within the confines of the CREATE_JOB procedure. However, programs can also be created as independent objects that can be reused by many different jobs. And because programs can also accept arguments, they offer flexibility and encourage reuse.

In the following sections, you will learn the different attributes that define a Scheduler program object. You will learn how to create new programs and how to drop them. You will also learn to define arguments for programs.

Program Attributes

Scheduler programs have a specific set of attributes that you can set to define their characteristics. These attributes can be set at creation time through the following CREATE_PROGRAM procedure parameters:

PROGRAM_NAME  The PROGRAM_NAME parameter specifies the name assigned to the new program. Because programs are stored like any other database object, standard Oracle objectnaming requirements are enforced for programs. This means that the program name must not only be a valid Oracle object name; it must also be unique within the schema.

PROGRAM_TYPE  The PROGRAM_TYPE parameter specifies the type of program that will be created. This is a required parameter and cannot be excluded. It can be any one of the following:

PLSQL_BLOCK  The program is an anonymous PL/SQL block. Anonymous PL/SQL block jobs do not accept job or program arguments, so the NUMBER_OF_ARGUMENTS attribute must be set to 0.

STORED_PROCEDURE  The program is a PL/SQL stored procedure. When you use PL/SQL’s External Procedure feature, the PL/SQL procedure could be a wrapper to call a Java stored procedure or an external C routine.

EXECUTABLE  The program is external to the database. An external program is any program that can be executed from the operating system’s command line.

PROGRAM_ACTION  The PROGRAM_ACTION attribute specifies the code to be executed. For a PL/SQL block, the Scheduler automatically wraps the PROGRAM_ACTION code in its own PL/ SQL block prior to execution. Therefore, this attribute can be a complete PL/SQL block or one or more lines of valid PL/SQL code.

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

ENABLED  The ENABLED parameter specifies whether the job is created in an enabled state. A value of TRUE means the program will be enabled. By default, all programs are created disabled, so the default value for this parameter is FALSE.

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

Creating Programs

New programs can be created by using the DBMS_SCHEDULER.CREATE_PROGRAM procedure. This procedure creates a new program object that can in turn be called by job objects. The procedure’s parameters match the list of attributes described in the previous section.

Programs, like jobs, are stored as independent schema objects. Therefore, they must have unique names within the schema, and they must conform to Oracle’s standards for valid object naming.

To create a program that executes a stored procedure, see the following example:

SQL> begin

2dbms_scheduler.create_program(

3program_name => ‘STATS_PROGRAM’,

4program_type => ‘STORED_PROCEDURE’,

5 program_action => ‘DBMS_STATS.GATHER_SCHEMA_STATS’,

6number_of_arguments => 1,

7comments => ‘Gather stats for a schema’);

8 end;

9/

PL/SQL procedure successfully completed.

This example creates a reusable program that will gather statistics for a schema. As you can see, the program requires one argument, which is the name of the schema. The argument can be defined by using the DEFINE_PROGRAM_ARGUMENT procedure, as shown here:

SQL> begin

2dbms_scheduler.define_program_argument(

582  Chapter 12  n  Using the Scheduler to Automate Tasks

3 program_name => ‘STATS_PROGRAM’,

4argument_position => 1,

5 argument_type => ‘VARCHAR2’);

6 end; SQL> /

PL/SQL procedure successfully completed.

You may have noticed that the example of the DEFINE_PROGRAM_ARGUMENT procedure doesn’t specify a name for the argument. The ARGUMENT_NAME parameter is available, but it’s completely optional.

This program can now be used by a job object, and the schema name can be passed in as an argument. Therefore, the same program can be used by many jobs, each gathering statistics for a different schema.

Arguments can be dropped from programs as well. The DBMS_SCHEDULER.DROP_PROGRAM_ ARGUMENT procedure allows arguments to be dropped either by name or by the position of the argument. The following examples show how an argument may be dropped by specifying its position:

PL/SQL procedure successfully completed.

This example shows how an argument may be dropped by specifying its name:

PL/SQL procedure successfully completed.

Dropping Programs

Program objects can be dropped through the use of the DBMS_SCHEDULER.DROP_PROGRAM procedure. This procedure removes the program entirely from the database. If existing job definitions include the program that you are attempting to drop, the drop will fail. However, if you set the FORCE parameter to TRUE, the program will be dropped and the referencing jobs will become disabled.

The following example drops the STATS_PROGRAM program and disables any referencing jobs:

SQL> begin

2dbms_scheduler.drop_program (

3 program_name => ‘STATS_PROGRAM’,

4 force => TRUE);

5 end; SQL> /

PL/SQL procedure successfully completed.

Using Schedules

Schedules define when jobs run as well as when windows are opened. (Windows will be covered later in this chapter.) Like jobs and programs, schedules are stored objects and follow all the same naming requirements. When schedules are saved as independent objects, they can be used by multiple jobs.

Schedules define not only when a job will start, but also how often the job will be repeated. This is known as the repeat interval. Oracle’s Scheduler offers two ways to define the interval: using PL/SQL expressions or using the powerful new calendaring syntax introduced in Oracle 10g.

The Scheduler can schedule job execution based on the following methods: NN Time-based

NN Event-based

NN Dependency

In time-based scheduling, you define the time and date that you would like a job to run and repeat. Event-based scheduling allows you to start a job based on some event that signals the Scheduler. In dependency scheduling, the Scheduler runs jobs based on the results of previous jobs in a defined chain.

In the following sections, you will learn which attributes define a schedule object. You will learn how to create and drop schedules. You will also learn how to define repeat intervals using the calendaring syntax.

584  Chapter 12  n  Using the Scheduler to Automate Tasks

Schedule Attributes

Schedule objects have a specific set of attributes that you can set to define the characteristics of the schedule. These attributes can be set at creation time through the following CREATE_ SCHEDULE procedure parameters:

SCHEDULE_NAME  The SCHEDULE_NAME parameter specifies the name of the schedule. Because schedules are stored like any other database object, standard Oracle object-naming requirements are enforced for schedules. This means that the schedule name must not only be a valid Oracle object name it must also be unique within the schema.

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

END_DATE  The END_DATE parameter specifies the date when the schedule 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 parameter is set, the job will stop if either of these thresholds is met.

REPEAT_INTERVAL  The REPEAT_INTERVAL parameter specifies how often the schedule 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).

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

Creating Schedules

Schedules are created using the DBMS_SCHEDULER.CREATE_SCHEDULE procedure. By default, schedules are created with access to the PUBLIC role. Therefore, no privileges need to be granted to allow other users to use the schedule.

The following example creates a schedule that repeats every night at 8:00 p.m.:

SQL> begin

2dbms_scheduler.create_schedule(

3 schedule_name => ‘NIGHTLY_8_SCHEDULE’,

4start_date => SYSTIMESTAMP,

5 repeat_interval => ‘FREQ=DAILY; BYHOUR=20’,

6 comments => ‘Runs nightly at 8:00 PM’);

7 end; SQL> /

PL/SQL procedure successfully completed.

Setting Repeat Intervals

Oracle’s calendaring syntax offers tremendous flexibility when it comes to defining repeat intervals. The syntax includes a set of elements that offer different methods of specifying repeating dates. By mixing and matching these elements, you can generate fairly complex repeat intervals. Table 12.2 describes the clauses and their usage.

Ta b l e 12 . 2   ​  Calendaring​ Syntax Element Descriptions

Testing Repeat Intervals

One issue inherent in defining schedule repeat intervals is testing. How do you make sure you didn’t make a mistake in your logic? To address that issue, Oracle offers the DBMS_SCHEDULER

.EVALUATE_CALENDAR_STRING procedure. This procedure allows you to pass in a calendaring syntax expression and a start date, and it will return the time and date that the job will execute next. Optionally, you can also instruct the procedure to show the next execution time after

a certain date, thereby allowing you to see execution dates in the future. Table 12.4 lists the parameters for the EVALUATE_CALENDAR_STRING procedure and describes their usage.

Ta b l e 12 . 4 :     EVALUATE_CALENDAR_STRING Procedure Parameters

Parameter Description

CALENDAR_STRING The calendar expression to be evaluated.

RETURN_DATE_AFTER Instructs the procedure to return only execution dates that will occur after the date specified in this parameter. This allows you to see dates and times far out into the future. By default, Oracle uses the current SYSTIMESTAMP.

588  Chapter 12  n  Using the Scheduler to Automate Tasks

Ta b l e 12 . 4 :     EVALUATE_CALENDAR_STRING Procedure Parameters  (continued)

To use the EVALUATE_CALENDAR_STRING procedure, you will need to use PL/SQL that accepts a return value of type TIMESTAMP, as shown here:

SQL> DECLARE

2start_date TIMESTAMP;

3 return_date_after TIMESTAMP;

4next_run_date TIMESTAMP;

5BEGIN

6start_date := to_timestamp_tz(

7‘10-OCT-2008 10:00:00’,’DD-MON-YYYY HH24:MI:SS’);

8DBMS_SCHEDULER.EVALUATE_CALENDAR_STRING(

9 ‘FREQ=MONTHLY; INTERVAL=2; BYMONTHDAY=15’,

10start_date, null, next_run_date);

11DBMS_OUTPUT.PUT_LINE(‘next_run_date: ‘ ||

12next_run_date);

13END;

SQL> /

next_run_date: 15-OCT-08 10.00.00.000000 AM

PL/SQL procedure successfully completed.

As you can see, line 9 contains the actual calendar expression that is being evaluated. Also, because a value of NULL was submitted for the RETURN_DATE_AFTER parameter, Oracle uses the current date and time as the default.

The procedure returns only a single value for NEXT_RUN_DATE, but you may want to see more than one. If so, you can use the SQL shown here:

SQL> DECLARE

2start_date TIMESTAMP;

3 return_date_after TIMESTAMP;

4next_run_date TIMESTAMP;

5BEGIN

6start_date := to_timestamp_tz(

7 ‘10-OCT-2008 10:00:00’,’DD-MON-YYYY HH24:MI:SS’);