gbch-jstat - report job status as exit code

# 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.