PMDF System Manager's Guide
Previous Next Contents Index

28.6.1 Setting Up the Channel

There are two steps in setting up a printer channel: (1) adding the channel to the PMDF configuration file, and (2) setting up a channel option file, if necessary. For most "dumb" printers (e.g., a line printer), an option file is not required. In addition, no option file is required of "intelligent" printers (e.g., PostScript printers), if the printer's queue is managed by a symbiont which knows how to deal with raw ASCII text files.
If you want to select the usernames under which print jobs should be submitted, then specify SET_USERNAME=1 in the channel option file. The USERNAME addressing attribute can then be used to select the username under which a given message should be submitted. This makes it possible for banner and trailer pages to bear the name of the intended recipient rather than the username of the process running the printer channel.

28.6.1.1 Adding the Channel to the Configuration File

First determine the names of the printer queues (OpenVMS) or print job destinations (UNIX) to which you will be directing mail and then select a domain name to identify with each queue. These domain names are used to route mail to a particular queue. For instance, suppose mail is to be routed to the printer SYS$PRINT on the host vaxa.example.com. Then an appropriate domain name might be sysprint.vaxa.example.com.

Once the printer names are determined and domain names selected, add a channel block of the form 


printer single 733 
PRINTER-DAEMON 
domain-name-1    printer-name-1
domain-name-2    printer-name-2
.
.
.
to the PMDF configuration file. Here domain-name-1, domain-name-2, ... and printer-name-1, printer-name-1, ... are, respectively, the selected domain name and the printer names. On OpenVMS you must use printer queue names. On UNIX, you must use printer names suitable for use in an lpr command with the -P switch.

Continuing with the SYS$PRINT and vaxa.example.com example from above, the channel block would be 


printer single 733 
PRINTER-DAEMON 
sysprint.vaxa.example.com   SYS$PRINT

After adding the channel block, go to the top of the configuration file and add rewrite rules of the form shown below: 


domain-name-1         $U@domain-name-1
domain-name-2         $U@domain-name-2
.
.
.
For instance, in the context of our example, the following rewrite rules can be added 


sysprint                   $U@sysprint.vaxa.example.com 
sysprint.vaxa.example.com  $U@sysprint.vaxa.example.com
The first rewrite rule shown is not necessary: it merely allows PMDF to recognize the address avpl@sysprint as a short form address for avpl@sysprint.vaxa.example.com.

Note
If you are part of a TCP/IP network, then you can want to add the printer domain names you selected to your DNS using MX records. This will allow other machines to route mail to your printer queues.

28.6.1.2 Option Files

In order to properly print messages on the printers associated with the channel, it can be necessary to use an option file. With an option file, the following items can be specified:

Option files are used to set run-time options on a per channel basis. Option files are stored in the PMDF table directory and have names of the form x_option, where x is the name of the printer channel to which the option file applies. (In most instances, the file name will be printer_option; i.e., PMDF_TABLE:printer_option. on OpenVMS or /pmdf/table/printer_option on UNIX.)

Note that an option file applies to an entire printer channel; a printer channel which can be serving more than one printer queue. If you have printer queues which require different option files, then you should set up multiple printer channels (giving the channels different names such as printer1 and printer2 instead of printer).

Option files consist of several lines. Each line contains the setting for one option. An option setting has the form: 


option=value
value can be either a string or an integer, depending on the option's requirements. If the option accepts an integer value, value, a base can be specified using notation of the form b%v, where b is the base expressed in base 10 and v is the actual value expressed in base b.

Comments are allowed. Any line that begins with an exclamation point, !, is considered to be a comment and is ignored. Blank lines are also ignored in any option file.

The available options are:

AT (string <= 252 characters long)

This option can be used to specify the content of the text string printed along with the contents of any /AT=value attribute-value pair (AVP) appearing in the To: address presented to the printer channel. If no AT option is specified in the option file, then the default string "Attention: " will be used. For example, if the To: address passed to the printer channel is 


"/AT=Mrocheck Doe/MS=DH X.25/"@printer.example.com
then the text 


Attention:        Mrocheck Doe
will be printed on the first page of the message.

BURST (0 or 1; OpenVMS only)

