Top  Previous  Next


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.


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.


The QMBasic PRINT statement directs its output to printer 0 unless the ON clause is used to specify some other printer:

PRINT ON 4 "Invoice Summary"


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.



Two Printing Models


There are two related methods by which the physical destination of printed output can be set. For compatibility with Information style multivalue products, QM supports the SETPTR command to set the characteristics of a print unit, including its destination.


Alternatively, for compatibility with Pick style products, a set of printer characteristics can be associated with a numbered form queue by use of the SET.QUEUE command which saves the characteristics in the file system for future reference by the SP.ASSIGN command.


The fundamental difference between the two approaches is that SETPTR directly specifies printer characteristics that take immediate effect whereas SET.QUEUE defines characteristics that can be set later by referencing the form queue number in an SP.ASSIGN command. Internally, SP.ASSIGN is simply executing a SETPTR command based on the characteristics previously defined using SET.QUEUE. The two printing models can be mixed in any way the application designer wishes.



Setting Print Unit Characteristics with SETPTR


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 command is frequently 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:

SETPTR unit {, width, depth, top.margin, bottom.margin, mode {, options }}


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. The name of the file used by mode 3 can be set using the AS option of the SETPTR command which includes the ability to add a rotating sequence number for generate a different name for each output job. This sequence number can be determined using the QMBasic GETPU() function or the @SEQNO variable.

Mode 4 directs the output to 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 slave printer 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.



Pick Style Form Queues


Although Pick style systems support the ON clause of the Basic PRINT statement, applications that need only one printer at a time more usually determine the output destination by selecting a numbered form queue. As an aid to migration, 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.


The SET.QUEUE command is very similar to SETPTR but instead of assigning the specified characteristics to a numbered print unit, they are stored in the $FORMS file with a numeric id that corresponds to the form queue number. Subsequent use of the SP.ASSIGN command picks up the form queue details from the $FORMS file and applies these to printer 0 by internal use of SETPTR. The R option of SP.ASSIGN allows the form characteristics to be applied to a different print unit.


Whereas each QM process has its own set of 256 numbered print units, form queue numbers and their settings are normally shared across all QM sessions because the same $FORMS file is visible to all accounts. By creating alternative $FORMS files and modifying the VOC F-pointer, it is possible to maintain separate form definitions for specific accounts or groups of accounts.


For more information, see the SP.ASSIGN and SET.QUEUE command descriptions.



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. QM does not provide any functions to generate GDI graphics. When using GDI mode, the printer's default font can be replaced by a fixed pitch font of a given size by use of the FONT.SIZE option to SETPTR.


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.


Use of print spoolers other than lp may require QM to use different options to the command to pass the printer name, copy count, etc. To support this, there is an X-type record in the VOC file of the QMSYS account named $SPOOLERS. This has six associated multivalued fields such that:

Field 2Spooler name
Field 3Option to specify printer name
Field 4Option to specify copy count
Field 5Option to specify banner text
Field 6Option to set spooler options
Field 7Option to set landscape mode


In each case, the variable data to be inserted into the option is represented by a percent sign (%). The $SPOOLERS record released with QM contains a definition for use of lpr. This has

Field 2lpr
Field 3-P %
Field 4-K %
Field 5-T "%"
Field 6-Z "%"
Field 7-Z "landscape"



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.


When a print unit is directed to a file, a check is made to see if there is a catalogued subroutine named HOLD.FILE.LOGGER and, if there is, this is called when the file is opened and again when it is closed. This subroutine can be used, for example, to build a log of hold file entries or to take some action after the file has been closed. The subroutine takes three arguments; the print unit number, a flag indicating if this is an open (1) or a close (0), and the pathname of the file being created.



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. Default values for the PCL parameters can also be set using a $PCL VOC record. For more details, see the SETPTR command.


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.





subroutine overlay(pu)

$catalog overlay

$include pcl.h


  s =               ;* Save cursor position

  s :=,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 :




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


CLEAN.ACCOUNTClears $HOLD and other system temporary files.
PRINTERVarious printer control operations
SET.QUEUEDefine a form queue
SETPTRDisplay or set print unit characteristics
SP.ASSIGNSet printer parameters using form queue emulation
SPOOLSends record(s) to the printer



Query Processor Keywords Relating to Printing


FOOTINGSet page footing
HEADINGSet page heading
LPTRDirect output to a printer (applies to many commands)



QMBasic Statements and Functions Relating to Printing


FOOTINGSet page footing
HEADINGSet page heading
GETPU()Retrieve print unit characteristics
PAGEForce a new page
PRINTEmit data to a print unit
PRINTER CLOSEClose a print unit
PRINTER OFFDirect print unit 0 to the screen
PRINTER ONDirect print unit 0 to the printer
PRINTER RESETResets the default print unit
PRINTER DISPLAYDirect printer output to the screen
PRINTER FILEDirect printer output to a file
PRINTER NAMEDirect printer output to a named printer
SETPUSet print unit characteristics