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 disable via texis.cnf). 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 (eg. every hour, but on the hour).

• URLEND=/func.txt
  Specifies the function and MIME-type file extension (p. ) 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 (p. ), 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).

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, eg. 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 (p. ).

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

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.

SEE ALSO
Scheduling section