X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;ds=sidebyside;f=tools%2Fwhenjobs.pod;h=1c96648e38830deb990817fc294dec4bd393fab5;hb=cffe87109d9c868eefd48f7d5255a4863a578e4d;hp=2acec9f96c554b262e77a8f65c14fce0399e4b0b;hpb=600c8000490fa8279b23ce866e9ecc2a90e5f79a;p=whenjobs.git diff --git a/tools/whenjobs.pod b/tools/whenjobs.pod index 2acec9f..1c96648 100644 --- a/tools/whenjobs.pod +++ b/tools/whenjobs.pod @@ -396,14 +396,18 @@ ran, then this evaluates to true, else false. This is the same as writing C variable>. -B There is a subtle and difficult problem with using the -I operator: The first time the expression is evaluated, the -job has (by definition) not yet run. Therefore C -evaluates to C<""> (see definition of I above). Since -C<"" E everything>, the I operator evaluates to -false, and since this usually means the job does not run, the -operator always evaluates to false. A future version of whenjobs -will address this problem. +B There is a subtle gotcha with the I operator: The +first time the expression is evaluated, the job has (by definition) +not yet run. Therefore C evaluates to C<""> (see +definition of I above). Since it is always true that + + "" < anything + +the I operator evaluates to false, and since this usually +means the job does not run, the operator always evaluates to false. + +To fix this, ensure that the variable is initialized (see +L below). =item B @@ -411,9 +415,7 @@ This evaluates to true the first time the expression is evaluated after the jobs file has been reloaded or the daemon restarted. Thereafter it evaluates to false. -You can use this to initialize variables, but note that this does not -solve the I operator problem described above, because -variables are initialized too late to affect that. +Don't use this to initialize variables: it won't do what you mean. =item B @@ -513,12 +515,163 @@ with C: The job name is passed to the shell script in the C<$JOBNAME> environment variable. +=head2 OCAML EXPRESSIONS + +As well as simple "every" and "when" expressions, advanced users may +want to use arbitrary OCaml expressions, functions, etc in the jobs +script. These are useful for factoring common code or strings, for +setting the initial values of variables, or for defining cleanup +functions. + +A simple example of an OCaml expression is: + + let prefix = "daily_" + + job (prefix ^ "virus_scan") + every day : + << + # ... + >> + + job (prefix ^ "disk_check") + every day : + << + # ... + >> + +which creates two jobs called C<"daily_virus_scan"> and +C<"daily_disk_check"> (C<^> is the OCaml string concatenation +operator). + +OCaml expressions have access to a library of functions called +B which is described below. It lets you set variables, +create jobs algorithmically, etc. + +The OCaml expressions run once, when the jobs file is being loaded or +reloaded. + +=head3 SETTING THE INITIAL VALUE OF VARIABLES + +Variables are created when they are referenced, and until set they +have the value empty string (just like the shell). Across file +reloads, the previous values of variables is preserved. + +To initialize a variable to a known value when the jobs file is +loaded, call one of the C functions as in +this example: + + let () = + Whentools.set_variable "name" "Richard"; + Whentools.set_variable_int "counter" 0 + +=head3 CLEANUP FUNCTIONS + +After a job runs, you can control what happens to its output by +writing a cleanup function. To write a cleanup function you have to +name the job (ie. have an explicit C statement). Put C +after the job name like this: + + job "poll source" + cleanup (Whentools.mailto "you@example.com") + every 10 seconds : + << + # ... + >> + +A number of cleanup functions are available in the library; see below. + +You can also write your own cleanup functions (in OCaml). The +function is passed one argument which is a C struct, +defined below. + +=head3 WHENTOOLS LIBRARY + +=head4 Functions + +=over 4 +=item B [I<~only_on_failure:true>] +[I<~from:from_address>] I I +Send the result of the script by email to the given email address. +If the optional C<~only_on_failure:true> flag is set, then it is only +sent out if the script failed. +If the optional C<~from> flag is set, then the from address is set +accordingly. This is sometimes needed when sending mail. +Note the C parameter is passed implicitly by the daemon. You +do not need to add it. +Here are some examples of using the mailto function: + + job "ex.1" + cleanup (Whentools.mailto "you@example.com") + every 10 seconds : + << + # do something + >> + + job "ex.2" + cleanup (Whentools.mailto ~only_on_failure:true + "you@example.com") + every 10 seconds : + << + # do something + >> + + let from = "me@example.com" + let to_addr = "you@example.com" + + job "ex.3" + cleanup (Whentools.mailto ~from to_addr) + every 10 seconds : + << + # do something + >> + +=item B I I + +Set variable I to the string. + +=item B I I + +Set variable I to the boolean value I. + +=item B I I + +Set variable I to the integer value I. + +=item B I I + +Set variable I to the string value . This is +the same as I. + +=item B I I + +Set variable I to the floating point value I. + +=back + +=head4 Structures + +=over 4 + +=item B + +This structure is passed to cleanup functions. It has the following +fields: + + type result = { + res_job_name : string; # job name + res_serial : big_int; # job serial (same as $JOBSERIAL) + res_code : int; # return code from the shell script + res_tmpdir : string; # temporary directory script ran in + res_output : string; # filename of stdout/stderr output + } + +=back =head1 FILES