Caché I/O Device Guide
Printers
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

This chapter discusses how to configure and use print devices in Caché. A printer is a physical output-only device. A printer may be a character printer, or a non-character device such as a fax or plotter.

In most cases, output is not sent directly to a printer. Often, output to be printed is first sent to a logical spool device (the ^SPOOL global). The contents of the ^SPOOL global can then be sent to the physical printer. For further details on spooling, refer to the Spool Device chapter of this manual.
Overview of Printers
Note that Windows and UNIX® handle printer I/O differently.
On a Windows system, you can return a count of the current printers on your system using the %Library.Device.InstalledPrinters() method. You can return a list of the current printers on your system using the %Library.Device.GetPrinters() method.
Specifying a Printer
A printer can be assigned a device number between 256 and 2047, inclusive. This range of device numbers are also used for terminals and flat files.
On a Windows system, you can refer to a printer using its device number or an assigned device mnemonic. The Windows default printer mnemonic is |PRN|.
There are two ways to specify a printer:
Opening a Printer
When opening a printer, you can use the device name to specify the device. The device name must be enclosed in quotes. The maximum length of this device name is 256 characters. The form is as follows:
OPEN "device"
USE "device"
CLOSE "device"
On Windows, you can also have a printer attached to a serial communications port. In this case, the printer is treated the same as terminal I/O with the following syntax:
OPEN "comn:"
Where n is the port number to which the printer is attached.
Specifying a Printer on Windows
To use the default printer on Windows, enter the following:
   OPEN "|PRN|"
This causes Caché to use the default Windows printer for your machine, if you have set the default printer for your machine. (For information on how to set the default printer, see your Windows documentation.)
To use a printer other than the default printer, enter the following:
  OPEN "|PRN|printer"
printer The Universal Naming Convention (UNC) name or a name that shows up on your machine's list of printers (Print Manager in Windows NT, 2000, and XP).
The following example illustrates the use of a UNC name:
   OPEN "|PRN|\\business\accounting"
The following example illustrates the use of a non-UNC name that might appear on your machine's list of printers:
   OPEN "|PRN|HP LaserJet 5P"
Note:
InterSystems discourages the use of printer port names like COM1, LPT1, etc. If you do use such a name, Caché will try to figure out which printer, if any, that name refers to and then it will use that name. However, this will be a slow operation and is not really appropriate for Windows
On Windows systems, a printer is identified by the name on the OPEN command and is handled by the sequential I/O module, not the terminal I/O module. Thus the OPEN and USE command arguments supported are the same as those for sequential file I/O, not terminal I/O. The exception to this is a printer connected to a Windows system through a serial communications port; in this case, the printer is handled as a terminal I/O device.
On Windows systems, you cannot use the “:n” positional parameter to control the print margin used. Such notation is ignored by Caché. Code such as "|PRN|":121 is ignored. To control the printer width, send the appropriate control characters for that printer. The notation does work on other platforms.
On Windows, OPEN supports most of the sequential I/O keyword parameters, as described in the Sequential File I/O chapter of this manual. The following table describes additional printer keyword parameters for controlling a printer (handled as a sequential file) on Windows systems with the OPEN command.
Additional OPEN Keyword Parameters for Windows Printers
Keyword Default Description
/DOCNAME= “name “Cache” /DOCNAME enables you to redefine the printer job name.
/OUTPUTFILE= “filename NULL /OUTPUTFILE redirects print to a file. Specify a fully-qualified pathname.
/DATATYPE= “type “RAW” /DATATYPE enables you to redefine the datatype of the printer spool data. One frequently-used datatype is TEXT.
On Windows systems, if the OPEN prints directly to the printer (does not use a logical spool device), the OPEN command timeout argument does not expire if the printer is turned off or does not exist. The Caché process remains in a suspended state until the printer becomes available, or until the print document is cancelled from the Windows Control Panel.
Specifying a Printer on UNIX®
To open an I/O device on a terminal that has the UNIX® device name /dev/tty06, enter the following command
   OPEN "/dev/tty06"
On UNIX® systems, a printer is identified by the name on the OPEN command and is handled as a “character special” file on a tty device. Thus the OPEN and USE command arguments supported are the same as those for terminal I/O, not sequential file I/O.
On UNIX®, OPEN supports most of the terminal I/O keyword parameters, as described in the Terminal I/O chapter of this manual. The following table describes additional printer keyword parameters for controlling printers on UNIX® systems with the OPEN command.
Additional OPEN Keyword Parameters for UNIX® Serial Printers
Keyword Default Description
/DOCNAME= “name “Cache” /DOCNAME enables you to redefine the printer job name.
/OUTPUTFILE= “filename NULL /OUTPUTFILE redirects print to a file. Specify a fully-qualified pathname.
/DATATYPE= “type “RAW” /DATATYPE enables you to redefine the data type of the printer spool data. One frequently-used data type is TEXT.
Directing Output to a Printer
You can use the %IS utility to direct output to a printer. You can invoke the %IS utility with the command DO ^%IS. (You can also use DO OUT^%IS to specify that you are selecting an output-only device.) In either case, Caché returns the Device: prompt. To specify a printer, reply with either the default mnemonic "|PRN|", or the mnemonic of another configured printer. The %IS utility then suggests OPEN parameters; for a printer, the default is “W” (write-only). You can accept the parameter default by pressing Return, as shown in the following example:
%SYS>DO ^%IS
Device: |PRN|
Parameters? "W" => <RETURN>
%SYS>
This opens the specified printer as an output device for the current process.
The %IS utility sets various variables. The following are the printer default values on a Windows system.
Variables Set by %IS
Variable Value Description
IO |PRN| Device mnemonic of selected device.
IOF # Form feed character. WRITE # issues a form feed and changes $Y. WRITE @IOF should be used to form feed.
IOBS $C(8) Backspace/overprint character (ASCII 8). WRITE $CHAR(8) issues a backspace and changes $X. WRITE *8 issues a backspace but does not change $X. WRITE @IOBS should be used to backspace.
IOM 132 Right margin; line length in characters.
IOSL 66 Page length in characters.
IOT OTH Device type. Here “Other”.
IOST P-DEC Device subtype name.
IOPAR ("W") OPEN parameters. Here “W” because a printer is a write-only device.
MSYS M/WNT Type of system (such as UNIX® or Windows NT). M/WNT is Caché on Windows NT.
POP 0 Indicates that %IS was run (and these variables initialized). If 0, a device was specified. If 1, no device was specified (user entered STOP in response to the Device: prompt).
Most of these values can also be viewed and set from the Management Portal. Select [Home] > [Configuration] > [Device Settings]. View the current contents of Devices and Device SubTypes. Select Edit to view the settings for a specific printer.
%IS Printer Set-Up Variable
When you call %IS for spooling, you can pass it the IOPGM variable, which specifies the name of the routine that sets up printer forms alignment.
Printer as Alternate Device
You can specify a printer as the alternate device for all processes by defining a new device named “A” and specifying a physical device of |PRN|. Then when you use %IS, specify A at the Device: prompt.
You can set a printer as the alternative I/O device for a terminal process. Go to the Management Portal. Select [Home] > [Configuration] > [Device Settings] > [Devices]. Select Edit for the current terminal device and specify an Alternate Device value.