tweaks

Validators-in-scripting-languages.md

@@ -1,36 +1,64 @@
-The validator **script_validator** allows you to write your validation logic
+The validator **script_validator** allows you to write validation logic
 in your language of choice (Python, PHP, Perl, Java, bash).
 **script_validator** takes two additional command-line arguments:
 
-### **--init_script "filename arg1 ... argn"**
-script to check the validity of a result.  Exit zero if valid.
-### **--compare_script "filename arg1 ... argn"**
-script to compare two results.  Exit zero if outputs are equivalent.
+```
+--init_script "scriptname arg1 ... argn"
+```
+This specifies a script to check the validity of a result.
+The script is passed parameters (see below) that identify the result.
 
-**arg1 ... argn** represent cmdline args to be passed to the scripts.
+The script's exit code is:
+
+* zero if the result is valid
+* 3 (```VAL_RESULT_TRANSIENT_ERROR``` in ```sched/validate_util2.h```)
+if a transient error occurred
+(for example, a file open failed because of an NFS mount failure).
+In this case the validation will tried again in a few hours.
+* Any other nonzero value indicates an error,
+and the result is marked as invalid.
+
+```
+--compare_script "filename arg1 ... argn"
+```
+This specifies a script to compare two results.
+The script's exit code is
+
+* zero if the results match
+* 3 (```VAL_RESULT_TRANSIENT_ERROR``` in ```sched/validate_util2.h```)
+if a transient error occurred.
+* Any other nonzero value if the results don't match.
+
+## Arguments passed to the scripts
+
+```arg1 ... argn``` represent cmdline args to be passed to the scripts.
 The options for init_script are:
-### **files**
+
+```files```:
 list of paths of output files of the result
-### **result_id**
-result ID
-### **runtime**
-task runtime in seconds
 
-Additional options for compare_script, for the second result:
-### **files2**
-list of paths of output files
-### **result_id2**
-result ID
-### **runtime2**
-task runtime
+```result_id```: the result ID.
 
-**arg1 ... argn** can be omitted,
+```runtime```: the job runtime in seconds
+
+The options for the compare script include the above, and also:
+
+```files2```:
+list of paths of output files of the 2nd result.
+
+```result_id2```: ID of the 2nd result.
+
+```runtime2```: runtime of the 2nd result, in seconds.
+
+```arg1 ... argn``` can be omitted,
 in which case only the output file paths are passed to the scripts.
 
 The scripts must be put in your project's bin/ directory.
 
-For applications that don't use replication, the compare script need not be given.
-For applications that don't need output file syntax checking, the init script need not be given.
+For applications that don't use replication,
+the compare script need not be given.
+For applications that don't need output file syntax checking,
+the init script need not be given.
 
 As an example, the following PHP script, used as a compare script,
 would require that results match exactly:
@@ -53,4 +81,4 @@ The corresponding entry in config.xml would look like
 <daemon>
     <cmd>script_validator --app uppercase -d 3 --compare_script compare.php</cmd>
 </daemon>
-```
+```