.\" Copyright (C), 2012  Dave Love, University of Liverpool
.\" You may distribute this file under the terms of the GNU Free
.\" Documentation License.
.TH qevent 1 2012-01-09
.SH NAME
qevent \- subscribe and respond to Grid Engine events
.SH DESCRIPTION
.I qevent
subscribes to "events" generated by the Grid Engine system and loops
after writing its pid to the file
.IR qevent.pid .
It is used by the Grid Engine test suite, and otherwise can be used to
wait for a job or task to finish more efficiently than running
.I qstat
in a loop.  See the example below.
.SH SYNOPSIS
.B qevent
.RB [ \-h | \-help ]
.RB [ \-ts | \-testsuite ]
.RB [ \-sm | \-subscribe ]
.RB [ \-trigger
.I event script
.RB [ \-trigger
.I event
.IR script ],...]
.SH OPTIONS
.TP
.BR \-h ,\  \-help
Show usage
.TP
.BR \-ts ,\  \-testsuite
Run in test suite mode.
.TP
.BR \-sm ,\  \-subscribe
Run in subscribe mode, printing events from the system.
.TP
.BI \-trigger\  event \  script
Start executable 
.I script
when the specified
.I event
occurs.
.I script
gets three arguments: event name, job id, and task id.
.I event
is one of
.BR JB_END :
signals a job end;
.BR JB_TASK_END :
signals a job task end.
.SH FILES
.TP
.I qevent.pid
Id of the
.I qevent
process.
.SH EXAMPLE
This is an example of waiting for a job which could be used if the
.BR \-sync ,
.BR \-hold_jid ,
or
.B \-hold_jid_ad
options of
.I qsub
aren't sufficient.
.PP
.nf
    $ cat wait-for-job
    #!/bin/sh
    if [ "$2" = $JOBID ]; then
        echo Job $JOBID finished
        kill $(cat qevent.pid)
        exit 0
    fi
    $ export JOBID=`qsub -b y -terse sleep 30`
    $ qevent -trigger JB_END ./wait-for-job 
    Job 122837 finished
    $ 
.fi
.SH BUGS
Needs tidying up and extending.