Queue a file for printing by the system
|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
LPQUE(filename[, LPNUM:device][, COPIES:number][, FORM:form_name][, ALIGN] & [, DELETE[:flag]])
Arguments
filename
The name of the file to be queued for output. The filename must conform to the form and restrictions imposed by the spooler device. (a)
LPNUM:device
(optional) Specifies the spooled print device to which the file is directed for output. Possible values depend on the spooler being used.
COPIES:number
(optional) Specifies the number of copies to print. Possible values depend on the spooler being used. (n)
FORM:form_name
(optional) Specifies the name of the form you want. The default is no special forms. The format of the form name depends on the spooler being used. On Windows and Unix, FORM only affects printing if system option #22 is set.
ALIGN
(optional) On Windows and Unix, ALIGN indicates that a spooler-defined alignment pattern is to be created and accepted by the system operator before the file contents are printed. This alignment depends on the spooler being used. On Windows and Unix, ALIGN only affects printing if system option #22 is set.
On OpenVMS, ALIGN tells the system spooler to place the entry on hold.
DELETE:flag
(optional) Specifies whether the file will be deleted after it is printed. If flag is a nonzero value, the file won’t be deleted. If DELETE is specified but flag is not specified or is zero, the file will be deleted. By default, if DELETE is not specified, the file won’t be deleted. (n)
Discussion
The LPQUE statement queues a file for printing by the system. This statement relies closely on the spooling facilities offered by each operating system. Not all systems provide support for each of the LPQUE options. LPQUE works in conjunction with system option #22, which determines how LPQUE interfaces with the operating system, and (on Windows) the PRINT_METHOD environment variable.
When specifying a filename, the default extension is .ddf. To print a file with no extension, append a period (.) to the end of the filename. For example:
lpque ("filename.")
If you don’t specify the COPIES qualifier, or if number is less than 1, one copy is printed.
Using LPQUE on Windows
|
On Windows, LPQUE is deprecated in favor of the Synergy Windows printing API. It is not compatible with remote terminal services printers and on-demand printer driver loading. |
The LPNUM value must be an alpha variable specifying the printer device in the form “name, [device]” unless system option #22 is set. If system option #22 is set, the runtime sends LPQUE arguments to the file DBLDIR:dblpq.bat, which can contain customized print commands. You must create your own dblpq.bat file. The LPQUE options specified in your Synergy program are passed as arguments to dblpq.bat. These arguments can then be processed as replaceable parameters (%1, %2, %3, etc.) within dblpq.bat. Although not all systems support all of the LPQUE options, a value is passed for each as shown in the table below.
|
DBLPQ argument |
LPQUE option |
Possible values |
Default value |
|---|---|---|---|
|
%1 |
filename | ||
|
%2 |
LPNUM | 0 - 99 | 0 |
|
%3 |
COPIES | 0 - 99 | 1 |
|
%4 |
FORM | "string" | NOFORM |
| %5 | ALIGN | 1 or 0 | 0 |
| %6 | DELETE | 1 or 0 | 0 |
The following table shows examples of LPQUE statements and the arguments they send to dblpq.bat:
|
LPQUE statement |
DBLPQ arguments |
|---|---|
|
lpque(“test.ddf”) |
TEST.DDF 0 1 NOFORM 0 0 |
|
lpque(“test.ddf”, lpnum:1, copies:2) |
TEST.DDF 1 2 NOFORM 0 0 |
|
lpque(“test.ddf”, lpnum:1, copies:2, form:var) |
TEST.DDF 1 2 VAR 0 0 |
|
lpque(“test.ddf”, lpnum:1, copies:2, align, delete) |
TEST.DDF 1 2 NOFORM 1 1 |
When using LPQUE with xfServer on Windows, we recommend that the client generate a print file locally and then print it on a printer accessible to the client. We do not recommend that the client print a remote file using xfServer; however, if you choose to, the printer must be attached directly to the server machine. Network printers are not supported from xfServer on Windows.
The default printer is used unless specified otherwise with the LPNUM argument. If no printers have been defined, LPQUE will fail. If you are using UI Toolkit, you can call the %U_PRINTSETUP routine to display a Windows printing dialog and let the user choose a printer.
|
|
LPQUE is not allowed on devices. We recommend that you don’t you use LPQUE from a service (such as dbssvc), but if you do, you must modify the service to run as a user account that has previously set up the printers that will be used as well as a default printer. In addition, if LPQUE is used with a remote LPQUE to xfServer or under xfServerPlus, the ENABLEUSERHIVE registry setting must be set. See Defining environment variables for a specific user for instructions on setting ENABLEUSERHIVE. In Synergy .NET, LPQUE requires the main program to have the [STAThread] attribute; therefore, Synergy .NET can’t use LPQUE within IIS. LPQUE and the underlying Windows COM/print drivers are not thread safe, so you should ensure that only one thread at a time uses LPQUE. |
Using LPQUE on Unix
You can customize printing on Unix by modifying the DBLDIR:dblpq shell script file to your own specifications. The runtime sends LPQUE arguments to this file if system option #22 is set. The LPQUE statement then executes the arguments in dblpq instead of those in the default printing program, which is either lp (the System V implementation) or lpr (the BSD implementation). If system option #22 is not set, the LPQUE statement executes the default printing program.
If you don’t have a printer connected but you want to test your programs, you can set the environment variable PCMD to cat to make LPQUE to send your output to your terminal.
You can either specify the printer number or the printer name (in quotation marks) as the argument to LPNUM, although an alpha printer name specification is not portable to all operating systems.
On a Unix System V, specifying a number n sends output to a printer named “lpn.” If you use a number on this system, you must run the Unix lpadmin program (which administers the Common Unix Printing System, or CUPS) and name your printers “lp1”, “lp2”, and so forth; lpadmin requires printers to be named, not numbered. For example, the following statement sends a listing to a printer named “lp3”:
lpque("test.lis", lpnum:3)
while the statement below sends a listing to a printer named “laser”:
lpque("test.lis", lpnum:"laser")
On other systems, such as 4.2BSD, specifying the number n sends output to the printer numbered n. You can’t use alpha printer names on 4.2BSD because the printers are numbered.
Using LPQUE on OpenVMS
You can use the LPQUE statement to add a job to the print-batch services queues. If you use LPQUE, the default condition is to use the $SNDJBC system service, which speeds up spooling. The drawback to this is that you can’t use wildcard characters in the file specification, and print switches on filename specifications are ignored.
LPQUE can also be used to submit batch jobs if its queue is a batch queue. However, if you specify system option #22, Synergy DBL constructs a DCL PRINT command line and spawns a subprocess to execute the PRINT command line. With this option, you can use wildcard characters, and valid print switches on a filename will be sent through to subprocesses as part of the PRINT command line. If system option #22 is set, printing errors may not be reported to your program.
If the LPNUM option is specified, the resulting queue name must be defined within the running system. If LPNUM is not specified, the default queue is SYS$PRINT. If LPNUM is specified as an alpha expression, that expression is used as the queue name. If LPNUM is specified as a numeric expression, the queue name is DBL$LPn, where n is the specified number.
To use the additional parameter SJC$_NO_PAGINATE, which is equivalent to using a PRINT/NOFEED DCL command, set DFLAG flag 8.
Examples
The following example sends the file test.1st to the print queue, prints three copies, and then deletes the file.
lpque("test.lst", copies:3, delete)
The following example sends the file, which is named in the variable file, to the printer to print aligned, and with the labels form. The file is deleted after printing.
lpque(file, form:"1-part", align, delete)
