Printing |
![]() ![]() ![]() |
QM applications do not drive printing devices directly. Instead they reference numbered print units with no knowledge of where the output will actually go. This leads to a very flexible printing system where the output can be sent to a printer, a file or the user's screen. QM uses the underlying Print Manager on Windows or the operating system spooler on other platforms to perform output to printer devices.
Windows Mobile and Windows CE used on PDA devices have no built-in printer support. Third party software packages are required to print on these platforms. QM retains support for mode 3 print units as described below.
Each QM session has its own pool of print units, numbered from 0 to 255. In most cases, if a print unit is not specified in a command, printer 0, the default printer, is used. Application developers are free to use these print units in any way that meets their needs. They might correspond to different printers, different paper types on the one printer, selection of portrait or landscape mode, etc. Although it is unlikely, all 256 print units can be used simultaneously.
Within QMBasic programs printer 0 is treated as a special case. If the program has not used the PRINTER ON statement (or the LPTR qualifier to the RUN command), output to printer 0 is actually sent to the user's screen rather than the printer. This allows an application to use either the screen or the default printer simply by choosing whether to execute the PRINTER ON statement rather than having to implement two alternative paths for every place that performs output.
QMBasic programs can also reference print unit -1 as a synonym for the user's screen.
Pick Style Form Queues
As an aid to migration from other systems, QM provides limited support for Pick style form queues by use of the SP.ASSIGN command. Internally, QM needs to relate form queue numbers to the equivalent SETPTR options and this is managed by a mapping file, $FORMS, using the SET.QUEUE command.
For more information, see the SP.ASSIGN and SET.QUEUE command descriptions.
Setting Print Unit Characteristics
Unless otherwise defined, print unit 0 is directed to the system's default printer and all other print units are directed to the $HOLD file. Almost all applications will need to modify this default behaviour by using the SETPTR command. This may be executed from the MASTER.LOGIN paragraph in the QMSYS account (to affect all users), from the LOGIN paragraph of a specific account (to affect only users of that account), or from within the application.
The SETPTR command defines the shape of the printed page (width, depth, margins), the destination and various options relating to the treatment of the output.
A print unit can operate in several modes: Mode 1 directs the output to the underlying operating system print processor, usually to send it to a physical printer. Mode 3 formats the data ready for printing but directs it to a record in the $HOLD file from where it may subsequently be viewed on the screen with a suitable editor or sent on to a printer when required. The hold file is most commonly used to defer printing until a process has completed, to gather diagnostic output, or for testing. Mode 4 directs the output the the stdout (standard output) file unit. Mode 5 buffers the data in the $HOLD file and then sends it to the terminal when the printer is closed, prefixing it with the control code to enable the terminal auxiliary port and disabling this port on completion of the print. This feature relies on the mc5 (aux on) and mc4 (aux off) terminfo items being set correctly. Mode 6 combines the actions of modes 1 and 3, creating a file and also printing the data.
A print job commences when the first line of output is sent to the printer and normally terminates when the program closes the print unit either explicitly or implicitly by returning to the command processor. It is possible to merge output from several successive print programs into one job by use of the PRINTER command. The KEEP.OPEN option used before output commences followed by the CLOSE option after the final program completes treats the entire sequence as a single print job.
Printing on Windows
Windows defines two alternative printing interfaces. The graphical device interface (GDI) allows a Windows application to construct complex text and graphics images whereas the non-GDI mode (known in QM as raw mode) is a much simpler interface that permits only simple text output. QM uses the raw mode by default though, for compatibility with older releases, the GDI configuration parameter can be used to make GDI the default though QM does not provide any functions to generate GDI graphics.
Some options of the SETPTR command are applicable only to one or other of the two modes. Also, some options may not be supported by all Windows print drivers. In most cases, inapplicable options are simply ignored.
Printing on Other Platforms
QM normally uses the underlying lp command to print data on these platforms though this can be modified by use of the SPOOLER configuration parameter or the SPOOLER option of the SETPTR command. SETPTR options that are not applicable are ignored.
Printing to a File
The SETPTR command can be used to direct output to a record in the $HOLD file or to any specific pathname on the server system. Hold file entries have a default name of Pn where n is the print unit number but this can be modified in SETPTR to use a different name and/or to add a rolling sequence number to the name.
Print Prefix Files
The PREFIX option of the SETPTR command can be used to specify the pathname of a file containing printer initialisation commands. The content of this file is sent to the printer before the first output from the application. A typical use of a prefix file might be to select a paper tray.
PCL Printer Support
The printing system of QM includes features for greater control of PCL printers. These include font selection, basic graphics and enhanced report formats. The PCL features are enabled by including the PCL option in the SETPTR command when defining the printer characteristics.
By default, a PCL printer will print in Courier font at 10 characters per inch and 6 lines per inch. The SETPTR command includes options to specify alternative values for the character and line spacing. The paper size defaults to A4 but can also be amended using SETPTR. The LANDSCAPE option will rotate the page through 90 degrees.
The query processor also has special support for PCL printers in report generation commands (e.g. LIST). Page headings, footings and breakpoint values are printed in bold face. The BOXED option draws a box around the page and separates the heading and footing from the text with horizontal lines.
Graphical Overlays
The OVERLAY option of the SETPTR command can be used to specify the name of a catalogued subroutine that will be called at the start of each page of output and can be used to emit printer specific control codes to draw a graphical overlay on the page. The OVERLAY option of the query processor reporting commands performs the same action but applies only to the report in which it is used.
In either usage, the catalogued subroutine takes a single argument which is the print unit number. Any control strings output by this subroutine should be emitted using the PRINT statement, normally with the trailing carriage return/line feed suppressed. For PCL printers, it is recommended that the standard QMBasic PCL control string functions should be used.
Example
subroutine overlay(pu) $catalog overlay $include pcl.h
s = pcl.save.csr() ;* Save cursor position s := pcl.box(0,0,2320,3300,2,10) ;* Draw box s := pcl.restore.csr() ;* Restore cursor position s := pcl.left.margin(1) ;* Left margin column 1 print on pu s : return end
The above subroutine draws a box around an A4 sized page on a PCL printer. Note how it saves the cursor position to ensure that subsequent application output appears at the correct place.
Because the subroutine is called before any other output to the page, it is possible for the subroutine to make other changes to the page settings. Note in the above example how the left margin is indented to bring the application output away from the left edge of the box.
Commands Relating to Printing
Query Processor Keywords Relating to Printing
QMBasic Statements and Functions Relating to Printing
|