NAME

       gspool_jobdata - retrieve the data for a job as a stream

SYNOPSIS

       #include <gspool.h>
       #include <stdio.h>

       FILE *gspool_jobdata(const int fd, const unsigned flags, const slotno_t slotno)

       int gspool_jobdata(const int fd, const int outfile, int (*func)(int,void*,unsigned), const
       unsigned flags, const slotno_t slotno)

DESCRIPTION

   Unix and GNU/Linux
       The function gspool_jobdata() is used to retrieve the job file of a job.

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

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

       The result is a "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, gspool_jobdata returns "NULL" and an error code is placed in the
       external variable "gsapi_dataerror".

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

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

       The third argument func is a function with the same specifications as "write", indeed it
       may very well be "write". The main reason for doing it this way is that some versions of
       Windows do strange things if "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 "FILE*" or "NULL".
       For consistency with the Unix version, the external variable "gsapi_dataerror" is also
       assigned any error code returned.

ERRORS

       If an error is detected the external variable "gsapi_dataerror" will be set to the error
       code.  Error codes which might be returned are:

       GSPOOL_INVALID_FD
               Invalid file descriptor

       GSPOOL_BADWRITE
               failure writing to network

       GSPOOL_BADREAD
               failure reading from network

       GSPOOL_UNKNOWN_JOB
               job not found

       GSPOOL_NOPERM
               job does not belong to user

       GSPOOL_SEQUENCE
               sequence error, job may be out of data

       GSPOOL_INVALIDSLOT
               Invalid slot number

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);

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).

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.

AUTHOR

       John M Collins, Xi Software Ltd.