Job Status Triggers

A typical application is updating an external SQL database when a job is completed.

Triggers are different from post-commands. Triggers are executed by vovtriggerd, which is normally run by the user who owns vovserver. The owner of the account that was used to start vovserver is the owner of vovserver. Post-commands are executed by the user who owns each job.

The following table summarizes the information about vovtriggerd:

Config file: vnc.swd/vovtriggerd/config.tcl
Sample config file: $VOVDIR/etc/config/vovtriggerd/config.tcl
Info file: vnc.swd/vovtriggerd/info.tcl

Set Up vovtriggerd

vovtriggerd is a daemon that is configured as follows:

Create a subdirectory called vovtriggerd in the server configuration directory
Create a configuration file called config.tcl with the main purpose of overriding the procedure called triggerCallBack

Start the daemon:

% mkdir `vovserverdir -p vovtriggerd`
% cd `vovserverdir -p vovtriggerd`
% mkdir autostart
% cp $VOVDIR/etc/config/vovtriggerd/config.tcl .
% vovdaemonmgr start vovtriggerd

The TRIGGER Property

The default trigger handler looks for the property TRIGGER attached to the object mentioned in the event. If the property exists, it is assumed to be the name of a trigger procedure to be called. There are three arguments for the trigger procedure: id, subject, verb.

The trigger procedures are defined in the config.tcl file. Following are the guidelines for implementing a trigger:

The trigger is stateless.
The trigger is fast; it should complete within a few seconds.

Following is an example of using the TRIGGER property:

Create a trigger call-back in the config.tcl file. In the following example, it is named trigShowJobEventCB.

#
# This goes in PROJ.swd/vovtriggerd/config.tcl
#
proc trigShowJobEventCB { id subject verb } {
    puts "TrigShowJobEventCB: Just got the event $id $subject $verb"
}

Attach the property TRIGGER to jobs in the flow. Example:

% vovprop set -text 000123456 TRIGGER trigShowJobEventCB
% vovprop set -text 000234567 TRIGGER trigShowJobEventCB

Trigger Events

Following are the events that are processed by vovtriggerd:

JOBID "JOB" "DISPATCH", when the job is dispatched to a tasker.
JOBID "JOB" "ERROR", if the job fails.
JOBID "JOB" "STOP", if the job succeeds.

Handling the OVERFLOW Event

If the vovtriggerd daemon receives an overflow event (the verb is the string OVERFLOW), the procedure overflowCallBack is called with no arguments. The overflow event is an indication of a buffer overflow inside the vovserver, which is typically caused by vovtriggerd being too slow in processing the events. Depending on the situation, it may be useful to reinitialize the trigger callbacks.

Example of Submission of Jobs with Triggers

The following example applies to Accelerator:

A trigger can be submitted by setting the TRIGGER property. Knowing the name of the trigger callback routine to call is required. In the following example, the name of the trigger callback is updateDbCallBack.

% nc run -P TRIGGER=updateDbCallBack sleep 10

# Example of updateDbCallBack
# This procedure is defined in *.swd/vovtriggerd/config.tcl
# Here we update a table called "mytable" based on the 
# value of a property called MYPROP.
proc updateDbCallBack { jobid subject verb } {
    switch $verb {
        "STOP" - "ERROR" {
            if [catch {set value [vtk_prop_get $jobid "MYPROP"]}] {
                set value -1
            }

            set    stmt "INSERT INTO mytable (id,value)"
            append stmt " VALUES ( $jobid, $value)"
            VovSQL::init
            set handle [VovSQL::open]
            VovSQL::query $handle $stmt
            VovSQL::close $handle
        }
    }
}