=head1 NAME

gspl-qdel - delete spool jobs

=head1 SYNOPSIS

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

=head1 DESCRIPTION

B<gspl-qdel> deletes one or more jobs from the B<GNUspool> job spool queue,
which may be on the local host or other hosts on the network. Jobs are
specified by the job number, which is reported by gspl-qlist(1) in the
first column of the default output, or by gspl-pr(1) or gspl-rpr(1) when the
job is queued with the I<verbose> option. Remote jobs are specified by
prefixing the job number by the host name and a colon, thus
C<host:1234>. Leading zeroes in the job number may be omitted.

B<Gspl-qdel> will not delete jobs not marked as "printed" unless the B<-y>
option is given.

=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_QDEL> 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>

may be used to set a class code to narrow or expand the range of jobs
from which jobs are selected. It is probably only relevant where the
user has I<override class> privilege and it is required to expand the
default class code to select additional jobs.

=item -d or +delete

cancel a previously-specified B<-k> option.

=item -D I<name> or +directory I<name>

Save unqueued jobs to I<name> rather than the current directory.

=item -e or +do-not-unqueue

cancel a previously-specified B<-u> option. The jobs will just be
deleted, not unqueued.

=item -J I<name> or +job-prefix I<name>

specify the given I<name> as the prefix for the job file, followed
by the job number, to be used by the B<-u> option rather than the
default of B<J> (which in turn may be changed by editing the
message file).

=item -k or +do-not-delete

when performing an unqueue as specified with the B<-u> option, do not
delete the job at the end.

=item -n or +keep-unprinted

is the default case. Jobs which have not yet been printed are not
deleted.

=item -S I<name> or +command-prefix I<name>

specify the given I<name> as the prefix for the command file, followed
by the job number, to be used by the B<-u> option rather than the
default of B<C> (which in turn may be changed by editing the
message file).

=item -u or +unqueue

unqueue jobs, i.e. copy to current directory or directory selected
with the B<-D> option. Jobs are copied as two files, a I<job file>
containing the text of the job and a I<command file> containing an
B<gspl-pr> command. The command file may be run as a shell script to
re-queue the job with the same options.

=item -y or +delete-unprinted

cancels all jobs, whether printed or not.

=item +freeze-current

Save all the current options in a F<.gnuspool> file in the current
directory. If there are no jobs given to operate on and this is
specified, then B<gspl-qdel> will quit without error. If it is unable
to save the options and jobs are specified, then B<gspl-qdel> will
continue.

=item +freeze-home

Save all the current options in a F<.gnuspool> file in the user's home
directory. If there are no jobs given to operate on and this is
specified, then B<gspl-qdel> will quit without error. If it is unable
to save the options and jobs are specified, then B<gspl-qdel> will
continue.

=back

=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_QDEL

space-separated options to override defaults.

=item SPRESTCONF

location of alternative help file.

=back

=head1 SEE ALSO

gspl-rpr(1),
gspl-pr(1),
gspl-pq(1),
gspl-qchange(1),
gspl-qlist(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 NOTES

The B<-C> option selects the class code for finding the jobs; if you
have I<override class> privilege, but your default class code does not
allow the jobs "to be seen" in the output of gspl-qlist(1), then you may
need to specify this.

Any errors are reported with appropriate messages on standard
error. If any errors are detected operating on several jobs, the exit
code will correspond to the last such error displayed.

=head1 AUTHOR

John M Collins, Xi Software Ltd.

=cut

## Local Variables:
## mode: nroff
## End:
## LocalWords:  gspl-qdel gspl-qlist gspl-pr gspl-rpr classcode SPRESTCONF
