=head1 NAME

gspl-qlist - display job queue

=head1 SYNOPSIS

B<gspl-qlist>
[ I<-options> ]
[ I<job number> ... ]

=head1 DESCRIPTION

B<gspl-qlist> outputs a table on standard output showing jobs on the
B<GNUspool> spool queue, including those queued on other hosts on the
network.

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 gspl-pq(1) command, something like:

 0024139     jmc report1 a4      23K 1 150
 0026921     jmc prgm.c  listing 12K 1 150
 red:0021941 pbt report  a4.lh   17K 2 150

The first field on each line is the numeric I<job number>, preceded
by a host name and a colon if on a remote machine.

Various options described below enable the user to control the output
in various ways. The job data itself may also be extracted.

To limit the output to information about a given job or jobs, job numbers may be
placed on the command line.

=head1 OPTIONS

=for man
Note that the order of treatment, letters and keywords described below
may be modified by editing the file \fIrest.help\fR \-
see \fIspsyntax\fR\|(5).

The environment variable on which options are supplied is C<GSPL_QLIST>
and the environment variable to specify the help file is
C<SPRESTCONF>.

=over 4

=item -? or +explain

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

=item -C I<nnnn> or +classcode I<nnnn>

restricts attention to jobs matching the class code given. This may be
reduced further by the user's class code unless he/she has I<override
class> privilege.

=item -D or +default-format

cancel a B<-F> option and restore the default format.

=item -e or +no-page-counts

do not try to represent page numbers and counts on the output (this
only affects the default format).

=item -E or +page-counts

do try to represent page numbers and counts on the output (this only
affects the default format).

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

Specify user defined output format. The	I<string> argument contains
characters to be printed and symbols representing the required data
fields. This option overrides and preceding B<-D> option, and is
itself overridden by a following B<-D> option.

=for html
<P>See <a href="#Gspl-Qlist_format">the section on format codes</a> for
details of the format code sequences.</P>

=for man
See the section on format codes below for details of the format code
sequences.

=item -H or +header

generate a header for each column of the output according to the field
displayed there. The headers are taken from the message file, by
default F<rest.help>, which may be adjusted as
required.

=item -l or +local-only

display only jobs local to the current host.

=item -N or +no-header

cancel the B<-H> option.

=item -n or +no-view-job

cancel the B<-V> option.

=item -P I<range> or +view-pages I<range>

with the B<-V> option, specify a range of pages to output.

A range may consist of single page numbers or subranges separated by
commas, thus:

	-V -P 1
	-V -P 1,3,4-9
	-V -P 2-7,12-

such arguments would respectively select page 1, pages 1, 3 and 4 to 9
and pages 2 to 7 and 12 to the end. Omitted numbers either side of the
B<-> denote "the beginning" and "the end".

=item -p or +printed-jobs

restricts attention to jobs which have been printed.

=item -q I<name> or +list-only I<name>

List only jobs for, or which could be printed on the specified subset
of printers. The set of printers may contain just one name, a list of
names or a list of patters for matching printer names. Shell-like
pattern matching applies to the pattern. You may well need to put
quotes around the pattern to avoid misinterpretation by the shell.

=for html
<P>This is further described in the <a href="#Gspl-Qlist_pattern">pattern
arguments</a> section.</P>

=for man
This is further described below.

To cancel this argument, give a single B<-> sign as an argument.

=item -r or +remotes

display jobs local to the current host and connected hosts.

=item -t I<string> or +just-title I<string>.

restricts attention to jobs whose title matches the pattern given.

=for html
<P>The pattern is further described in the <a href="#Gspl-Qlist_pattern">pattern
arguments</a> section.</P>

=for man
The pattern is further described below.

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

restricts attention to jobs owned by the given user or list of users
given by a pattern.

=for html
<P>The pattern is further described in the <a href="#Gspl-Qlist_pattern">pattern
arguments</a> section.</P>

=for man
The pattern is further described below.

=item -V or +view-job

cancel the job listing output and send the text of the job or jobs to
standard output.

=item -Y or +all-jobs

displays all jobs, canceling B<-y> or B<-p>.

=item -y or +unprinted-jobs

restricts attention to jobs which have not been printed.

=item -z or +include-null

when listing jobs restricted by a B<-q> argument, include jobs with no
destination printer.

=item -Z or +no-include-null

when listing jobs and printers restricted by a B<-q> argument, do not
include jobs without a destination printer.

=item +freeze-current

Save all the current options in a F<.gnuspool> file in the current
directory.

=item +freeze-home

Save all the current options in a F<.gnuspool> file in the user's home
directory.

=back

=head2 Patterns

=for html
<a name="Gspl-Qlist_pattern"></a>

The B<-q>, B<-t> and B<-u> options may all be given a name, a
comma-separated list of names or shell-like wildcard patterns. The
patterns all take the standard form:

=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
<div style="margin-left:1.0in;">
<table border=0 cellspacing=1 cellpadding=1 summary="wild cards">
<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>

Be careful to enclose these sequences in quotes in case the shell
misinterprets them.

For example

	gspl-qlist -q ljet,ptr3
	gspl-qlist -q 'ptr*,lp[1-9]'
	gspl-qlist -u 'j*'
	gspl-qlist -t 'Acc*'

=head2 Format codes

=for html
<a name="Gspl-Qlist_format"></a>

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, usually 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<%> sign

=item %A

C<wattn> if the write attention message flag is set.

=item %a

C<mattn> if the mail attention message flag is set.

=item %C

class code

=item %c

copies (right-justified)

=item %D

page delimiter

=item %d

delimiter number

=item %F

post-processing flags

=item %f

form type

=item %G

"halted at" page number.

=item %H

hold time

=item %h

job title.

=item %K

size of job in bytes

=item %L

position reached in bytes.

=item %l

C<local> if local job only

=item %m

C<mail> if mail completion flag set.

=item %N

job number, prefixed by host name if remote.

=item %O

odd/even/swap flags.

=item %o

originating host (might be different if via gspl-rpr(1)).

=item %P

printer destination

=item %p

priority.

=item %Q

page reached.

=item %q

C<retain> if retained on queue.

=item %R

page range.

=item %S

size in pages.

=item %s

C<nohdr> if header suppressed.

=item %T

delete time if not printed.

=item %t

delete time if printed.

=item %U

user name to be posted to.

=item %u

user name owned by

=item %W

submission or start time.

=item %w

C<write> if write completion message flag set.

=back

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

The default format is

	%N %u %h %f %Q %S %c %p %P

with the (default) B<-E> option and

	%N %u %h %f %L %K %c %p %P

with the B<-e> option.

=head1 FILES

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

F< .gnuspool>
configuration file (current directory)

F<rest.help>
message file

=head1 ENVIRONMENT

=over 4

=item GSPL_QLIST

space-separated options to override defaults.

=item SPRESTCONF

location of alternative help file.

=back

=head1 SEE ALSO

gspl-plist(1),
gspl-pq(1),
gspl-qchange(1),
gspl-qdel(1),
spsyntax(5),
gnuspool.conf(5),
gnuspool.hosts(5).

=head1 DIAGNOSTICS

Various diagnostics are read and printed as required from the message
file, by default F<rest.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:
## LocalWords:  gspl-qlist gspl-pq SPRESTCONF html
