PMDF System Manager's Guide

Setting up the cc:Mail channel in PMDF is best performed by running the PMDF-LAN configuration utility (see the appropriate edition of the PMDF Installation Guide for the use of the PMDF-LAN configuration utility) and editing the resulting files, if necessary, to perform any further customization necessary for your site. Each such file is described in detail in later sections:

1. pmdf.cnf, created by the PMDF configuration utility.
2. lan.rules, created by the PMDF-LAN configuration utility.
3. lan.chans, created by the PMDF-LAN configuration utility.
4. cc_local_option, created by the PMDF-LAN configuration utility.
5. pc_post.com (OpenVMS) or pc_post (UNIX), created by the PMDF-LAN configuration utility.

38.5.3.1 Creating or Editing lan.chans

cc_local master defragment charset8 ibm850 ccmail-domain-name

The master keyword enables the normal PMDF periodic delivery jobs to check for the existence of the export file to be processed. It should be omitted if you chose to use pc_post or your own procedure to pick up mail from the PC. See Section 38.2.2 for more details.

The defragment keyword tells PMDF to reassemble any fragmented MIME messages before sending them to cc:Mail.

The charset8 keyword controls the character set label that gets applied to text attachments containing eight bit characters. ibm850 is a standard eight bit PC character set commonly used internationally; ibm437 is another eight bit PC character set commonly used in the United States.

ccmail-domain-name should be a valid domain name that you have reserved for use by the cc:Mail channel. One possible choice is to prepend the official local host name with "ccmail.". For example, in the domain example.com, a reasonable domain name for the cc:Mail channel might be ccmail.example.com and the channel entry would then appear as

cc_local master charset8 ibm850 ccmail.example.com

38.5.3.2 Creating or Editing lan.rules

ccmail $U%ccmail.examplecom ccmail.example.com $U@ccmail.example.com

The address user@ccmail.example.com cc:Mail subscriber user associated with the Import/Export utility's post office. The address user%po@ccmail.example.com maps to a cc:Mail subscriber user associated with the PO post office.

Although this addressing format is sufficient to access all available cc:Mail post offices, it is sometimes useful to associate additional domain names with other cc:Mail post offices. Such a domain name need to follow the rules governing the naming conventions for domain names specified in RFC 952. For example, the domain name can not contain the underscore character although the cc:Mail post office name can contain such characters. This can be handled with rewrite rules of the general form:

ccpohost $U%ccpohost.example.com ccpohost.example.com $U%PO@ccmail.example.com$E$F ccpohost.example.com $U%ccpohost.example.com@ccmail.example.com$Ccc_local ccpohost.example.com $U%PO@ccmail.example.com

These rules associate the domain name ccpohost.example.com with the cc:Mail post office PO. Although these rules can look complex, their actions are reasonably straightforward: they insure that the cc:Mail name for the post office (PO) is used in the headers of messages queued to the cc:Mail channel, while the domain name for the post office (ccpohost.example.com) is used in all other cases. Any number of similar rule sets can be used to associate additional domain names with more remote cc:Mail post offices.

38.5.3.3 cc:Mail Channel Option Files

The names of the mandatory options are

• CC_INPUT_FILE_NAME,
• CC_OUTPUT_FILE_NAME, and
• CC_UNDEL_FILE_NAME.

38.5.3.4 Location of the Option File

38.5.3.5 Format of the Option File

option=value

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

38.5.3.6 Contents of the Option File

ACCESS_METHOD (0)

Specifies the access method that PMDF will use to read and write message files. A value of 0, which is the default, selects normal I/O.

BINARY_ENCODING (string)

