The SETPTR command sets print unit characteristics.
Format
SETPTR unit {, width, depth, top.margin, bottom.margin, mode {, options }}
SETPTR DISPLAY {LPTR {printer}}
SETPTR unit, DISPLAY
where
unit | is the print unit number in the range 0 to 255 or the keyword DEFAULT. |
width | is the page width in characters, excluding any left margin. |
depth | is the total page length in lines, including the top and bottom margins. A value of zero implies no pagination of the output data. |
top.margin | is the number of lines to be left blank at the top of the page. |
bottom.margin | is the number of lines to be left blank at the bottom of the page. |
mode | is the print unit mode: |
1 | Output is sent to a printer. |
3 | Output is directed to a hold file. |
4 | Output is directed to stderr (standard error). |
5 | Output is directed to the terminal auxiliary port. |
6 | Output is written to a file and also printed. |
options | qualify 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.
The options available are:
AS { NEXT } { id } | Specifies the hold file record name in modes 3 and 6. 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 a four digit 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.
AS PATHNAME path | Specifies a destination pathname for output in modes 3 and 6. |
AT printer.name | Specifies 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. |
BANNER text | Set the text to appear on a banner page. |
BRIEF | Suppresses the normal confirmation prompt before setting the printer characteristics. This is typically used in SETPTR commands from paragraphs or QMBasic programs. |
COPIES n | Specifies the number of copies to be printed. |
GDI | Specifies that the GDI mode API calls are to be used to initiate printing. |
KEEP.OPEN | Keeps the printer open to merge successive printer output. Use the PRINTER CLOSE command to terminate the print job. |
LANDSCAPE | When 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 n | Inserts a margin of n spaces to the left of the printed data. |
NEWLINE mode | Determines the newline sequence used by the QMBasic PRINT statement. This may be CR, LF or CRLF. The default is LF. |
NFMT | Specifies 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. |
NODEFAULT | Omitted options normally take their default values. Use of this keyword leaves the option at its current value. |
OPTIONS xxx | Passes the given option(s) to the underlying operating system print spooler (e.g. OPTIONS "landscape" on non-Windows systems). |
OVERLAY subr | Identifies 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. |
PCL | Specifies that this printer supports PCL. This option cannot be used with GDI mode Windows printers. |
PORTRAIT | Where supported by the underlying print driver, this keyword specifies that the output is to be printed in portrait format. |
PREFIX path | Sends 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. |
RAW | Specifies that the non-GDI mode API calls are to be used to initiate printing. |
SPOOLER name | Specifies 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 copies | If COPIES is greater than 1. |
-d prt.name | To set the printer name if AT is used. |
-t banner | Banner 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.
STYLE name | Specifies the name of a 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. |
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 n | Specifies the number of characters per inch. The value may be non-integer. |
DUPLEX | Selects duplex (double sided) printing, binding on the long edge. |
DUPLEX SHORT | Selects duplex (double sided) printing, binding on the short edge. |
LANDSCAPE | Prints the page in landscape format. |
LPI n | Specifies the number of lines per inch. The value must be 1, 2, 3, 4, 6, 8, 12, 16, 24 or 48. |
PAPER.SIZE xx | Specifies the paper size. Valid size names are A4, LETTER, LEGAL, LEDGER, A3, MONARCH, COM_10, DL, C5, B5. |
SYMBOL.SET xx | Specifies the character set. Valid values of xx are ROMAN8 (the default), LATIN1, ASCII, PC8. |
WEIGHT xx | Specifies 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. |
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.
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.
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. Headings, footings and other pagination related features are ignored for printers in mode 4.
The SETPTR DISPLAY command displays a report of the settings of all print unit. The optional LPTR keyword directs this report to a printer.
Examples
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.
SETPTR 0,80,66,0,0,3,AS SALES_REPORT,BRIEF
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:
PRINTER, SET.QUEUE, SP.ASSIGN
|