PMDF System Manager's Guide

After an e-mail message has been converted to an encapsulated PostScript program by the TEXT_TO_PS channel, it is passed to the PS_TO_G3 channel. The PS_TO_G3 channel invokes a PostScript interpreter to process the output of the TEXT_TO_PS channel. The PostScript interpreter produces bitmaps for each page of the message body. The PS_TO_G3 channel also generates, by means of the PostScript interpreter, bitmaps for each cover page that will be transmitted with the FAX message. A separate cover page is generated for each recipient of the FAX. The bitmaps for the message body and cover pages are stored in a single "G3" file. The PS_TO_G3 channel may send e-mail messages back to the FAX message's originator as described in the Section 37.2.7.

By supplying cover page templates in the form of PostScript programs, system managers may, on a per channel basis, specify the appearance of the cover pages used for the channel. For the less adventurous, the simple default cover page can be used and its appearance varied in limited ways (e.g., font style, font size, margins, etc.) with channel options.

Both the master_debug and slave_debug channel keywords may be used with the PS_TO_G3 channel: if either master_debug or slave_debug is set then status messages are written to the log file of the message submission job; if master_debug and slave_debug are both set then, in addition to status messages, all PostScript input and output is also written to the log file.

37.2.16.1 Supported Mapping Tables

37.2.16.1.1 FAX_COVER_PAGE Mapping Table

If the FAX_COVER_PAGE mapping table is defined, then for each FAX the channel name, originator address, default cover page for the channel, and any cover page requested with the COVER addressing attribute will be passed through this mapping.

If no FAX_COVER_PAGE mapping table is defined, then the default cover page for the channel will always be used regardless of whether or not a different cover page has been requested with the COVER addressing attribute. Since cover pages are interpreted in a privileged context, it is crucial that the PS_TO_G3 channel operate this way and not blindly process any cover page template file requested by a user with the COVER attribute. It is also important that any FAX_COVER_PAGE mapping not return as its result the name specified with the COVER attribute but rather return the name of a known cover page file in response to a cover page requested with the COVER attribute. See Example 37-3 below for examples of this behavior.

The left-hand side of each entry in the FAX_COVER_PAGE mapping table takes the form

channel-name|from-address|default-cover|user-cover

where channel-name is the name of the channel doing the mapping, from-address is the envelope From: address of the message's originator, default-cover is the name of the default cover page for the channel as specified with the COVER_PAGE channel option, and user-cover is any cover page requested with the COVER addressing attribute.

If the mapping produces no result or a result with $N, then the default cover page template file will be used. If the mapping produces a result with $Y, then that result will be used as the cover page template file.

For a given channel, all cover page files returned by this mapping must be of the same "type" as the channel's default cover page. That is, if the channel's default cover page requires COVER_PROC=1 then the same must be true for any cover pages returned by the mapping for that channel. (See Sections 37.2.14 and 37.2.16.2 for information on the COVER_PROC channel option, its meaning and implication.)

In Example 37-3, the first two entries select the cover page template files
d1:[ps]chem_cover.ps or
d1:[ps]math_cover.ps for any message with, respectively, /COVER=CHEMISTRY/ or /COVER=MATH/ specified in the To: address. The last two entries select the cover pages d1:[ps]chem_cover.ps or d1:[ps]math_cover.ps for, respectively, messages from the hosts chem.example.com or math.example.com.

Example 37-3 FAX_COVER_PAGE Mapping

FAX_COVER_PAGE *|*|*|chemistry $Yd1:[ps]chem_cover.ps *|*|*|math $Yd1:[ps]math_cover.ps *|*@chem.example.com|*| $Yd1:[ps]chem_cover.ps *|*@math.example.com|*| $Yd1:[ps]math_cover.ps

37.2.16.1.2 FAX_SETUP Mapping Table

channel-name|from-address|setup-string

where channel-name is the name of the channel doing the mapping, from-address is the envelope From: address of the message's originator, and setup-string is the name specified with the SETUP addressing attribute.