The BINARY_ENCODING option is optional. This option controls the MIME transfer encoding used when binary cc:Mail attachments are converted into MIME bodyparts. Possible values include BASE32, BASE64, COMPRESSED-BASE64, BASE85, BINHEX, BTOA, HEXADECIMAL, PATHWORKS, QUOTED-PRINTABLE, X-UUENCODE, and COMPRESSED-UUENCODE. The MIME standard encoding BASE64 is the default and is appropriate in most cases. When such a message is read from a non-MIME aware user agent such as VMS MAIL, you can extract the MIME bodyparts between the MIME boundary markers to a file and use the PMDF DECODE (OpenVMS) or pmdf decode (UNIX) utility to decode it. From a MIME aware user agent such as PMDF MAIL, just use the appropriate command to extract a message part and it will be automatically decoded (e.g., PMDF MAIL's EXTRACT/PART command). A different encoding can be appropriate when messages always go to another mail system which does not support MIME or the MIME encodings.

CC_ADDRESS_BITS (encoded value)

This option controls the handling of spaces and commas in cc:Mail addresses. A cc:Mail address is an address in the cc:Mail domain, not one in the RFC 822 domain like your VMS Mail address or a UNIX mail address. PMDF's cc:Mail channel is capable of mapping the space character to and from either the underscore character or the period character; and comma character to and from plus sign character. The specific mappings used in each direction (PMDF to cc:Mail or cc:Mail to PMDF) can be controlled separately and do not have to be invertible. The following definition specifies how the values of bit pairs are used to control address mapping:

N = 0 Don't perform any character substitutions at all. N = 1 Substitute characters for mail coming from cc:Mail and going to cc:Mail as follows: "_" <--> " " underscore is changed to space and space is changed to underscore "," <--> "+" comma is changed to plus and plus is changed to comma N = 2 Not valid, do not set this bit. Unpredictable results can occur if you do. N = 3 In the PMDF to cc:Mail direction substitute characters as follows: "_" --> " " underscore is changed to space "+" --> "," plus is changed to comma " " --> " " space is not changed "," --> "," comma is not changed In the cc:Mail to PMDF direction substitute characters as follows: " " --> "_" space is changed to underscore "," --> "+" comma is changed to plus "_" --> "_" underscore is not changed "+" --> "+" plus is not changed

The specific bit values in CC_ADDRESS_BITS are then assigned as follows:

N * 1 = Controls the handling of cc:Mail user names going from PMDF to cc:Mail. N * 4 = Controls the handling of cc:Mail post office names going from PMDF to cc:Mail. N * 16 = Controls the handling of cc:Mail user names going from cc:Mail to PMDF. N * 64 = Controls the handling of cc:Mail post office names going from cc:Mail to PMDF. 256 = When set map RFC 822 addresses will be quoted if necessary, and @localhost appended to it if not present. When clear, or if the address contains @,% or ! then use it as is. You should clear this if your cc:Mail users are using regular RFC 822 addresses to send mail (e.g. user@example.com at PMDF). You have to set this bit if your cc:Mail users are using cc:Mail formatted addresses to send mail to the RFC 822 world. (e.g. you have set up names in the cc:Mail directory for people in the RFC 822 world, such as Smith, Fred is set up in Section 38.5.6) 512 = When set, substitute characters for mail coming from cc:Mail and going to cc:Mail as follows: "." <--> " " period is changed to space and space is changed to period "," <--> "+" comma is changed to plus and plus is changed to comma

A value of 0 disables all mapping of addresses completely. The default for CC_ADDRESS_BITS is to map to and from underscore and plus in all directions and locations. The corresponding value is:

1 * 1 + 1 * 4 + 1 * 16 + 1 * 64 + 256 = 341.

CC_ADDRESS_MAP (0-3)

This option is obsolete, but still supported for backwards compatibility. CC_ADDRESS_BITS should be used instead. If CC_ADDRESS_MAP is present and no CC_ADDRESS_BITS value is specified CC_ADDRESS_MAP is mapped to the new CC_ADDRESS_BITS option as follows:

ADDRESS_MAP ADDRESS_BITS 0 256 = 256 1 1 * 1 + 1 * 4 + 1 * 16 + 1 * 64 + 256 = 341 2 0 = 0 3 1 * 1 + 1 * 4 + 1 * 16 + 1 * 64 = 85

CC_GATEWAY_NAME (string)

Specifies the name of a post office that will be associated with PMDF (and hence with the entire world of RFC 822 addresses to which PMDF provides access). This post office must be defined in the cc:Mail installation that the Export utility accesses. In general, cc:Mail users address mail to PMDF users with an address of the form:

user@host AT pmdfpostoffice

where user@host is any normal PMDF address and pmdfpostoffice is the name of the post office associated with PMDF specified by this option. If no CC_GATEWAY_NAME option is specified in the options file a post office name of PMDF will be assumed.

CC_INPUT_FILE_NAME (string)

Required option which specifies the name of the inbound message file to be read by the cc:Mail slave channel program. This is the file produced by running cc:Mail Export utility which exports messages for the post office associated with PMDF. This file will be read by PMDF and the messages it contains will be delivered by PMDF. Errors are handled by writing error messages out as mail; these message will then pass through the cc:Mail master channel program and back into cc:Mail. This option specifies the complete filename on the system running PMDF, including device and directory.²

CC_INPUT_FILE_PATTERN (string)

When SEPARATE_FILES has bit 0 set, i.e., is set to an odd value, then the CC_INPUT_FILE_PATTERN option is used in place of the usual CC_INPUT_FILE_NAME option. CC_INPUT_FILE_PATTERN specifies a pattern for the files for the cc:Mail channel to read coming from cc:Mail, when SEPARATE_FILES has bit 0 set.

CC_OUTPUT_FILE_NAME (string)

Required option which specifies the name of the outbound message file that is created or appended to by the cc:Mail master channel program. This file is in a format that is suitable for use by the cc:Mail Import utility. This file must be transferred to the cc:Mail system and the Import utility must be run to import the messages which the transferred file contains into cc:Mail. This option specifies the complete filename on the system running PMDF, including device and directory.³

CC_POSTOFFICE_HOST (string)

The options CC_POSTOFFICE_HOST and CC_PRIMARY_HOST are discussed in Section 38.5.7.

CC_PRIMARY_HOST (string)

The options CC_POSTOFFICE_HOST and CC_PRIMARY_HOST are discussed in Section 38.5.7.

CC_SLAVE_DELETE (0 or 1)

Specify CC_SLAVE_DELETE=0 if you are testing and do not want the cc:Mail export files (e.g., the exported file CCMAIL.EXP and the undeliverable messages file CCMAIL.UND) to be deleted automatically by CC_SLAVE. The default is 1. If this is set incorrectly, you will get duplicate messages.

CC_UNDEL_FILE_NAME (string)

Specifies the name of the undeliverable message file to be read by the cc:Mail slave channel program. This is a file produced by cc:Mail Import utility containing messages which cannot be imported correctly, usually because the addressee does not exist. This file will be read and the messages it contains will be processed by PMDF to be returned to the sender. This option specifies the complete filename on the system running PMDF, including device and directory.³

CHECK_LINE_LENGTH (0 or 1)

The documented behavior of the cc:Mail Import utility in earlier versions was to truncate lines in the messages longer than 80 characters. As of version 6.0 of cc:Mail, Lotus documents that long lines in message bodies will be wrapped. In order to ensure not losing data, PMDF by default (CHECK_LINE_LENGTH=1) converts message part containing long lines into a file item. If this option is set to 0, then PMDF does not convert such message parts into a file item. If you are using an older version of cc:Mail, you should use CHECK_LINE_LENGTH=1, the default, as otherwise you are ikely to lose information in messages containing long lines. But if you are using a newer version of cc:Mail, you can be able to safely disable this PMDF option and instead have Lotus wrap the lines for you.

ENVELOPE_INTO_TO (0 or 1)

cc:Mail uses a different approach to header and envelope addresses than what RFC 822 and X.400 use. In cc:Mail, header and envelope information is merged into a single simpler structure. This difference makes it difficult to capture the exact semantics of RFC 822 and X.400 in cc:Mail. In particular, problems arise with RFC 822 messages containing addresses that only appear in the envelope and not the header. The ENVELOPE_INTO_TO option controls the disposition of such addresses. The default is 0, which means that such addresses are turned into cc:Mail blind carbon addresses. This is normally sufficient. In some cases, however, the loss of addressing information that results can be a problem. If ENVELOPE_INTO_TO is set to 1 the addresses are added to the primary recipient list instead. This setting is not without its own serious drawbacks, as duplication of replies often will be the result of using it.

REPEAT_COUNT (integer)

SLEEP_TIME (integer)

PMDF's cc:Mail channel shares the files it produces with the cc:Mail Import/Export utility. Moreover, the actual file server facilities used to provide the necessary file access are quite variable. Some file servers, in an effort to get improved performance, can employ various caching techniques. Use of these techniques can result in transient accessibility problems when the cc:Mail channel attempts to read export files. The REPEAT_COUNT and SLEEP_TIME options are provided as a means to work around file server specific problems. The REPEAT_COUNT option controls how many times the channel programs will attempt to open an input file before giving up. REPEAT_COUNT defaults to 2 (two attempts). The SLEEP_TIME option is provided as a means to work around file server specific problems. The SLEEP_TIME option controls how long in seconds the channel program waits between attempts. SLEEP_TIME defaults to 2 (two seconds between retries).

SAVE_HEADERS (0, 1 or 2)

The SAVE_HEADERS option is used to control whether or not RFC 822 headers are retained in any cc:Mail produced by PMDF. A value of 0 is the default, and specifies that no headers are to be retained. A value of 1 places the RFC 822 headers in a text part at the beginning of the message. A value of 2 places the RFC 822 headers in a text part at the end of the message. Saved headers can optionally be trimmed as well. Create a header trimming option file in the PMDF table directory with a name of the form channel_save_headers.opt where channel is the name of the channel, usually cc_local; (hence on OpenVMS, the file is usually PMDF_TABLE:cc_local_save_headers.opt, or on UNIX, the file is usually /pmdf/table/cc_local_save_headers.opt). This header trimming will be automatically applied as the text attachments containing the headers are written out. For more information on header trimming option files, see Section 2.3.7.2.

SEPARATE_COUNT (integer)

SEPARATE_COUNT specifies the maximum number of messages that PMDF should write to a file going to cc:Mail, when SEPARATE_FILES has bit 1 set. The default is to impose no limit---essentially, keep on writing messages to the one file as long as the channel runs.

SEPARATE_FILES (integer)

SEPARATE_FILES takes a bit-encoded integer value. Bit 0 (counting starting from 0) controls whether or not the cc:Mail channel should read separate files coming from cc:Mail. Bit 1 controls whether or not the cc:Mail channel should write separate files for messages going to cc:Mail. The default value is 0. When SEPARATE_FILES has bit 0 set, i.e., is set to an odd value, then CC_INPUT_FILE_NAME should be set to a directory specification, rather than a full file name, and CC_INPUT_FILE_PATTERN should be set specifying a pattern for the names of the files which the cc:Mail channel is to read coming from cc:Mail. For instance, to read in all files with names of the form cc*.exp from the directory D2:[pmdfcc] one might set:

SEPARATE_FILES=1 CC_INPUT_FILE_NAME=D2:[pmdfcc] CC_INPUT_FILE_PATTERN=D2:[pmdfcc]cc*.exp

Or if you want to write a separate file for each message going to cc:Mail (but messages coming from cc:Mail will still appear in just one file), set SEPARATE_FILES=2 and SEPARATE_COUNT=1. You should then also set CC_OUTPUT_FILE_NAME to a directory specification, rather than a full file name; for instance, if you previously had the CC_OUTPUT_FILE_NAME option set to D2:[pmdfcc]ccmail.imp, instead set it to D2:[pmdfcc] The files PMDF writes will have names such as 00000001.out, etc. A PMDF user account is required in order to write separate files going to cc:Mail. On OpenVMS, if you want to use this functionality, but you didn't say yes to create such an account when you installed PMDF, then you should create one now by using the PMDF_COM:create_pmdf_user_account.com procedure.

SEPARATE_SIZE (integer)

SEPARATE_SIZE specifies a number of bytes beyond which to force a new file for messages going to cc:Mail, when SEPARATE_FILES has bit 1 set. (Note that while this imposes an upper limit on the size of files of messages going to cc:Mail, it is not itself exactly the limit---after PMDF outputs a message, if the cumulative size is then bigger than this option value, then the next message goes into a new file.) The default to impose no size limit.

STUFF_TEXT_PART (0 or 1)

cc:Mail has trouble replying to messages that do not have initial text. Setting STUFF_TEXT_PART to 1 causes PMDF to create and insert an empty initial text message body on messages going to cc:Mail that would otherwise consist solely of attachments, thereby making the message repliable. With the default value of 0, PMDF preserves the original message structure of having no initial text.

TIMEZONE (string)

Specify the cc:Mail time zone.

38.5.3.7 Example Option Files

! On OpenVMS CC_GATEWAY_NAME=PMDF CC_OUTPUT_FILE_NAME=d1:[ccmail.pmdf]ccmail.imp CC_INPUT_FILE_NAME=d1:[ccmail.pmdf]ccmail.exp CC_UNDEL_FILE_NAME=d1:[ccmail.pmdf]ccmail.und

! On UNIX CC_GATEWAY_NAME=PMDF CC_OUTPUT_FILE_NAME=/dev1/ccmail/pmdf/ccmail.imp CC_INPUT_FILE_NAME=/dev1/ccmail/pmdf/ccmail.exp CC_UNDEL_FILE_NAME=/dev1/ccmail/pmdf/ccmail.und