Print Destination Category

The functions in the Print Destination category control the printers on a server that receives spooled print jobs.

Function

Description

DosPrintDestControl

Cancels, pauses, continues, or restarts the print job being processed on a specified print destination.

DosPrintDestEnum

Retrieves a list of all print destinations and, optionally, status information on a specified server.

DosPrintDestGetInfo

Retrieves information about a specified print destination on a specified server

A print destination is any spooled device, such as a line or laser printer, that is available to a server. Print destinations are normally controlled by the Advanced Server spooler service. By calling the functions in this category, they can also be controlled by other applications, such as a print queue’s print processor.

Once a print job is submitted to a print destination, the controlling application can call DosPrintDestControl to kill or restart the current print job on the print destination. The application can also pause or continue the printer.

To get information about a particular print destination, an application calls DosPrintDestGetInfo. Information about all print destinations on a server can be obtained by calling the DosPrintDestEnum function.

For more information on print queues and print processors, see Print Queue Category.

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

Print Destination Category Data Structures

The DosPrintDestEnum and DosPrintGetInfo functions accept or return information at a level 0, 1, 2, or 3 detail, controlled by the value of the uLevel parameter. Levels 0 and 1 data structures are provided for compatibility with LAN Manager 1.0 applications. Advanced Server system applications should use level 2 and level 3 data structures.

Advanced Server uses only printer names. For Advanced Server, logical address = printer name, up to a length of PDLEN. Levels 0 and 1 return all printer names truncated to PDLEN. Levels 2 and 3 return full printer names.

There is a one-to-one mapping from the prdest_info elements to the PRDINFO elements, as shown in the following table:

prdest_info

PRDINFO

prdest_name

szName

prdest_username

szUserName

prdest_jobid

uJobId

prdest_status

fsStatus

prdest_status_string

pszStatus

prdest_time

time

DosPrintDestEnum and DosPrintDestGetInfo accept levels 0, 1, 2, and 3. They accept or return the logical address at level 0, the PRDINFO data structure at level 1, the printer name at level 2, and the PRDINFO3 data structure at level 3. New applications should use levels 2 and 3.

DosPrintDestControl does not use this data structures. The required data is defined within the API function definition. The Print Destination data structures and the Print Destination functions use Microsoft conventions.

The os2def.h header files defines the following types:

MS Type Definition

C LanguageType

CHAR

char

PBYTE

unsigned char *

PSZ

unsigned char *

PUSHORT

unsigned short *

SPLENTRY

pascal

SPLERR

unsigned

USHORT

unsigned short

Print Destination Name (level 0)

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

Within this structure, szName specifies an ASCIIZ string that contains the name of a print destination. The constant PDLEN is defined in the pmspl.h header file.

Print Destination Information (level 1)

The PRDINFO data structure has the following format:

Within this structure, the following parameters are defined:

szName specifies an ASCIIZ string that contains the name of the print destination. The constant PDLEN is defined in the pmspl.h header file, as explained in level 0.

szUserName specifies an ASCIIZ string that contains the name of the user who submitted a print job. This component is valid only during printing. A null string indicates that the job was submitted from the local computer. The constant UNLEN is defined in the pmspl.h header file.

uJobId contains an unsigned short integer that specifies the identification number of the current print job. If no job is printing, uJobId is 0.

fsStatus contains a short integer that specifies the status of the print destination. The bits of fsStatus are defined in pmspl.h.

Bits 0 - 1 have the code PRD_STATUS_MASK and the value 0x0003. This bit mask isolates the print destination status as follows:

Bit

Code

Value

Meaning

0

PRD_ACTIVE

0

The print job is processing.

0

PRD_PAUSED

1

The print job is paused.

Bits 2 through 11 have the codes PRJ_DEVSTATUS and PRD_DEVSTATUS, and the value 0x0FFC. This bit mask isolates the print job status, as follows:

Bit

Code

Value

Meaning

2

PRJ_COMPLETE

0x0004

If 1, the print job is complete.

3

PRJ_INTERV

0x0008

If 1, intervention is required.

4

PRJ_ERROR

0x0010

If 1, an error occurred (pszStatus can contain a comment explaining the error).

5

PRJ_DESTOFFLINE

0x0020

If 1, the print destination is off-line.

6

PRJ_DESTPAUSED

0x0040

If 1, the print destination is paused.

7

PRJ_NOTIFY

0x0080

If 1, an alert is raised.

prsStatus points to an ASCIIZ string that contains a comment about the print destination error status, posted by the print destination’s print processor. This element contains valid data only while the job is printing and an error occurs.

time contains an unsigned short integer that specifies the number of minutes the current job has been printing. This value is valid only while the job is printing.

Print Destination Information (level 2)

At level 2, the pszPrinterName element of the PRDINFO3 data structure is returned in the following format:

PSZ pszPrinterName;

Within this structure, pszPrinterName points to an ASCIIZ string that specifies the name of the print destination. The name can contain blanks. The string can have as many as CCHMAXPATHCOMP bytes, as defined in the bsedos.h header file.

Print Destination Information (level 3)

The PRDINFO3 data structure has the following format:

Within this structure, the following parameters are defined:

pszPrinterName points to an ASCIIZ string that specifies the name of the printer. The name can contain blanks. The string can have as many as CCHMAXPATHCOMP bytes, as defined in the bsedos.h header file.

Note

UNIX system servers do not accept embedded blanks in the printer name.

pszUserName points to an ASCIIZ string that specifies the name of the user who submitted the currently active job. This variable is valid only during printing. A null string or null pointer indicates the job was submitted from the local computer.

pszLogAddr points to an ASCIIZ string that specifies the name of the logical address where this printer prints. This field represents first PDLEN characters of the printer name. If the printer is not connected to a logical address, pszLogAddr is a null pointer.

uJobId contains an unsigned short integer that specifies the ID number of a job currently being printed. If no job is printing, uJobId is 0.

fsStatus contains an unsigned short integer that specifies the status of the print destination. The bits of fsStatus are identical to the fsStatus element of the PRDINFO data structure. For a complete description, see Print Destination Information (level 1).

pszStatus points to an ASCIIZ string that contains a comment about the print destination error status, posted by the print destination’s print processor. This value is valid only while the job is printing and an error occurs.

pszComment points to an ASCIIZ string that contains a printer description.

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

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

time contains an unsigned short integer that specifies the number of minutes the current job has been printing. This value is valid only during printing.

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

Previous Page Page Top Index Next Page See Page