NAME

       gspool_jobadd - create a new job

SYNOPSIS

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

       FILE *gspool_jobadd(const int fd, struct apispq *jobd, const char *delim, const unsigned deliml, const
       unsigned delimnum)

       int gspool_jobres(const int fd, jobno_t *jobno)

       int gspool_jobadd(const int fd, const int infile, int (*func)(int,void*,unsigned) struct apispq *jobd,
       const char *delim, const unsigned deliml. const unsigned delimnum)

DESCRIPTION

   Unix and GNU/Linux
       The functions gspool_jobadd() (the first form) and gspool_jobres are used to add a job under Unix and
       GNU/Linux.

       fd is a file descriptor previously returned by gspool_open

       jobd is a pointer to a "struct apispq", as defined in gsapi.h, containing all the details of the job.
       The fields in struct apispq are defined in the documentation for gspool_jobread(3).

       Note that we recommend that the whole structure be cleared to zeroes initially and then required fields
       added; this approach will cover any future extensions with additional fields which will behave as at
       present if zero.

       Also note that from release 23 an additional field "apispq_pglim" is provided in the structure. If this
       is non-zero, then the size of the job is limited. If the bit "APISPQ_PGLIMIT" in "apispq_dflags" is zero,
       then the size is limited to the given number of kilobytes. If this bit is set, then the size is limited
       to the given number of pages. If a job exceeds the given limit, then its treatment depends upon the
       setting of the bit "APISPQ_ERRLIMIT" in "apispq_dflags". If this is zero, then the job is truncated to
       the given number of kilobytes or pages and still proceeds (although a warning code is returned by
       gspool_jobres). If it is set, then it is rejected altogether.

       delim is a pointer to a string containing the page delimiter string, or "NULL" if the user is content
       with the single formfeed character. deliml is the length of the delimiter string delim. This is necessary
       because delim is not necessarily null-terminated.

       delimnum in the number of instances of the delimiter string/character to be counted to make up a page.

       The result is either a standard I/O stream, which can be used as output for putc(3), fprintf(3),
       fwrite(3) etc, or "NULL" to indicate an error has been detected. The I/O stream connection should be
       closed, when complete, with fclose(3). Finally a call should be made to gspool_jobres.

       For reasons of synchronisation you must call gspool_jobres immediately after fclose(3) even if you are
       not interested in the answer. Apart from that several calls to gspool_jobadd may be in progress at once
       to submit several jobs simultaneously.

       gspool_jobres returns zero on successful completion (or "GSPOOL_WARN_LIMIT" if the job was truncated but
       still submitted). The parameter jobno is assigned the job number of the job created. This value is also
       assigned to the field "apispq_job" in the passed structure jobd to gspool_jobadd.

       Note that you should not call gspool_jobres if gspool_jobadd returns "NULL" for error. Most errors are
       detected at the gspool_jobadd stage and before any data is passed across, but this should not in general
       be relied upon.

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

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

       The third argument func is a function with the same specifications as "read", indeed it may very well be
       "read". The main reason for doing it this way is that some versions of Windows do strange things if
       "read" 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".

       There is no gspool_jobres in the windows version, the job number is placed in the field "apispq_job" in
       the passed structure jobd to gspool_jobadd. 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 "gspool_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_SEQUENCE
               job sequence error - slot may be out of date

       GSPOOL_UNKNOWN_JOB
               job not found

       GSPOOL_NOPERM
               job does not belong to user

       GSPOOL_INVALIDSLOT
               invalid slot number

       GSPOOL_ZERO_CLASS
               invalid (effectively zero) class code

       GSPOOL_BAD_PRIORITY
               invalid priority

       GSPOOL_BAD_COPIES
               invalid number of copies

       GSPOOL_BAD_FORM
               invalid form type

       GSPOOL_UNKNOWN_USER
               unknown user name

       GSPOOL_NOMEM_QF
               no memory for queue file

       GSPOOL_FILE_FULL
               file system is full on host

       GSPOOL_QFULL
               message queue full on host

       GSPOOL_EMPTYFILE
               no job data given

       GSPOOL_BAD_PTR
               invalid printer name given (user is limited)

       GSPOOL_WARN_LIMIT
               job size exceeded limit, truncated

       GSPOOL_PAST_LIMIT
               job size exceeded limit, rejected

EXAMPLE

       An example to add a job called "readme" from standard input:

        int fd, ret, ch;
        struct apispq outj;
        jobno_t jn;
        FILE *f;

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

        /* It is safest to clear the structure first */
        memset((void *) &outj, '\0', sizeof(outj));

        /* set defaults */
        outj.apispq_nptimeout = 24 * 7;
        outj.apispq_ptimeout = 24;
        outj.apispq_cps = 1;
        outj.apispq_pri = 150;

        /* The class code specified in gspool_open is not used here. However the
        user's class code will be &ed with this unless the user has override
        class privilege. */

        outj.apispq_class = 0xffffffff;

        /* set a large page range to to ensure all pages are printed */
        outj.apispq_end = 4000;

        /* Only the form type is compulsory here. The others may
           be set to NULL */

        strcpy(outj.apispq_file, "readme");
        strcpy(outj.apispq_form, "a4");
        strcpy(outj.apispq_ptr, "laser");

        /* add the job with the default page delimiter */

        f = gspool_outjadd(fd, &outj, (char *) 0, 1, 1);
        if (!f)  { /* error handling error in gsapi_dataerror */
            ...
        }

        /* now send the data */

        while ((ch = getchar()) != EOF)
            putc(ch, f);
        fclose(f);

        ret = gspool_jobres(fd, &jn);
        if (ret < 0) { /* error handling */
            ...
        } else
            printf("success the job number is %ld\n", jn);

        gspool_close(fd);

SEE ALSO

       gspool_joblist(3),    gspool_jobread(3),    gspool_jobdata(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.

GNUspool Release 1                                 2009-05-30                                   gspool_jobadd(3)