NAME

gbch-jstat - report job status as exit code


SYNOPSIS

gbch-jstat [ -options ] jobnumber


DESCRIPTION

gbch-jstat is provided to enable shell scripts to determine the status of a single job.

The jobs is specified by using the job number, as displayed by gbch-r(1) with the -v (verbose) option, or as in the output of the first column of the gbch-jlist(1) command with default format.

A remote job should be specified by prefixing the job number with the host name thus:

        host:1234

It is not necessary to include any leading zeroes.

By default, the job is checked to see if it is running, just starting or just finishing, but by means of the -s option, the user can specify which states to test for.

Btjstat returns an exit code of 0 (true to shells) if the job is in the given state, 1 if it is not, and some other exit code (and a diagnostic) if some other error occurs, e.g. the job does not exist.


OPTIONS

The environment variable on which options are supplied is BTJSTAT and the environment variable to specify the help file is BTRESTCONF.

-? or +explain

Causes a summary of the other options to be displayed without taking further action.

-d or +default-states

Cancel a -s option and revert to checking whether the job is running, just starting or just finishing.

-s statecodes or +state statecodes

Specify statecodes as the states to be tested for. statecodes is a comma-separated list of states exactly as reported by gbch-jlist(1). (The strings are read from the message file, and can be altered if required). As distributed, they are

empty string

Ready to run, represented if necessary by two quotes, or an empty field preceding a comma, as in

        gbch-jstat -s '' 1234
        gbch-jstat -s ,Done 1234
Done

Normal exit

Err

Error exit

Abrt

Aborted

Canc

Cancelled

Init

Startup stage 1 (included in the default case)

Strt

Startup stage 2 (included in the default case)

Run

Running (included in the default case)

Fin

Terminating (included in the default case)

The state names are case insensitive. If one (typically the ``ready to run'' state) is a null string, then this can be tested for by using a null string or two consecutive commas, thus:

        -s ''
        -s ,canc
+freeze-current

Save all the current options in a .gnubatch file in the current directory.

+freeze-home

Save all the current options in a .gnubatch file in the user's home directory.


EXAMPLE

The following shell script displays a list of the titles of jobs ready to run or running

        gbch-jlist -F '%N %H'|while read num title
        do
        if gbch-jstat -s '' $num
        then
                echo $title is ready to run
        elif gbch-jstat $num
        then
                echo $title is running
        fi
        done


FILES

~/.gnubatch configuration file (home directory)

.gnubatch configuration file (current directory)

/usr/spool/progs/btrest.help message file


ENVIRONMENT

GBCH_JSTAT

space-separated options to override defaults.

BTRESTCONF

location of alternative help file.


SEE ALSO

gbch-jlist(1), gbch-jchange(1), btsyntax(5), gnubatch.conf(5), gnubach.hosts(5).


DIAGNOSTICS

Various diagnostics are read and printed as required from the message file btrest.help.


COPYRIGHT

Copyright (c) 2009 Free Software Foundation, Inc. This is free software. You may redistribute copies of it under the terms of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>. There is NO WARRANTY, to the extent permitted by law.


AUTHOR

John M Collins, Xi Software Ltd.