=head1 NAME

gbch-jlist - display lists of batch jobs

=head1 SYNOPSIS

B<gbch-jlist>
[ I<-options> ]
[ job numbers ]

=head1 DESCRIPTION

B<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 I<job number> of the job, prefixed by
a machine name and colon if the job is on a machine other than the one
B<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.

=head1 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 C<GBCH_JLIST> and the
environment variable to specify the help file is C<BTRESTCONF>.

=over 4

=item -? or +explain

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

=item -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 I<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.

=item -D or +default-format

Revert the output format to the default format.

=item -F I<format string> or +format I<format string>

Changes the output format to conform to the pattern given by the
I<format string>. This is further described below.

=item -g I<group> or +just-group I<group>

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

=item -H or +header

Generate a header for each column in the output.

=item -L or +local-only

Display only jobs local to the current host.

=item -l or +no-view-jobs

Cancel the B<-V> option and view job parameters rather than job scripts.

=item -N or +no-header

Cancel the B<-H> option. Do not print a header.

=item -n or +no-sort

Cancel the B<-s> option. Do not sort the jobs into the order in which
they will run.

=item -q I<name> or +job-queue I<name>

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

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

=item -R or +include-all-remotes

displays jobs local to the current host and exported jobs on remote
machines.

=item -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 I<possibly> be executed
by the current machine.

=item -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
B<-F> option is specified.

=item -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.

=item -T or +full-times

Displays times and dates in full. This option is ignored if the
B<-F> option is specified.

=item -u I<user> +just-user I<user>

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

=item -V or +view-jobs

Do not display job details at all, output the scripts (input to the
command interpreter) on standard output.

=item -Z or +no-null-queues

In conjunction with the B<-q> parameter, do not include jobs with no
queue prefix in the list.

=item -z or +null-queues

In conjunction with the B<-q> parameter, include jobs with no queue
prefix in the list.

=item +freeze-current

Save all the current options in a F<.gnubatch> file in the current
directory with keyword C<BTJLIST>. There is no output if this is
specified, the options are just saved.

=item +freeze-home

Save all the current options in a F<.gnubatch> file in the user's home
directory with keyword C<BTJLIST>. There is no output if this is
specified, the options are just saved.

=back

=head2 Wild cards

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

=for man
.IP "*" 4
matches anything
.IP "?" 4
matches a single character
.IP "[a-mp-ru]" 4
.IX Item "[a-mp-ru]"
matches any one character in the range of characters given
.IP "[!n-z9]" 4
.IX Item "[!n-z9]"
matches any one character not in the range of characters given

=for html
<a name="Selection_wild_cards"></a>
<div style="margin-left:1.0in;">
<table border=0 cellspacing=1 cellpadding=1 summary="Btjlist matches">
<tr>
<td><span class=FileName>*</span></td>
<td>matches anything</td>
</tr>
<tr>
<td><span class=FileName>?</span></td>
<td>matches a single character</td>
</tr>
<tr>
<td><span class=FileName>[a-mp-ru]</span></td>
<td>matches any one character in the range of characters given</td>
</tr>
<tr>
<td><span class=FileName>[!n-z9]</span></td>
<td>matches any one character not in the range of characters given</td>
</tr>
</table>
</div>

Alternatives may be included, separated by commas. For example

	-q 'a*'

displays jobs with queue prefixes starting with C<a>

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

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

	-u jmc,tony

displays jobs owned by C<jmc> or C<tony>

	-g 's*'

displays jobs owned by groups with names starting C<s>.

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

=head2 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.

=over 4

=item %%

Insert a single C<%> character.

=item %A

Insert the argument list for job separated by commas.

=item %a

Insert the "days to avoid" separated by commas.

=item %b

Display job start time or time job last started.

=item %C

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

=item %c

Display conditions for job with variable names only.

=item %D

Working directory for job.

=item %d

Delete time for job (in hours).

=item %E

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

=item %e

B<Export> or B<Rem-runnable> for exported jobs.

=item %f

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

=item %G

Group owner of job.

=item %g

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

=item %H

Title of job including queue name (unless queue name restricted with
B<-q> option).

=item %h

Title of job excluding queue name.

=item %I

Command interpreter.

=item %i

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

=item %k

Kill signal number at end of maximum run time.

=item %L

Load level

=item %l

Maximum run time for job, blank if not set.

=item %M

Mode as a string of letters with C<U:>, C<G:> or C<O:> prefixes as in
C<U:RWSMPUVGHDK,G:RSMG,O:SM>.

=item %m

Umask as 3 octal digits.

=item %N

Job number, prefixed by host name if remote.

=item %O

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

=item %o

Original date or time job submitted.

=item %P

Job progress code, C<Run>, C<Done> etc.

=item %p

Priority.

=item %q

Job queue name.

=item %R

Redirections.

=item %r

Repeat specification.

=item %S

Assignments in full with operator and constant.

=item %s

Assignments (variable names only).

=item %T

Date and time of next execution.

=item %t

Abbreviated date or time if in next 24 hours.

=item %U

User name of owner.

=item %u

Ulimit (hexadecimal).

=item %W

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

=item %X

Exit code ranges

=item %x

Last exit code for job.

=item %Y

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

=item %y

Last signal number for job.

=back

Note that the various strings such as B<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) B<-S> option and

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

with the B<-T> option.

=head1 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 I<read> permission on a job, then only
limited information is displayed.

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

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

=head1 FILES

F<~/.gnubatch>
configuration file (home directory)

F<.gnubatch>
configuration file (current directory)

F<btrest.help>
message file

=head1 ENVIRONMENT

=over 4

=item GBCH_JLIST

space-separated options to override defaults.

=item BTRESTCONF

location of alternative help file.

=back

=head1 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).

=head1 DIAGNOSTICS

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

=head1 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.

=head1 AUTHOR

John M Collins, Xi Software Ltd.

=cut

## Local Variables:
## mode: nroff
## End:
