Documentation task

A scheduler user can create tasks for scheduler scripts that are not blocked.
Each time a new task is created it gets a unique number:

Id

The scheduler task identifier.
Each scheduler task has a unique number.
This unique identifier cannot be changed.

Privileges needed

A scheduler user has access to the following scripts:

Back to top 

Create scheduler tasks

Each task is based on one scheduler script. After a task is created the task's script cannot be changed.
Tasks are created on the script submit window, this window has the following panels.

Parameters

Screenshot PL/SQL scheduler window W22 Script submit (parameters panel)

This panel contains the scheduler script parameters
If a script has no parameters the panel will be empty.

Description

A short description of the script parameter.

Back to top 

Schedule

Screenshot PL/SQL scheduler window W22 Script submit (schedule panel)

On this panel the information when the new scheduler task needs to be activated is given.

Date

The date used as a basis for calculating the final schedule date.

Till

The last date the scheduler task can be scheduled.

Shift days

The number of days that must be added to each schedule date.

Maximum tasks

The maximum number of times (days) the scheduler task can be scheduled.
A value one means it is activated once, no value means unlimited.
The number of times the scheduler task is repeated during a day has no effect on the maximum tasks.

Moved

A new schedule date only applied to this task.
The scheduler task is activated exactly on this date and time; all other schedule settings are ignored.
The next schedule, if the scheduler task is scheduled more than once, is based again on the original schedule date.

Keep days

The number of days after which a ready scheduler task is deleted.
The default is specified at the scheduler script keep days.
The maximum number of days is 99999.

Load

The load of the task.
A scheduler task is only started if this load and the total load of the already activated tasks is less or equal the scheduler server.
The default is specified at the scheduler script load.
The minimum load value is zero and the maximum load is 99.

Priority

The priority of the scheduler task.
A priority can range from zero till 99.
If at the same date and time different scheduler tasks have to be activated the tasks with a higher priority are activated before the tasks with a lower priority.
The default is specified at the scheduler script priority.

Run exclusive

If set the scheduler task runs exclusive in the scheduler queue.

Hold exclusive

If set other scheduler tasks must wait when this scheduler task needs exclusive access to the scheduler queue.
This situation only occurs when the scheduler task could not be activated because other scheduler tasks are still running in the scheduler queue.

Next if error

If set the scheduler task must be rescheduled even when it is ready with an error status.
If not set the scheduler task must be rescheduled manually.
This property only applies to scheduler tasks who are scheduled more than once.

Restart on error

If set the scheduler task is restarted immediate if the task is ready with status Error.

Historical

If set the scheduler task can be scheduled before the date it is created.
If for exampler a scheduler task is scheduled to run every day but the task on monday was activated on wednesday the task for tuesday and wednesday are still created.
If not set then for a new scheduler task the first valid date and time after the current date and time is calculated.

Precreate tasks

If set and the scheduler task is scheduled more than once then all the tasks are created immediately.

Back to top 

Task

Screenshot PL/SQL scheduler window W22 Script submit (task panel)

Status

The initial scheduler task status.
The initial is always Hold or Scheduled.

Last scheduled

Contains the schedule date of the last task created with this window.

Comment

Contains comment about the scheduler task.

Back to top 

Queue

Screenshot PL/SQL scheduler window W22 Script submit (queue panel)

If the scheduler queue is closed the queue description contains the extra text (CLOSED).

Name

The scheduler queue name.

Description

The queue description.

Back to top 

Flow

Screenshot PL/SQL scheduler window W22 Script submit (flow panel)

The scheduler flow properties are only used if a flow task id is given in the Wait for task field.

Check the flow documentation for more information on how a task flow works.
Wait for task

The flow task identifier this task must be waiting on.

Reschedule

If set this scheduler task is also rescheduled when the previous flow task is rescheduled.

Restart

If set this scheduler task is also restarted when the previous flow task is restarted.

Finished