In Example 37-4, the setup file d1:[ps]chem_ltrhd.ps is selected in response to /SETUP=LETTER-HEAD/ for messages from the host chem.example.com, while the setup file d1:[ps]math_ltrhd.ps is selected for messages from math.example.com. For messages from admin.example.com the module LETTER is used from the text library d3:[formats]ps.tlb. (Text libraries are only supported on OpenVMS.)

Example 37-4 FAX_SETUP Mapping Table

FAX_SETUP *|*@chem.example.com|letter-head $YD1:[ps]chem_ltrhd.ps *|*@math.example.com|letter-head $YD1:[ps]math_ltrhd.ps *|*@admin.example.com|letter-head $YD3:[formats]ps.tlb(letter)

37.2.16.2 Option Files

See Section 37.2.15.3 for a description of the format of option files.

The available options are:

ADDRESS_FIRST_LINE_POS (real number)

This option is used to specify in points where the first attribute-value pair list (AVPL) item should begin on the FAX cover page. This specification is made by giving the vertical distance from the bottom of the page to the baseline of the first header line. By default, this distance is set to 648 points (9 inches). This option may be overriden for various AVPL items with a cover page template. Subsequent AVPL items are displayed below the first item; each item is spaced below the previous item by amount ADDRESS_SPACING * ADDRESS_SIZE. This option may be overriden for various AVPL items with a cover page template.

ADDRESS_LEFT_MARGIN (real number)

This option is used to specify in points the width of the left margin used when displaying attribute-value pair list (AVPL) items on the FAX cover page. By default, the left margin is 36 points (1/2 inches) wide. This option may be overriden for various AVPL items with a cover page template.

ADDRESS_SIZE (real number > 0)

This option specifies the font size (in points) to use for displaying cover page information provided in the attribute-value pair list (AVPL) (e.g., "/FN=", "/AT=", "/O=", etc.) used to address the originating e-mail message. By default, a 10 point Courier font is used for displaying header lines. This option may be overriden for various AVPL items with a cover page template.

ADDRESS_PERSONAL_LIMIT (integer > 0)

PS_TO_G3 channels build cover page addresses from RFC 822 personal name fields followed by the RFC 822 address. If the personal name field is too long, the RFC 822 address will be pushed completely off the page. This option can be used to limit the number of characters of personal name information that are extracted. Set this option to the largest number of characters that will still allow a reasonable-sized RFC 822 address to fit in the alloted space. The default is to use as much personal name as is available.

ADDRESS_SPACING (real number <> 0)

The spacing (i.e., baseline skip) between attribute-value pair list (AVPL) items on the FAX cover page is given by the product ADDRESS_SPACING * ADDRESS_SIZE; as a default, ADDRESS_SPACING has the value 1.0. This option may be overriden for various AVPL items with a cover page template.

BITMAP_HEIGHT_IN_PIXELS (integer > 0)

This option controls the number of horizontal scanlines per FAX page. The default value for this option is computed so that the vertical length of the transmitted page is 10.75 inches (273.05 mm). This corresponds to the values:
BITMAP_HEIGHT_IN_PIXELS=1053 at 98 dpi vertical resolution;
BITMAP_HEIGHT_IN_PIXELS=2107 at 196 dpi vertical resolution. By selecting different values for this option, you may generate FAXes with page lengths other than 10.75 inches. Note that many FAX modems place an upper bound on the number of scanlines per page; the default page length of 10.75 inches does not violate the upper bound for the FAX modems supported by PMDF-FAX. See Section 37.2.8 for a detailed discussion on controlling the length of received FAX pages.

BITMAP_WIDTH_IN_PIXELS (integer > 0)

As a standard, all FAX modems send and receive horizontal scanlines which are each composed of 1728 pixels. This is the default width used by the PS_TO_G3 channel. If your FAX modem is capable of sending longer or shorter scanlines AND this channel will be communicating only with other FAX devices with similar capabilities, then this option may be used to select the desired scanline width (in pixels).

BITMAP_HORIZONTAL_DPI (real number > 0)

