Top  Previous  Next


The SETPTR command sets print unit characteristics.





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






unitis the print unit number in the range 0 to 255 or the keyword DEFAULT.


widthis the page width in characters, excluding any left margin. This value is used to calculate alignment in query processor reports and headings/footings but does not prevent application programs emitting data that exceeds this width.


depthis the total page length in lines, including the top and bottom margins. This value is used to control insertion of form feeds, headings and footings. into the printed data. A value of zero implies no pagination of the output data.


top.marginis the number of lines to be left blank at the top of the page.


bottom.marginis the number of lines to be left blank at the bottom of the page.


modeis the print unit mode:
1Output is sent to a printer.
3Output is directed to a hold file.
4Output is directed to stderr (standard error).
5Output is directed to the terminal slave printer port.
6Output is written to a file and also printed.


optionsqualify the destination as described below. There should be a comma between each option.


If only unit is given, the current settings of the print unit are reported.


Use of the DEFAULT keyword in place of a unit number records the default values to be used when a new print unit is accessed without prior use of SETPTR to define its settings. Note that this operation does not affect the default printer, print unit 0, which is configured with standard default settings on entry to QM. These can be changed with a SETPTR command specifying unit 0.


The third form of SETPTR with a unit number and the DISPLAY keyword shows the current settings in a form that can be captured by a program and later used to restore the settings by executing a SETPTR command with the captured value appended.


When using printer modes 3 or 6, 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.



The options available are:


AS { FILE name}Specifies an alternative hold file name instead of the default $HOLD for modes 3 and 6. Use of this option with other mode values will result in an error. The name must reference a directory file.
AS { NEXT } { id }Specifies the hold file record name in modes 3 and 6. Use of this option with other mode values will result in an error. At least one of the optional components must be present.

id is the name of the record to be created in the $HOLD file. If omitted, a default name of Punit is used.

The optional NEXT keyword causes QM to attach an underscore and a cyclic sequence number to the end of the name so that successive output is stored separately. Note that this sequence number is shared across all printer output directed to the $HOLD file by all processes, thus two successive jobs from one process may have non-adjacent sequence numbers. The default behaviour is for the sequence number to be four digits, cycling through the range 0001 to 9999. The next available sequence number is stored in field 2 of a record named $NEXT in the dictionary of the $HOLD file. An alternative number of digits in this value may be specified in field 3 of this dictionary record and must be in range 3 to 9. The sequence number can be determined using the GETPU() function or the @SEQNO variable. If id is a quoted null string, the underscore is omitted.

These two variants of the AS clause may be combined (AS FILE name NEXT id). When used in this way the sequence number management process described above uses the dictionary of the named file. Use of AS NEXT "" will create items where the name is just the sequence number.

AS PATHNAME pathSpecifies a destination pathname for output in modes 3 and 6. Use of this option with other mode values will result in an error.
AT printer.nameSpecifies the printer name in modes 1 and 6. This name must be enclosed in quotes if it contains spaces or backslashes. The name is case sensitive except on Windows. Note that printing occurs on the server on which QM is running and the printer name must be known to the server.

Mode 5 provides a way to print on printers connected to the client system. For users connecting to QM from AccuTerm using a terminal type with the -at suffix, the AT option can be used to select a printer name which is known to the client PC.

