Managing printers and print jobs

About printer interface scripts

A ``printer interface script'' is a program that the print service uses to manage the printer each time it prints a file. The interface script initializes the printer, takes advantage of its particular capabilities, prints the file, and reports any errors.

The printer interface scripts are associated with the printer model and are located in /usr/spool/lp/model. For example, the printer interface script for a PostScript^® printer is called /usr/spool/lp/model/postscript. You can also create your own interface scripts or customize existing ones to suit your needs. See ``Creating printer interface scripts''.

Interface scripts:

initialize the printer port (the connection between the computer and the printer). The standard interface script uses stty(C) to initialize the printer port.
initialize the physical printer (restore the printer to a normal state in case a previously printed file has left it in an unusual state), setting the character pitch, line pitch, page size, and character set requested by the user. The standard interface script uses lp.set(ADM) to initialize the printer.
print banner page (or pages), if required.
print the requested files. The standard interface script calls the lp.cat(ADM) printer filter to print the files.
report any errors to the print service. The standard interface script uses lp.tell(ADM) to send descriptions of printer faults to the print service; the print service forwards that information as an alert to the print administrator.

The interface script does not open the printer port; the print service opens the printer port (or calls a dialup printer if that is how the printer is connected). The print service gives the printer port connection to the interface script as standard output and sets the printer to be the controlling terminal for the interface script. If the port experiences a hangup, a SIGHUP signal is sent to the interface script.

Many of the interface scripts provide special options that the user can specify with the -o option to lp(C). (Read the appropriate interface file for this information.) For example, the PostScript interface script includes the options listed in ``PostScript options''.

PostScript options

Option Description

land prints text in landscape mode

land2 prints text in two-page landscape mode

port prints text in portrait mode

raw prints a PostScript file. Use the raw option for PostScript files only; the PostScript interface script converts text files to PostScript automatically if you do not specify raw.

Option	Description
land	prints text in landscape mode
land2	prints text in two-page landscape mode
port	prints text in portrait mode
raw	prints a PostScript file. Use the raw option for PostScript files only; the PostScript interface script converts text files to PostScript automatically if you do not specify raw.

The print service runs the interface script to send the print job to the printer:

/usr/spool/lp/admins/lp/interfaces/printer id user title copies options file1 file2 ...

Arguments to the interface script are:

printer: The name of the interface script (the same as the printer name).
id: Request-ID returned by lp.
user: Login name of user who made the request.
title: Optional title specified by the user.
copies: Number of copies requested by the user.
options: List of blank-separated options, specified by the user (using lp -o) or by the print service (from default values specified by the administrator with lpadmin). See lp(C) for the list of options recognized by the standard interface.
file: Full pathname of a file to be printed.

When the interface script is invoked, standard input comes from /dev/null, standard output is directed to the printer port, and standard error output is directed to a file that will be displayed to the user who submitted the print request.

The print service passes additional printer configuration information to the interface script as shell variables:

TERM=printer-type: Specifies the printer type. The value is used as a key for getting printer capability information from the extended terminfo database.
FILTER='pipeline': Specifies the filter to use to send the request content to the printer; the filter is given control of the printer.
CHARSET=character-set: Specifies the character set to use when printing the content of a print request. The standard interface script extracts the control sequences needed to select the character set from the terminfo database.

Creating printer interface scripts

If you have a printer that is not supported by simply adding an entry to the terminfo database, or if your printing needs are not supported by the standard or other interface scripts provided in /usr/spool/lp/model, you can create your own printer interface script.

To create a customized interface script:

Start with the standard interface script (or one of the other scripts in /usr/spool/lp/model) and modify it, rather than starting from scratch. For example:

cd /usr/spool/lp/model
cp standard okidatanew
Make sure that the custom interface script sets the proper stty modes (terminal characteristics such as baud rate or output options). Look for the section that begins with this line:
```
   ## Initialize the printer port
```
Modify the code in the standard interface script. It sets both the default modes and the adjusted modes given by the print service or the user with a line like:

stty mode options 0<&1
This command line takes the standard input for the stty command from the printer port. For example, this stty command line sets the baud rate to 1200bps and sets some of the option modes:

