Print Job Category

The functions in the Print Job category control the print jobs in a server’s print queue.

Function

Description

DosPrintJobContinue

Continues a paused print job.

DosPrintJobDel

Deletes a print job from a print queue.

DosPrintJobEnum

Retrieves a list of print jobs in a specified print queue, and, optionally, status information on each.

DosPrintJobGetInfo

Retrieves information about a specified print job.

DosPrintJobPause

Pauses a specified print job in a print queue.

DosPrintJobSetInfo

Sets parameters for a submitted print job.

A print job is a file submitted for printing. Print jobs are submitted to a print queue and stored there until a printer is available. A print queue is an ordered list of submitted print jobs used by a server’s spooler service to control printer access (more than one print queue can exist on a server). The spooler continuously examines each available print queue, deciding which print job to send to the next available printer. Generally, the spooler chooses the print job submitted first to be printed first.

To submit a print job to a print queue, a UNIX system application must first open the print queue by implicitly or explicitly establishing a connection to it.

The following example shows how DosOpen is used to establish an implicit connection with the remote print queue \\srv.serve\prq1:

The same remote print queue can also be opened through an explicit connection.

In this case, an application would redirect a local device name (such as LPT1 or LPT2) to the print queue by calling NetUseAdd and then performing an open on the redirected device name with DosOpen, as follows:

With the print queue opened, the application can submit files to it by calling the DosWrite function. DosWrite does not accept the name of a file, but instead writes a buffer of information. Thus, the file must be opened and then sent to the buffer via DosWrite, as follows:

Once a print job is queued, the functions in the Print Job category can control when the print job is printed (by changing its position in the queue, pausing, or deleting the job from the queue).

To retrieve a list of the print jobs in a particular print queue, an application can call the DosPrintJobEnum function. The DosPrintJobGetInfo function can then be called to retrieve information about a specified print job.

Print jobs can be paused or continued by calling the DosPrintJobPause or DosPrintJobContinue function, respectively. A paused print job is not sent to a printer by the spooler. If it reaches the front of the queue, the spooler bypasses it and prints the jobs behind it (until the job is reactivated via DosPrintJobContinue).

To give a particular print job priority over other print jobs, an application can call DosPrintJobSetInfo to change the job’s position in the print queue. An application that does not have administrative privileges can only move its jobs backwards in a queue.

DosPrintJobDel removes a print job from a queue and cancels printing.

When an application no longer requires the use of a print queue, it should close the queue by calling DosClose. The functions in the Print Job category control individual jobs within print queues. For information on controlling the print queues that handle the jobs, see Print Queue Category.

Note

All functions in the Print Job category require the UNIX system print spooler on the server to be running at the time an application calls them.

Print Job Category Data Structures

The functions in the Print Job Category accept or return data at levels 0, 1, 2, or 3. DosPrintJobEnum uses levels 0, 1, and 2. DosPrintJobGetInfo uses levels 0, 1, 2, and 3. DosPrintJobSetInfo uses levels 1 and 3.

The Print Job data structures and the Print Job functions use Microsoft conventions for names and type definitions. The os2def.h header file defines these types:

MS Type Definition

C Language Type

CHAR

char

HFILE

unsigned short

PBTYE

unsigned char *

PSZ

unsigned char *

PUSHORT

unsigned short *

SPLENTRY

pascal

SPLERR

unsigned

USHORT

unsigned short

Level 0 and level 1 data structures are provided for compatibility with existing LAN Manager 1.0 applications. Advanced Server system applications should use level 0, 2, and 3 data structures.

There is one-to-one mapping from the prjob_info elements to the PRJINFO elements, as shown in the following table:

prjob_info

PRJINFO

prjob_id

uJobId

prjob_username

szUserName

prjob_pad_1

pad_1

prjob_notifyname

szNotifyName

prjob_datatype

szDataType

prjob_parms

pszParms

prjob_position

uPosition

prjob_status

fsStatus

prjob_status_string

pszStatus

prjob_submitted

ulSubmitted

prjob_size

ulSize

prjob_comment

pszComment

