GBCH-JSTAT(1)

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
Note that the order of treatment, letters and keywords described below may be modified by editing the file F<btrest.help> - see btsyntax(5). 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.