Documentation script

A scheduler script contains information about the PL/SQL program and how it must be started by the scheduler server.
With this script a scheduler task can be created. When this task is activated it uses the script definition for executing the right PL/SQL program.

A scheduler task contains the information on when the scheduler script needs to run.
The scheduler script contains the information about what PL/SQL program needs to be executed.
Back to top 

Privileges needed

If a scheduler user wants to create or edit scripts it needs the developer privilege.

Back to top 

Create and edit scripts

Each script is identified by the scheduler user who created it and the script name. After creation the owner and the name cannot be changed anymore.

Owner

The scheduler user who created the scheduler script.

Name

The scheduler script name.
The name is always uppercase and has a maximum length of thirty characters.
A name can consist of the characters A till Z, the digits 0 till 9 (but not at the first position) or the underscore character, the dollar and number sign (also not at the first position). If the name contains another character an error is generated.

Back to top 

Scripts are created and changed on the script edit window.

Screenshot PL/SQL scheduler window W16 Script edit

Script

Screenshot PL/SQL scheduler window W16 Script edit (script panel)

Description

The script description.
The description has a maximum size of 100 characters

Public

If set all scheduler users are able to create, edit or delete scheduler tasks for this scheduler script.
This also implies that a scheduler task created by one scheduler user can be changed by all other scheduler users.

Public read

If set all scheduler tasks created with this scheduler script can be viewed by all scheduler users.

Disabled

If set the scheduler script is disabled.
Scheduler tasks for which the scheduler script is disabled are not activated.
New scheduler tasks can still be created and existing can be changed or deleted.

Blocked

If set the scheduler script is blocked.
No more scheduler tasks can be created (or changed) for this scheduler script.
However existing scheduler tasks are still activated.

Back to top 

PL/SQL

Screenshot PL/SQL scheduler window W16 Script edit (PL/SQL panel)

The PL/SQL panel contains the plsql procedure that is executed when the scheduler task for this script is activated.

Script procedure

The name of the procedure to be called when the scheduler script is executed.
If the procedure is located in a package then also specify the package name.
The maximum length including the name of the package is 64 characters.

Check procedure

Contains the procedure to be executed for validation before a task is scheduled (or changed).
If the procedure is located in a package then also the package name must be specified here.
The name of the procedure is not case sensitive.
The maximum length including the name of the package is 64 characters
The check procedure must have the same parameters (name and datatype) as the script procedure.
If the check procedure raises an exception the scheduler task is not created.

Check runtime

If set the check procedure is again executed just before the scheduler task is activated.
If the procedure raises an exception the task is not activated but gets status Error.
The error can be found in the task output and the scheduler server log.

Create procedure

If set a PL/SQL procedure is created in the database with the same name and parameters as the scheduler script.
This procedure can be used for easily creating scheduler tasks in PL/SQL programs.

Back to top 

Queue

Screenshot PL/SQL scheduler window W16 Script edit (queue panel)

A default scheduler queue can be assigned to the scheduler script. If no default scheduler queue is defined a queue must be specified each time a scheduler task is created.

Queue updatable

If set another scheduler queue can be assigned to the scheduler task.

Back to top 

Schedule

Screenshot PL/SQL scheduler window W16 Script edit (schedule panel)

The schedule panel contains default scheduler task properties.

Run exclusive

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

Run exclusive updatable

If set a scheduler task can overrule the script's run exclusive setting.

Hold exclusive

If set and a scheduler task must run exclusive but cannot be activated (because scheduler tasks are still running) other new scheduler tasks ready to be activated must wait.

Hold exclusive updatable

If set a scheduler task can overrule the scheduler script hold exclusive setting.

Priority

The priority of a scheduler script. This priority is used as default when a new scheduler task is created.
The minimum is zero and the maximum is 99.

Priority updatable

If set a priority different than the priority of the scheduler script can be assigned to a scheduler task.

Keep days

Specifies the number of days after which a ready scheduler task is deleted.
Before this date the task can always be manually deleted.
This parameter only applies to tasks that do not have a parent task and are not part of a flow.

Keep days updatable

If set a scheduler task can overrule the number of days after which it is deleted.

Load

The load of the scheduler script.
A scheduler task can only be activated if the sum of this load and the total load of the already activated tasks is less or equal the scheduler server load.

Load updatable

If set a load different than the load of the scheduler script can be assigned to a scheduler task.

Back to top 

Child task

Screenshot PL/SQL scheduler window W16 Script edit (child task panel)

On this panel the behaviour of a new scheduler task is defined when it is created within another running task.

Never

If set and the scheduler script is submitted from within another running scheduler task the running task will not be the parent for the new task.
A scheduler task created with this script will never have a parent task.

Always

If set the scheduler script can only be started from within another running scheduler task.

Queue

If set a scheduler task with a parent task must be added to the number of running tasks in the scheduler queue.

Back to top 

Create script example

In this example the database package CLIENTPACKAGE with the two procedures RUN and RUN_TIMES_10 is used (the source can be downloaded here).
After the scheduler client is started select from the scheduler window menu Script -> New -> Package.
The script create (select package) window is opened.

Screenshot PL/SQL scheduler window W07 Script create (select package)