The new data structures are supported when they are directed to servers that run LAN Manager 1.0 software (down-level servers). New elements are given default values or values that indicate the element is not available, such as NULL.

DosPrintJobSetInfo uses the level 1 data structure PRJINFO and the level 3 data structure PRJINFO3. DosPrintJobEnum uses levels 0, 1, and 2. DosPrintJobGetInfo uses levels 0, 1, 2, and 3.

DosPrintJobGetID returns the PRIDINFO data structure.

Print Job Identification Number (level 0)

At level 0, data is returned in the following format:

Within this structure, uJobId contains an unsigned short integer that specifies the identification number assigned to the print job when it was queued. The identification number is unique on a particular computer. A combination of the computername and uJobId is sufficient to identify a particular print job uniquely.

Print Job Information (level 1)

The PRJINFO data structure has the following format:

Within this structure, the following parameters are defined:

uJobId contains an unsigned short integer that specifies the identification number of the print job. The identification number is assigned by the print spooler.

szUserName contains an ASCIIZ string that specifies the name of the user who submitted the print job. A null string indicates that the job was submitted from the local computer and the user did not log on. LM20_UNLEN specifies the maximum length of username.

pad_1 aligns the next data structure element on a word boundary.

szNotifyName contains an ASCIIZ string that specifies the message alias that receives alert messages relating to the print job. The constant CNLEN is defined in the pmspl.h header file. A null string is used for jobs submitted from the local computer.

szDataType contains an ASCIIZ string that specifies the data type for the print job. DTLEN specifies the maximum length of a data type.

pszParms points to an ASCIIZ string containing a parameter string to be passed to the spooler in the form parm1=val1 parm2=val2 ....

Parameter strings and valid values follow:

uPosition contains an unsigned short integer that specifies the position of the print job in the printer queue. If uPosition is 1, the print job prints next.

fsStatus contains an unsigned short integer used as a status flag. Possible values are defined in the pmspl.h header file.

Bits 0 and 1 have the code PRJ_QSTATUS and the value 0x0003. This bit mask isolates the print job queued status bits as follows:

Bits

Code

Value

Meaning

0-1

PRJ_QS_QUEUED

0

Print job is queued.

0-1

PRJ_QS_PAUSED

1

Print job is paused.

0-1

PRJ_QS_SPOOLING

2

Print job is spooling.

0-1

PRJ_QS_PRINTING

3

Print job is printing (bits 2 through 11 are valid).

Bits 2 through 11 have the code PRJ_DEVSTATUS and the value 0x0FFC. This bit mask isolated the print job status bit as follows:

Bit

Code

Value

Meaning

2

PRJ_COMPLETE

0x0004

If 1, job complete.

3

PRJ_INTERV

0x0008

If 1, intervention required.

4

PRJ_ERROR

0x0010

If 1, an error occurred (pszStatus_string generally contains a comment, such as "out of paper").

5

PRJ_DESTOFFLINE

0x0020

If 1, print destination off-line.

6

PRJ_DESTPAUSED

0x0040

If 1, print destination paused.

7

PRJ_NOTIFY

0x0080

If 1, alert should be raised.

8

PRJ_DESTNOPAPER

0x0100

If 1, print destination out of paper.

9

PRJ_DESTFORMCHG

0x0200

If 1, the printer is waiting for a form change.

10

PRJ_DESTCRTCHG

0x0400

If 1, the printer is waiting for a cartridge change.

11

PRJ_DESTPENCHG

0x0800

If 1, the printer is waiting for a pen change.

15

PRJ_DELETED

0x8000

If 1, indicates job deleted.

pszStatus points to an string that contains a comment about the status of the print job posted by the queue’s print processor. A null pointer or null string indicates that no information was posted. This element contains valid data only while the job is printing and an error occurs.

ulSubmitted contains an unsigned long integer that specifies the time the user submitted the print job. The time is stored in seconds elapsed since 00:00:00, January 1, 1970.

ulSize contains an unsigned long integer that specifies the size of the print job.

