PMDF System Manager's Guide
PMDF-REF-6.0

38.5.3 Telling PMDF about cc:Mail

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:

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

38.5.3.1 Creating or editing lan.chans
The first step in installing a cc:Mail channel is to add the channel definition to the PMDF configuration file---or as it is more commonly done, add the channel definition to a file lan.chans which is referenced by (read in to) the PMDF configuration file proper. The channel definition should appear along the lines of:
```
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 acme.com, a reasonable domain name for the cc:Mail channel might be ccmail.acme.com and the channel entry would then appear as
```
cc_local master charset8 ibm850 
ccmail.acme.com 
```
38.5.3.2 Creating or editing lan.rules
Rewrite rules are needed in the PMDF configuration file---or as is more commonly done, in a file lan.rules which is referenced by (read in to) the PMDF configuration file proper. Continuing the ccmail.acme.com example, a start at a set of appropriate rules would be:
```
ccmail              $U%ccmail.acme.com 
ccmail.acme.com     $U@ccmail.acme.com 
```
The address user@ccmail.acme.com cc:Mail subscriber user associated with the Import/Export utility's post office. The address user%po@ccmail.acme.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 may contain such characters. This can be handled with rewrite rules of the general form:
```
ccpohost                  $U%ccpohost.acme.com 
ccpohost.acme.com         $U%PO@ccmail.acme.com$E$F 
ccpohost.acme.com         $U%ccpohost.acme.com@ccmail.acme.com$Ccc_local 
ccpohost.acme.com         $U%PO@ccmail.acme.com 
```
These rules associate the domain name ccpohost.acme.com with the cc:Mail post office PO. Although these rules may 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.acme.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
An option file must be created to control various characteristics of the cc:Mail channel.
The names of the mandatory options are
- CC_INPUT_FILE_NAME,
- CC_OUTPUT_FILE_NAME, and
- CC_UNDEL_FILE_NAME.
Their significance and usage are described in Section 38.5.3.6 . Before setting up the PMDF configuration files, you must know the correct values to specify for these mandatory options. Contact whoever does the cc:Mail administration tasks at your local site. Impress upon them that if they unilaterally change the cc:Mail configuration, it will break the mail gateway. Ask them to notify you before making those types of changes so that you can keep the PMDF configuration synchronized.

38.5.3.4 Location of the option file
Option files are stored in the PMDF table directory (PMDF_TABLE: on OpenVMS or /pmdf/table on UNIX) and must have names of the form channelname_option with channelname the name of the cc:Mail channel for which this option file applies. Since the channel name for cc:Mail is usually cc_local, the full file specification is usually PMDF_TABLE:cc_local_option. on OpenVMS, or /pmdf/table/cc_local_option on UNIX.

38.5.3.5 Format of the option file
Option files consist of several lines. Each line contains the setting for one option. An option setting has the form:
```
option=value
```
where value may be either a string or an integer, depending on the option's requirements. If the option accepts an integer value, value, a base may 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
The available options are:
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 may 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 may 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@innosoft.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 may 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, may employ various caching techniques. Use of these techniques may 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
This is an example option file for the cc_local channel. The file's name must be cc_local_option and the file must be stored in the PMDF table directory, i.e., PMDF_TABLE:cc_local_option. on OpenVMS or /pmdf/table/cc_local_option on UNIX. This example would be used when PMDF accesses messages stored on its host system. The messages must be moved by a transfer PC which can access both the remote PC LAN file server and the system hosting PMDF (e.g., via Pathworks coexistence, FTP PC/TCP InterDrive plus NFS server, etc.).
```
! 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 
```
Note

² You should not use a directory in the PMDF directory tree.

Previous | Next | Contents

PMDF System Manager's GuidePMDF-REF-6.0

38.5.3 Telling PMDF about cc:Mail

38.5.3.1 Creating or editing lan.chans

38.5.3.2 Creating or editing lan.rules

38.5.3.3 cc:Mail channel option files

38.5.3.4 Location of the option file

38.5.3.5 Format of the option file

38.5.3.6 Contents of the option file

ACCESS_METHOD (0)

BINARY_ENCODING (string)

CC_ADDRESS_BITS (encoded value)

CC_ADDRESS_MAP (0-3)

CC_GATEWAY_NAME (string)

CC_INPUT_FILE_NAME (string)

CC_INPUT_FILE_PATTERN (string)

CC_OUTPUT_FILE_NAME (string)

CC_POSTOFFICE_HOST (string)

CC_PRIMARY_HOST (string)

CC_SLAVE_DELETE (0 or 1)

CC_UNDEL_FILE_NAME (string)

CHECK_LINE_LENGTH (0 or 1)

ENVELOPE_INTO_TO (0 or 1)

REPEAT_COUNT (integer)

SLEEP_TIME (integer)

SAVE_HEADERS (0, 1 or 2)

SEPARATE_COUNT (integer)

SEPARATE_FILES (integer)

SEPARATE_SIZE (integer)

STUFF_TEXT_PART (0 or 1)

TIMEZONE (string)

38.5.3.7 Example option files

Note

² You should not use a directory in the PMDF directory tree.

PMDF System Manager's Guide
PMDF-REF-6.0