This option specifies the horizontal resolution in dots per inch of the bitmaps produced by the PS_TO_G3 channel. While you may select any resolution desired, note that Group 3 FAXes have only one standardized horizontal resolution, which is roughly 204 dpi. (A FAX scanline is 215 millimeters long and is composed of 1728 pixels.) Although the bitmaps will be rendered at the desired resolution, they will be transmitted at a resolution of 1728*25.4/215 dots per inch. If you change the value of BITMAP_HORIZONTAL_DPI, then it is strongly recommended that BITMAP_WIDTH_IN_PIXELS be set to 1728. Otherwise, bitmaps with nonstandard widths (i.e., widths other than 1728 pixels) will be generated. Most FAX devices will not accept FAX images of nonstandard width. It is also recommended that BITMAP_HEIGHT_IN_PIXELS be set to 2107.

BITMAP_VERTICAL_DPI (real number > 0)

This option specifies the vertical resolution in dots per inch (i.e., lines per inch) of the bitmaps produced by the PS_TO_G3 channel. While you may select any desired resolution, note that Group 3 FAXes have only two standardized vertical resolutions: 98 and 196 dpi. These resolutions are often referred to as "standard" (98 dpi) and "fine" (196 dpi) resolution. If you select a resolution other than one of these two, the bitmaps will be rendered at the selected resolution but transmitted to the receiving FAX device at either 98 or 196 lines per inch: if BITMAP_VERTICAL_DPI is equal to or less than 98, then the FAX will be transmitted at 98 dpi, otherwise the FAX will be transmitted at 196 dpi. By default, the PS_TO_G3 channel uses BITMAP_VERTICAL_DPI = 196. To select standard resolution, place the line
BITMAP_VERTICAL_DPI=98 in the channel option file. See Section 37.2.8 for a detailed discussion on controlling the length of received FAX pages.

COVER_PAGE_FILE (filename <= 252 characters long)

This option specifies the name of a cover page template to be used by the channel. If no name is specified, the PS_TO_G3 channel will use the file ps_to_g3_cover.ps located in the PMDF table directory.

COVER_PAGES (0 or 1)

Specifies whether or not cover pages are to be generated for messages passing through this channel. By default, a cover page is generated for each To: recipient of a FAX message (COVER_PAGES=1). If COVER_PAGES=0 is specified, no cover pages will be generated for any of the To: recipients.

COVER_PROC (0 or 1)

If set to 1, COVER_PROC=1, then the PS_TO_G3 channel will only feed the cover page template to the PostScript interpreter once and issue SHOW_COVER (PostScript) commands for each cover page to be generated. If set to 0, COVER_PROC=0, then PS_TO_G3 channel will feed the cover page template to the PostScript interpreter for each cover page to be processed. See Section 37.2.14 for further information about cover page templates.

HEADER_FIRST_LINE_POS (real number)

This option is used to specify in points where the first message header line should begin on the FAX cover page. This specification is made by giving the vertical distance from the bottom of the page to the baseline of the first header line. By default, this distance is set to 324 points (4.5 inches). Subsequent header lines are printed below the first header line; each line is spaced below the previous line by amount HEADER_SPACING * HEADER_SIZE. This option is ignored when a cover page template containing the SHOW_HEADER procedure is provided or if the channel is tagged headeromit in the channel block in the PMDF configuration file.

HEADER_LEFT_MARGIN (real number)

This option is used to specify in points the width of the left margin used when displaying message header lines on the FAX cover page. By default, the left margin is 36 points (1/2 inches) wide. This option is ignored when a cover page template containing the SHOW_HEADER procedure is provided or if the channel is tagged headeromit in the channel block in the PMDF configuration file.

HEADER_LINE_LEN (integer > 0)

The PS_TO_G3 channel will automatically split header lines (i.e., wrap header lines) into separate lines each containing at most HEADER_LINE_LEN characters. This option is used to alter the value of HEADER_LINE_LEN. By default, HEADER_LINE_LEN is set to 96 --- a value which works well when the header lines are displayed in 9 point type and confined to a 468 point (6.5 inch) wide region. This option is ignored if the channel is tagged headeromit in the channel block in the PMDF configuration file.

HEADER_MAX_LINES (integer >= 0)