The flow action if the flow task has status Finished.

Error

The flow action if the flow task has status Error.

Pass

The flow action if the flow task has status Passed.

Unknown

The flow action if the flow task has status Unknown.

Days Hours Minutes Seconds

The sum of these values incremented with the schedule date of the very first flow task is the new schedule date of this task.

Back to top 

Days of the week

Screenshot PL/SQL scheduler window W22 Script submit (days of the week panel)

On this panel for each day of the week, monday till sunday, can be specified if the scheduler task is allowed to be scheduled on that day.
At least one day must be enabled.

Back to top 

Months

Screenshot PL/SQL scheduler window W22 Script submit (months panel)

On this panel the months of the year can be specified on which the scheduler task is allowed to be scheduled.
At least one month must be enabled.

Back to top 

Days of the month

Screenshot PL/SQL scheduler window W22 Script submit (days of the month panel)

On this panel can be specified for every day in all the months of the year if a scheduler task is allowed to be scheduled.

Back to top 

Weeks

Screenshot PL/SQL scheduler window W22 Script submit (weeks panel)

On this panel for every week of the year can be specified if a scheduler task is allowed to be scheduled.

Back to top 

Repeat

Screenshot PL/SQL scheduler window W22 Script submit (repeat panel)

On this panel the number of times a scheduler task must be repeated after it has been activated.
The default and minimum value is one; this means the task is not repeated.

Check the repeat documentation for more information and examples on how a repeated task works.
Number

The total times a scheduler task must be repeated.
The total includes the first schedule; default a scheduler task is not repeated but activated only once.
If the repeat number has a value one then all the other repeat properties are ignored.

Till

The time (format HH24:MI:SS) untill the scheduler task is repeated.
Even if the repeat number has not been reached no more new scheduler tasks are scheduled after this time.
The repeat till value is only applied to the repeated tasks; not to the first task.

Historical

If set the next repeated task can be scheduled before the current date and time, otherwise these scheduler tasks are skipped.

From starttime

If set the next repeat is scheduled at the schedule date of the last task incremented with the repeat interval period.
If not set the next repeat is schedule at the date and time the last repeated task was ready incremented with the repeat interval.

Precreate tasks

If set all the repeated tasks are created immediately when the scheduler script is submitted.

Hours Minutes Seconds

The total of these three values determine the repeat interval between each repeated scheduler task.

Back to top 

Overtime

Screenshot PL/SQL scheduler window W22 Script submit (overtime panel)

On the overtime panel the overtime period is defined.
This is the period after the schedule date in which the scheduler task must be activated.
When the period expires the overtime indication determines what action must be taken for the task.

Check the overtime documentation for more information on how overtime works.
Indication

The overtime indication code.

Days Hours Minutes Seconds

The total of these four values determine the overtime period.

Back to top 

Trace

Screenshot PL/SQL scheduler window W22 Script submit (trace panel)

On this panel the scheduler trace or the oracle trace can be enabled.

Task

If set the scheduler trace is enabled.

Oracle

If set an oracle trace file is generated containing all the sql statements used by the script program.

Back to top 

Dbms_job

Screenshot PL/SQL scheduler window W22 Script submit (job panel)

Oracle restart

If set and the running scheduler task database session aborts abnormally (for example the database shuts down during execution) it is restarted.

Restart wait

The period in seconds after which the scheduler task must be restarted.

Back to top 

Create task example

Each scheduler task is based on one scheduler script so first a script must be selected.
Select from the scheduler window menu Script -> Submit.
Now select a scheduler script on the script submit (select) window.

Screenshot PL/SQL scheduler window W19 Script submit (select)

Select a script (in this example LINESSCRIPT) and press the submit button (or double click on the script). The script submit window is opened.

It is possible to select more than one scheduler script. For each scheduler script a script submit window is opened.
Screenshot PL/SQL scheduler window W22 Script submit

