=head1 NAME

gspool_jobdata - retrieve the data for a job as a stream

=head1 SYNOPSIS

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

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

B<FILE *gspool_jobdata(const int>
I<fd>B<, const unsigned>
I<flags>B<, const slotno_t>
I<slotno>B<)>

B<int gspool_jobdata(const int>
I<fd>B<, const int>
I<outfile>B<, int (*>I<func>B<)(int,void*,unsigned), const unsigned>
I<flags>B<, const slotno_t>
I<slotno>B<)>

=head1 DESCRIPTION

=head2 Unix and Linux

The function B<gspool_jobdata()> is used to retrieve the job file of a job.

I<fd> is a file descriptor previously returned by B<gspool_open>. I<flags>
is zero, or C<GSPOOL_FLAG_IGNORESEQ> to ignore changes since the job
list was last read.

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

The result is a C<FILE> pointer which can be used with all standard
I/O input functions such as fgets(3), getc(3) etc. At the end of the
data fclose(3) must be called. For reasons of sychronisation the file
should be read to the end before other operations are attempted.

If an error is detected, B<gspool_jobdata> returns C<NULL> and an error
code is placed in the external variable C<gsapi_dataerror>.

=head2 Windows

The second format of the B<gspool_jobdata> function is for use by Windows
programs, as there is no acceptable equivalent of the pipe(2)
construct.

The second argument I<outfile> is (possibly) a file handle to the file
from to which the job data is passed as the first argument to
I<func>.

The third argument I<func> is a function with the same specifications
as C<write>, indeed it may very well be C<write>. The main reason for
doing it this way is that some versions of Windows do strange things
if C<write> is invoked from within a DLL.

Other aspects of the interface are similar to the Unix routine, apart
from the routine returning zero for success and an error code for
failure rather than a C<FILE*> or C<NULL>. For consistency with the
Unix version, the external variable C<gsapi_dataerror> is also
assigned any error code returned.

=head1 ERRORS

If an error is detected the external variable C<gsapi_dataerror> will
be set to the error code.

=for html
<P>Error codes are <A HREF="TxtAPI-3.html#Error_codes">listed in Chapter
3</A>.</P>

=for man
Error codes which might be returned are:
.Ip "GSPOOL_INVALID_FD" 8
Invalid file descriptor
.Ip "GSPOOL_BADWRITE" 8
failure writing to network
.Ip "GSPOOL_BADREAD" 8
failure reading from network
.Ip "GSPOOL_UNKNOWN_JOB" 8
job not found
.Ip "GSPOOL_NOPERM" 8
job does not belong to user
.Ip "GSPOOL_SEQUENCE" 8
sequence error, job may be out of data
.Ip "GSPOOL_INVALIDSLOT" 8
Invalid slot number

=head1 EXAMPLE

An example to retrieve the data for a job:

 int     fd, ret, ch;
 slotno_t slot, *list;
 FILE *inf;

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

 /* Select a job slot and assign this to "slot" */
 .......

 inf = gspool_jobdata(fd, 0, slot);
 if (!inf)  { /* handle errors */
     ...
 }

 while ((ch = getc(inf)) != EOF)
     putchar(ch);
 fclose(inf);
 gspool_close(fd);

=head1 SEE ALSO

gspool_joblist(3),
gspool_jobread(3),
gspool_jobadd(3),
gspool_jobdel(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:
## LocalWords:  jobdata const int fd slotno GSPOOL
