The functions in the Print Queue category control a server’s print queues.
|
Function |
Description |
|
Establishes a print queue on a server. |
|
|
Re-enables a paused print queue. |
|
|
Deletes a print queue from a server. |
|
|
Lists all print queues on a server and optionally supplies additional information on each. |
|
|
Retrieves information about a specified print queue on a server. |
|
|
Pauses a print queue, suspending all processing of print jobs except the current one. |
|
|
Removes all but the current print job from a print queue. |
|
|
Modifies a print queue’s configuration. |
A print queue is an ordered list of submitted print jobs on a server. Print queues can be created only on a server and are controlled by a server’s spooler service and the functions in this category.
Note
All functions in the Print Queue category require the UNIX system print spooler on the server to be running at the time an application calls them.
Level 0, level 1, and level 2 data structures are provided for compatibility with existing LAN Manager 1.0 applications. Advanced Server system applications should use level 3, level 4, and level 5 data structures.
There is one-to-one mapping from the size and type of the prq_info elements to the PRQINFO elements, as shown in the following table:
|
prq_info |
PRQINFO |
|
prq_name |
szName |
|
prq_pad1 |
pad_1 |
|
prq_priority |
uPriority |
|
prq_starttime |
uStartTime |
|
prq_untiltime |
uUntilTime |
|
prq_separator |
pszSepFile |
|
prq_processor |
pszPrProc |
|
prq_destinations |
pszDestinations |
|
prq_parms |
pszParms |
|
prq_comment |
pszComment |
|
prq_status |
fsStatus |
|
prq_jobcount |
cJobs |
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 that the element is not available, such as NULL.
DosPrintQAdd and DosPrintQSetInfo use the level 1 data structure PRQINFO or the level 3 data structure PRQINFO3.
DosPrintQEnum and DosPrintQGetInfo use levels 0, 1, 2, 3, 4, and 5.
At level 0, data is returned in the following format:
CHAR szName[LM20_QNLEN+1];
Within this structure, szName is an ASCIIZ string containing the name of a print queue.
The PRQINFO data structure has the following format:
typedef struct _PRQINFO {
CHAR szName[LM20_QNLEN+1];
CHAR pad_1;
USHORT uPriority;
USHORT uStartTime;
USHORT uUntilTime;
PSZ pszSepFile;
PSZ pszPrProc;
PSZ pszDestinations;
PSZ pszParms;
PSZ pszComment;
USHORT fsStatus;
USHORT cJobs;
} PRQINFO;
Within this structure, the following parameters are defined:
szName is an ASCIIZ string containing the name of a print queue.
pad_1 word-aligns the data structure components.
uPriority displays the print queue’s priority. The range is 1 (high) through 9 (low).
When several print queues submit print jobs to the same destination, jobs in print queues with higher priorities are processed before those in lower-priority queues.
uStartTime specifies the time of day (in minutes from 12:00 am) that a print queue becomes active (able to send print jobs to print destinations). Note that the spooler service must be installed.
uUntilTime specifies the time of day (in minutes from 12:00 am) that a print queue becomes inactive (unable to send print jobs to print destinations).
If uStartTime equals uUntilTime, round the clock printing is enabled.
pszSepFile points to an ASCIIZ string containing the path name of a separator file printed before each print job. The separator is a clear text or graphics file that contains the banner as it appears. Using a separator also relates to the BANNER=yes/no parameter on a queue or print job.
pszPrProc points to an ASCIIZ string specifying the path name and parameters of a print queue’s print processor.
pszDestinations points to an ASCIIZ string containing a concatenated list of print destinations separated by spaces that process the print queue’s print jobs. Each print job is sent to the next available destination in the list. Do not use NULL as a destination unless you are using a customized script.
Note
If NULL is one of the print destinations and there is no processor defined, some jobs may be printed to /dev/null. If this occurs, the job disappears from the queue and you will receive a message indicating that the job has been successfully completed, however, the print job has been lost.
pszParms points to an ASCIIZ string containing parameters that print processors need. The format of pszParms is as follows:
parm1=value1 parm2=value2 ...
where a single space separates the parameter/value pairs.
The parameters are not passed to the print processor; they are used internally to control printing. If a print processor is defined, the COPIES keyword value is made available to the processor through the environment variable $COPIES. For more information, see the DosPrintQSetInfo manual page.
Standard pszParms parameters are defined in the pr.h and pmspl.h files:
|
Parameter |
Meaning | ||
|
TYPES=names |
The names parameter is one or more spool file data type name, separated by commas. The first names entry is assumed to be the default data type. If the data type of a print job is not NULL and does not match one of the names entries, the job will not be queued. | ||
|
EJECT=switch |
If switch is YES or AUTO, a formfeed is issued between jobs when multiple jobs are specified. If switch is NO, no formfeed is issued. | ||
|
BANNER=switch |
The switch parameter determines whether or not banners are printed between separator pages. If switch is YES, a banner is printed. If switch is NO, no banner is printed. The relationship between the BANNER switch setting and the separator field setting is described in the following chart. | ||
|
Banner |
Separator |
Resulting Banner |
|
|
yes |
file name |
file name |
|
|
yes |
nothing |
LP banner |
|
|
no |
nothing |
no banner |
|
|
COPIES+# |
Number of copies for each job sent to the queue. | ||
Applications should check the pszParms string to verify whether a file can be processed for a particular print queue and print destination.
pszComment points to an ASCIIZ string containing a comment about the print queue.
fsStatus displays the status of a print queue through a bit setting defined in the pmspl.h file, as follows:
|
Manifest |
Bit Mask |
Meaning |
|
PRQ_STATUS_MASK |
3 |
The status of the print queue is as shown in the following table. |
|
Manifest |
Value |
Status |
|
PRQ_ACTIVE |
0 |
Active |
|
PRQ_PAUSE |
1 |
Paused by a DosPrintQPause call. |
|
PRQ_ERROR |
2 |
Error occurred. |
|
PRQ_PENDING |
3 |
Deletion pending (DosPrintQDel call has been made). |
cJobs displays the number of print jobs pending in the queue.
Level 2 indicates that the return data consists of the Print Queue data structure PRQINFO followed by a Print Job data structure PRJINFO for every job in the queue. For a complete description of the Print Queue data structure PRQINFO, see Print Queue Information (level 1). For a complete description of the Print Job data structure PRJINFO, see Print Job Category Data Structures.
The PRQINFO3 data structure has the following format:
typedef struct _PRQINFO3 {
PSZ pszName;
USHORT uPriority;
USHORT uStartTime;
USHORT uUntilTime;
USHORT pad1;
PSZ pszSepFile;
PSZ pszPrProc;
PSZ pszParms;
PSZ pszComment;
USHORT fsStatus;
USHORT cJobs;
PSZ pszPrinters;
PSZ pszDriverName;
PDRIVDATA pDriverData;
} PRQINFO3;
Within this structure, the following parameters are defined:
uPriority, uStartTime, uUntilTime, pad1, pszSepFile, pszPrProc, pszParms, pszComment, fsStatus, and cJobs are the same as the corresponding elements of the PRQINFO data structure, with the following modifications:
At level 3, fsStatus uses a single bit of PRQ_STATUS to indicate status:
PRQ_ACTIVE 0x0
PRQ_PAUSED 0x1
PRQ_PENDING 0x2
pszPrProcis ignored.
For a complete description, see Print Queue Information (level 1).
The remaining parameters are defined as follows:
szName points to an ASCIIZ string that contains the name of the printer queue. The queue name can have as many as CCHMAXPATHCOMP bytes, as defined in the bsedos.h header file.
Under the UNIX system, pszName cannot exceed 14 characters.
pszPrinters points to an ASCIIZ string that contains a list of printers that can print from the printer queue. These names reference printers that already exist. Printer names in the list are separated by commas.
pszDriverName points to an ASCIIZ string that contains the name of the PSI (printer subsystem interface) library use to communicate with the native UNIX system print spooler. This field cannot be changed.
pDriverData points to the device driver data for the default driver. This data is specific to the device driver, and it is used only if pszDriverName is not a null pointer or a null string.
The parameter points to data indicating "no driver data."
Level 4 indicates that the return data consists of the Printer Queue data structure PRQINFO3, followed by a Print Job data structure PRJINFO2 for each job in the queue.
For a complete description of PRQINFO3, see Print Queue Information (level 3). For a complete description of PRJINFO2, see Print Job Category Data Structures.
At level 5, data is returned in the following format:
PSZ pszName;pszName
points to an ASCIIZ string that specifies the name of the printer queue. The queue name can have as many as CCHMAXPATHCOMP bytes, as defined in the bsedos.h header file.
The maximum length of pszName under the UNIX system is 14 characters.
