Jobs

Configure Interchange's "batch jobs" facility.

Synopsis

You can set multiple values at once by using the Perl-style "here document" syntax, as follows:

Scope

This directive is available for use globally (in the "interchange.cfg" configuration file), and locally (in the "catalog.cfg" configuration file).

The global configuration affects all websites running under the Interchange instance.  Each individual website's local configuration will not affect or influence other websites in any way. 

Description

This parameter allows you to configure Interchange's "batch jobs" facility.  This facility essentially allows you to create a kind of "Interchange script", using ICML tags, and run that from the command line or as a cron job.

The following local configuration declares the directory that will hold the job files, and sets up a log file to log information about the job runs.  It also declares an email address to which any output from the job(s) will be sent:

Assuming your website (as set up using the Catalog global configuration directive) is named "foobar", and the Interchange instance is owned and run by the "ic_username" user, the following command, combined with the above settings, will run all of the files it finds in the "jobs/baz directory in alphabetical order:

Warning Job filenames that end with the HTMLsuffix value (usually ".html") will be silently ignored.

The following crontab entry will run the job files found in the "foobar" website's "jobs/baz" directory every day at 2:12am:

Some points to note:

• The above command only queues the job for execution and will therefore return you to the shell prompt before the job has even started.
• A session will be created for use by all of the files in the job run, for the storage of scratchpad variables etc., but that session will be discarded when the job is complete.  Job sessions will not be saved for future use.
• The "mv_tmp_session" [cgi] variable will be set to 1.
• The "remote" IP address will be set to "none".
• The user agent (browser) string will be set to "commandline".

Settings

The following Job directive settings can be specified in the global (interchange.cfg) configuration file:

The following Job directive settings can be specified in the local (catalog.cfg) configuration file:

Parameter	Description	Default
add_session	If set to "Yes" then the job output will include a dump of the current session.  See the "log" and/or "email" parameters if you need to make use of the output.	No
autoend	a Sub or GlobalSub to execute after each individual file in the job run.	None
autoload	a Sub or GlobalSub to execute before each individual file in the job run.	None
base_directory	Directory to search for cron jobs. Warning The "etc" in the default does not reflect the RunDir value.  You will need to change the default using this parameter if you change the RunDir configuration value.	etc/jobs
email	Email any output from the jobs to this address (if provided). Note If SendMailProgram is set to "none" then the email will not be sent, and an error will be logged to the local and/or global error log files.	None
extra_headers	Additional SMTP headers for the email messages, if required.	None
filter	Send the job output through the named Filters before sending to the log file (see the "log" setting) and/or the email address (see the "email" setting), if either or both of these destinations are configured.  The default is to strip leading and trailing whitespace from the output.	strip
from	Set the "From" address in any outgoing email.	See MailOrderTo
initialize	A Sub or GlobalSub to execute before the job commences.  This can be used to initialise session values, or any other similar job setup task.	None
log	A log file to hold job output and other job-related information.	None
reply_to	Set the "Reply-To" address in any outgoing email.	None
subject	Specify the subject for any outgoing email.	Interchange results for job:  directory name
trackdb	If specified then Interchange will write the job name, the start date/time and the process ID to a new row in the named table.  The table will be expected to have at least four columns, named "code", "name", "begin_run" and "pid".	None
use_global	If set to "Yes" then search for the "base_directory" in the Interchange instances installation directory, as well as under the website's home.  The first directory found will be used.  The search order is local and (if not found) global.	No