gspool_jobadd - create a new job

# 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 Linux

The functions gspool_jobadd() (the first form) and gspool_jobres are used to add a job under Unix and 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 gspool_jobread(3) documentation.

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 are listed in Chapter 3, Almost all the codes are possible.

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

# AUTHOR

John M Collins, Xi Software Ltd.