=head1 NAME

gspool_jobread - get the details of 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_jobread(const int>
I<fd>B<, const unsigned>
I<flags>B<, const slotno_t>
I<slot>B<, struct apispq *>I<jobd>B<)>

=head1 DESCRIPTION

The B<gspool_jobread()> function is used to retrieve the details of a job
from a given slot number.

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

I<flags> is zero, or a logical OR of one or more of the following values

=over 4

=item GSPOOL_FLAG_LOCALONLY

Ignore remote printers/hosts, i.e. not local to the server, not the
client.

=item GSPOOL_FLAG_USERONLY

Ignore other users jobs

=item GSPOOL_FLAG_IGNORESEQ

Ignore changes since the list was last read

=back

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

I<jobd> is a descriptor, which on return will contain the details of
the job in a C<struct apispq> as defined in F<gspool.h> and containing
the following elements:

=for html
<A NAME="Apispq_def"></a>
<div class=indtab>
<table border=0 cellpadding=1 cellspacing=0 summary="spq fields">
<tr>
<th align=left class=dense>Type</th>
<th align=left class=dense>Field</th>
<th align=left class=dense>Description</th>
</tr>
<tr>
<td class=dense><span class=FileName>jobno_t</span></td>
<td class=dense><span class=FileName>apispq_job</span></td>
<td class=dense>Job number</td>
</tr>
<tr>
<td class=dense><span class=FileName>netid_t</span></td>
<td class=dense><span class=FileName>apispq_netid</span></td>
<td class=dense>Host address (network byte order)</td>
</tr>
<tr>
<td class=dense><span class=FileName>netid_t</span></td>
<td class=dense><span class=FileName>apispq_orighost</span></td>
<td class=dense>Originating host address</td>
</tr>
<tr>
<td class=dense><span class=FileName>slotno_t</span></td>
<td class=dense><span class=FileName>apispq_rslot</span></td>
<td class=dense>Slot number on owning machine</td>
</tr>
<tr>
<td class=dense><span class=FileName>time_t</span></td>
<td class=dense><span class=FileName>apispq_time</span></td>
<td class=dense>Time job was submitted</td>
</tr>
<tr>
<td class=dense><span class=FileName>time_t</span></td>
<td class=dense><span class=FileName>apispq_starttime</span></td>
<td class=dense>Time job was started (if applicable)</td>
</tr>
<tr>
<td class=dense><span class=FileName>time_t</span></td>
<td class=dense><span class=FileName>apispq_hold</span></td>
<td class=dense>Time job held to, 0 if not held</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned short</span></td>
<td class=dense><span class=FileName>apispq_nptimeout</span></td>
<td class=dense>Time after to delete job if not printed (hours)</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned short</span></td>
<td class=dense><span class=FileName>apispq_ptimeout</span></td>
<td class=dense>Time after to delete job if printed (hours)</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned short</span></td>
<td class=dense><span class=FileName>apispq_extrn</span></td>
<td class=dense>External job type index</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned short</span></td>
<td class=dense><span class=FileName>apispq_pglim</span></td>
<td class=dense>Job size limit applies</td>
</tr>
<tr>
<td class=dense><span class=FileName>long</span></td>
<td class=dense><span class=FileName>apispq_size</span></td>
<td class=dense>Size of job in bytes</td>
</tr>
<tr>
<td class=dense><span class=FileName>long</span></td>
<td class=dense><span class=FileName>apispq_posn</span></td>
<td class=dense>Offset reached if currently being printed</td>
</tr>
<tr>
<td class=dense><span class=FileName>long</span></td>
<td class=dense><span class=FileName>apispq_pagec</span></td>
<td class=dense>Currently-reached page if being printed</td>
</tr>
<tr>
<td class=dense><span class=FileName>char[]</span></td>
<td class=dense><span class=FileName>apispq_uname</span></td>
<td class=dense>User name of job owner</td>
</tr>
<tr>
<td class=dense><span class=FileName>char[]</span></td>
<td class=dense><span class=FileName>apispq_puname</span></td>
<td class=dense>User name of posting user</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned char</span></td>
<td class=dense><span class=FileName>apispq_cps</span></td>
<td class=dense>Copies</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned char</span></td>
<td class=dense><span class=FileName>apispq_pri</span></td>
<td class=dense>Priority</td>
</tr>
<tr>
<td class=dense><span class=FileName>classcode_t</span></td>
<td class=dense><span class=FileName>apispq_class</span></td>
<td class=dense>Class code bits 1=A 2=B 4=C etc</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned short</span></td>
<td class=dense><span class=FileName>apispq_jflags</span></td>
<td class=dense>Job flags</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned char</span></td>
<td class=dense><span class=FileName>apispq_dflags</span></td>
<td class=dense>Despooler flags</td>
</tr>
<tr>
<td class=dense><span class=FileName>slotno_t</span></td>
<td class=dense><span class=FileName>apispq_pslot</span></td>
<td class=dense>Printer slot assigned to if printing</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned long</span></td>
<td class=dense><span class=FileName>apispq_start</span></td>
<td class=dense>Start page 0=first page</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned long</span></td>
<td class=dense><span class=FileName>apispq_end</span></td>
<td class=dense>End page</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned long</span></td>
<td class=dense><span class=FileName>apispq_npages</span></td>
<td class=dense>Number of pages</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned long</span></td>
<td class=dense><span class=FileName>apispq_haltat</span></td>
<td class=dense>"Halted at" page</td>
</tr>
<tr>
<td class=dense><span class=FileName>char []</span></td>
<td class=dense><span class=FileName>apispq_file</span></td>
<td class=dense>Job title</td>
</tr>
<tr>
<td class=dense><span class=FileName>char []</span></td>
<td class=dense><span class=FileName>apispq_form</span></td>
<td class=dense>Job form type</td>
</tr>
<tr>
<td class=dense><span class=FileName>char []</span></td>
<td class=dense><span class=FileName>apispq_ptr</span></td>
<td class=dense>Printer pattern assigned to job</td>
</tr>
<tr>
<td class=dense><span class=FileName>char []</span></td>
<td class=dense><span class=FileName>apispq_flags</span></td>
<td class=dense>Post-processing flags</td>
</tr>
</table>
</div>

