SCHEDULE - schedule periodic execution of script

`SCHEDULE` - schedule periodic execution of script

SYNOPSIS

<SCHEDULE [options] WHEN=schedule [--] [var=val] [...]>

DESCRIPTION
The SCHEDULE directive causes the script to be periodically executed, according to the given WHEN schedule. The WHEN schedule is a string with one of the following syntaxes:

minutes
[EVERY] [n] DAY[S]|DAILY timeofday [minutes]
[EVERY] [n] WEEK[S|LY] [ON] weekday timeofday [minutes]
[EVERY] [n] MONTH[S|LY] [ON] [THE] FIRST|SECOND|THIRD|FOURTH|n [TO LAST] weekday|DAY [OF THE MONTH] timeofday [minutes]

with these additional definitions:

minutes = [EVERY] [n] MIN[UTE[S]] [[REPEAT] n [TIME[S]]

timeofday = AT [h]h[:][[m]m][A|P[M]]

weekday = SUN|MON|TUE|WED|THU|FRI|SAT| SUNDAY|MONDAY|TUESDAY|WEDNESDAY|THURSDAY|FRIDAY|SATURDAY

Alternatively, the WHEN schedule may be a string with the vCalendar 1.0 scheduling syntax (available at http://www.imc.org/pdi/pdiproddev.html).

SCHEDULE may also be called as a function; it returns 0 on error, 1 if ok, and 2 if nothing done (scheduler disabled via texis.ini). The primary function usage is to unschedule a script (with WHEN set to "off") or all scripts ("all-off").

In addition to the WHEN schedule, the following options may appear in the SCHEDULE directive or function:

START=date The starting date for the schedule, as a Texis-parseable date/time. This defaults to now. The first run of the schedule will be the next valid WHEN event on or after START. It is recommended that a START date be given if the WHEN argument is of the EVERY [n] MINUTES syntax, if the script is to start at a fixed wall-clock time (e.g. every hour, but on the hour).
URLEND=/func.txt Specifies the function and MIME-type file extension (here) to be appended to the script name when run. This allows a function other than <main> to be the starting point for the script run.
COMMENT=text Specifies a short text comment to be associated with this schedule. This is viewable when the -LS command-line option is used (here), and can be use to denote the purpose of each scheduled event.
SCRIPT=file Script to schedule/unschedule. Only valid if called as function; directive script is always current script. Default is main script (non-module).
FLAGS=flags
Set space-separated list of flags. May include:
- mutex
  Run jobs mutually-exclusive: do not start a scheduled run of the script if a previous run of the same script same schedule is still active. Scripts should still run their own mutex check however, as this only prevents scheduled collisions, not web or command-line runs from colliding. This is the default in version 8 and later.
- nomutex
  Do not mutually-exclude runs. Default in version 7 and earlier.
FLAGS was added in version 7.02.1409016000 20140825. Note that previous versions will take this option as a variable assignment.
--
Indicates end of options, and that all arguments that follow (if any) are variable assignments to pass to the script. Ensures that any var assignments will not be confused with options. Added in version 7.02.1409016000 20140825.

After all options, a list of variable assignments may be given. These will be passed to the script when it is run, allowing user-defined configuration options to be set.

Multiple <SCHEDULE> tags are permitted, e.g. to run different parts of the script at different times. To unschedule a script, remove the <SCHEDULE> tag and re-compile or re-run the script, use -sched all-off, or -wipesched (here).

For more information on scheduling, see the Scheduling section, here.

EXAMPLE

<SCHEDULE WHEN="daily at 10pm">

<SCHEDULE WHEN="every month on the first Sunday at 4am"
          URLEND=/monthly.txt>

The first example schedules the script to run the <main> function every day at 10pm local time. The second example runs the <monthly> function on the first Sunday of every month, at 4am.

CAVEATS
The <SCHEDULE> tag was added in version 3.01.985400000 20010323. The function syntax was added in version 3.01.988150000 20010424.

The script must be compiled, either explicitly via the -C option or implicitly by running the source, for the <SCHEDULE> tag to take effect, since Vortex must be made aware of it.

The Texis Monitor (monitor) is responsible for starting scheduled scripts, so it must be running for SCHEDULE to work. Running texis, tsql or vhttpd will start the Texis Monitor; alternatively it may be automatically run by the OS at machine boot (under Windows the install program for Texis arranges this). Make sure it is run as the Texis user, not root.