Only the first four panels are shown here. More panels can be enabled and disabled with the Display menu.
After pressing the submit button a scheduler task is created.

On the next screenprint a task is created that runs only on friday every week at 22:00 (for the next 900 weeks). Note that even if the current schedule date does not fall on a friday a new scheduled date for the next monday is calculated (and will be 19 january 2007 at 22:00:00).

Screenshot PL/SQL scheduler window W22 Script submit Back to top 

Task status

A task always has a status, when a new task is created it's initial status is Scheduled or Hold.
In the table column Next the next possible status is shown.

Status Name Next Description
S Scheduled A D H P The task is scheduled.
A Activated R U The task is activated by the scheduler server.
R Running E F U The scheduler task is actually running.
W Waiting R U The task is waiting on another task. When this task is ready the task will be running again.
F Finished D The plsql scheduler task has finished successfully.
H Hold S D The task has been hold which implies that the scheduler server will never activate it.
Setting the status to scheduled will make the task available again.
E Error D During execution of the task an exception was raised. The exception error message is displayed in the task output and in the scheduler server log.
U Unknown D If a task is terminated during a database shutdown or is killed abnormally the status is set to unknown.
D Deleted The task has been deleted. The scheduler server will remove at certain intervals the deleted tasks from the database.
P Passed D The task is not executed.

Note that the status unkown only occurs when an activated or running task does not finish correct (with or without an error).

Back to top 

Tasks not activated

A task may be scheduled now but is still not activated by the server. In the following table all the reasons why a task cannot be activated are given and a possible solution to get the task activated.

Reason Name Description
C Queue closed The scheduler queue is closed.
Problem can be solved by opening the queue by a scheduler user with the administrator privilege or by changing the scheduler queue.
L Low priority The priority of the task is lower than the minimum priority of the queue.
A scheduler user with the administrator privilege could lower the minimum priority of the queue, the priority of the task could be incremented or simply changing the scheduler queue could solve the problem.
H High priority The priority of the task is higher than the maximum priority of the queue.
A scheduler user with the administrator privilege could increase the maximum priority of the queue, the priority of the task could be decremented or simply changing the scheduler queue could solve the problem.
Q Queue full The total number of activated and running tasks has reached the scheduler queue limit.
Wait for the currently running tasks to finish, move the task to another scheduler queue or a scheduler user with the administrator privilege should increase the scheduler queue limit.
E Exclusive access The task is waiting for exclusive access to the scheduler queue but there are still tasks running in the scheduler queue.
Wait for the running tasks to complete or, if the tasks needs to start immediate, kill the currently running tasks or change the queue in which no running tasks exist.
X Wait exclusive There is currently a task active with exclusive access in the scheduler queue. New tasks must wait until this task is ready.
Wait till the exclusive task is ready, kill the currently running exclusive task or change the scheduler queue of this task.
S Server error Someting went wrong when the task was activated by the scheduler server.
Check the scheduler server log for details, correct the error and restart the task.
T Task hold The task has status hold.
Set the status back to scheduled if the task needs to be activated.
D Script disabled The scheduler script has been disabled.
Enable the script if the scheduler task needs to be activated.
U User disabled The scheduler user that created the scheduler script has been disabled.
The task will be activated after the user is enabled.
M Maximum load The scheduler server load has been reached.
Wait till other tasks are ready, change the task load or increment the scheduler server load.
F Flow The task is part of a flow and is not activated because the flow action is set to Flow.
Change the flow action.
W Wait The task is waiting for another flow task to finish.
Wait for the flow task to finish.
O Overtime The task could not be started in time because the overtime period has expired.
Reschedule the task at a different time, change the overtime indication or increase the overtime period.
Back to top 

Skip scheduled tasks

A task that runs more than once can be skipped. This means that a new schedule date is calculated for the task according to the old schedule date.
Tasks who only run once cannot be skipped, just delete these tasks or change the schedule date.

Back to top 

