Maint: Reorganization of my directory structure

[bex.git] / NOTES

diff --git a/NOTES b/NOTES
index 703001534933c078613c91d2bd86f0b3b7129939..366a4092130fad07a487870524b62fc4c8f9d4df 100644 (file)
--- a/NOTES
+++ b/NOTES
@@ -9,8 +9,10 @@
        /<job-id>.log           (Optional) transcript of output produced by the job (including
                                previous failed attempts)
 
-<queue>/jobs/<job-id>.job      All jobs issued on this queue, including those which
+<queue>/jobs/                  All jobs issued on this queue, including those which
                                are no longer queued for any machine
+       /<job-id>.job           Description of the job (see below)
+       /<job-id>.attach/       A directory containing attachments (if any)
 
 <queue>/history/<hostname>/    Successfully completed jobs (their .job, .stat and .log files)
                                are moved here if the keep_history config switch is set.
@@ -32,6 +34,13 @@ Known header fields:
 
 ID: <job-id>                   Identifier of the job, unique in the scope of a queue
 Subject: <subject>             Subject to be displayed to the user
+Prep: <command>                        Run <command> in a shell before the job body is executed;
+                               $HOST contains the name of the host. This is useful for
+                               example if you want to transfer data to the host by rsync.
+
+Whenever a user command wants a job ID, it accepts any substring starting
+at a component boundary (start of the ID or a "-"), as long as the substring
+is unique.
 
 ### Status files ###
 
@@ -45,21 +54,26 @@ Message: <msg>                      (Optional) human-readable message explaining the status
 
 ### Status codes ###
 
+FAILED         Job failed to execute (i.e., it returned a non-zero exit code)
+INTERR         Internal error of BEX (e.g., failed to read job prolog file)
+NEW            Newly inserted job, which did not run yet
 NOPING         Host does not respond to ping
 NOXFER         Transfer of the job body to a temporary file on the host has failed
 OK             Job finished successfully (this is usually not seen in the queue, since
                finished jobs are immediately deleted or moved to the history)
-FAILED         Job failed to execute (i.e., it returned a non-zero exit code)
-INTERR         Internal error of BEX (e.g., failed to read job prolog file)
+PREP           Running preparatory commands (i.e., those present in Prep header field)
+PREPFAIL       Preparatory commands failed (i.e., those present in Prep header field)
+REMOVED                Job removed from the queue (behavior similar to OK)
+RUN            Job is running
 
-These are present only in log files and messages sent over status FIFO:
+Additional status codes recorded in the log files:
 
-RUN            Job is running
-SEND           Sending job to the host
+REQUEUE                Attempted to put on a queue, but it already was there
 
-Status codes not tied to a specific job (sent over status FIFO):
+Additional status codes sent only over status FIFO:
 
-PING           Trying to ping the host
+DONE           Done with the host (job equals "-")
+INIT           Host or job ready, preparing to execute jobs
 LOCKED         Host or job not available, because it is locked by another brun
-INIT           Host ready, preparing to execute jobs
-DONE           Done with the host
+PING           Trying to ping the host (job equals "-")
+SEND           Sending job to the host