pszComment points to an ASCIIZ string containing a remark about the print job. This string can have a maximum length of LM20_MAXCOMMENTSZ bytes.

Print Job Information (level 2)

The PRJINFO2 data structure has the following format:

Within this structure, the following parameters are defined:

uJobId contains an unsigned short integer that specifies the identification number of the print job. The identification number is assigned by the print spooler.

uPriority contains an unsigned short integer that specifies the priority of the print job. The range is 1 (lowest priority) through 99 (highest priority). If the constant PRJ_NO_PRIORITY is used, a default job priority is computed based on the queue priority.

The default job priority is defined as follows:

The job priority determines the order of print jobs in the queue. If multiple queues print to the same printer, the spooler compares the priorities of the jobs at the front of the queues and schedules the job with the highest priority first. If job priorities are equal, the oldest job is scheduled.

Job priority must be mapped to LP priorities 0 (highest priority) through 39 (lowest priority). The computation required by this mapping results in a job priority that may be off by 1 from the actual job priority.

pszUserName points to an ASCIIZ string that specifies the name of the user who submitted the print job.

uPosition, fsStatus, ulSubmitted, ulSize, and pszComment are the same as the corresponding elements of the PRJINFO data structure. For a complete description, see Print Job Information (level 1).

pszDocument points to an ASCIIZ string that contains the document name of the print job. This string can have as many as CCHMAXPATH bytes.

Print Job Information (level 3)

The PRJINFO3 data structure has the following format:

Within this structure, the following parameters are defined:

uJobId, uPriority, pszUserName, uPosition, fsStatus, ulSubmitted, ulSize, pszComment, and pszDocument are the same as the corresponding elements of the PRJINFO2 data structure. For a complete description, see Print Job Information (level 2).

pszNotifyName points to an ASCIIZ string that contains the message alias that receives alert messages related to the print job. A null string indicates that the job was submitted from the local computer.

pszDataType points to an ASCIIZ string that contains the data type for the print job.

pszParms points to an ASCIIZ string that contains a parameter string to pass to the printer queue processor. The parameter string has the following format:

Parameter strings and valid values follow:

pszStatus points to an ASCIIZ string that contains a comment about the status of the print job posted by the queue’s print processor. A null pointer or null string indicates that no information was posted. This element contains valid data only while the job is printing and an error occurs.

pszQueue points to an ASCIIZ string that contains the name of the print queue that contains the print job.

pszQProcName points to an ASCIIZ string that contains the name of the print queue processor.

pszQProcParms points to an ASCIIZ string that contains parameters passed to the print queue processor. The parameter string has the following format:

The parameter, COP=n, specifies that n copies of the document are to be printed.

The parameter COP is used to change the number of copies requested for a job; the parameter COPIES, usually associated with the pszParms field, is ignored. COP is the only parameter recognized for this field.

pszDriverName points to an ASCIIZ string that contains the name of the PSI (printer subsystem interface) library uses to communicate with the native UNIX system print spooler. This field cannot be changed.

pDriverData points to the driver data structure for the default driver. This parameter points to data indicating "no driver data".

pszPrinterName points to an ASCIIZ string that contains the name of the printer on which the job is printing. If the job is not printing, pszPrinterName contains a null string or a null pointer.

Print Job Identification Number

DosPrintJobGetId returns the PRIDINFO data structure:

Within this structure, the following parameters are defined:

uJobId contains an unsigned short integer that specifies the identification number assigned to the print job when it was queued. The identification number is unique on a particular computer. A combination of the computer name and uJobId is sufficient to identify a particular print job uniquely.

szServer[CNLEN+1] specifies an ASCIIZ string that contains the name of the computer handling the print job. The constant CNLEN is defined in the pmspl.h header file. If the name has more than CNLEN bytes, a null string is returned.

szQName[QNLEN+1] specifies an ASCIIZ string that contains the name of the print queue for the job. The constant LM20_QNLEN is defined in the pmspl.h header file. If the name has more than LM20_QNLEN bytes, a null string is returned.

pad_1 aligns the next data structure on a word boundary.

Previous Page Page Top Index Next Page See Page