| 9th October 2007 |
The progress of each job should be recorded and stored as follows:
Excerpts from the history can be read via the TCP interface.
The History Table Columns
| id | The Unique Task Identifier (the primary table key) |
| spooler_id | Scheduler Id |
| job_name | Job name |
| start_time | Start time (yyyy-mm-dd HH:MM:SS) |
| end_time | End time (yyyy-mm-dd HH:MM:SS) |
| steps | Number of spooler_process() steps |
| cause | Cause of start |
| error | 0: No error; 1: Error |
| error_code | Error code |
| error_text | Error text |
| parameters | Job parameters (if available) as XML document (Clob) |
| log | Job protocol (not in the tab-separated file when operating without a database) |
The history can either be written in a simple file or recorded in a database.
A record file in the protocol file folder (Option -log-dir=) is created for every job. Fields in this file are separated by tabulator characters. An entry is made at the start of a job, which is then overwritten with the complete data after the job has ended.
The file name is: log_dir/history. scheduler_id.job. jobname.txt
The file is rewritten each time the Job Scheduler is started. A previously existing file can be renamed and/or compressed before a Job Scheduler start.
The Job Scheduler writes column names in the first row of the file.
Tab characters in the file (resulting from error messages) are suppressed.
Every field has a maximum length of 1024 characters. Longer entries are cut off.
Archiving
Existing history files are overwritten when the Job Scheduler is started.
However, these files can be archived using the history_archive entry in the
factory.ini:
[spooler] history_archive = yes|no|gzip [Job jobname] history_archive = yes|no|gzip
history_archive=yes renames a history file. Note that this command causes the file name to be extended with an (exact to the second) time stamp.
history_archive=gzip compresses the file using
zlib (gzip) from Jean-loup Gailly (http://www.gzip.org/zlib/).
The file name ending is thereby extended with .gz.
The resulting file can be decompressed using gzip.
It is however also readable using Hostware with
"nl | gzip | history.gz".
All data is written in a database table. The task protocol is written in a blob.
The table name is spooler_history. If this file does not exist, then a database with the same name is created. If the database table spooler_history does not exist, then it will be created (only for MS Access databases).
The table names can be set in the factory.ini configuration file:
[spooler] db_history_table = tabellenname | SCHEDULER_HISTORY db_variables_table = tabellenname | SCHEDULER_VARIABLES
The next free job number is held in an entry in the SCHEDULER_VARIABLES table.
The need_db=no entry is used to allow the Job Scheduler to start when the history database cannot be opened. The default setting here is need_db=yes.
[spooler] db = odbc -db=schedul er need_db = no
When only a database file name is specified with db= and log_dir=*stderr is set, then the database cannot be opened because of the missing directory. In this case the Job Scheduler does not start if need_db=yes is set.
Automatic Creation of a MS Access Database
Should only a simple file name be specified with db=, then the Job Scheduler can automatically create a Microsoft MS Access database when "odbc -create" is set (see ODBC file type).
The SCHEDULER_HISTORY and SCHEDULER_VARIABLES tables are used in the database. These tables are created as necessary using the Microsoft Access SQL syntax.
Job Scheduler Start Entry
The Job Scheduler makes an entry in the history with its own ID on starting. On ending, the Job Scheduler writes the time in this entry, so that both start and end times are noted. The job name is "(Spooler)".
The following parameters can be set in the factory.ini configuration file:
[spooler] db = database db_history_table = SCHEDULER_HISTORY db_variables_table = SCHEDULER_VARIABLES history = no|yes history_columns = field1, field2, ... history_on_process = yes|1|2 history_with_log = no|yes|gzip history_archive = no|yes|gzip [Job jobname] history = no|yes history_file = filename history_columns = field1, field2, ... history_on_process = yes|1|2 history_with_log = no|yes|gzip history_archive = no|yes|gzip
Settings made in [Job jobname] have priority over those made in [spooler].
history=no suppresses the history. Should a database be specified, however, the entry for the start of the Job Scheduler will still be made.
history_on_process sets the number of requests of spooler_process() which can be made before an entry is made in the history. Should spooler_open return false, then an entry will not be made when history_on_process is set to 1.
history_with_log allows the task protocol to be recorded in the database as well. The protocol may be compressed if desired.
The cause of a job start is noted in a row in the history:
| Event Code | Meaning |
|---|---|
| none | The task has not started (this is not noted in the history) |
| period_once | <run_time once="yes"> |
| period_single | <run_time single_start="..."> |
| period_repeat | <run_time repeat="..."> |
| job_repeat | spooler_job.repeat=... |
| queue | spooler_job.start() oder <start_job> |
| queue_at | as queue, with specified start time (Option at) |
| directory | Directory monitoring (start_when_directory_changed) has started the job |
| signal | <signal_object> |
| delay_after_error | spooler_job.delay_after_error |
Every task has an identifier. When a database is used, the Job Scheduler obtains this identifier from the SCHEDULER_VARIABLES table. This identifier is then unique to all Job Schedulers which use this database table. Otherwise consecutive numbers are given. The first task is given the number 1.
The identifier can then be recalled in scripts, which use the Job Scheduler API, with the id property:
meine_id = spooler_task.id
The history can accept further fields which the job can fill:
spooler_task.history_field( "fieldname" ) = value
The fieldname must be declared as a row in the tabular file or in the history table. The case used here is irrelevant.
When the history is recorded in a database, then it may be significant which type a value is, in particular if it is a number or a character string.
Extra fields must be declared in the factory.ini configuration file
[spooler] history_columns = columnlist [Job jobname] history_columns = columnlist
The columnlist is a list of column names, separated by columns and which is included in the tabular file.
Extra rows in the history table are automatically recognized.
When the Job Scheduler creates the SCHEDULER_HISTORY table, it also creates the necessary rows as defined in history_columns. These rows are defined as char(250) type.
<show_history job="jobname" prev="number|all "what="all"/>
Returns, for the current job jobname, the last number of entries in the history, sorted in reverse order. The default value for number is 10. All entries are read when tail="all" is set. Note that this function requires a lot of memory. This is because the history is compiled as an XML document with the DOM in the main memory. A maximum of 1000 entries will be returned.
what="all" returns the job protocol as well.
Extracts out of the history can be read using the following
(note that the what attribute can always be used here):
to obtain the number of entries before the ID:
<show_history job="jobname" id="id" prev="number"/>
to obtain the number of entries after the ID:
<show_history job="jobname" id="id" next="number"/>
to obtain only the id entry:
it is recommended that the job protocol for a particular task is read with what="all".
<show_history job="jobname" id="id"/>
The result looks like:
<history>
<history.entry id="identifier" job="jobname" start_time="starttime" end_time="end time" ...>
<variableset>
<variable name="name1" value="value1"/>
<variable name="name2" value="value2"/>
</variableset>
<log>Jobprotocol</log>
</history.entry>
<history.entry ...>
...
</history.entry>
...
</history>
Errors on opening or writing the history are noted in the Job Scheduler protocol and otherwise ignored.