Select package CLIENTPACKAGE and press the select button (or double click on CLIENTPACKAGE.
On the script create (select package procedure) window one of the two procedures must be selected.

Screenshot PL/SQL scheduler window W08 Script create (select package procedure)

Select procedure RUN_TIMES_10 and press the select button (or double click on RUN_TIMES_10.
Now change the new script name to SCRIPT_RUN_TIMES_10 (or any other name).

Screenshot PL/SQL scheduler window W38 Input

Press the create button.
The script edit window is now displayed.

Screenshot PL/SQL scheduler window W16 Script edit

We are not changing anything but are creating a scheduler task directly; press the submit button.
The scheduler script is now created and the script submit window is opened.

Screenshot PL/SQL scheduler window W22 Script submit

Enter a value for the parameter LINES, select a scheduler queue and press the submit button.
Now a new scheduler task is created and will be activated immediatly by the scheduler server.

Back to top 

Parameters

A script can have parameters. Parameters are added on the script edit window (parameters panel).
There are four datatypes possible for a parameter.
Each parameter has his own panel.

All parameters have the next generic properties.

Name

The name of the script parameter.
Each script parameter must correspond with a PL/SQL script procedure parameter with exactly the same name and datatype.
The name is not case sensitive and has a maximum length of 32 characters

Description

A short description of the script parameter.
The description can have a maximum length of 50 characters

Default

A PL/SQL expression that returns a default value for the script parameter when a scheduler task is created and no value is given for this script parameter.
The return value must have the same datatype as the parameter except for the boolean parameter. In case of a boolean parameter the expression must return a varchar2. A string value false evaluates to the boolean false, the string value NULL or empty string evaluates to NULL, any other string results in a boolean value true.
The maximum length for the default expression is hundred characters.

Check procedure

Contains a validation procedure to be executed before a scheduler task is created.
If the procedure is located in a package the package name must also be specified here. The name of the procedure is not case sensitive.
The procedure must have a parameter with the same name and datatype as the script parameter.
If the parameter check procedure raises an exception the task is not created.

Check runtime

If set the parameter check procedure is again executed just before the scheduler task is activated.
If the procedure raises an exception the task is not activated but gets status Error.
The error can be found in the task output and the scheduler server log.

Mandatory

If set a value must be specified for the script parameter when a scheduler task is created.

Nullable

If set the value NULL can be assigned as a parameter value.

Visible

If set a value can be assigned to this parameter.
If not set the parameter default value is assigned when a new scheduler task is created.

Hidden

If set the parameter value is not visible; this can be usefull if the parameter contains sensitive information like passwords.

Back to top 

Parameter database view

For each parameter, except the boolean, a database view can be defined which contains a list of values.
These values are shown as a drop down list on the script submit window (parameters panel).

The returned values by the database view are combined with the predefined list of values.
Database view

The name of the database view which contains a list of allowable values for the script parameter.

Value column

An expression based on the database view containing the allowed value for the parameter.

Display column

An expression used on the scheduler client for displaying the allowed value. If no expression is given the allowed value column is displayed.

List editable

If set the values for the scheduler script parameters are not restricted by the list of values returned by the database view and the list of values.

Back to top 

List of values

For each parameter, except the boolean, a list of values can be given.
These values are shown as a drop down list on the script submit window (parameters panel).

The list of values is combined together with the values returned by the parameter database view.
Value

The list of value.

Display

The display value for each parameter list value.

Back to top 

Date parameter

Screenshot PL/SQL scheduler window W16 Script edit (date parameter panel)

Time part

If set the date parameter value can contain a time part.

Back to top 

Varchar2 parameter

Screenshot PL/SQL scheduler window W16 Script edit (varchar2 parameter panel)

Trim left

If set all the spaces at the beginning of the parameter value are removed.

Trim right

If set all the spaces at the end of the parameter value are removed.

Case

Indicates if the parameter value is converted to uppercase (U) or lowercase (L).
Default no casing is applied.

Length

Specifies the maximum length of the parameter value.
The maximum length must lie between 1 and 4000.

Back to top 

Number parameter

Screenshot PL/SQL scheduler window W16 Script edit (number parameter panel)

Digits

Specifies the maximum number of digits including the decimals.
The maximum number of digits must lie between 1 and 38.

Decimals

The maximum number of decimals.
The maximum must lie between 0 and 38.

Back to top 

Boolean parameter

Screenshot PL/SQL scheduler window W16 Script edit (boolean parameter panel)

Display value true

A display value for the boolean value TRUE.

Display value false

A display for the boolean value FALSE.

Display value null

A display value for the boolean value NULL.

Back to top 

Delete scripts

A script can only be deleted by the scheduler user who created it. Scripts are deleted using the script delete (select) window. This window is started from the scheduler window menu Script -> Delete.

Only scripts can be deleted for which no scheduler tasks exist.
Back to top 

Granting scripts

Granting a script to a scheduler user gives this user the privilege to create scheduler tasks with this script.

Also existing scheduler tasks can be changed and deleted by the scheduler user to which the script has been granted.
Scheduler users with the administrator privilege can create, change and delete any scheduler task for all scripts.
Public scripts can be accessed by all scheduler users.

Scripts can only be granted by the scheduler script owner or by scheduler users with the administrator privilege.
Granting scripts is done on the user privileges window (scripts panel).

Screenshot PL/SQL scheduler window W28 User privileges (scripts panel)

Select the scripts to be granted, press the grant button and select the scheduler users on the script grant window to which the scripts must be granted.
All granted scheduler scripts appear on the user privileges window (granted panel).

Back to top 

Revoking scripts

Scripts granted to a scheduler user can be revoked by the owner of the script or by scheduler users with the administrator privilege.

After a script has been revoked from a the scheduler user tasks created by this user for this script are still activated.

Scheduler scripts can be revoked on the user privileges window (granted panel).

Screenshot PL/SQL scheduler window W28 User privileges (granted panel)

Back to top