| Previous | Contents | Index |
You must perform the following configuration tasks on the Lotus Notes side.
The sub-sections below provide step-by-step instructions on performing these tasks to inform Lotus Notes about PMDF.
38.6.4.1 Create a Directory on the Lotus Notes Server System
On the Lotus Notes server system you must create a scratch directory
for the PMDF Notes Gateway Server Add-ins' use. Although the Add-ins
use a TCP/IP protocol to communicate with PMDF, the Notes API expects
to pass messages, and especially attachments, to Server Add-in programs
as files. Thus the PMDF Notes Gateway Server Add-ins need a scratch
area for these temporary files. The PMDF Notes Gateway Server Add-ins
have to be given a directory name through which messages and
attachments will be staged as they are imported into Notes, and which
will be used to stage messages and attachments as they are exported
from Notes.
The directory for temporary files needs to be created. A typical name would be
c:\pngate\intemp\ |
c:\pngate\intemp.
The PMDF Notes Gateway Server Add-ins must be told of the name chosen; see Section 38.6.4.3 for how to configure the PMDF Notes Gateway Server Add-ins.
38.6.4.2 Copy the Add-in Iimage to the Lotus Notes Server System
Copy the appropriate version of the PMDF Notes Gateway Server Add-in
images, pngatecin.exe and pngatecout.exe, to
the Lotus Notes program directory on the PC server system.
For an NT (Intel hardware) based Lotus Notes server, copy the
pngatecin.exe and pngatecout.exe images from
either the pmdf_root:[other.nt-intel.notes] (OpenVMS),
/pmdf/other/nt-intel/notes/ (UNIX), or the
C:\pmdf\other\nt-intel\notes\ (NT) directory on the PMDF
system, or directly from the [other.nt-intel.notes]
(OpenVMS), the /other/nt-intel/notes (UNIX), or the
\other\nt-intel\notes (NT) directory on the PMDF
distribution CD-ROM (an ISO 9660 with Rockridge extensions CD-ROM
directly readable from many platforms including most PC operating
systems) to the Lotus Notes program directory on the PC server system.
For an OS/2 based Lotus Notes server, copy the
pngatecin.exe and pngatecout.exe images from
either the pmdf_root:[other.os2.notes] (OpenVMS), the
/pmdf/other/os2/notes (UNIX), or the
C:\pmdf\other\os2\notes\ (NT) directory on the PMDF
system, or directly from the [other.os2.notes] (OpenVMS),
the /other/os2/notes (UNIX), or the
\other\os2\notes (OS/2) directory on the PMDF distribution
CD-ROM (an ISO 9660 with Rockridge extensions CD-ROM directly readable
from many platforms including most PC operating systems) to the Lotus
Notes program directory on the PC server system.
38.6.4.3 Configure Server Add-in Options in the Lotus Notes Server Initialization File
Now configure the options for the PMDF Notes Gateway Server Add-in.
Edit the Lotus Notes server initialization file,
notes.ini, setting options for the PNGATECIN and
PNGATECOUT tasks. On an OS/2 based Lotus Notes server, this
initialization file is normally located in the Lotus Notes data
directory; on an NT based Lotus Notes server, this file can be
located in the Lotus Notes data directory but normally is instead
located in the Windows NT installation directory, generally
\winnt. To the notes.ini, file, add the lines:
PNGateDomain=PMDF-domain PNGateInTemp=intempdir PNGateHost=PMDF-host-name PNGateInPort=master-port PNGateOutPort=slave-port PNGateInterval=polling-delay MailTimeout=export-time-limit PNGateCharSet=l_cp850.cls |
PMDF-domain is the name used from the Lotus
Notes side to address messages to PMDF, typically just
PMDF, where intempdir is the name of
the scratch directory used for temporary message and attachment files
being imported into and out of Notes, as described in Section 38.6.4.1
above, where PMDF-host-name is the TCP/IP name of
the PMDF system, where master-port is the port on
which the Dispatcher listens to run the master direction of the channel
(the PMDF to Notes direction), where slave-port
is the port on which the Dispatcher listens to run the slave direction
of the channel (the Notes to PMDF direction), where
polling-delay is the frequency in minutes with
which the Lotus Notes server should run the Add-ins, and where
export-time-limit is the time limit in hours
after which to bounce messages that could not be exported from Lotus
Notes during that time.
The PNGateCharSet option specifies the name of a Lotus
Notes server .cls file, which controls what character set
the Lotus Notes server will accept from the Lotus Notes Server Add-in.
The usual recommended value is
PNGateCharSet=l_cp850.cls |
For instance, a site where PMDF is running on a machine with the TCP/IP
name of mailhub.example.com, and that created a \pngate
directory on the C: drive might use:
PNGateDomain=PMDF PNGateInTemp=c:\pngate\tmp\ PNGateHost=mailhub.example.com PNGateInPort=9972 PNGateOutPort=9971 PNGateInterval=2 MailTimeout=72 PNGateCharSet=l_cp850.cls |
When selecting an appropriate MailTimeout value, consider how long it would be reasonable to expect that the PMDF system might be unavailable for TCP/IP connections. The sample value shown, 72, would cover the case of a network outage extending for a three day weekend.
In addition to the above mandatory options, you can also want to set additional options; Section 38.6.4.3.1, Section 38.6.4.3.2, and Section 38.6.4.3.3 discuss additional options.
38.6.4.3.1 "Tunnelling" Complete Notes Documents
Lotus Notes documents can contain formatting information, graphics,
etc., usable only by another Lotus Notes user. The PMDF Notes
Gateway Add-in always extracts a plain text version of a Notes document
from Lotus Notes. Optionally, the PMDF Notes Gateway Add-in can also
extract the complete Lotus Notes document, in case the message
recipient will be another Lotus Notes user. In the latter case, the
Lotus Notes channel will generate a MIME multipart/alternative part
containing both a text version of the Notes document and the complete
Notes document. If the recipient of the message receives it through
another PMDF Notes Gateway, then the full Notes document version will
be used. Other recipients can instead read the text/plain version. To
enable this feature, to the notes.ini file add the line
PNGateAlternate=1 |
PNGateAlternate=0 |
Note that if desired, the PMDF conversion channel can be used to remove the "tunnelled" complete version of the Notes document from messages destined for recipients known not to use Lotus Notes. (Note that mail user agents that support the MIME multipart/alternative format should not insist on displaying the Notes part to non-Notes recipients in any case, but removing the "tunnelled" Notes parts can still be useful to cut down on message bandwidth.) A DELETE=1 conversion file entry can be used to delete the tunnelled parts themselves, and in addition, the Level CHARSET-CONVERSION keyword tells PMDF to remove the (redundant, once the "tunnelled" original Notes part has been deleted) multipart/alternative structure from around the remaining text part.
For instance, a site that already has a conversion channel set up and that wants to remove the "tunnelled" complete Notes documents from messages going to their L (local) channel, might use CHARSET-CONVERSION and CONVERSIONS mapping table such as
CONVERSIONS IN-CHAN=ln_*;OUT-CHAN=l;CONVERT Yes CHARSET-CONVERSION IN-CHAN=conversion;OUT-CHAN=l;CONVERT Level |
in-chan=ln_*; out-chan=l; in-type=application; in-subtype=x-pmdf-notes-doc; delete=1 |
38.6.4.3.2 Debug Output
You can need from time to time to ask the PMDF Notes Server Add-in to
produce debugging information. To turn on such debugging, add to the
notes.ini file the line
PNGateDebug=level |
level is an integer between 0 and 9. 0
means no debugging; 1 through 9 stand for increasing levels of
verbosity. Messages are written to the Lotus Notes log and console.
Note that the line
PNGateDebug |
38.6.4.3.3 Additional Server Add-in Options
Specifying
PNGateFixedFont=1 |
By default, if PNGateStrictTimer=0 is set in the Notes
server initialization file or if the option is not set at all, Lotus
Notes will immediately send each outbound message to PMDF. Specifying
PNGateStrictTimer=1 |
PNGateLineLen=x |
38.6.4.4 Starting the PMDF Notes Gateway Service
If you want the PMDF Notes Gateway service to start automatically when
the Lotus Notes server is started, then add PNGATECIN and PNGATECOUT to
the list of server tasks. That is, edit the notes.ini file
further and add ,PNGATECIN,PNGATECOUT to the ServerTasks
line, i.e.,
ServerTasks=...,PNGATECIN,PNGATECOUT |
For testing, or if you cannot restart the Lotus Notes server now, you
can manually start the PMDF Notes Gateway service using the LOAD
PNGATECIN and LOAD PNGATECOUT commands from the
Lotus Notes server console. (This will start PNGATECIN and PNGATECOUT
even if they haven't been added to the ServerTasks line.)
If you want to halt just the PNGATECIN task, you can use the TELL
PNGATECIN QUIT command; similarly, TELL PNGATECOUT
QUIT halts the PNGATECOUT task. If Lotus Notes does not respond
to such a command, repeat it several times. An Add-in can only respond
to such a command when it is idle. You can find the you have to prefix
the image name with the dollar character on OS/2 or N character on NT
Intel, e.g., TELL $PNGATECIN QUIT on OS/2, or
TELL NPNGATECIN QUIT on NT Intel.
To check if the PNGATECIN and PNGATECOUT tasks are running, issue the
command SHOW TASKS from the Lotus Notes server console.
For an overview of installing and managing server add-in tasks, see Chapter 4 and Chapter 5 of the Lotus Notes API 3.4 User Guide.
38.6.4.5 Add a Foreign Domain Record to the Lotus Notes Address Book
With a Lotus Notes client, use the Create/Server/Domain form (Lotus
Notes V4.x) to add a foreign domain record to the Lotus Notes server's
Public Name & Address Book. Set the fields as follows. With Lotus
Notes V4.x:
Domain type: Foreign Domain Foreign domain name: PMDF-domain Gateway server name: Notes-server-name Gateway mail file name: pngate.nsf |
PMDF-domain is the Lotus Notes side's name
for PMDF, as specified by the PNGateDomain Notes
initialization file option described in Section 38.6.4.3, and where
Notes-server-name is the Lotus Notes server's
name for itself.
Normally this is done by the Server Administrator, (or by anyone else
who has appropriate access to be able to modify the server's Public
Name & Address Book). To check if the new domain has been
successfully entered, while still in the public name and address book,
go to the navigation pane and expand "Folders and Views",
then expand "Server", and then expand "Domain".
PMDF-domain should show up as one of the entries
in the view pane.
| Previous | Next | Contents | Index |