gspool_jobread - get the details of a job
int gspool_jobread(const int fd, const unsigned flags, const slotno_t slot, struct apispq *jobd)
The gspool_jobread() function is used to retrieve the details of a job from a given slot number.
fd is a file descriptor previously returned by gspool_open
flags is zero, or a logical OR of one or more of the following values
Ignore remote printers/hosts, i.e. not local to the server, not the client.
Ignore other users jobs
Ignore changes since the list was last read
slot is the slot number corresponding to the job as returned by gspool_joblist or gspool_jobfindslot.
jobd is a descriptor, which on return will contain the details of
the job in a struct apispq
as defined in gspool.h and containing
the following elements:
Type | Field | Description |
---|---|---|
jobno_t | apispq_job | Job number |
netid_t | apispq_netid | Host address (network byte order) |
netid_t | apispq_orighost | Originating host address |
slotno_t | apispq_rslot | Slot number on owning machine |
time_t | apispq_time | Time job was submitted |
time_t | apispq_starttime | Time job was started (if applicable) |
time_t | apispq_hold | Time job held to, 0 if not held |
unsigned short | apispq_nptimeout | Time after to delete job if not printed (hours) |
unsigned short | apispq_ptimeout | Time after to delete job if printed (hours) |
unsigned short | apispq_extrn | External job type index |
unsigned short | apispq_pglim | Job size limit applies |
long | apispq_size | Size of job in bytes |
long | apispq_posn | Offset reached if currently being printed |
long | apispq_pagec | Currently-reached page if being printed |
char[] | apispq_uname | User name of job owner |
char[] | apispq_puname | User name of posting user |
unsigned char | apispq_cps | Copies |
unsigned char | apispq_pri | Priority |
classcode_t | apispq_class | Class code bits 1=A 2=B 4=C etc |
unsigned short | apispq_jflags | Job flags |
unsigned char | apispq_dflags | Despooler flags |
slotno_t | apispq_pslot | Printer slot assigned to if printing |
unsigned long | apispq_start | Start page 0=first page |
unsigned long | apispq_end | End page |
unsigned long | apispq_npages | Number of pages |
unsigned long | apispq_haltat | "Halted at" page |
char [] | apispq_file | Job title |
char [] | apispq_form | Job form type |
char [] | apispq_ptr | Printer pattern assigned to job |
char [] | apispq_flags | Post-processing flags |
The following bits are set in the apispq_jflags
field to indicate
job parameters:
Bit (#define) | Meaning |
---|---|
APISPQ_NOH | Suppress header |
APISPQ_WRT | Write result |
APISPQ_MAIL | Mail result |
APISPQ_RETN | Retain on queue after printing |
APISPQ_ODDP | Suppress odd pages |
APISPQ_EVENP | Suppress even pages |
APISPQ_REVOE | Invert APISPQ_ODDP and API_EVENP after printing |
APISPQ_MATTN | Mail attention |
APISPQ_WATTN | Write attention |
APISPQ_LOCALONLY | Handle job on local machine only |
APISPQ_CLIENTJOB | Job originated with windows client |
APISPQ_ROAMUSER | Job originated with DHCP windows client |
The apispq_dflags
field contains the following bits:
Bit (#define) | Description |
---|---|
APISPQ_PQ | Job being printed |
APISPQ_PRINTED | Job has been printed |
APISPQ_STARTED | Job has been started |
APISPQ_PAGEFILE | Job has a page file |
APISPQ_ERRLIMIT | Error if size limit exceeded |
APISPQ_PGLIMIT | Size limit in pages not KB |
Note that the field apispq_pglim
and the field bits
APISPQ_ERRLIMIT
and APISPQ_PGLIMIT
will always be zero when read
with gspool_joblist, but the description is included for
completeness. The fields are only used when creating jobs.
The function returns 0 if successful otherwise one of the error codes listed in Chapter 3.
An example to read the names of all jobs
int fd, ret, nj, i; struct apispq job; slotno_t *slots;
fd = gspool_open("myhost", (char *)0, 0); if (fd < 0) { /* error handling */ ... }
ret = gspool_joblist(fd, 0, &nj, &slots); if (ret < 0) { /* error handling */ ... }
for (i = 0; i < nj, i++) { ret = gspool_jobread(fd, 0, slots[i], &job); if (ret < 0) { /* error handling */ ... } printf("%s\n", job.apispq_file); } gspool_close(fd);
gspool_jobfind(3), gspool_jobfindslot(3), gspool_joblist(3), gspool_jobdata(3), gspool_jobadd(3), gspool_jobdel(3), gspool_jobupd(3), gspool_jobmon(3), gspool_jobpbrk(3).
John M Collins, Xi Software Ltd.