stty -parenb -parodd 1200 cs8 cread clocal ixon 0<&1
Set the hardware flow control printer port characteristic. The standard interface script does not set hardware flow control. This is set according to your computer hardware. The code for the standard interface script suggests where to set this and other printer port characteristics. Look for the section that begins with this line:
```
   # Here you may want to add other port initialization code.
```
Because different printers have different numbers of columns, make sure the header and trailer for your interface script correspond to your printer. The standard interface script prints a banner that fits on an 80-column page (except for the user's title, which may be longer). Look for the section in the code for the standard interface script that begins with this line:
```
   ## Print the banner page
```
Specify that the custom interface script print all user-related error messages to the standard output or to the standard error. The print service prints standard output errors on the page and mails standard error to the user.
Specify that when printing is complete, the interface script exits with a code that tells the status of the print job. ``Exit codes'', describes how the print service interprets exit codes.
One way of alerting the administrator to a printer fault is to exit with a code of 129. Unfortunately, if the interface script exits, the print service reprints the print job from the beginning once the fault is cleared. To get an alert to the administrator without reprinting the entire job, specify that the interface script send a fault message to the print service, but wait for the fault to clear. When the fault clears, the interface script resumes printing the job. When finished printing, the interface script can exit with zero as if the fault never occurred. An added advantage is that the interface script can detect when the fault is cleared automatically so that the administrator does not have to reenable the printer.
To specify that fault messages be sent to the print service, use lp.tell(ADM). The standard printer interface code calls lp.tell(ADM) with the LPTELL shell variable. The lp.tell program sends its standard input to the print service. The print service forwards the message as an alert to the administrator. If its standard input is empty, lp.tell does not initiate an alert. Examine the code immediately following these comments in the standard interface script for an example of how to use the lp.tell (LPTELL) program:
```
   # Here's where we set up the $LPTELL program to capture
   # fault messages.
   #
   # Here's where we print the file.
```
With the special exit code 129 or lp.tell, there is no longer the need for the interface script to disable the printer itself. Your interface script can disable the printer directly, but doing so overrides the fault-alerting mechanism. Alerts are sent only if the print service detects that the printer has faulted and the special exit code and lp.tell program are its main detection tools.
If the print service has to interrupt the printing of a file at any time, it kills the interface script with a signal 15 (see the signal(S) and kill(C) manual pages for more information).
If the interface script dies from receipt of any other signal, the print service assumes that future print jobs are not affected and continues to use the printer. The print service notifies the person who submitted the print job that the job did not finish successfully.
The signals SIGHUP, SIGINT, SIGQUI, and SIGPIP (trap numbers 1, 2, 3, and 13) start out being ignored when the interface is invoked. The standard interface script changes this to trap these signals at appropriate times, interprets these signals to mean that the printer has a problem, and issues a fault.

Exit codes

Code Meaning to the print service

0 The print job completed successfully. If a printer fault occurred, it was cleared.

1 to 127 The print service encountered a problem in printing the job (for example, there were too many nonprintable characters or the job exceeded the printer's capabilities). This problem does not affect future print jobs. The print service should notify the person who submitted the print job (via write(C) or mail(C)) that an error occurred in printing the job. If a printer fault occurred, it was cleared.

128 Reserved for internal use by the print service. Interface scripts must not exit with this code.

129 The print service encountered a printer fault in printing the job. This problem affects future print jobs. If the fault recovery for the printer directs the print service to wait for the administrator to fix the problem, the print service should disable the printer. If the fault recovery is to continue printing, the print service should not disable the printer, but try printing again in a few minutes.

> 129 Reserved for internal use by the print service. Interface scripts must not exit with codes in this range.

Code	Meaning to the print service
0	The print job completed successfully. If a printer fault occurred, it was cleared.
1 to 127	The print service encountered a problem in printing the job (for example, there were too many nonprintable characters or the job exceeded the printer's capabilities). This problem does not affect future print jobs. The print service should notify the person who submitted the print job (via write(C) or mail(C)) that an error occurred in printing the job. If a printer fault occurred, it was cleared.
128	Reserved for internal use by the print service. Interface scripts must not exit with this code.
129	The print service encountered a printer fault in printing the job. This problem affects future print jobs. If the fault recovery for the printer directs the print service to wait for the administrator to fix the problem, the print service should disable the printer. If the fault recovery is to continue printing, the print service should not disable the printer, but try printing again in a few minutes.
> 129	Reserved for internal use by the print service. Interface scripts must not exit with codes in this range.

Setting up printer interface scripts

By default, the print service uses the standard interface script, /usr/spool/lp/model/standard. This interface script should handle most of your printing needs. If you plan to use the standard interface program, simply select the standard model when you add the printer.

If the standard interface script does not meet your needs, you might be able to use one of the printer interface scripts provided in the /usr/spool/lp/model directory. When you add the printer, select the model name from the list that most closely matches your printer. See ``Adding local printers''. (You do not need to perform any special tasks to use either the standard interface or one of the other interfaces provided.)

To change the interface script after you add the printer, in the Printer Manager, select Model from the Settings menu.

If neither the standard interface script nor the scripts listed by the Printer Manager (or in /usr/spool/lp/model directory) work for your printer, you can modify an existing printer interface script or create your own. See ``Creating printer interface scripts''.

If you use a customized printer interface script, you must associate it with your printer. To do this, place the script in the /usr/spool/lp/model directory. In the Printer Manager, select Model from the Settings menu and select the customized printer interface script from the list. When you associate a printer with a customized interface script, the Printer Manager copies the specified printer interface program to the /usr/spool/lp/admins/lp/interfaces directory and renames the file printer_name.