=for man
.Ip "jobno_t apispq_job" 8
Job number
.Ip "netid_t apispq_netid" 8
Host address (network byte order)
.Ip "netid_t apispq_orighost" 8
Originating host address
.Ip "slotno_t apispq_rslot" 8
Slot number on owning machine
.Ip "time_t apispq_time" 8
Time job was submitted
.Ip "time_t apispq_starttime" 8
Time job was started (if applicable)
.Ip "time_t apispq_hold" 8
Time job held to, 0 if not held
.Ip "unsigned short apispq_nptimeout" 8
Time after to delete job if not printed (hours)
.Ip "unsigned short apispq_ptimeout" 8
Time after to delete job if printed (hours)
.Ip "unsigned short apispq_extrn" 8
External job type index
.Ip "unsigned short apispq_pglim" 8
Job size limit applies
.Ip "long apispq_size" 8
Size of job in bytes
.Ip "long apispq_posn" 8
Offset reached if currently being printed
.Ip "long apispq_pagec" 8
Currently-reached page if being printed
.Ip "char apispq_uname[]" 8
User name of job owner
.Ip "char apispq_puname[]" 8
User name of posting user
.Ip "unsigned char apispq_cps" 8
Copies
.Ip "unsigned char apispq_pri" 8
Priority
.Ip "classcode_t apispq_class" 8
Class code bits 1=A 2=B 4=C etc
.Ip "unsigned short apispq_jflags" 8
Job flags
.Ip "unsigned char apispq_dflags" 8
Despooler flags
.Ip "slotno_t apispq_pslot" 8
Printer slot assigned to if printing
.Ip "unsigned long apispq_start" 8
Start page 0=first page
.Ip "unsigned long apispq_end" 8
End page
.Ip "unsigned long apispq_npages" 8
Number of pages
.Ip "unsigned long apispq_haltat" 8
"Halted at" page
.Ip "char apispq_file[]" 8
Job title
.Ip "char apispq_form[]" 8
Job form type
.Ip "char apispq_ptr[]" 8
Printer pattern assigned to job
.Ip "char apispq_flags[]" 8
Post-processing flags

The following bits are set in the C<apispq_jflags> field to indicate
job parameters:

