SETPTR

width

is 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.

depth

is 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.

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.

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 path

Specifies the pathname of the output file to be created (not the directory in which it is to be created) for output in modes 3 and 6. Use of this option with other mode values will result in an error.

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

BRIEF

Suppresses the normal confirmation prompt before setting the printer characteristics. This is typically used in SETPTR commands from paragraphs or QMBasic programs.

ENCODING mode

Sets 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. See Character Encodings for a summary of supported encodings. The hyphen in the UTF-8, UCS-2 and UTF-16 encoding names may be omitted.

INFORM

Displays 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.OPEN

Keeps the printer open to merge successive printer output. Use the PRINTER CLOSE command (not the QMBasic PRINTER CLOSE statement) 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".

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. Use of this mode is essential when sending binary data such as images to the printer.

OPTIONS xxx

Passes 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 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.

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.

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:

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 name

Specifies 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.

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.

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.

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.

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:

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 from a QM console session 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 auxiliary 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 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 units. 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

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.

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.

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