gbch-jlist - display lists of batch jobs
gbch-jlist [ -options ] [ job numbers ]
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.
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
.
causes a summary of the other options to be displayed without taking further action.
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.
Revert the output format to the default format.
Changes the output format to conform to the pattern given by the format string. This is further described below.
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.
Generate a header for each column in the output.
Display only jobs local to the current host.
Cancel the -V option and view job parameters rather than job scripts.
Cancel the -H option. Do not print a header.
Cancel the -s option. Do not sort the jobs into the order in which they will run.
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.
displays jobs local to the current host and exported jobs on remote machines.
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.
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.
causes the output to be sorted so that the jobs whose next execution time is soonest comes at the top of the list.
Displays times and dates in full. This option is ignored if the -F option is specified.
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.
Do not display job details at all, output the scripts (input to the command interpreter) on standard output.
In conjunction with the -q parameter, do not include jobs with no queue prefix in the list.
In conjunction with the -q parameter, include jobs with no queue prefix in the list.
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.
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 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.
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.
Insert the argument list for job separated by commas.
Insert the ``days to avoid'' separated by commas.
Display job start time or time job last started.
Display conditions for job in full, showing operations and constants.
Display conditions for job with variable names only.
Working directory for job.
Delete time for job (in hours).
Environment variables for job. Note that this may make the output lines extremely long.
Export or Rem-runnable for exported jobs.
Last time job finished, or blank if it has not run yet.
Group owner of job.
Grace time for job (time after maximum run time to allow job to finish before final kill) in minutes and seconds.
Title of job including queue name (unless queue name restricted with -q option).
Title of job excluding queue name.
Command interpreter.
Process identifier if job running, otherwise blank. This is the process identifier on whichever processor is running the job.
Kill signal number at end of maximum run time.
Load level
Maximum run time for job, blank if not set.
Mode as a string of letters with U:
, G:
or O:
prefixes as in
U:RWSMPUVGHDK,G:RSMG,O:SM
.
Umask as 3 octal digits.
Job number, prefixed by host name if remote.
Originating host name, possibly different if submitted via gbch-rr(1) or the API.
Original date or time job submitted.
Job progress code, Run
, Done
etc.
Priority.
Job queue name.
Redirections.
Repeat specification.
Assignments in full with operator and constant.
Assignments (variable names only).
Date and time of next execution.
Abbreviated date or time if in next 24 hours.
User name of owner.
Ulimit (hexadecimal).
Start time if running, end time if just finished, otherwise next time to run.
Exit code ranges
Last exit code for job.
If ``avoiding holidays'' is set, display holiday dates for the next year.
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.
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
~/.gnubatch configuration file (home directory)
.gnubatch configuration file (current directory)
btrest.help message file
space-separated options to override defaults.
location of alternative help file.
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).
Various diagnostics are read and printed as required from the message file btrest.help.
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.
John M Collins, Xi Software Ltd.