BANNER textSet the text to appear on a banner page.
BRIEFSuppresses the normal confirmation prompt before setting the printer characteristics. This is typically used in SETPTR commands from paragraphs or QMBasic programs.
COPIES nSpecifies the number of copies to be printed. Some printers may not handle this option.
EJECTAppends a form feed to the end of the print data.
ENCODING modeSets the character encoding to be used for this printer. On ECS mode systems, the default behaviour is to output the low order byte of each character which will lead to incorrect printed output if characters outside the 8 bit set appear in the data. On all systems, ECS or non_ECS, the ENCODING option can be used to set a character encoding such as UTF-8. Encoding can be used with all print modes except mode 4 (print to standard error). Used with mode 6 (file and printer), the same encoding applies to both destinations.
FORM.FEED modeDetermines the form feed sequence used by the QMBasic PRINT statement. This may be FF or CRFF. The default is CRFF.
GDISpecifies that the GDI mode API calls are to be used to initiate printing on Windows systems.
INFORMDisplays file details when opening a print file in mode 3. Except in phantom or QMClient processes, the session will pause for 1.5 seconds after the message is displayed to allow for situations where the screen would be overwritten.
KEEP.OPENKeeps the printer open to merge successive printer output. Use the PRINTER CLOSE command to terminate the print job.
LANDSCAPEWhen used without the PCL option, this option is passed to the underlying print driver to request landscape format printing where this is supported. On non-Windows platforms, this is equivalent to use of OPTIONS "landscape".
LEFT.MARGIN nInserts a margin of n spaces to the left of the printed data.
NEWLINE modeDetermines the newline sequence used by the QMBasic PRINT statement. This may be CR, LF or CRLF. The default is LF.
NFMTSpecifies that no page formatting is to be applied to the output data. The entire output is treated as a single page with no further inserted form feeds or top and bottom margins.
NHEADSuppress banner page (default)
NODEFAULTOmitted options normally take their default values. Use of this keyword leaves the option at its current value.
NOEJECTSuppresses the normal page throw at the end of a print job. This option applies to Windows only.
NOHEADSuppress banner page (default)
OPTIONS xxxPasses the given option(s) to the underlying operating system print spooler (e.g. OPTIONS "landscape" on non-Windows systems). Multiple options may be given as a single quoted qualifier to the OPTIONS setting.
OVERLAY subrIdentifies a catalogued subroutine that will be executed at the start of each page of output. This subroutine takes a single argument which is the print unit number and can be used to send printer control codes for a graphical page overlay, if required. It should not perform any other printer output. This option is ignored for Windows GDI mode printing.
PCLSpecifies that this printer supports PCL. This option cannot be used with GDI mode Windows printers.
PORTRAITWhere supported by the underlying print driver, this keyword specifies that the output is to be printed in portrait format.
PREFIX pathSends the contents of the named file to the printer at the start of each job. This can be used to send printer specific commands for features that are not available through other SETPTR options. This option is ignored for Windows GDI mode printing.
RAWSpecifies that the non-GDI mode API calls are to be used to initiate printing.
SPOOLER nameSpecifies and alternative spooler to be used on non-Windows systems. If not specified, the spooler selected by the SPOOLER configuration parameter is used or, if this is not set, the standard lp spooler is used. The name can include other spooler options if required but must be quoted if it includes spaces or other reserved characters. The actual command executed to print the job will be name with options appropriate to lp added as follows:
-n copiesIf COPIES is greater than 1.
-d prt.nameTo set the printer name if AT is used.
-t bannerBanner text if BANNER is used.
-o "options"Text from OPTIONS if used.
-o "landscape"If LANDSCAPE is used.

The SPOOLER option can be used to access another standard operating system spooler package or to direct output to a user written shell script or program to perform custom processing. The $SPOOLERS record in the VOC of the QMSYS account can be used to configure different options from those described above. See Printing for details. As an aid to diagnosing printing problems, the SPOOL.COMMAND option of the OPTION command can be used to display the operating system command used to initiate printing.

STYLE nameSpecifies the name of an X-type VOC record that defines the query processor report style to be used for all reports directed to this print unit unless overridden by the STYLE option in the query command.


GDI Printers

The following additional options can be used with GDI mode printers on Windows. If neither of the FONT and FONT.SIZE options is present, the printer's default font is used, otherwise default values are as shown below.


FONT nameSets the font name. Defaults to Courier New if omitted. The font name must be quoted if it contains spaces.
FONT.SIZE nSpecifies the font size. If n is omitted, specified as zero or DEFAULT, 10 point size is used.


PCL Printers

The following additional options are available. Although the values set will be saved and can be accessed by application software, they only affect printing when used with the PCL option. In many cases, the list of acceptable parameter values can be extended by modifying the SYSCOM $PCLDATA record.