The BURST option controls whether two file flag pages with a burst bar between them are printed preceding the mail message. BURST=0 requests that no burst pages be printed; BURST=1 requests that the burst pages be printed preceding the message. By default, no burst pages are requested (BURST=0).

END_ATTRIBUTE (string <= 252 characters long)

The END_ATTRIBUTE option specifies a text string to be printed immediately following the display of an attribute value extracted from the mail message's To: address. By default, no text string is printed after displaying an attribute value.

END_COVER (string <= 252 characters long)

The END_COVER option specifies a text string to be printed at the end of the cover page printed prior to the message body. By default, a form feed character is printed at the end of the cover page.

END_HEADERLINE (string <= 252 characters long)

The END_HEADERLINE option specifies a text string to be printed immediately following a header line from the mail message (e.g., To:, From:, Subject:, etc.). By default, no text string is printed after a header line.

END_JOB (string <= 252 characters long)

The END_JOB option specifies a text string to be printed at the end of the mail message. By default, no text string is printed.

END_LINE (string <= 252 characters long)

The END_LINE option specifies a text string to be printed immediately following a line from the mail message's body. By default, no text string is printed after a message body line.

FLAG (0 or 1; OpenVMS only)

The FLAG option controls whether a flag page is printed preceding the mail message. FLAG=0 requests that no flag page be printed; FLAG=1 requests that a flag page be printed preceding the message. By default, no flag page is requested (FLAG=0). The setting of this option has no effect if BURST=1 is specified in the option file.

FORM (string <= 252 characters long; OpenVMS only)

Specifies the name or number of the print form to be associated with the message when it is submitted to the printer queue. By default, no print form is associated with messages when they are submitted for printing.

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.

MIME_HANDLING (0 or 1)

By default, the printer channel will interpret the MIME structure of MIME messages, decoding and printing each part of a multipart message. This corresponds to specifying MIME_HANDLING=1. To supress the MIME interpretation of messages and have their content just printed as an ordinary RFC 822 message, specify MIME_HANDLING=0.

MS (string <= 252 characters long)

This option can be used to specify the content of the text string printed along with the contents of any /MS=value attribute-value pair (AVP) appearing in the To: address presented to the printer channel. If no MS option is specified in the option file, then the default string "Mail stop: " will be used. For example, if the To: address passed to the printer channel is 


"/AT=Mrocheck Doe/MS=DH X.25/"@printer.example.com
then the text 


Mail stop:        DH X.25
will be printed on the first page of the message.

NOTIFY (0 or 1; OpenVMS only)

Generate a notification broadcast when a mail message is printed. By default, this notification is not generated, NOTIFY=0. It will only be generated when NOTIFY=1, SET_USERNAME=1, and a username has been specified in the printer address. In that case, the specified user will receive a broadcast message after their mail message has completed printing.

O (string <= 252 characters long)

This option can be used to specify the content of the text string printed along with the contents of any /O=value attribute-value pair (AVP) appearing in the To: address presented to the printer channel. If no O option is specified in the option file, then the default blank string will be used.

OU (string <= 252 characters long)

This option can be used to specify the content of the text string printed along with the contents of any /OU=value attribute-value pair (AVP) appearing in the To: address presented to the printer channel. If no OU option is specified in the option file, then the default blank string will be used.

P1--P8 (string <= 252 characters long; OpenVMS only)

These options can be used to specify the content of the text string printed along with the contents of any /P1=value, ..., /P8=value attribute-value pair (AVP) appearing in the To: address presented to the printer channel. If no P1, P2, ..., or P8 option is specified in the option file, then the default blank string will be used.

P1_DEFAULT--P8_DEFAULT (string <= 252 characters long; OpenVMS only)

These eight options set values for the parameters P1 through P8 to be specified when submitting a print job. Unless a message specifically sets any of P1 through P8 with addressing attributes, these default values will be used. If a message specifies any of P1 through P8, then none of these default values will be used and the values specified by the message will instead be used.

PAGINATE (0 or 1; OpenVMS only)

