PMDF System Manager's Guide
Previous Next Contents Index

38.9 WordPerfect Office (GroupWise) Channels

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.

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

38.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 (page 102).

38.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...   | 
+------------------------------------+
Then select specifics in the settings to get into the API gateway configuration screen and enter the path where you the messages to and from PMDF will be stored. The value given below is just an example. 


+---- 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.
If you created the gateway successfully, then you should find the directory structure created as follows: 


                   m:\wpdomain\wpgate\api40 
                            | 
               +---------+-------+----------+ 
             API_IN   ATT_IN  API_OUT  ATT_OUT
The API_IN and ATT_IN directories are where messages from PMDF are stored. The API_OUT and ATT_OUT directories are where messages to PMDF are stored. Depending on the transfer method, PMDF can directly read and write these directories, or you can have a .bat file 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).

38.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:
  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. wpo_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.9.4.1 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-name should 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

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.com (OpenVMS) or pc_post (UNIX) 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 WordPerfect Office.

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

38.9.4.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 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
The address user@wpo.example.com maps to a WordPerfect Office subscriber user associated with a specified default WordPerfect Office domain and post office. The address user%domain.po@wpo.example.com maps to a WordPerfect Office subscriber user associated with the po post office in the domain WordPerfect 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         $U%po.domain@wpo.example.com$E$F 
wg.example.com         $U%wg.example.com@wpo.example.com$Cwpo_local 
wg.example.com         $U%po.domain@wpo.example.com
These rules associate the domain name wg.example.com with the WordPerfect Office domain domain and po post 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 user@po.domain.wpo.example.com will be converted to and from the address domain.po.user on the WordPerfect Office side. If this option is set, an additional rewrite rule needs to be specified: 


.wpo.example.com        $U%$H.wpo.example.com@wpo.example.com

38.9.4.2.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 files lan.rules and lan.chans. The contents of the lans.rules file might appear as: 


wpo                 $U%wpo.example.com 
wpo.example.com     $U@wpo.example.com
The contents of the corresponding lan.chans file 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 xyz@wpo.example.com, the rewrite rules convert the address to xyz@wpo.example.com.

The resultant xyz@wpo.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 as: 


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
and the corresponding lan.chans file 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_.

38.9.4.3 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:

Their significance and usage are described in Section 38.9.4.6. Before setting up the PMDF configuration files, you must know the correct values to specify for these mandatory options. Contact whoever does WordPerfect Office administration tasks at your local site. Impress upon them that if they unilaterally change their WPO configuration it can break the mail gateway. Ask them to notify you before making changes so that you can keep the PMDF configuration synchronized with WordPerfect Office.

38.9.4.4 Location of the Option File

Option files are stored in the PMDF table directory and must have names of the form channelname_option with 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.

38.9.4.5 Format of the Option File

WordPerfect Office channel option files have the same format as cc:Mail channel option files. Refer to Section 38.5.3.5.

38.9.4.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, 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 38.9.7.3 for additional information on this mapping.

REPEAT_COUNT (integer)

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.

38.9.4.7 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, etc.).

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]
The following is an example on UNIX. 


! 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/

38.9.5 Addressing WPO from PMDF

The general format of an address in for a message destined for WPO is 


wpouser%wpodomain.wpopo@wpogw
From VMS MAIL, use: 


IN%"wpouser%wpodomain.wpopo@wpogw"
wpouser is the name of a WPO user, wpodomain is the name of the WPO domain the user's post office is in, and the wpopo is the name of the user's WPO post office. The wpodomain, wpopo, and associated punctuation can be omitted, leaving wpouser@wpogw if they are the same as the WPO_DEFAULT_DOMAIN and WPO_DEFAULT_PO options in the channel options file. In either format, the wpogw portion works with the PMDF rewrite rules to actually route the message to a particular channel and to a specific WPO gateway.

38.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: 


pmdfdomain.pmdfpo.user
pmdfdomain.pmdfpo."user@host"

The first format specifies a user directly associated with the machine running PMDF. The second format is equivalent to the RFC 822 address user@host. The pmdfdomain and pmdfpo must 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.

38.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 copy wpo_mappings.sample to mappings and edit it to suit your site.

38.9.7.1 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

38.9.7.2 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

38.9.7.3 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

38.9.7.4 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

38.9.7.5 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 would be: 


WPO-TO-MIME-CHARSETS 
 
  T50                             US-ASCII 
  T61                             T61

Previous Next Contents Index