This appendix describes the file formats of the ASCII text files that compose the printer object database (POD).
The following major topics are discussed:
The printer object database (POD) contains information on the current configuration, status, and job history of a single printer. Each printer that is physically installed on a system must maintain its own POD. To maintain network-transparent, mediated access to the POD files, all interaction between the printer driver and POD files must be through the libpod API. For additional information, see “The libpod Library” in Chapter 5 and the libpod(3) reference page.
The initial set of POD files created by the printer driver developer and installed on the host server system must include the following:
<printer name>.config: a configuration file representing the printer's capabilities
<printer name>.stats: a status file indicating a typical printing state
<printer name>.log: an empty log file
The name of each POD file is formed from the printer name and the suffix .config, .status, or .log, respectively. Note that the printer name must be the same as the name of the printer model file. All POD files are copied from the template POD files and installed in the appropriate directory.
The information contained in each POD file is summarized below and explained in detail in subsequent sections.
The printer configuration file (<printer name>.config) contains detailed information on the printer's capabilities. The file is created by the printer driver developer to characterize the printer's capabilities. The possible paper sizes, printer location, and available fonts are all specified in this file. Typically the information in the config file does not change over time. Printer filters and drivers treat it as a read-only file. The printer install tools may modify the file at printer installation time to enter site-specific data, such as printer location, or note the presence of optional equipment, such as a duplex option or an envelope feeder.
The printer status file (<printer name>.status) contains information about the current operational status of the printer. The information in the file indicates whether the printer is busy, what type of printing media is installed, and so on. The contents of this file change during every print job. The driver developer provides an initial copy of the status file, but it is the job of the printer driver to update the file. Printer filter programs normally treat this file as if it were a read-only file.
The printer log file (<printer name>.log) contains the print job history for the printer. Information for old jobs as well as the current print job is maintained. Typically, printer filters and drivers append information to the log file, while general applications treat the file as if it were a read-only file.
<space>: 0x09, 0x20 (<sp>, <ht>)
<null>: 0x00-0x08, 0x0B, 0x0C, 0x0E-0x1F, 0x7F-0xFF
<endline>: 0x0A, 0x0D (<nl>, <cr>)
<separator>: 0x7C ('|')
<plainchar>: 0x21-0x7B, 0x7D, 0x7E
<ddigit>: 0x30-0x39 ('0'-'9')
<hdigit>: <ddigit>, 0x41-0x46, 0x61-0x66
('0'-'9', 'A'-'F', 'a'-'f')
<sign>: 0x2B, 0x2D ('+', '-')
<point>: 0x2E ('.')
|
<white>: <space> [<space>...]
<word>: <plainchar> [<plainchar>...]
<keyword>: <word> with a specific sequence of <plainchar>
<keyfield>: [<white>] <keyword> [[<white> <keyword>]...]
[<white>]
<string>: [<white>] <word> [[<white> <word>]...]
[<white>]
<int>: <ddigit> [<ddigit>...]
<hbyte>: ["0x" | "0X"] [<hdigit>] <hdigit>
<float>: [<sign>] <int> [<point> [<int>]]
or
[<sign>] <point> <int>
<array>: <string> [[<separator> <string>]...]
|
The following rules apply when a POD file is parsed by the libpod API:
All <null> characters are ignored. Their use is discouraged to avoid errors caused by nonprinting characters appearing in the POD files.
All input lines are truncated to PD_STR_MAX-1, not counting <null> characters and <endline>, which are removed on input. The value of PD_STR_MAX is defined in the header file /usr/include/pod.h.
All occurrences of <white> sequences are reduced to a single <sp> character. Any <white> at the beginning or end of a field is removed.
There are no quoted strings. Quotation marks are treated like any other characters and cannot be used to force additional <white> into a field.
All fields are checked for correct syntax based on entry type. Failure to provide information in the correct format results in improper parsing.
When scanning for <int> or <float> numbers within a field, all characters that are not valid within an <int> or <float> are treated as <white> (in the case of an <int>, <sign> and <point> are treated as <white>). This allows characters to be inserted to improve readability. For example, the following are equivalent if two <int> items are expected:
300 300
300 x 300
300 by 300
300,300
Entries containing no characters other than <white> before the first <separator> or <endline> are treated as null entries and discarded without error. These lines may be used as comments by placing a <separator> before any other information.
Blank lines are ignored and may be inserted to improve readability.
<keyfield> matching is done in a case-independent manner.
Fields designed to be human-readable are not modified, except to remove <null> and excess <white>. Case and all <plainchar> sequences are preserved.
A <keyfield> may require a long list of items (for example, Available Fonts). To improve readability and avoid the risk of input line buffer overflow (see the second bullet item above), a <keyfield> may be repeated.
For example, a list of fifty Available Fonts items may be broken into two Available Fonts entries with 25 items each. The overall number of items that can be specified in a list is limited only by available system memory resources.
There is no required entry order. The <keyfield> entries may appear in any order within a POD file.
Default values are assumed for certain fields if values are not specified. The values of these defaults should not be relied upon and may change in future releases.
This section describes the format of the printer configuration file. The configuration file is installed by the printer install tools with the name <printer name>.config.
The format for an entry in the configuration file is
<keyfield> <separator> [<infofield>] <endline> |
where
| <keyfield> | is one of the reserved fields described in the “Key Field” column of Table C-1. | |
| <separator> | is the “separator” character defined in “Character Set”. | |
| <infofield> | is one or more of the options specified in the “Info Field Type” column of Table C-1. | |
| <endline> | is one of the “endline” characters defined in “Character Set”. |
All entries in the config file are optional. Entries that are not provided or that have no <infofield> specified are assigned default values. However, since printer capabilities differ, it is strongly recommended that no entries be omitted. The defaults should not be relied on, as they may change in future releases. Table C-1 lists the config file options in alphabetical order. A detailed explanation of each option follows the table.
Table C-1. Config File Options
Key Field | Info Field Type | Default |
|---|---|---|
Active Status Path | <word> | See “Active Status Path”. |
Available Fonts | <array> | (0 elements) |
Black Substitute | <keyword> | No |
Color Adjustment | <array> | (0 elements) |
Cost per Page | <float> | 0.00 |
Default CA | <int> | 0 |
Default IS | <int> [,gamma=<float>] | 0, gamma=-1.0 |
Default MT | <int> | 0 |
Default QM | <int> | 0 |
Driver Path | <word> | See “Driver Path”. |
Error Retry Wait | <int> | 10 seconds |
Input Source | <array> | (0 elements) |
Location Code | <keyword> | None |
Manual Capable | <keyword> | No |
Maximum Addr | <Maximum Addrint> <int> | See “Minimum Addr”. |
Maximum Print Area | <float> <float> | See “Maximum Print Area”. |
Media Standard | <keyword> | American |
Media Type | <array> | (0 elements) |
Media Wait | <int> | 300 seconds |
Minimum Addr | <int> <int> | See “Minimum Print Area”. |
Minimum Print Area | <float> <float> | See “Minimum Print Area”. |
Number of Colors | <int> [<int>] | 1 1 |
Physical Location | <string> | Unknown |
Port Path | <word> | /dev/null |
Printer Class | <keyword> | Dumb |
Printer Model | <string> | Unknown |
Printer Options | <string> | (empty string) |
Quality Modes | <array> | (0 elements) |
Resolution | <int> <int> | 300 dpi 300 dpi |
Size Table Entry | <sizeentry> | See “Size Table Entry”. |
Status Update Wait | <int> | 300 seconds |
Technology | <string> | Unknown |
Time per Page | <int> [<int>] | 0 0 |
Active Status Path is the full pathname of the POD status file. The value of this entry is not used by the libpod API. The value of this entry is always set by the API to PDpod_path/<printer name>.status. Refer to the libpod(3) reference page for additional information.
The Available Fonts option contains a list of font names representing the fonts available on the printer. For printers with built-in PostScript interpreters, this list should include only those fonts built into the printer (typically a set of 35 standard fonts). The default value is 0 elements.
For raster printers, the PostScript interpretation is performed on the printer host machine. Thus, the fonts listed for these printers should correspond to the names of the font outline files installed on the printer host. There are two methods for specifying the font names: the names can be listed individually or a full path to the directory where the outline fonts are stored can be specified. The two methods can be mixed. When a path is specified, the names of the files in that directory are assumed to be the names of the fonts. To exclude filenames from the directory, specify the names of the files to be excluded with a leading “!”. The filenames to be excluded must appear on the same line as the directory containing the filename to be excluded. The following is a valid Available Fonts list:
NewYearRoman | /usr/lib/DPS/outline/base | !fonts.dir |
This entry indicates that the only font available on the printer is NewYearRoman, and all file names are in the directory /usr/lib/DPS/outline/base with the exception of fonts.dir. Note that font names must not contain any white space.
Starting with Impressario 2.0, a new logical AND operator, &, is available for font lists. It allows the list of fonts on the printer to be logically AND'ed with the list of fonts on the print server, generating a list of fonts that are common to both. The common list is needed for the text2ps(1) filter, which uses the font metric information from the print server fonts to determine where line and page breaks should be made. The AND operator is intended for use by printer drivers that send PostScript directly to the printer.
The entry below says that NewYearRoman is available on the printer, and if it is also available in /usr/lib/DPS/outline/base, it should be on the list of available fonts when a printer driver is installed:
| NewYearRoman | &/usr/lib/DPS/outline/base |
For another example, see the file
/usr/lib/print/data/lexmarkoptra_model.config
The Black Substitute option is either yes, indicating that the printer should by default substitute true black for composite black, or no, indicating that it should not. The default value is no.
The Color Adjustment option is a list of color adjustment methods available for the printer. The color adjustment methods perform color correction between the current input source and the printer. An example entry is
None | Fix Blue | Gamma Correct |
The default value is 0 elements.
Starting with Impressario 2.0, International Color Consortium (ICC) color profiles and various filters, such as cocostiff, are used to perform color management. Color correction is applied as a filter before the driver is invoked (FTR rules have been added so fileconvert will invoke the correct filters based on the file type). The Color Adjustment entry in the POD file is currently not used. See Appendix G for more information on color management in Impressario.
The Cost per Page option is the cost per printed page in local currency. For example, 0.50 for 50 cents per page. The default value is 0.00.
The Default CA option is the index to the Color Adjustment list indicating the default adjustment method. This index is based at one rather than zero. Thus, the first method in the list is at position 1, the second at 2, and so on. If there are no adjustment methods specified, this entry should either be left empty or set to 0. The default value is 0.
Default IS is the index to the Input Source list indicating the default input source. This index is based at one rather than zero. Thus, the first source in the list is at position 1, the second at 2, and so on. If there are no input sources specified, this entry should either be left empty or set to 0.
When used for printer color correction, this entry can also be used to specify the default device's gamma correction value. The gamma value is specified after the default input source index, as in the following example:
1, gamma = 1.0 |
Default MT is the index to the Media Type list indicating the default media. This index is based at one rather than zero. Thus, the first media in the list is at position 1, the second at 2, and so on. If there are no media types listed, this entry should either be left empty or set to 0. The default value is 0.
Default QM is the index to the Quality Modes list indicating the default quality mode. This index is based at one rather than zero. Thus, the first quality mode in the list is at position 1, the second at 2, and so on. If there are no quality modes specified, this entry should either be left empty or set to 0. The default value is 0.
Driver Path is the full pathname of the installed printer driver. The default is the full pathname of the POD config file, with the suffix .config removed.
Error Retry Wait refers to the number of seconds to wait after an error has occurred before attempting to resume printing. The default is 10 seconds.
Input Source is a list of printer input sources. The primary use of this entry is to list the image source devices that have been characterized for printer color correction. A common input device is the monitor. An example entry is Sony 16” Monitor.
The Location Code option is used to supply a site-specific keyword that identifies the printer's physical location. For example, 3U-924. There is no default value. This code should be machine-readable and -sortable for use by a location-querying browser.
Manual Capable is either yes, indicating that the printer is capable of being manually fed, or no, indicating that it is not. The default value is no. This value should be set to yes only if the printer supports the -m option (see “The Filter/Driver Specification and psrip” in Chapter 2).
Maximum Addr is the maximum printable area dimensions expressed in dots. The default values for this entry assume an A-size page (8.5 by 11.0 inches) in portrait orientation with 0.5-inch margins. At 300 dpi, this gives a printable area of 2250 by 3000 dots. The minimum and maximum values are identical in the default case. If a Page Size Table has been specified, the values for this entry are derived from it. Also see “Minimum Addr.”
Maximum Print Area is the maximum printable area dimensions expressed in inches. The default values for this entry assume an A-size page (8.5 by 11.0 inches) in portrait orientation with 0.5-inch margins. This gives a printable area of 7.5 by 10.0 inches. The minimum and maximum values are identical in the default case. If a Page Size Table has been specified, the values for this entry are derived from it. Also see “Minimum Print Area.”
Media Standard indicates the paper measurement standard. Keywords are American and Metric. The default value is American.
Media Type is an array that contains the output media types supported by the printer. Typical items are Bond Paper and Transparency Film. The default array has 0 elements.
Media Wait is the number of seconds to wait for manual feed or print media changes before the default media source is used. The default is 300 seconds.
Minimum Addr is the minimum printable area dimensions expressed in dots. The default values for this entry assumes an A-size page (8.5 by 11.0 inches) in portrait orientation with 0.5-inch margins. At 300 dpi, this gives a printable area of 2250 by 3000 dots. The minimum and maximum values are identical in the default case. If a Page Size Table has been specified, the values for this entry are derived from it. Also see “Maximum Addr.”
Minimum Print Area is the minimum printable area dimensions expressed in inches. The default values for this entry assume an A-size page (8.5 by 11.0 inches) in portrait orientation with 0.5-inch margins. This gives a printable area of 7.5 by 10.0 inches. The minimum and maximum values are identical in the default case. If a Page Size Table has been specified, the values for this entry are derived from it. Also see “Maximum Print Area.”
Number of Colors is the minimum or, optionally, maximum number of colors that are available on the printer. If the maximum number of colors is not provided, it is assumed to be the same as the minimum. A monochrome printer or printer ribbon provides one color. A CMY printer or ribbon provides three colors.
Note that this field should contain only the number of colors available on the printer. The colorspace, depth, and data format are provided in the Number of Colors entry in the status file. The default value is 1.
Physical Location is the human-readable description of the printer's physical location. For example, Bldg. 3 Upper, Room 924. The default value is Unknown.
Port Path is the full pathname of the I/O port to which the printer is physically connected. For example, /dev/plp for a parallel printer, /dev/ttyd2 for a serial printer, and /dev/scsi/sc0d6l0 for a SCSI printer. The default value is /dev/null.
The Printer Class entry is used to specify the class of printer being used. Available values are Dumb, Raster, ColorRaster, MonoPostScript, ColorPostScript, and Plotter. The following printer classes are obsolete and should not be used for new development: DumbColor, PostScript, and Color. The default value is Dumb.
The Printer Model entry is a keyword that is the manufacturer's description of the printer. For example, Tektronix Phaser II SX or Apple LaserWriter II NTX. The default value is Unknown.
Printer Options describe the standard installed printer optional equipment. For example, 8 megabytes RAM. The default is an empty string.
Quality Modes is a list of output quality modes available on the printer. For example, draft and letter. The default value is 0 elements.
Resolution is the horizontal or vertical printer resolution in dots per inch (dpi). For printers that allow multiple resolutions, the status file Printer Options entry should be parsed for the CurrentRes keyword. This keyword indicates the current printer resolution. If the keyword is not found, the config file Resolution entry should be used. The default values are both 300 dots per inch.
The Size Table Entry <infofield> has the format <sizeentry> defined as
<sizeentry>: <keyword> <int> <int> <float> <float> <float>
<float> [<hbyte> [<hbyte>]]
|
Size Table Entry describes a particular media size that is supported by the printer. Typically, there is one Size Table Entry per supported media size (for example, an entry each for A size and B size), although it is acceptable to have multiple entries for a paper size if multiple resolutions or ribbons are supported. The media size entry has seven required fields and two optional fields. All fields are separated by white space.
The first required field contains the Media Size (for example, A). The list of possible media sizes can be found in the file /usr/include/pod.h. The media size keyword is simply the media size listed in pod.h with the PD_SIZE_ prefix removed. The size names listed in pod.h with the suffix _LAND indicate landscape orientation and should not be used as media size keywords. Media with landscape orientation is indicated by the width and height fields of the size table entry.
The next two fields are the media-imageable width and height expressed in dots. Typically, the imageable dimensions are derived by subtracting the margins from the total media size and converting the result to dots.
The next two fields are the overall media width and height expressed in inches.
The last two required fields are the left and top margins expressed in inches.
The first optional field specifies the printing raster direction. Refer to pod.h for the values that may be specified in this field.
The second optional field is the media validation mask. This mask can be used to differentiate among media entries that have the same media name but differ in other respects (for example, resolution). The field is a bit mask and so, to fully differentiate among similar entries, the values must be powers of two. Refer to the PDReadInfo(3) reference page for more information on the use of this field.
A default Size Table Entry is always added to the end of the table when it is read by libpod. This default entry is
A 2250 3000 8.500 11.000 0.500 0.500 0x00 0xFF |
Status Update Wait is the number of seconds to wait between updates of the POD status file when no error has occurred. The default is 300 seconds.
The Technology option indicates the type of printing technology used in the printer. For example, ink jet, wax transfer, dye sublimation, and color laser. The default value is Unknown.
This section describes the format of the printer status file. The status file is installed by the printer install tools with the name <printer name>.status.
The format for an entry in the printer status file is
<keyfield> <separator> [<infofield>] <endline> |
where
| <infofield> | is the parameter is specified by Table C-2. | |
| <separator> | is the separator defined in “Character Set”. | |
| <endline> | is one of the endline characters defined in “Character Set”. |
All entries in the status file are optional. Entries that are not provided or that have no <infofield> are assigned default values. However, since the status file is the only means to indicate printer status to the user, it is strongly suggested that a complete status file be provided by the developer and that the printer driver update the status file to reflect the printer's current status.
Table C-2 lists the printer status file entries.
Table C-2. Printer Status File Entries
Key Field | Info Field Type | Default |
|---|---|---|
Operational Status | <keyword> | Idle |
Media Size | <keyword> [Land] | A |
Media Type | <keyword> | Paper |
Number of Colors | <dataentry> | 1 k 1 chunky |
Printer Options | <string> | (empty string) |
Validation Mask | <hbyte> | 0 |
Error | <msgentry> | (no message) |
Warning | <msgentry> | (no message) |
Information | <msgentry> | (no message) |
Operational Status is the keyword specifying the current operational status of the printer. The possible values are Idle, Busy, Faulted, and Unavailable.
The status Faulted indicates that there is a problem with the printer but not with communication to the printer. The Unavailable designation is similar to the Faulted state but indicates that communication could not be established with the printer. The default value is Idle.
Media Size is the keyword indicating the currently loaded media size. The media size keywords are listed in the file pod.h. The keyword is the size name listed with the PD_SIZE_ prefix removed. The size names listed in pod.h with the suffix _LAND indicate landscape orientation and are specified in the entry by the keyword Land.
Media Type is the keyword indicating the currently loaded media type. The value is Paper, Transparency, Other, or Unknown. The default is Paper.
This field specifies not only the number of output colors but the colorspace, depth, and organization of the output data. There is one required field and three optional fields. For proper operation of printing filters, it is strongly recommended that the optional fields be specified.
The Number of Colors <infofield> has the format <dataentry> defined as
<int> [<keyword> <int> <keyword>] |
Arguments:
| <int> | Required. Specifies the number of output colors the printer can currently print. If only this field is present, the following defaults apply
| |||||||||||||||||
| <keyword> | Optional. This field specifies the output colorspace and is either k, rgb, cmy, ymc, cmyk, ymck, w, or kcmy. | |||||||||||||||||
| <int> | Optional. This field specifies the number of bits per color component and may be 1, 4, or 8. | |||||||||||||||||
| <keyword> | Optional. This field specifies the data organization of the output data and is either chunky or planar. |
An example output specification is
3 rgb 4 planar |
This specifies a three-color RGB output with four bits per component (12 bits total) and a planar data organization. Refer to the libstiff(3) reference page for additional information on raster data output formats.
This field is used to describe the currently available optional equipment or configurations. The field is also used to indicate the current printer resolution for printers that allow multiple output resolutions. To indicate the current resolution, the string
CurrentRes = <int> x <int> |
is specified. The first integer is the horizontal resolution in dots per inch, and the second integer is the vertical resolution in the same units. The current resolution values are used by printing filters such as the PostScript interpreter psrip to calculate margins for printers whose resolutions can change, and it is very important that printer drivers update this information field to ensure proper rendering.
This field can be used to differentiate among media entries that have the same media name but differ in other respects (for example, resolution). The field is a bit mask and so, to fully differentiate among similar entries, the values must be powers of two. Refer to the PDReadStatus(3) reference page for more information on the use of this field.
Each Error, Warning, and Information message <infofield> has the format <msgentry> defined as
<hbyte> [<hbyte> [<hbyte>]] <separator> <string> |
These three entries indicate messages written by the printer driver to provide information to the printer user regarding the state of the printer. The three hex bytes provide a message code. The available message codes are listed in pod.h (see PD_ERROR_*). The low-order three bytes of the codes listed in pod.h are the codes specified in this field. The high-order byte of the code is implied by the first field (for example., Information = 00, Warning = 01, Error = 02). The last field is a string providing the text for the message. There can be up to PD_MESSAGE_MAX (see pod.h) message entries in a status file. An example of a complete message entry is
Information | 01 00 00 | version: driver = 00.00 |
See the PDMakeMessage() routine for the best method of construction these messages. For the sake of internationalization, it is strongly recommended that you do not customize messages.