=head1 NAME

gspool_jobdel - delete a job

=head1 SYNOPSIS

=for man
\&\fB#include <gspool.h>\fR
.PP

=for html
<STRONG>#include &lt;gspool.h&gt;</STRONG>
<br>

B<int gspool_jobdel(const int>
I<fd>B<, const unsigned>
I<flags>B<, const slotno_t>
I<slot>B<)>

=head1 DESCRIPTION

The B<gspool_jobdel()> function is used to delete a job, aborting it if it
is currently printing.

I<fd> is a file descriptor previously returned by B<gspool_open>

I<flags> is zero, or the logical OR of one or both of the following:

=over 8

=item GSPOOL_FLAG_IGNORESEQ

Ignore changes since the list was last read

=item GSPOOL_FLAG_FORCE

Ignore "not printed" flag

=back

I<slot> is the slot number corresponding to the job as previously
returned by B<gspool_joblist>, or B<gspool_jobfindslot>.

If the job has not been printed, and I<flags> does not contain
C<GSPOOL_FLAG_FORCE>, then the job will not be deleted, but the error
C<GSPOOL_NOT_PRINTED> will be reported. You can tell whether the job
has been printed from the C<struct apispq> job structure returned by B<xb_jobread>
or B<xb_jobfind>. The field C<apispq_dflags> has the bit designated by
C<APISPQ_PRINTED> set if it has been printed.

=head1 RETURN VALUES

=for html
<P>The function returns 0 if successful otherwise one of the error codes
<A HREF="TxtAPI-3.html#Error_codes">listed in Chapter 3</A>.</P>

=for man
The function \fBgspool_jobdel()\fR returns 0 if successful, otherwise one
of the following codes:
.Ip "GSPOOL_UNKNOWN_JOB" 8
job not found
.Ip "GSPOOL_INVALID_FD" 8
Invalid File descriptor
.Ip "GSPOOL_BADWRITE" 8
failure writing to the network
.Ip "GSPOOL_BADREAD" 8
failure reading from the network
.Ip "GSPOOL_NOPERM" 8
The user does not have permission
.Ip "GSPOOL_SEQUENCE" 8
sequence error, slot may be out of date
.Ip "GSPOOL_INVALIDSLOT" 8
Invalid slot number
.Ip "GSPOOL_NOT_PRINTED" 8
the job has not been printed

=head1 EXAMPLE

An example to delete all jobs:

 int fd, ret, nj, i;
 slotno_t *slots;

 fd = gspool_open("myhost", (char *) 0, 0);
 if (fd < 0) { /* error handling */
     ...
 }

 ret = gspool_joblist(fd, 0, &nj, &slots);
 if (ret < 0) { /* error handling */
     ...
 }

 for (i = 0; i < nj; i++) {
     ret = gspool_jobdel(fd, GSPOOL_FLAG_FORCE, slots[i]);
     if (ret < 0) { /* error handling */
         ...
     }
 }
 gspool_close(fd);

=head1 SEE ALSO

gspool_joblist(3),
gspool_jobread(3),
gspool_jobdata(3),
gspool_jobadd(3),
gspool_jobfind(3),
gspool_jobfindslot(3),
gspool_jobupd(3),
gspool_jobmon(3),
gspool_jobpbrk(3).

=head1 AUTHOR

John M Collins, Xi Software Ltd.

=cut

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