Sambar Server Documentation

Task Scheduler


The Sambar Server has a built-in task scheduler for managing events such as log file rotation, search re-indexing, and dial-on-demand. User-defined events can be configured in the config/schedule.ini file. Changes to the schedule.ini file are automatically detected by the scheduler and reloaded. No attempt is made to issue commands lost due to a reboot/restart.

The Sambar Server Scheduler has two scheduler modes, a UNIX cron implementation, and a simple scheduler for: hourly, daily, weekly or monthly execution. The scheduler thread runs every minute to service scheduled tasks, and executes tasks either serially in the order they were scheduled or in parallel. If the task is executed serially (the default), and several events are scheduled to execute at the same time (i.e. weekly), the first will begin executing Sunday at midnight and the others will execute after each preceeding task completes. So if the first task takes 5 minutes, the second task will not run until Sunday at 12:05AM. Note: The timeout period for the CRON scheduler is every minute.

The serial nature of the scheduler can affect the server adversly if time-sensitive features such as dial-on-demand are being used in addition to longer-running tasks. For example, dial-on-demand feature uses the scheduler to determine if the connection should be "hung-up". If the task to test the "hang-up" condition cannot run because of a long-running task (such as log-file rotation/processing), the "hang-up" will not occur until the previous event completes. Any task that will take more than a few seconds should be executed in parallel.

Parallel Execution

By default, tasks are executed serially. To execute tasks in parallel, the task command should end with an ampersand (&).

Task Termination

All tasks should terminate and return an error code of 0. By default, any user-defined tasks that are still running after 5 minutes are terminated. The duration of the Scheduler timeout can be configured via the config/config.ini file: Scheduler Task Timeout.

schedule.ini file

The format of the config/schedule.ini file is as follows:

# schedule.ini
# Schedule tasks for execution

[cron]
15,45 * * * * perl\perl.exe tmp\logtask.pl
10 4 * * * perl\perl.exe tmp\logtask.pl &

[hourly]
Hourly Perl Test = perl\perl.exe tmp\logtask.pl

[daily]
Daily Perl Test = perl\perl.exe tmp\logtask.pl

[weekly]
Weekly Perl Test = perl\perl.exe tmp\logtask.pl

[monthly]
Monthly Perl Test = perl\perl.exe tmp\logtask.pl

Blank lines and leading spaces are ignored. Lines whose first non-space character is a pound-sign (#) are comments and are ignored. Lines ending with an ampersand (&) are executed in parallel.

The section heading (i.e. [hourly]) indicates when the scheduled task should run. Tasks running daily run at 12:00AM, weekly tasks run at 12AM on Sunday, monthly tasks run on the 1st of the month at 12AM. Section can then have multiple entries for actions to take; in the above example, a simple task is started which logs the occurence of the event to the file tmp/logtask.log.

The name = command pair identifies the symbolic name of the task (for logging and debugging purposes), and the command to be executed. The command is passed to the CreateProcess() windows command; your should test all task commands in a DOS command shell to ensure they will work properly when executed by the Scheduler.

[cron] Scheduling

The Sambar Server CRON format is roughly similar to that used by the basic UNIX cron, but without complex features. Individual fields may contain a time, a time range, a time range with a skip factor, a symbolic range for the day of week and month in year, and additional subranges delimited with commas. As with all Sambar Server configuration files, blank lines or lines that begin with a hash (#) are ignored. If you specify both a day in the month and a day of week, the result is effectively ORd... the CRON entry will be run on the specified day of week and on the specified day in the month.

# MIN HOUR DAY MONTH DAYOFWEEK COMMAND
# at 2:20 a.m. every day .br 20 2 * * * perl\perl.exe tmp\logtask.pl

# every four hours at the top of the hour
0 */4 * * * perl\perl.exe tmp\logtask.pl

# every two hours from 11p.m. to 7a.m., and at 8a.m.
0 23-7/2,8 * * * perl\perl.exe tmp\logtask.pl

# at 11:00 a.m. on the 4th and on every mon, tue, wed
0 11 4 * mon-wed perl\perl.exe tmp\logtask.pl

# 1:00 a.m. on january 1st
0 1 1 jan * perl\perl.exe tmp\logtask.pl

The format of of the cron table entry includes five time fields followed by a command. The commands are executed when the time specified by the date fields matches the current time. The five time fields are as follows:

FieldAllowed Values
minute0-59
hour0-23
day of month1-31
month1-12 (or names, see below)
day of week0-7 (0 or 7 is Sun, or use names)

A field may be an asterisk (*), which indicates all values in the range are acceptable. Ranges of numbers are allowed, i.e."2-5" or "8-11", and lists of numbers are allowed, i.e. "1,3,5" or "1,3,8-11". Step values can be represented as a sequence, i.e. "1-9/2", or "*/2"; The range "1-9/2" is the same as "1,3,5,7,9".

Names can be used for the month and day of the week fields. Use the first three letters (case-insensitive) of the month or day (english only). Ranges or lists of names are not allowed.

/session/ or /servlet/ RPC Execution

RPCs can be scheduled for execution as the following sample illustrates:

[daily]
Daily Template Regeneration = /session/url2file?fname=/docs/inline.htm&url=/samples/inline.stm
Daily Servlet Execution = /servlet/admin.Rebuild.class?name=/docs/foobar.htm

The above scheduled event uses the "special" /session/url2file RPC to execute the URL specified and direct it to disk. Run daily, the URL can take dynamically generated content and refresh a static page daily rather than each time the URL is requested. Note: Any output generated by the RPC command are written to session.out in the Sambar Server installation directory (this file is over-written by each scheduled RPC).

The /session/url2file template execution RPC can be especially useful when combined with either the /session/sendmail or /session/ftp RPCs. One company runs RDBMS reports using /session/url2file on templates, followed by /session/ftp to automatically copy the template output up to their internal report server.

[daily]
RDBMS Report = /session/url2file?fname=/docs/report1.htm&url=/dbms/report1.stm
Upload Report = /session/ftp?action=put&server=reportsrv&user=foo&pass=bar&rmtname=report.htm&locname=d:/sambar42/docs/report1.htm