Printers

This chapter discusses how to configure and use print devices in InterSystems IRIS® data platform. 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.

Windows systems handle a printer as a sequential I/O device, and thus follows the same syntax as sequential file I/O. However, a printer connected through a serial communications port is handled as a terminal I/O device.
UNIX® systems always handle a printer as a terminal I/O device. UNIX® treats it as a “character special” file on a tty device, and thus follows the same syntax as terminal I/O.

On a Windows system, you can return a count of the current printers on your system using the %Library.Device.InstalledPrinters()Opens in a new tab method. You can return a list of the current printers on your system using the %Library.Device.GetPrinters()Opens in a new tab 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:

Call the %IS utility, which allows you to specify the device by using a mnemonic defined in the %IS global. This utility opens the device and sets its parameters.
Issue the I/O commands OPEN, USE, and CLOSE, using the operating system device name, specified as a quoted string.

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 InterSystems IRIS 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"

Parameter	Description
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, InterSystems IRIS 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 InterSystems IRIS. 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”	“IRIS”	/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 InterSystems IRIS 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.

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, InterSystems IRIS 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 Enter, 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 InterSystems IRIS 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 System Administration, 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 System Administration, Configuration, Device Settings, Devices. Select Edit for the current terminal device and specify an Alternate Device value.

Spool Device