NAME

gspool_jobread - get the details of a job


SYNOPSIS

#include <gspool.h>

int gspool_jobread(const int fd, const unsigned flags, const slotno_t slot, struct apispq *jobd)


DESCRIPTION

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

GSPOOL_FLAG_LOCALONLY

Ignore remote printers/hosts, i.e. not local to the server, not the client.

GSPOOL_FLAG_USERONLY

Ignore other users jobs

GSPOOL_FLAG_IGNORESEQ

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.


RETURN VALUES

The function returns 0 if successful otherwise one of the error codes listed in Chapter 3.


EXAMPLE

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


SEE ALSO

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


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.