CPI nSpecifies the number of characters per inch. The value may be non-integer.
DUPLEXSelects duplex (double sided) printing, binding on the long edge.
DUPLEX SHORTSelects duplex (double sided) printing, binding on the short edge.
FONT nameSets the font name. The font name must be quoted if it contains spaces.
LANDSCAPEPrints the page in landscape format.
LPI nSpecifies the number of lines per inch. The value must be 1, 2, 3, 4, 6, 8, 12, 16, 24 or 48.
PAPER.SIZE xxSpecifies the paper size. Valid size names are A4, LETTER, LEGAL, LEDGER, A3, MONARCH, COM_10, DL, C5, B5.
SYMBOL.SET xxSpecifies the character set. Valid values of xx are ROMAN8 (the default), LATIN1, ASCII, PC8.
WEIGHT xxSpecifies the font weight. Valid values of xx are ULTRA-THIN, EXTRA-THIN, THIN, EXTRA-LIGHT, LIGHT, DEMI-LIGHT, SEMI-LIGHT, MEDIUM, SEMI-BOLD, DEMI-BOLD, BOLD, EXTRA-BOLD, BLACK, EXTRA-BLACK, ULTRA-BLACK though specific printers might not support all values.


When setting a print unit to PCL mode, if the above parameters are not specified, printing defaults to 10 cpi, 6 lpi, medium weight using A4 paper and the Roman8 symbol set. These defaults can be modified by adding an X-type record named $PCL to the VOC. This record must have an X as the first character of field 1. Remaining fields may contain any of the CPI, LPI , PAPER.SIZE, SYMBOL.SET and WEIGHT parameters as described above. For example:

0001: X


0003: LPI 5


Note: The quality of PCL implementations varies widely and these options may not give the expected results on some printers. In particular, setting some font metrics may cause inconsistent character placement. It is the application developer's responsibility to ensure that the printed results are acceptable.



Windows Printing


On Windows systems, two styles of interface with the underlying Print Manager are supported. The GDI mode uses the Windows Graphical Device Interface API calls. Non-GDI mode uses an alternative set of API calls. For most purposes, the non-GDI mode is likely to be preferable.


The GDI parameter to SETPTR sets GDI mode and the RAW parameter sets non-GDI mode. The default is normally non-GDI but this can be modified by setting the GDI configuration parameter to 1.



Special Print Modes


Use of mode 4 (stderr) allows an application developer to direct output to the standard error file handle. It is the user's responsibility to ensure that this points to an appropriate destination as the default settings may cause the screen display to be overwritten. Data sent to a mode 4 printer is output immediately rather than being buffered by QM. Headings, footings and other pagination related features are ignored for printers in mode 4.


Mode 5 print units direct output to the terminal slave printer port, typically to a printer local to the client. The data is buffered by QM until the print unit is closed and then sent to the terminal prefixed by the string defined in the mc5 terminfo entry for the selected terminal type. The data will be followed by the string defined by the mc4 terminfo entry. The mc5/mc4 pair should be set to the control codes necessary to enable/disable the slave printer port. For users connecting to QM via AccuTerm with a terminal type that has a -at suffix, the AT option to SETPTR can be used to select a printer name that is known to the client PC.



The SETPTR DISPLAY command displays a report of the settings of all print unit. The optional LPTR keyword directs this report to a printer.





When setting print unit configuration, the SETPTR command checks for an X-type record named $SETPTR.DEFAULTS in the VOC  or, if not found, in the QMSYS VOC. If this record exists, fields 2 onwards can be used to set default options that will effectively be inserted after the mode value. Each field corresponds to a different print mode such that field 2 is used for mode 1, field 3 is used for mode 2 (currently not supported on QM), field 4 is used for mode 3 and so on. Thus, a $SETPTR.DEFAULTS record that reads

1: X


would behave as though these two options were present when setting a print unit into mode 1. Because the default options are inserted between the mode and options elements of the command, they can be overridden by other options specifically set in the command.





SETPTR 0,80,66,3,3,1,AT laser,BRIEF

Directs print unit 0 output to a printer named "laser" with a page shape of 80 columns by 66 lines and a 3 line top and bottom margin. The BRIEF option suppresses the normal confirmation prompt.



Directs print unit 0 output to a record named "SALES_REPORT" in the $HOLD file. The BRIEF option suppresses the normal confirmation prompt.


SETPTR 0,,,,,3

Directs print unit 0 output to the default $HOLD file record (P0), leaving all page shape parameters unchanged.



See also: