gspool_jobread - get the details of a job

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

# AUTHOR

John M Collins, Xi Software Ltd.