This chapter discusses the printer model files and describes the modifications to be made by printer-driver developers to the printer model file template.
The following major topics are discussed in this chapter:
Model files are Bourne shell scripts that form an interface between the System V, Release 3 spooling system and the printer. Each printer has its own model file, which is customized by the printer installation tools when the printer is installed. The customized copy of the printer model file is the interface file. The interface file is invoked by the spooling scheduler lpsched when the printer is ready to accept a new print job. The interface file sets up printer-specific options, calls filters, and invokes the printer driver.
System V model files differ greatly from BSD /etc/printcap entries. The reader unfamiliar with System V spooling should refer to the IRIX Admin: Peripheral Devices manual for more information.
The model file expects these command-line arguments from lpsched in the order listed:
| 1 | ||
| 2 | ||
| 3 | ||
| 4 | ||
| 5 | -o printer options | |
| 6-n | name(s) of the file(s) to be printed |
The end user does not invoke the model file manually; it is invoked only through lpsched. If you want to check for gross syntax errors, you can do this quickly by running the model file with dummy arguments such as:
laserjetPJL_model a b c d e |
Not all errors can be found this way, since the model file does not run to completion, but this does provide a quick test for gross syntax errors. If errors are found, putting the -x flag at the end of the first line in the model file may help debug the error. See the sh(1) reference pages for more details on debugging Bourne shell scripts.
This section explains how the Impressario model files work.
The source code for the template laserjetPJL_model file is located in the directory /usr/impressario/src/models. The main steps in the template model file are shown below and described in more detail in the following sections:
Declare global and external variables and define convenience functions.
Interpret and store the command-line options.
Verify that the prerequisites are in place.
Set the output device driver, which can be either a driver for the parallel port or a driver for a network card that is installed in a printer.
Invoke the driver to update the POD status file with the current printer state and the current job setting.
Note: This is an important step. All filters use the status file to determine what parameters to use. The driver must ensure that the POD status file is absolutely up to date before the first filter is run, or a change in printer status between jobs could compromise the next job. Start the active icon tagging subprocess.
If pages stack face down, print a banner page if requested.
Use filters to convert the submitted file to the data type required by the printer driver.
Invoke the printer driver with the converted data.
Repeat steps 8 and 9 for each file to be printed and report any errors encountered to standard error.
If pages stack face up, print a banner page if requested.
Clean up after the job and exit with an appropriate exit code.
The steps given below tell you what variables to declare. Note that variable names are in all uppercase letters. Those variables are exported for use by the filters invoked when converting input files into printable data. See the fileconvert(1) reference page for more information.
Define NAME and TYPE. If the type is not defined, then the model file writes an error message and exits.
Append the standard error output from the filters and driver to the spooler log file.
Define the file paths, directory paths, and Boolean flags used in the model file.
Define the locations and options for all filters. (The model file checks to make sure that the printer-specific driver exists and that the spooler log file is writable. If these conditions are not met, the model file writes an error message and exits.)
The next portion of the model file contains various convenience functions used within the model file. The convenience functions listed in Table 3-1 are routines contained within the model file. These routines are used for parsing the -o options and for various utility functions.
Table 3-1. Convenience Functions
Function Name | Description |
|---|---|
BeginTagging() | Sets up the tagging job that monitors the printer's status. |
CleanUpAfterJob() | Does any cleanup needed at the end of the job. |
EndTagging() | Ends the tagging of the printer. |
ParseOptions() | Parses the -o command-line options and sets appropriate variables. Expects the command-line options string as the first argument. |
PrintBannerPage() | Prints a banner page. |
PrintMessage() | Prints its arguments as text on the printer. Used to report errors to the user. Accepts any number of arguments. |
ReportBadFile() | Reports unknown file type to the printer and to the spooler log. Expects the filename as the first argument and the file type as the second argument. |
ReportUnknownOption() | Reports an error when an unknown option is parsed. Expects the unknown option as the first argument. |
SetCancelTrap() | Sets up the trap command for the signals SIGHUP, SIGINT, and SIGTERM. |
SetDebug() | Turns on debugging mode for all filters and drivers. |
SetDeviceDriver() | Sets the output device driver to a parallel port driver or to a driver for a network card installed in a printer. |
TestExitStatus() | Interprets exit status from the last command and sends error message to both the spooler log and the printer if needed. Expects the exit code of the last command as the first argument, a string describing the last command as the second argument, and the file in question as the third. |
The template model file follows these steps to process command-line arguments:
Retrieve the command-line arguments.
Set up the cancellation signal handler for SIGHUP, SIGINT, and SIGTERM. This allows the user to cater the job cancellation signal sent by the spooler and clean up.
Parse the options passed with the -o switch.
Set the device driver.
If the verbose switch is set, send a message to the spooler log that the job has begun filtering.
Call the printer status and communications driver to update the status database before job filtering begins.
Start the tagging subprocess to tag the printer's workspace icon with the appropriate print-engine type and status.
The model file prints a banner page is printed if the banner switch is set. (The banner page may be printed last for face-up stacking printers.)
The fileconvert command automatically determines the file type of each file using the Indigo Magic file typing rule database. (See the reference pages for ftr(1) and fileconvert.) If a fast text path exists, and the user has not requested options that require the slower path, then the file is converted using the fast text path. Otherwise, the normal fileconvert path is used. See the template model file for specifics.
fileconvert produces a shell command string that, when executed, produces the requested data type on standard output.
If the file could not be converted, ReportBadFile() is called; otherwise the fileconvert shell program is executed and the output piped to the printer driver.
TestExitStatus() is called to test whether the driver reported an error.
After the printing is complete, perform any needed cleanup.
End the tagging subprocess.
Append an ending message to the log file if the debug switch is set.
If there were unsupported file types in the list of files to be processed, exit the model file with an easily understood error code.
The -o option to the spooler allows model files to accept a variety of non-spooler options. These are the options specified with -o on the lp command line. It is these options that are produced by the graphical printer options panel.
Impressario defines a number of general file filtering options for the convenience of the end user, and reserves those option names.
The reserved options are listed in Table 3-2 in alphabetical order. Their meanings should not be changed by printer driver developers. Developers should choose short, understandable option names for any additional options. These options may be seen by end users, so they should not be verbose.
Table 3-2. Reserved Option Names
Option Name | Description |
|---|---|
banner | Prints a banner page. |
bestfit | Uses the best fit orientation for image files (default is on). |
bottommargin | Sets the bottom margin size for text. |
columns | Sets the number of columns on the page for text. |
debug | Causes filters to report debugging information (default is off). |
duplex | Turns duplex on or off. |
flip | Flips the image, producing a mirror image. |
fontname | Uses a specified font name for text. |
fontsize | Uses a specified font size for text. |
gamma | Uses a specified value for image gamma correction. |
gaudy | Uses a fancy page header for formatted text. |
halftone | Sets the halftone or dithering option to be used. |
intray | Specifies the input media source (same as the tray option). |
landscape | Uses landscape page orientation for text. |
leftmargin | Sets the left margin size for text. |
manpage | Indicates the preformatted reference (manual) page to be printed. |
manual | Sets manual feed. |
nobanner | Sets the “do not print a banner page” option. |
nogaudy | Sets the “do not use fancy page header for formatted text” option. |
noverbose | Sets the “do not print verbose messages in the spooler log file” option (same as the -h option). |
numberpages | Sets the number of text pages. |
outtray | Specifies the output media source. |
papersize | Selects the paper size. |
portrait | Uses portrait page orientation for text. |
ppi | Scales the final image size to match the specified original image resolution, in pixels per inch. |
psevenpage | Prints even pages only (PostScript). |
psoddpage | Prints odd pages only (PostScript). |
pspagerange | Prints the specified page range (PostScript). |
psreversepage | Reverses the page order (PostScript). |
resolution | Sets x and y resolutions (for resolution-switchable printers). |
reversepages | Reverses text document page order (prints the last page first). |
rightmargin | Sets the right margin size for text. |
rotate | Rotates the image clockwise in 90 degree increments. |
topmargin | Sets the top margin size for text. |
tray | Specifies the input media source. |
verbose | Records debugging messages in the spooler log file. |
zoom | Scales the image to fit the page (default is a scale of 1.0). |
Printer-driver developers must customize the model file template supplied by Silicon Graphics to the specifications of their printers. The template model is located in the file /usr/impressario/src/models/template_model. This code is the same as the code in the laserjetPJL_model file so that developers can have a working, debugged example from which to begin.
The following ten items must be specified by you. They are listed and explained in the order in which they appear in the model file template.
Printer name.
Device interface.
Printer type.
GUI class.
Printer-specific filter/driver.
Debug routine.
Cleanup routine.
Printer-specific banner page.
Printer-specific filtering options.
Fast path for text.
| Note: All items that must be modified by the developer have been marked with “#XXX” in the model file. Search for and remove these markers as you progress to be sure all necessary modifications have been made. |
The NAME variable identifies the real printer name, such as “HP DeskJet 500C.” NAME contains the string that is presented to the end user in the Printer Manager's graphical printer install tool. Multiple NAME variables are allowed on separate lines if the model file can support more than one printer.
The DEVICE variable identifies the hardware interface where the printer is attached. The value is used by the printer install tool to present models by connection type. Multiple connections are supported. (Use multiple lines for multiple devices; that is, simply repeat the line for each different device.) The values currently allowed are SERIAL, SCSI, CENTRONICS, NETPRINTER, and REMOTE. Obsolete types that should not be used are VERSATEC and TEK.
The TYPE variable identifies the printer type. This information is used by the Print Manager, routeprint, libspool functions, and other system software, including the active icons subsystem. Table 3-3 shows the values allowed for the TYPE variable. Obsolete types are Dumb, Color, and PostScript.
Table 3-3. Printer Type Specifications
TYPE Value | Data Types Accepted | Printer Examples |
|---|---|---|
Raster | At least text, .SGI image, PostScript | HP LaserJet |
ColorRaster | At least text, .SGI image, PostScript | Tektronix Phaser II SX |
Plotter | HP-GL only | HP 7550A |
ColorPostScript | At least text, .SGI image, PostScript | Tektronix Phaser II PXi |
MonoPostScript | At least text, .SGI image, PostScript | LaserWriter II NTX |
The value of this variable is the name of the resource file for the graphical options panel. This value must match the #define GUI_CLASS in the options panel gui_class.h. If an options panel is not provided, do not specify a value for this variable.
The file laserjetPJL.c contains an example of a complete printer driver. This driver is used in the /usr/impressario/src/models/laserjetPJL_model file. For comments about the model file, see the /usr/impressario/src/models/template_model.README file.
To turn on debugging for developer-supplied filters, modify SetDebug() to set the debug switch (-D) for each filter.
Some developers may need to perform some cleanup at the end of each job. If so, add this cleanup to the routine CleanUpAfterJob() in the model file. To make this step easier, the use of temporary or intermediate files is strongly discouraged.
It is recommended that you do not modify this routine. However, to create a customized banner page that uses printer features such as page counts or graphics, modify PrintBannerPage() as required. The banner page should not unduly slow down the printing process, and customized banner pages should include at least as much job-specific information as the default banner page: job ID, user name, job title, date and time, and the filename(s).
If your printer is unlikely to be shared, or has high per-page costs, you may want to turn off banner pages by default. In this case, set the variable banner to zero (0). However, users can still choose to print a banner page.
Printers that stack pages face down should print the banner page before any files, while those that stack pages face up should print the banner page last. This is handled automatically if the faceup variable is set appropriately.
The ParseOptions() routine parses the -o command-line options and sets appropriate global variables. This routine contains many general options, and developer-specific options can be added if required. However, developer-supplied options must not duplicate Silicon Graphics reserved words. See “Printer-Specific Options” for a complete, alphabetized list of existing options.
It is recommended that any developer-specific options be full-word names to improve the readability of the stored settings files and to reduce name-space conflicts. This also aids users who use command-line interfaces to printing. However, option names should be kept brief.
You should modify the path in the file filtering section of the model file to use native text support if your printer supports native text printing that is faster than PostScript printing. Users, however, must still have access to all PostScript formatting options. Do not disable the slower PostScript path.