GBCH-JLIST(1)

NAME
gbch-jlist - display lists of batch jobs

SYNOPSIS
gbch-jlist [ -options ] [ job numbers ]

DESCRIPTION
gbch-jlist is a program to display a summary of the jobs (or to be precise the jobs visible to the user) on the standard output.

Each line of the output corresponds to a single job, and by default the output is generally similar to the default format of the jobs screen of the gbch-q(1) command. The first field on each line (unless varied as below) is the numeric job number of the job, prefixed by a machine name and colon if the job is on a machine other than the one gbch-jlist is run on, job thus:

        3493
        macha:9239
        machb:19387

This is the required format of the job number which should be passed to gbch-jdel(1) and gbch-jchange(1).

Various options allow the user to control the output in various ways as described below. The user can limit the output to specific jobs by giving the job numbers as additional arguments.

OPTIONS
Note that the order of treatment, letters and keywords described below may be modified by editing the file btrest.help - see btsyntax(5).

The environment variable on which options are supplied is "GBCH_JLIST" 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.

-B or +bypass-modes
    Disregard all modes etc and print full details. This is provided for dump/restore scripts. It is only available to users with Write Admin File permission, otherwise it is silently ignored. This option is now deprecated as gbch-cjlist(8) is now provided for the purpose for which this option was implemented.

-D or +default-format
    Revert the output format to the default format.

-F format string or +format format string
    Changes the output format to conform to the pattern given by the format string. This is further described below.

-g group or +just-group group
    Restrict the output to jobs owned by the group specified, or groups specified with shell-like wild cards as described below. To cancel this argument, give a single - sign as a group name.

-H or +header
    Generate a header for each column in the output.

-L or +local-only
    Display only jobs local to the current host.

-l or +no-view-jobs
    Cancel the -V option and view job parameters rather than job scripts.

-N or +no-header
    Cancel the -H option. Do not print a header.

-n or +no-sort
    Cancel the -s option. Do not sort the jobs into the order in which they will run.

-q name or +job-queue name
    Restricts attention to jobs with the queue prefix name. The queue may be specified as a pattern with shell-like wild cards as described below. To cancel this argument, give a single - sign as a queue name.

    The queue prefix is deleted from the titles of jobs which are displayed.

-R or +include-all-remotes
    displays jobs local to the current host and exported jobs on remote machines.

-r or +include-exec-remotes
    displays jobs local to the current host and jobs on remote machines which are remote-executable, i.e. which might possibly be executed by the current machine.

-S or +short-times
    Displays times and dates in abbreviated form, i.e. times within the next 24 hours as times, otherwise dates. This option is ignored if the -F option is specified.

-s or +sort
    causes the output to be sorted so that the jobs whose next execution time is soonest comes at the top of the list.

-T or +full-times
    Displays times and dates in full. This option is ignored if the -F option is specified.

-u user +just-user user
    Restrict the output to jobs owned by the user specified. The user name may be a pattern with shell-like wild cards as described below. To cancel this argument, give a single - sign as a user name.

-V or +view-jobs
    Do not display job details at all, output the scripts (input to the command interpreter) on standard output.

-Z or +no-null-queues
    In conjunction with the -q parameter, do not include jobs with no queue prefix in the list.

-z or +null-queues
    In conjunction with the -q parameter, include jobs with no queue prefix in the list.

+freeze-current
    Save all the current options in a .gnubatch file in the current directory with keyword "BTJLIST". There is no output if this is specified, the options are just saved.

+freeze-home
    Save all the current options in a .gnubatch file in the user's home directory with keyword "BTJLIST". There is no output if this is specified, the options are just saved.

  Wild cards
Wild cards in queue, user and group name arguments take a format similar to the shell.

*   matches anything

?   matches a single character

[a-mp-ru]
    matches any one character in the range of characters given

[!n-z9]
    matches any one character not in the range of characters given

Alternatives may be included, separated by commas. For example

        -q 'a*'

displays jobs with queue prefixes starting with "a"

        -q '[p-t]*,*[!h-m]'