=for html
<div class=indtab>
<table border=0 cellpadding=1 cellspacing=0 summary="job flags">
<tr>
<th align=left class=dense>Bit (#define)</th>
<th align=left class=dense>Meaning</th>
</tr>
<tr>
<td class=dense><span class=FileName>APISPQ_NOH</span></td>
<td class=dense>Suppress header</td>
</tr>
<tr>
<td class=dense><span class=FileName>APISPQ_WRT</span></td>
<td class=dense>Write result</td>
</tr>
<tr>
<td class=dense><span class=FileName>APISPQ_MAIL</span></td>
<td class=dense>Mail result</td>
</tr>
<tr>
<td class=dense><span class=FileName>APISPQ_RETN</span></td>
<td class=dense>Retain on queue after printing</td>
</tr>
<tr>
<td class=dense><span class=FileName>APISPQ_ODDP</span></td>
<td class=dense>Suppress odd pages</td>
</tr>
<tr>
<td class=dense><span class=FileName>APISPQ_EVENP</span></td>
<td class=dense>Suppress even pages</td>
</tr>
<tr>
<td class=dense><span class=FileName>APISPQ_REVOE</span></td>
<td class=dense>Invert <span class=FileName>APISPQ_ODDP</span> and <span class=FileName>API_EVENP</span> after printing</td>
</tr>
<tr>
<td class=dense><span class=FileName>APISPQ_MATTN</span></td>
<td class=dense>Mail attention</td>
</tr>
<tr>
<td class=dense><span class=FileName>APISPQ_WATTN</span></td>
<td class=dense>Write attention</td>
</tr>
<tr>
<td class=dense><span class=FileName>APISPQ_LOCALONLY</span></td>
<td class=dense>Handle job on local machine only</td>
</tr>
<tr>
<td class=dense><span class=FileName>APISPQ_CLIENTJOB</span></td>
<td class=dense>Job originated with windows client</td>
</tr>
<tr>
<td class=dense><span class=FileName>APISPQ_ROAMUSER</span></td>
<td class=dense>Job originated with DHCP windows client</td>
</tr>
</table>
</div>

=for man
.Ip "APISPQ_NOH" 8
Suppress header
.Ip "APISPQ_WRT" 8
Write result
.Ip "APISPQ_MAIL" 8
Mail result
.Ip "APISPQ_RETN" 8
Retain on queue after printing
.Ip "APISPQ_ODDP" 8
Suppress odd pages
.Ip "APISPQ_EVENP" 8
Suppress even pages
.Ip "APISPQ_REVOE" 8
Invert \fBAPISPQ_ODDP\fR and \fBAPI_EVENP\fR after printing
.Ip "APISPQ_MATTN" 8
Mail attention
.Ip "APISPQ_WATTN" 8
Write attention
.Ip "APISPQ_LOCALONLY" 8
Handle job on local machine only
.Ip "APISPQ_CLIENTJOB" 8
Job originated with windows client
.Ip "APISPQ_ROAMUSER" 8
Job originated with DHCP windows client

The C<apispq_dflags> field contains the following bits:

=for html
<div class=indtab>
<table border=0 cellpadding=1 cellspacing=0 summary="despooler flags">
<tr>
<th align=left class=dense>Bit (#define)</th>
<th align=left class=dense>Description</th>
</tr>
<tr>
<td class=dense><span class=FileName>APISPQ_PQ</span></td>
<td class=dense>Job being printed</td>
</tr>
<tr>
<td class=dense><span class=FileName>APISPQ_PRINTED</span></td>
<td class=dense>Job has been printed</td>
</tr>
<tr>
<td class=dense><span class=FileName>APISPQ_STARTED</span></td>
<td class=dense>Job has been started</td>
</tr>
<tr>
<td class=dense><span class=FileName>APISPQ_PAGEFILE</span></td>
<td class=dense>Job has a page file</td>
</tr>
<tr>
<td class=dense><span class=FileName>APISPQ_ERRLIMIT</span></td>
<td class=dense>Error if size limit exceeded</td>
</tr>
<tr>
<td class=dense><span class=FileName>APISPQ_PGLIMIT</span></td>
<td class=dense>Size limit in pages not KB</td>
</tr>
</table>
</div>

=for man
.Ip "APISPQ_PQ" 8
Job being printed
.Ip "APISPQ_PRINTED" 8
Job has been printed
.Ip "APISPQ_STARTED" 8
Job has been started
.Ip "APISPQ_PAGEFILE" 8
Job has a page file
.Ip "APISPQ_ERRLIMIT" 8
Error if size limit exceeded
.Ip "APISPQ_PGLIMIT" 8
Size limit in pages not KB

Note that the field C<apispq_pglim> and the field bits
C<APISPQ_ERRLIMIT> and C<APISPQ_PGLIMIT> will always be zero when read
with B<gspool_joblist>, but the description is included for
completeness. The fields are only used when creating jobs.

=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_jobread()\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
Printer sequence error, slot may be out of date
.Ip "GSPOOL_INVALIDSLOT" 8
Invalid slot number

=head1 EXAMPLE

An example to read the names of all jobs

 int fd, ret, nj, i;
 struct apispq job;
 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_jobread(fd, 0, slots[i], &job);
     if (ret < 0) { /* error handling */
         ...
     }
     printf("%s\n", job.apispq_file);
 }
 gspool_close(fd);

=head1 SEE ALSO

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

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