This chapter discusses the printer model files and describes the modifications to be made by printer vendors to the printer model file template.
The major topics discussed in this chapter are:
Model files are Bourne shell scripts that form an interface between the System VR 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 called the interface file. The interface file is invoked by the System VR3 spooling scheduler lpsched(1M) 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 Advanced Site and Server Administration Guide for more information.
The model file expects the following command-line arguments from lpsched in the order listed:
| 1 | ||
| 2 | ||
| 3 | ||
| 4 | ||
| 5 | -o options (printer options) | |
| 6-n | Name(s) of 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, this can be done quickly by running the model file with dummy arguments; for example:
laserjet_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) man pages for more details on debugging Bourne shell scripts.
This section explains how the Impressario model files work.
The source code for the template laserjet_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:
Define global and external variables and convenience functions.
Interpret and store the command-line options.
Verify that the prerequisites are in place.
Invoke the driver to update the POD status file with the current printer state and the current job setting. This is important; 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 7 and 8 for each file to be printed and report any errors encountered to stderr.
If pages stack face up, print a banner page if requested.
Clean up after the job and exit with an appropriate exit code.
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) man 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 all filter and driver standard error output to the spooler log file.
Define file and directory paths and Boolean flags used in the model file.
Define 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 not, 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 4-1 are routines contained within the model file. These routines are used for parsing the -o options and for various utility functions.
Table 4-1. Convenience Functions
Function Name | Description |
|---|---|
BeginTagging | Sets up the tagging job that begins monitoring the printer status. |
CleanUpAfterJob | Does any cleanup needed at end of job. |
EndTagging | Ends tagging of the printer. |
ParseOptions | Parses the -o command-line options and sets appropriate variables. Expects the command-line options string as argument 1. |
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 argument 1 and the file type as argument 2. |
ReportUnknownOption | Reports an error message when an unknown option is parsed. Expects the unknown option as argument 1. |
SetCancelTrap | Sets up the trap command for the signals SIGHUP, SIGINT, and SIGTERM. |
SetDebug | Turns on debug mode for all filters and drivers. |
TestExitStatus | Interprets exit status from 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 argument 1, a string describing the last command as argument 2, and the file in question as argument 3. |
Retrieve the command-line arguments.
Parse the options passed with the -o switch.
Call the printer status and communications driver to update the status database before job filtering begins.
Set up the cancellation signal handler to handle SIGHUP, SIGINT, and SIGTERM. This allows use to cater the job cancellation signal sent by the spooler and clean up.
If the verbose switch is set, send a message to the spooler log that the job has begun filtering.
Start the tagging subprocess to tag the printer's workspace icon with the appropriate print-engine type and status.
A banner page is printed if the banner switch is set. (The banner page may be printed last for faceup stacking printers.)
fileconvert(1) automatically determines the file type of each file using the Indigo Magic file typing rule database. (See ftr(1) and fileconvert(1).) 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 excluded and the output piped to the printer driver.
TestExitStatus is called to test whether the driver reported an error.
After printing is complete, any additional cleanup needed is performed.
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, the model file exits with a well-known 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(1) 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 4-2 in alphabetical order. Their meanings may not be changed by vendors. Vendors should choose short but understandable option names for any additional options. These options may be seen by end users, so they should not be too verbose.
Table 4-2. Reserved Option Names
Name | Description |
|---|---|
banner | Prints a banner page. |
bestfit | Uses the best fit orientation for image files (defaults to "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 debug information (defaults to "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. |
landscape | Uses landscape page orientation for text. |
leftmargin | Sets the left margin size for text. |
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. |
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 PostScript page order. |
resolution | Sets x and y resolutions (for resolution-switchable printers). |
reversepages | Reverses text document page order (that is, print last page first). |
rightmargin | Sets right margin size for text. |
rotate | Rotates the image clockwise an integer number of degrees. |
topmargin | Sets the top margin size for text. |
verbose | Records debug messages in the spooler log file. |
zoom | Scales the image to fit the page (defaults to 1.0 scale). |
Printer vendors 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 laserjet_model file so that developers will have a working, debugged example from which to begin.
The following ten items must be specified by the vendor. 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 vendor have been marked with an "#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." It appears twice in each model file: once in the comments parsed by the printer install tools and once in the actual interface program code. We refer here only to the first, comment instance of NAME. The NAME is 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, CENTRONICS, SCSI, 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 Manger, routeprint, libspool functions, and other system software, including the active icons subsystem. Table 4-3 shows the values allowed for the TYPE variable. Obsolete types are: Dumb, Color, and PostScript.
Table 4-3. Printer Type Specifications
TYPE | Data Types Accepted | Printer Examples |
|---|---|---|
Raster | At least text, SGI, PostScript | HP LaserJet |
ColorRaster | At least text, SGI, PostScript | Tektronix Phaser II SX |
Plotter | HP-GL only | HP 7550A |
ColorPostScript | At least text, SGI, PostScript | Tektronix Phaser II PXi |
MonoPostScript | At least text, SGI, 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 GUI_CLASS define in the options panel gui_class.h. If an options panel is not provided, do not specify a value for this variable.
The file laserjet.c contains an example of a complete printer driver. This driver is used in the /usr/impressario/src/models/laserjet_model file. Also, see the /usr/impressario/src/models/template_model.README file for comments about the model file.
To turn on debugging on vendor-supplied filters, modify SetDebug() to turn on the debug switch (-D) for each vendor-supplied filter.
Some vendors may need to perform some cleanup at the end of each job. If needed, add this cleanup to the routine CleanUpAfterJob() in the model file. 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 vendor-specific options can be added if required. However, Silicon Graphics reserved words must not be duplicated by vendor-supplied options. See "Printer-Specific Options" for a complete, alphabetized list of existing options.
It is recommended that any vendor-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 using PostScript. Users, however, must still have access to all PostScript formatting options. Do not disable the slower PostScript path.