displays jobs with queue prefixes starting with "p" to "t" or ending with anything other than "h" to "m".

        -u jmc,tony

displays jobs owned by "jmc" or "tony"

        -g 's*'

displays jobs owned by groups with names starting "s".

You should always put quotes around arguments containing the wildcard characters, to avoid misinterpretation by the shell.

  Format codes
The format string consists of a string containing the following character sequences, which are replaced by the corresponding job parameters. The string may contain various other printing characters or spaces as required.

Each column is padded on the right to the length of the longest entry. If a header is requested, the appropriate abbreviation is obtained from the message file and inserted.

%%  Insert a single "%" character.

%A  Insert the argument list for job separated by commas.

%a  Insert the "days to avoid" separated by commas.

%b  Display job start time or time job last started.

%C  Display conditions for job in full, showing operations and constants.

%c  Display conditions for job with variable names only.

%D  Working directory for job.

%d  Delete time for job (in hours).

%E  Environment variables for job. Note that this may make the output lines extremely long.

%e  Export or Rem-runnable for exported jobs.

%f  Last time job finished, or blank if it has not run yet.

%G  Group owner of job.

%g  Grace time for job (time after maximum run time to allow job to finish before final kill) in minutes and seconds.

%H  Title of job including queue name (unless queue name restricted with -q option).

%h  Title of job excluding queue name.

%I  Command interpreter.

%i  Process identifier if job running, otherwise blank. This is the process identifier on whichever processor is running the job.

%k  Kill signal number at end of maximum run time.

%L  Load level

%l  Maximum run time for job, blank if not set.

%M  Mode as a string of letters with "U:", "G:" or "O:" prefixes as in "U:RWSMPUVGHDK,G:RSMG,O:SM".

%m  Umask as 3 octal digits.

%N  Job number, prefixed by host name if remote.

%O  Originating host name, possibly different if submitted via gbch-rr(1) or the API.

%o  Original date or time job submitted.

%P  Job progress code, "Run", "Done" etc.

%p  Priority.

%q  Job queue name.

%R  Redirections.

%r  Repeat specification.

%S  Assignments in full with operator and constant.

%s  Assignments (variable names only).

%T  Date and time of next execution.

%t  Abbreviated date or time if in next 24 hours.

%U  User name of owner.

%u  Ulimit (hexadecimal).

%W  Start time if running, end time if just finished, otherwise next time to run.

%X  Exit code ranges

%x  Last exit code for job.

%Y  If "avoiding holidays" is set, display holiday dates for the next year.

%y  Last signal number for job.

Note that the various strings such as export etc are read from the message file also, so it is possible to modify them as required by the user.

Only the job number, user, group, originating host and progress fields will be non-blank if the user may not read the relevant job. The mode field will be blank if the user cannot read the modes.

The default format is

        %N %U %H %I %p %L %t %c %P

with the (default) -S option and

        %N %U %H %I %p %L %T %c %P

with the -T option.

EXAMPLES
The default output might look like this:

 15367 jmc  Go-to-optician  memo 150 100  10/08
 25874 uucp dba:Admin       sh   150 1000 11:48      Done
 25890 uucp dba:Uuclean     sh   150 1000 23:45
 25884 uucp dba:Half-hourly sh   150 1000 10:26 Lock
 26874 adm

If the user does not have read permission on a job, then only limited information is displayed.

This might be limited to a different format with only jobs in queue "dba" as follows:

        $ gbch-jlist -q dba -Z -H -F "%N %H %P"
        Jobno Title       Progress
        25874 Admin       Done
        25890 Uuclean
        25884 Half-hourly

FILES
~/.gnubatch configuration file (home directory)

.gnubatch configuration file (current directory)

btrest.help message file

ENVIRONMENT

GBCH_JLIST
    space-separated options to override defaults.

BTRESTCONF
    location of alternative help file.

SEE ALSO
btsyntax(5), gnubatch.conf(5), gnubatch.hosts(5), gbch-r(1), gbch-rr(1), gbch-jchange(1), gbch-jdel(1), gbch-jstat(1), gbch-vlist(1), gbch-cjlist(8), gbch-cvlist(8).

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.