Edit task

Only tasks with the following statusses can be changed:

Tasks that has been created from within another running task and have this task as a parent cannot be changed.

Tasks are edited on the task edit window.

Back to top 

Hold tasks

Only for a task with status Scheduled the status can be set to hold.
A task with status Hold is ignored by the scheduler server and will never be activated.

Back to top 

Restart tasks

A task can only be restarted under the following conditions.

It is possible to set restart values during the execution of a task. These restart values can be accessed in the restarted task and can be used if the original task ended with an error to determine where the restarted task should resume processing.
Setting restart values must be done in the executed program itself; it is embedded in the PL/SQL program code that is executed

The restart values are removed if a scheduler task is ready with status Finished.
This means that restarting a sucessfully finished task is the same as scheduling a new task with the same properties.
Check the PL/SQL restart documentation on how to implement restart values.
Back to top 

Delete tasks

Except the tasks who are activated and not ready yet all tasks can be deleted directly.
If the task has a parent task then this parent task must be deleted (if a parent task is deleted all the child tasks are also removed).

If the task is part of a tree because it has a parent task or is part of a flow then the root of the tree determines the deletion of the entire tree.
Back to top 

Kill tasks

Tasks with status Running and Waiting can be killed; this means the oracle session is killed that executes the current task.
The task will get status Error or, if the sesion has been removed at os level, status Unknown.

Back to top 

Suspend tasks

The scheduler offers the capability of suspending running tasks. This can be used for long running tasks that for some reason for a period must be stopped and must continue processing later on.
Instead of killing the task and restart the task later on suspending the task is a nice alternative because the session itself stays intact.

The time when a task can be suspended is determined by the executed program itself; it is embedded in the PL/SQL program code that is executed.
Check the PL/SQL suspend documentation on how to enable the suspend option.

Tasks can be (un)suspended by any scheduler user who has access to the task.
A task is suspended till a given date and time, after this timestamp the task will continue processing. The suspend date and time can be changed to a different value at any moment.
Task suspend information is displayed on the task properties window (suspend panel).

Screenshot PL/SQL scheduler window W25 Task properties (suspend panel)
Status

The scheduler task suspend status.

By

The scheduler user who suspended the scheduler task for the last time.

Last check

The last date and time the running scheduler task checked if it had to be suspended.

Request

The date and time the last suspend request was done.
All suspend requests are logged in the scheduler server log together with the scheduler user name who did the request.

Checks

The total number of times the running scheduler task checked if it had to be suspended.

At

The date and time at which the scheduler task was suspended.

Time

The total time the scheduler task has been suspended.

Till

The date and time untill the scheduler task is suspended.

The task status of a suspended task does not change but stays Running.
A task is unsuspended by simply suspending it till the current date and time.

A running task can have four different suspend statusses.

Status Name Description
D Disabled The task cannot be suspended. This is the default.
E Enabled The task can be suspended by any scheduler user who has access to this task.
P Pending A request is pending for the task to be suspended.
S Suspended The running task is suspended.
Back to top 

Task progress information

The scheduler also can display progress information; it estimates how long the task still has to run to complete a certain operation.
This is especially usefull for long running tasks for which it is important how long it will take to be ready.

The task progress information is generated by the executed program itself; it is embedded in the PL/SQL program code that is executed.
Check the PL/SQL progress documentation on how to generate progress information.

Task progress information is displayed on the task properties window (progress panel).

Screenshot PL/SQL scheduler window W25 Task properties (progress panel)
Total

The total items of the running scheduler task that needs to be processed.

Done

The total items of the running task that are processed.

Elapsed

The time elapsed (displayed as "HH24:MI:SS").

Remaining

The estimated time (displayed as "HH24:MI:SS") needed for processing the remaining items.

Updated

The last date and time the progress information was updated.

Ready

The estimated date and time at which all the items will be processed.

Percentage done

The percentage done.

Back to top