This option controls the maximum number of message header lines which will be displayed on the FAX cover page. By default, up to 24 header lines are displayed. (A single header line which is wrapped into N header lines will count as N header lines when counting the total number of lines displayed.) This option is ignored if the channel is tagged headeromit in the channel block in the PMDF configuration file.

HEADER_OPTIONS (filename <= 252 characters long)

This option specifies the name of a header option file to use when parsing message header lines. By default, no header option file is used. If the channel is tagged headeromit in the channel block in the PMDF configuration file, this option is ignored.

HEADER_SIZE (real number > 0)

This option specifies the font size (in points) to use for displaying message header lines (from the e-mail message's envelope) on the FAX cover page. By default, a 9 point Courier font is used for displaying header lines. This option is ignored when a cover page template containing the SHOW_HEADER procedure is provided or if the channel is tagged headeromit in the channel block in the PMDF configuration file.

HEADER_SPACING (real number <> 0)

The spacing (i.e., baseline skip) between message header lines is given by the product HEADER_SPACING * HEADER_SIZE; as a default, HEADER_SPACING has the value 1. This option is ignored when a cover page template containing the SHOW_HEADER procedure is provided or if the channel is tagged headeromit in the channel block in the PMDF configuration file.

K (integer >= 1)

When K specifies an integer greater than zero, each FAX page will be imaged and encoded using both the one-dimensional Group 3 encoding as well as the two-dimensional Group 3 encoding with the encoding parameter K as specified. Use K=2 for low resolution FAXes and K=4 for high resolution FAXes. By default, only the one-dimensional encoding is produced (K=1). When a FAX is encoded with both a one and two-dimensional encoding, then the G3_TO_FAX channel will transmit whichever encoding is smaller, provided that the remote end can receive such an encoding; note that the one-dimensional encoding will always be sent if either the FAX modem does not support two-dimensional encoding or fails to negotiate transfer of a two-dimensional encoded FAX with the remote FAX device. At present, the one PMDF-FAX driver which supports two-dimensional encodings is that for Service Class 2 modems.

RETURN_CONTENT (0 or 1)

When set to 1, the contents of the FAX will be preserved in PostScript form in case the FAX cannot be delivered; if the G3_TO_FAX channel option RETURN_CONTENT=1 is also set and a bounce message needs to be generated by the G3_TO_FAX channel, that bounce message will then include the PostScript corresponding to the attempted FAX. The default is 0, meaning that no such content preservation is attempted.

RETURN_OUTPUT (0 or 1)

By default, any output generated by the PostScript interpreter will be returned to the message originator in an e-mail message. Many applications, however, generate PostScript which outputs a lot of meaningless chatter (e.g., the Macintosh laser prep causes lots of chatter to be generated --- chatter intended for the program driving the laser printer). You can prevent your users from receiving any non-error output produced by the interpreter by specifying RETURN_OUTPUT=0.

TRUNCATE (0 or 1)

By default (TRUNCATE=1) the blank, bottommost portion of the image data for each FAX page is not stored in the G3 file. This saves on transmission time with the dexNET 200 and DCE FaxBox/30 FAX modems which will nonetheless transmit a full page. (These two modems know what the expected page length is.) However, Service Class 2 FAX modems generally will transmit only the truncated page. By specifying TRUNCATE=0, the PS_TO_G3 channel will not truncate the image data and consequently a Service Class 2 modem will transmit a full page. If TRUNCATE=1 is specified in the PS_TO_G3 and G3_TO_FAX option files for a dexNET 200 modem, or simply in the PS_TO_G3 option file for Service Class 2 modems, then the transmitted FAX pages will be cut short. See Section 37.2.9 for further details.

USE_REPLY_TO (0 or 1)

One possible address messages from the PS_TO_G3 channel are sent to is the original message's Reply-To: address. Under some circumstances it is never appropriate to use the Reply-To: address for this purpose. The USE_REPLY_TO option controls the use of the Reply-To: address for acknowledgements. A value of one (the default) causes the Reply-To: header to be used in the normal course of events. A value of zero inhibits use of the Reply-To: header.

37.2.16.3 PostScript Interpreter