Specify whether or not the printer symbiont should paginate the output by inserting a form feed whenever output reaches the bottom margin of the output form. PAGINATE=0 disables the insertion of form feeds; PAGINATE=1 enables the insertion of form feeds. By default, form feeds are inserted by the symbiont (PAGINATE=1).

PREAMBLE (string <= 252 characters long)

The PREAMBLE option specifies a text string to print at the top of the cover page for the message. If the first character in the string is an at-sign, @, then the remainder of the string is interpreted as a file name and the contents of that file is first sent to the printer prior to the cover page. (This mechanism can be used to download code to intelligent printers such as PostScript printers.)

PRINT_COMMAND (string <= 252 characters long; UNIX only)

Specifies the format of the command to issue to print a message. By default, the lpr command is used with the format 


PRINT_COMMAND=lpr -P%p -r %f
See Section 28.6.1.2 for further details.

QUOTE_CHARS (string <= 252 characters long; UNIX only)

Specifies the shell metacharacters which require quoting with a backslash, \, in order to literalize them. By default, 


QUOTE_CHARS="#$&'()*;<=>?[\]`{|}
is used. Specify 


QUOTE_CHARS=
to disable the quoting of characters. See Section 28.6.1.3 for further details.

SET_USERNAME (0 or 1; OpenVMS only)

USERNAME addressing attributes-value pairs are ignored by default and not passed on to the print subsystem when the message is spooled for printing. By specifying SET_USERNAME=1 in the option file, these attribute-value pairs will be honored; the spooled print job will be submitted using the specified username. Process running the channel --- typically SYSTEM --- must have CMKRNL privilege in order to use this option. The channel itself does not make use of this privilege: the $SNDJBC system service requires it of any process which submits jobs under a different username. The username under which PMDF channel programs run usually has CMKNRL privilege. This username is given by the PMDF_BATCH_USERNAME logical.

SETUP (string <= 252 characters long)

This option can be used to specify the content of the text string printed along with the contents of any /SETUP=value attribute-value pair (AVP) appearing in the To: address presented to the printer channel. If no SETUP option is specified in the option file, then the default blank string will be used.

SETUP_DEFAULT (string <= 252 characters long; OpenVMS only)

This option allows specification of a setup module to be used by the print symbiont. This setup module will be specified unless the printer address itself specifies a setup module. In that case, the module specified in the address is instead used. To specify multiple module names, specify each name separated by commas; e.g., 


SETUP_DEFAULT=module1,module2,module3

START_ATTRIBUTE (string <= 252 characters long)

The START_ATTRIBUTE option specifies a text string to be printed immediately prior to the display of an attribute value extracted from the mail message's To: address. By default, no text string is printed before displaying an attribute value.

START_HEADERLINE (string <= 252 characters long)

The START_HEADERLINE option specifies a text string to be printed immediately before a header line from the mail message (e.g., To:, From:, Subject:, etc.). By default, no text string is printed before a header line.

START_LINE (string <= 252 characters long)

The START_LINE option specifies a text string to be printed immediately before a line from the mail message's body. By default, no text string is printed before a message body line.

TN (string <= 252 characters long)

This option can be used to specify the content of the text string printed along with the contents of any /TN=value attribute-value pair (AVP) appearing in the To: address presented to the printer channel. If no TN option is specified in the option file, then the default string "Telephone number: " will be used. For example, if the To: address passed to the printer channel is 


"/AT=Mrocheck Doe/TN=900-555-1212/"@printer.example.com
then the text 


Telephone number: 900-555-1212
will be printed on the first page of the message.

TRAILER (0 or 1; OpenVMS only)

The TRAILER option controls whether a file trailer page is requested when the message is submitted to the printer queue. TRAILER=0 requests that no trailer page be printed; TRAILER=1 requests that a trailer page be printed. By default, no trailer page is requested (TRAILER=0).

28.6.1.3 Controlling the Print Command (UNIX)

On UNIX systems, the print command issued by the printer channel can be controlled with the PRINT_COMMAND channel option. With that option, the format of the print command to issue is specified: 


