WordPerfect Office channels are used to convert messages between the RFC 822 and MIME message formats used by PMDF and the format used by the WordPerfect Office API gateway. Versions 1.0 and 1.1 of the API format are presently supported. The WordPerfect Office channel programs combined with the WordPerfect Office API gateway and some mechanism to transfer files between systems produces an effective gateway between PMDF and WordPerfect Office.
The WordPerfect Office channel programs attempt to convert as much of MIME as possible to compatible WordPerfect Office message formats. However, limitations in WordPerfect Office make a complete conversion impossible, so in some cases the conversion will be limited in scope. In particular, WordPerfect Office is incapable of handling nested multipart and message structures, so any sense of nested structure is lost in the conversion process.
WordPerfect Office also provides some messaging capabilities that cannot be converted into MIME. Specifically, only messages of type MAIL are supported by this channel at the present time.
39.9.1 Required WordPerfect Software
A copy of the WordPerfect Office API Gateway is required.
With WordPerfect Office 4.0, the WordPerfect Office API Gateway 4.0 was included automatically; if you have WordPerfect Office 4.0, then you have the required API gateway also.
With WordPerfect Office 4.1, the WordPerfect Office API Gateway 4.1 is now a separate product, Novell part number 00662644057743; if you do not already have this product, you will need to obtain it from Novell.
39.9.2 Related WordPerfect Office Documentation
The WordPerfect Office side reference is the manual WordPerfect
Office API Gateway 4.0, publication GWUSIGL40, May 1993. (Note
that the software must be at least version 4.0A.) Someone trying to set
up a gateway who is unfamiliar with WordPerfect Office should read the
Introduction and Chapter One, "Planning", for an overview of
the API Gateway and its terminology, and Chapters 2 and 3, which
explain how to install and configure the API Gateway. A very useful
graphic showing the API directory structure can be found in Appendix J
39.9.3 How to Prepare Your WordPerfect Office for PMDF
You should have already installed WordPerfect Office and created a
domain and post office for your WP users. In order for WP Office to
exchange email with PMDF, you need to create a Gateway using the WP
Office ADMIN utility. First select your current domain, then choose
"Create" in the menu, then select "Gateway" to
create a gateway. The following fields in the Gateway Information
screen should be filled in as appropriate.
1. Domain: current domain +---2. Gateway ID --------------------------------+ |WP Name: PMDF | |Foreign Name: | |Description: PMDF to WPO gateway | |Directory: api40 | |Gateway alias type: PMDF | +-------------------------------------------------+ +---3. Gateway Execution -------------------------+ |Execution mode: MS launch | |Executable filename: api.exe | |Command line arguments: | |Launch on high priority : Yes | +-------------------------------------------------+ 4. Time Zone : as appropriate 5. Administrators: None +--- Settings -----------------------+ | Time... Optional... Specifics... | +------------------------------------+
+---- API Gateway Configuration ------------------+ |1. Gateway File Path | |Root directory for gateway messages: | | Path: m:\wpdomain\wpgate\api40 | |-------------------------------------------------+ |Root directory for directory services messages: | | Path: m:\wpdomain\wpgate\api40 | +-------------------------------------------------+ 2. [ ] Component keyword addressing 3. [x] Save Bad Messages in GWPROB directory.
m:\wpdomain\wpgate\api40 | +---------+-------+----------+ API_IN ATT_IN API_OUT ATT_OUT
.batfile running to copy files between VMS and these directories.
You then need to configure and set up a Message Server station, the "support PC", to run the Message Server (aka Connection Server) to transfer messages between post offices and the API gateway (PMDF).
39.9.4 Telling PMDF about WordPerfect Office
Setting up the WordPerfect Office (a.k.a. GroupWise) 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.
wpo_local_option, created by the PMDF-LAN configuration utility.
pc_post(UNIX), created by the PMDF-LAN configuration utility.
18.104.22.168 Creating or Editing lan.chans
The first step in installing a WordPerfect Office channel is to add a
channel definition to the PMDF configuration file---or as is more
commonly done, add the channel definition to a file
lan.chans file which is referenced by (read in to) the
PMDF configuration file proper. The entry should appear as
wpo_local master defragment charset8 ibm850 wpo-domain-name
wpo-domain-nameshould be a valid domain name that is reserved for use by the WordPerfect Office channel. One possible choice is to prepend the official local host name with "wpo.". For example, in the domain example.com, a reasonable domain name for the WordPerfect Office channel might be wpo.example.com and the channel entry would then appear as
wpo_local master defragment charset8 ibm850 wpo.example.com
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.com (OpenVMS) or
pc_post (UNIX) or
your own procedure to pick up mail from the PC. See Section 39.2.2 for
defragment keyword tells PMDF to reassemble any
fragmented MIME messages before sending them to WordPerfect Office.
charset8 keyword controls the character set label that
gets applied to text attachments containing eight bit characters.
ibm850 is a commonly used eight bit PC character set, but
use of other character sets is also possible. Mark your channel with
the eight bit character set actually in use by your WordPerfect Office.
22.214.171.124 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
wpo.example.com example, a start at a set of appropriate rules would be:
wpo $U%wpo.example.com wpo.example.com $U@wpo.example.com
email@example.com to a WordPerfect Office subscriber
userassociated with a specified default WordPerfect Office domain and post office. The address
firstname.lastname@example.org to a WordPerfect Office subscriber
userassociated with the
popost office in the
domainWordPerfect Office domain.
Although this addressing format is sufficient to access any subscriber using any post office in any WordPerfect Office domain, it is sometimes useful to associate additional domain names with other Wordperfect Office domains and post offices. This can be done with rewrite rules of the general form:
wg $U%wg.example.com wg.example.com $Uemail@example.com$E$F wg.example.com $Ufirstname.lastname@example.org$Cwpo_local wg.example.com $Uemail@example.com
popost office. Although these rules can look complex, their actions are reasonably straightforward: They insure that the WordPerfect Office names for domain and post office are used in the headers of messages queued to the WordPerfect Office channel, while the domain name for the workgroup (wg.example.com) is used in all other cases. Any number of similar rule sets can be used to associate additional domain names with additional WordPerfect Office domains and post offices.
The WordPerfect Office domain and post office can also be derived
directly from the domain name if desired. If the WPO_MAP_DOMAIN option
is set to 1 in the channel options file, an address of the form
firstname.lastname@example.org will be
converted to and from the address
on the WordPerfect Office side. If this option is set, an additional
rewrite rule needs to be specified:
126.96.36.199.1 An Example Channel Configuration
The following is an excerpt from a hypothetical PMDF configuration
which defines a WordPerfect office channel channel via the include
lan.chans. The contents
lans.rules file might appear as:
wpo $U%wpo.example.com wpo.example.com $U@wpo.example.com
lan.chansfile might then appear as:
wpo_local master defragment charset8 ibm850 wpo.example.com
In the above example, when a local user addresses a message to xyz@wpo, or email@example.com, the rewrite rules convert the address to firstname.lastname@example.org.
The resultant email@example.com uses a fully qualified domain name but it doesn't refer to a real machine. It defines a pseudonym used to route messages to a specific channel. This pseudonym must appear in one and only one channel block.
If you have multiple WordPerfect Office servers, you might allow users
to direct their messages to specific gateways on different servers. For
example, you could use two pseudonyms based on WPENGR and WPSALES. The
configuration will then contain the following rewrite rules and
channels. Note that additional option files are required for the added
channels. In such a case, the
lan.rules file might appear
wpo $U%wpo.example.com wpo.example.com $U@wpo.example.com wpengr $U%wpengr.example.com wpengr.example.com $U@wpengr.example.com wpsales $U%wpsales.example.com wpsales.example.com $U@wpsales.example.com
lan.chansfile would then be:
wpo_local master defragment charset8 ibm850 wpo.example.com wpo_gw1 master defragment charset8 ibm850 wpengr.example.com wpo_gw2 master defragment charset8 ibm850 wpsales.example.com
The WPO gateway channel is normally named wpo_local when connecting to just one WordPerfect Office API gateway. This is not an absolute rule, however --- PMDF's only real requirement is that the channel name begin with wpo_.
188.8.131.52 WordPerfect Office Channel Option Files
A channel option file must be created to control various
characteristics of a Wordperfect Office channel. Several mandatory
options must be specified in the option file, so the option file cannot
be omitted entirely. In general, options supply site specific
information to PMDF: the NetWare host containing the WPO directory
structure, the WPO directories volume, the WPO domain and post office
names assigned to PMDF, and a default WPO domain and post office name
to use when none are specified in an address.
The names of the mandatory options are:
184.108.40.206 Location of the Option File
Option files are stored in the PMDF table directory and must have names
of the form
channelname being the name of the WPO channel to
which this option file applies. Since the channel name for WPO is
usually wpo_local, the filename is usually
PMDF_TABLE:wpo_local_option. on OpenVMS or
/pmdf/table/wpo_local_option on UNIX.
220.127.116.11 Format of the Option File
WordPerfect Office channel option files have the same format as cc:Mail
channel option files. Refer to Section 18.104.22.168.
22.214.171.124 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, 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 WordPerfect Office 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 or Pine, 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. The WPO-TO-MIME-ENCODINGS mapping, if supplied and matched, will override the BINARY_ENCODING option's value. See Section 126.96.36.199 for additional information on this mapping.
SLEEP_TIME (integer)PMDF's WPO channel shares the files it produces with the WordPerfect Office API Gateway. 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 WordPerfect Office channel attempts to read its message files. The REPEAT_COUNT and SLEEP_TIME options are provided as a means to work around file server specific problems. The REPEAT_COUNT option specifies 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 specifies 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 messages PMDF sends to WordPerfect Office. 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.
TIMEZONE (string)Specifies the WordPerfect Office (GroupWise) time zone.
WPO_API_IN (string)WordPerfect Office communicates with each gateway via a gateway-specific directory containing at least four subdirectories. On the WPO side, the API_IN subdirectory contains the headers of messages to be imported into Wordperfect Office, the ATT_IN subdirectory contains message text and attachments associated with the headers in the API_IN subdirectory, the API_OUT subdirectory contains headers for messages exported from WPO to be picked up by the gateway, and the ATT_OUT subdirectory contains message text and attachments for the headers in the API_OUT subdirectory. Files must be transferred from the channel's WPO_API_OUT and WPO_ATT_OUT directories to WPO's API_IN and ATT_IN directories. Files must also be transferred from the channel's WPO_IN and WPO_IPARCEL directories to WPO's OUT and OPARCEL directories. PMDF does not automatically provide this. The installer must set up this copy, or transfer, process. Some utilities are provided to assist with this task. The installer must also ensure that the Wordperfect Office Connectivity Manager is operating. This option specifies the device and directory path on the system running PMDF where messages which are inbound to PMDF are stored.
WPO_API_OUT (string)Location of messages outbound from PMDF. Each file contains the header information, including the names of any message text or attachments, and the main body part. See the description under the WPO_API_IN option. Specifies the device and directory path on the system running PMDF where the messages which are outbound from PMDF are stored.
WPO_ATT_IN (string)Location of message text and any attachments associated with messages inbound to PMDF. Each attachment file is associated with exactly one header file in the WPO_API_IN directory. See the description under the WPO_API_IN option. Specifies the device and directory path on the system running PMDF where attachment files are stored.
WPO_ATT_OUT (string)Location of message text and any attachments associated with messages outbound from PMDF. Each attachment file is associated with exactly one header file in the WPO_API_OUT directory. See the description under the WPO_API_IN option. Specifies the device and directory path on the system running PMDF where the attachment files are stored.
WPO_DEFAULT_DOMAIN (string)Required option which specifies the name of the WPO domain to which the channel connects. The WPO_DEFAULT_PO option provides the name of the corresponding post office. When an address inbound to WPO does not contain an explicit workgroup or host name, PMDF uses this value and the WPO_DEFAULT_PO value, since WPO requires a WPO domain and post office in all addresses.
WPO_DEFAULT_PO (string)Required option which specifies the name of the WPO post office the channel connects to. See the discussion of the WPO_DEFAULT_DOMAIN option above for additional information.
WPO_FIRST_PART_ONLY (0 or 1)The default is 1, which means leave the original message structure alone, as much as possible, on messages going to WordPerfect Office (GroupWise). WPO_FIRST_PART_ONLY=0 means that for messages without an initial text part, the first text attachment, if there is one, should be promoted to being the "message text".
WPO_GATEWAY_DOMAIN (string)Required option which specifies the name of a WPO domain that will be associated with PMDF (and hence with the entire world of RFC 822 addresses PMDF provides access to). The WPO_GATEWAY_PO option provides the name of the corresponding post office. This WPO domain and post office must be made known to Wordperfect Office API Gateway when it is configured. To direct mail to the gateway, the PC user must use the value of this option as the WPO domain component (the first address field) in an address. The post office specified by the WPO_GATEWAY_PO must also be specified (the second address field).
WPO_GATEWAY_PO (string)Required option which specifies the name of a WPO post office that will be associated with PMDF. See the description of the WPO_GATEWAY_DOMAIN option above for additional information.
WPO_MASTER_DELETE (0 or 1)Specify WPO_MASTER_DELETE=0 if you are testing and do not want PMDF messages to be deleted from the PMDF channel queue by WPO_MASTER. The default is 1. WPO users will receive an endless stream of duplicate messages if this option is set incorrectly.
WPO_SLAVE_DELETE (0 or 1)Specify WPO_SLAVE_DELETE=0 if you are testing and do not want Wordperfect Office message files to be deleted automatically by WPO_SLAVE. The default is 1. PMDF users will get an endless stream of duplicate messages if this option is set incorrectly.
188.8.131.52 Example Option Files
This is an example option file for the wpo_local channel. The file's
name must be
wpo_local_option and the file must be stored
in the PMDF table directory, i.e.,
PMDF_TABLE:wpo_local_option. on OpenVMS or
/pmdf/table/wpo_local_option on UNIX. This example would
be used when PMDF accesses messages stored on local disks via normal
I/O methods. The messages must be moved by a transfer PC which can
access both the remote PC LAN file server and the PMDF system (via
Pathworks coexistence, FTP PC/TCP InterDrive plus NFS server,
The following is an example on OpenVMS system.
! Sample PMDF_TABLE:wpo_local_option. file on OpenVMS WPO_GATEWAY_DOMAIN=PROCESS WPO_GATEWAY_PO=PMDF ! WPO_DEFAULT_DOMAIN=EXAMPLE WPO_DEFAULT_PO=HQ ! WPO_API_IN=d1:[pmdf_wpo.api_in] WPO_ATT_IN=d1:[pmdf_wpo.att_in] WPO_API_OUT=d1:[pmdf_wpo.api_out] WPO_ATT_OUT=d1:[pmdf_wpo.att_out]
! Sample /pmdf/table/wpo_local_option file on UNIX WPO_GATEWAY_DOMAIN=PROCESS WPO_GATEWAY_PO=PMDF ! WPO_DEFAULT_DOMAIN=EXAMPLE WPO_DEFAULT_PO=HQ ! WPO_API_IN=/dev1/pmdf_wpo/api_in/ WPO_ATT_IN=/dev1/pmdf_wpo/att_in/ WPO_API_OUT=/dev1/pmdf_wpo/api_out/ WPO_ATT_OUT=/dev1/pmdf_wpo/att_out/
39.9.5 Addressing WPO from PMDF
The general format of an address in for a message destined for WPO is
wpouseris the name of a WPO user,
wpodomainis the name of the WPO domain the user's post office is in, and the
wpopois the name of the user's WPO post office. The
wpopo, and associated punctuation can be omitted, leaving
wpouser@wpogwif they are the same as the WPO_DEFAULT_DOMAIN and WPO_DEFAULT_PO options in the channel options file. In either format, the
wpogwportion works with the PMDF rewrite rules to actually route the message to a particular channel and to a specific WPO gateway.
39.9.6 Addressing PMDF from WPO
The generic formats for WPO addresses, as defined by Wordperfect Office
itself, used in a PC based user agent, and applying to PMDF, are:
The first format specifies a user directly associated with the machine
running PMDF. The second format is equivalent to the RFC 822 address
match both the WordPerfect Office API gateway configuration as well as
the settings of the WPO_GATEWAY_DOMAIN and WPO_GATEWAY_PO options in
the channel options file.
39.9.7 Content Type and Character Set Mappings
WordPerfect Office uses file names to indicate what sort of data is
present in an attachment. Although file names do not provide an exact
typing scheme, nevertheless they can be mapped to and from MIME content
types and subtypes. For this reason, the WPO channel maps WordPerfect
Office attachment file names to MIME content types and subtypes and
back again. Selection of an appropriate MIME transfer encoding is also
necessary for each sort of file. All this is implemented using a set of
mapping tables in the mapping file.
The following sections describe the mappings used by the WPO channel.
Examples of these mappings are also provided in a sample file included
in the table directory of the PMDF distribution,
PMDF_TABLE:wpo_mappings.sample on OpenVMS or
/pmdf/table/wpo_mappings.sample on UNIX. If you do not
have a PMDF mapping file in your PMDF table directory, you can just
mappings and edit
it to suit your site.
184.108.40.206 MIME-CONTENT-TYPES-TO-WPO Mapping
The MIME-CONTENT-TYPES-TO-WPO mapping table maps MIME content type and
subtype information into Wordperfect Office attachment file names. A
minimal MIME-CONTENT-TYPES-TO-WPO mapping would be:
MIME-CONTENT-TYPES-TO-WPO TEXT/PLAIN TEXT.TXT APPLICATION/POSTSCRIPT PS.PS
220.127.116.11 WPO-TO-MIME-CONTENT-TYPES Mapping
The WPO-TO-MIME-CONTENT-TYPES mapping table maps WPO attachment file
names into MIME content type and subtype information. A minimal
WPO-TO-MIME-CONTENT-TYPES mapping would be:
WPO-TO-MIME-CONTENT-TYPES *.TXT TEXT/PLAIN *.PS APPLICATION/POSTSCRIPT
18.104.22.168 WPO-TO-MIME-ENCODINGS Mapping
The WPO-TO-MIME-ENCODINGS mapping table maps WordPerfect Office
attachment file names to an appropriate MIME transfer encoding. The
left hand side of the mapping should be a pattern intended to match a
file name and the result should be a MIME transfer encoding identifier
(7BIT, 8BIT, BASE64, QUOTED-PRINTABLE, etc.) A minimal
WPO-TO-MIME-ENCODINGS mapping would be:
WPO-TO-MIME-ENCODINGS *.TXT NONE *.PS QUOTED-PRINTABLE
22.214.171.124 MIME-TO-WPO-CHARSETS Mapping
The MIME-TO-WPO-CHARSETS mapping table maps MIME charset parameter
information into Wordperfect Office character set information. A
minimal MIME-TO-WPO-CHARSETS mapping would be:
MIME-TO-WPO-CHARSETS US-ASCII T50 T.61 T61
126.96.36.199 WPO-TO-MIME-CHARSETS Mapping
The WPO-TO-MIME-CHARSETS mapping table maps WPO character sets into
MIME charset parameter values. A minimal WPO-TO-MIME-CHARSETS mapping
WPO-TO-MIME-CHARSETS T50 US-ASCII T61 T61