Chapter 3. Printer Model Files
Prev |  | Next

## Chapter 3. Printer Model Files

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:

- “Overview”

- “Command-Line Arguments”

- “Template Model File Execution”

- “Printer-Specific Options”

- “Developer-Supplied Model File Additions”

## Overview

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.

## Command-Line Arguments

The model file expects these command-line arguments from `lpsched` in the order listed:

1 |  | job sequence ID number
2 |  | user login name
3 |  | job title
4 |  | number of copies to be printed
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.

## Template Model File Execution

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:

1. Declare global and external variables and define convenience functions.

2. Interpret and store the command-line options.

3. Verify that the prerequisites are in place.

4. 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.

5. 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.

6. Start the active icon tagging subprocess.

7. If pages stack face down, print a banner page if requested.

8. Use filters to convert the submitted file to the data type required by the printer driver.

9. Invoke the printer driver with the converted data.

10. Repeat steps 8 and 9 for each file to be printed and report any errors encountered to standard error.

11. If pages stack face up, print a banner page if requested.

12. Clean up after the job and exit with an appropriate exit code.

### Declaring Variables

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.

1. Define NAME and TYPE. If the type is not defined, then the model file writes an error message and exits.

2. Append the standard error output from the filters and driver to the spooler log file.

3. Define the file paths, directory paths, and Boolean flags used in the model file.

4. 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.)

### Defining Convenience Functions

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.

### Processing Command-Line Arguments

The template model file follows these steps to process command-line arguments:

1. Retrieve the command-line arguments.

2. 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.

3. Parse the options passed with the `-o` switch.

4. Set the device driver.

5. If the verbose switch is set, send a message to the spooler log that the job has begun filtering.

6. Call the printer status and communications driver to update the status database before job filtering begins.

7. Start the tagging subprocess to tag the printer's workspace icon with the appropriate print-engine type and status.

### Printing Banner Page

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.)

### Using Filters to Process Files

1. 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.

2. `fileconvert` produces a shell command string that, when executed, produces the requested data type on standard output.

3. 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.

4. `TestExitStatus()` is called to test whether the driver reported an error.

### Cleaning Up and Exiting

1. After the printing is complete, perform any needed cleanup.

2. End the tagging subprocess.

3. Append an ending message to the log file if the debug switch is set.

4. If there were unsupported file types in the list of files to be processed, exit the model file with an easily understood error code.

## Printer-Specific Options

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).

## Developer-Supplied Model File Additions

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.

1. Printer name.

2. Device interface.

3. Printer type.

4. GUI class.

5. Printer-specific filter/driver.

6. Debug routine.

7. Cleanup routine.

8. Printer-specific banner page.

9. Printer-specific filtering options.

10. 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.

### Printer Name

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.

### Device Interface

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.

### Printer Type

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

### GUI Class

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.

### Printer-Specific Filter/Driver

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.

### Debug Routine

To turn on debugging for developer-supplied filters, modify `SetDebug()` to set the debug switch (`-D`) for each filter.

### Cleanup Routine

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.

### Printer-Specific Banner Page

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.

### Printer-Specific Filtering Options

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.

### Fast Path for Text

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.

Prev | Table of Contents | Next
Chapter 2. Printer Drivers |  | Chapter 4. Printer Graphical Options Panel