PRINT_COMMAND=command
where command is the command to issue. command can contain two special sequences, %f and %p. Should they appear, they will be replaced, respectively, with the name of the file to print and the name of the printer to use. The PRINT_COMMAND should be such as to delete the file after printing. The printer name is the name given in the channel definition (e.g., printer-name-1, printer-name-2, ... in Section 28.6.1.1. To specify a literal % or \ in the print command, use \% or \\ in command.

For example, the default value of the PRINT_COMMAND option is 


PRINT_COMMAND=lpr -P%p -r %f
Thus with this default, when given a printer name of PS_TIPSY and file name of /pmdf/queue/printer/spool/ZZAX02G.00, the resulting print command would be 


lpr -PPS_TIPSY -r /pmdf/queue/printer/spool/ZZAX02G.00
Note that the -r switch of the lpr command requests that the file be deleted after it has been printed.

Prior to be being substituted into the print command, any occurrences of the characters 


" # $ & ' ( ) * ; < = > ? [ \ ] ` { | }
in the printer name or file name are preceded with a backslash, \, so as to literalize them and prevent them from being interpreted as shell metacharacters. Use the QUOTE_CHARS channel option to change the list of characters requiring quoting. To inhibit the quoting of characters, specify a null string with the QUOTE_CHARS option.

Utmost care is taken to ensure that user-supplied information is not injected into the command line executed by the forked child. As such, several of the features found in the OpenVMS printer channel are not available under UNIX (e.g., the ability to specify the username under which to print, use of the destination address in the print job name, specification of printing options, etc.).

28.6.1.4 Handling Multipart Messages

By default, the printer channel will interpret MIME messages, decoding and printing each part of the message. This is likely to cause problems when a user sends a binary message part such as an executable to a printer channel. There are two ways to deal with this: (1) disable entirely the interpretation of MIME messages, printing the entire message as a single RFC 822 message without decoding any encoded message parts, or (2) using a conversion channel to discard unwanted message parts.

While (1) is easily implemented by just specifying MIME_HANDLING=0 in the channel option file, it can result in printing large amounts of unwanted data (e.g., printing an encoded executable). Approach (2) is therefore more practical. See Section 24.1 for complete information on configuring a conversion channel. Note that when using this approach, it's best to use entries in the conversions file which explicitly accept the message content types which you will allow to be printed and then discard all other types.

For instance, to print only message parts of type text and substitute for all other message parts a text string stating that an original part was discarded, on OpenVMS you might use: 


out-chan=printer; in-type=text; in-subtype=*; 
  command="COPY 'INPUT_FILE' 'OUTPUT_FILE'" 
 
out-chan=printer; in-type=*; in-subtype=*; 
  out-type=text; out-subtype=plain; out-mode=text; out-encoding=none; 
  command="@PMDF_TABLE:discard.com"
where PMDF_TABLE:discard.com is the site-supplied DCL command procedure 


$ SIZE = F$FILE_ATTRIBUTES (INPUT_FILE, "EOF") 
$ OPEN/WRITE FILE 'OUTPUT_FILE' 
$ WRITE FILE - 
  "[''SIZE' block ''INPUT_TYPE'/''INPUT_SUBTYPE' message part discarded]" 
$ CLOSE FILE
Similarly, on UNIX you might use: 


out-chan=printer; in-type=text; in-subtype=*; 
  command="COPY 'INPUT_FILE' 'OUTPUT_FILE'" 
 
out-chan=printer; in-type=*; in-subtype=*; 
  out-type=text; out-subtype=plain; out-mode=text; out-encoding=none; 
  command="/pmdf/table/discard.sh"
where /pmdf/table/discard.sh is the site-supplied shell script 


size=`wc -c $INPUT_FILE | awk '{print $1}'`
echo '['$size 'byte' $INPUT_TYPE'/'$INPUT_SUBTYPE \
 'message part omitted]' > $OUTPUT_FILE

Alternatively, to simply discard non-text parts silently, without bothering to include a text note explaining that a part was discarded, you could use DELETE=1 in the conversion entry, e.g., 


out-chan=printer; in-type=text; in-subtype=*; 
  command="COPY 'INPUT_FILE' 'OUTPUT_FILE'" 
 
out-chan=printer; in-type=*; in-subtype=*; 
  delete=1

Previous Next Contents Index