SETPTR

Top  Previous  Next

 

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

 

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.

 

depthis the total page length in lines, including the top and bottom margins. 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 auxiliary 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.

 

 

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 pathSpecifies a destination pathname for output in modes 3 and 6.
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.
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.
GDISpecifies that the GDI mode API calls are to be used to initiate printing.
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.
NODEFAULTOmitted options normally take their default values. Use of this keyword leaves the option at its current value.
OPTIONS xxxPasses the given option(s) to the underlying operating system print spooler (e.g. OPTIONS "landscape" on non-Windows systems).
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.

STYLE nameSpecifies 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 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.
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.

 

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