gspool_jobadd - create a new job
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)
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
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.
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.
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.
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);
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 (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.
John M Collins, Xi Software Ltd.