SUMMARY
Application Note WA0728, "Troubleshooting the Mail Connection Gateway,"
is designed to help you troubleshoot and correct common problems
encountered with the Microsoft Mail Connection gateway, version 1.0b.
You can obtain this Application Note from the following sources:
- Microsoft's World Wide Web Site on the Internet
- The Internet (Microsoft anonymous ftp server)
- The Microsoft Network (MSN)
For complete information, see the "To Obtain This Application Note"
section at the end of this article.
The TEXT OF WA0728
======================================================================
Microsoft(R) Product Support Services Application Note (Text File)
WA0728: TROUBLESHOOTING THE MAIL CONNECTION GATEWAY
======================================================================
Revision Date: 2/93
No Disk Included
The following information applies to Microsoft Mail Connection Gateway
version 1.0b.
--------------------------------------------------------------------
| INFORMATION PROVIDED IN THIS DOCUMENT AND ANY SOFTWARE THAT MAY |
| ACCOMPANY THIS DOCUMENT (collectively referred to as an |
| Application Note) IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY |
| KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO |
| THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A |
| PARTICULAR PURPOSE. The user assumes the entire risk as to the |
| accuracy and the use of this Application Note. This Application |
| Note may be copied and distributed subject to the following |
| conditions: 1) All text must be copied without modification and |
| all pages must be included; 2) If software is included, all files |
| on the disk(s) must be copied without modification [the MS-DOS(R) |
| utility DISKCOPY is appropriate for this purpose]; 3) All |
| components of this Application Note must be distributed together; |
| and 4) This Application Note may not be distributed for profit. |
| |
| Copyright 1993 Microsoft Corporation. All Rights Reserved. |
| Microsoft and MS-DOS are registered trademarks and Windows |
| is a trademark of Microsoft Corporation. |
--------------------------------------------------------------------
INTRODUCTION
============
This application note is designed to help you troubleshoot and correct
common problems encountered with the Microsoft Mail Connection
gateway, version 1.0b. Additional information is available in the
"Mail Connection Administrator's Guide" and the README files located
on the Mail Connection distribution disks.
HOW THE MAIL CONNECTION WORKS
=============================
The Microsoft Mail Connection can be broken down into two separate
gateway components, a Macintosh component and a PC component. Both
gateway components perform the same tasks and operate independently.
Each is responsible for extracting outgoing gateway messages and
importing incoming gateway messages to their respective mail servers.
The two gateway components transfer messages and directory lists
between each other by depositing and retrieving message files to or
from designated directories located on a file server that is
accessible to the PC and the Macintosh. The shared directory structure
that the gateway components use to transfer their messages is called
the "Connection store".
The Connection store contains two subdirectories, MACTOPC and PCTOMAC.
The names of the directories describe the direction in which the
message files stored within them are traveling. Message files found in
the MACTOPC directory originate from the AppleTalk Mail network and
are destined for the PC Mail network. Message files stored in the
PCTOMAC directory are traveling in the opposite direction, from the PC
Mail network to the AppleTalk Mail network.
The PC and Macintosh gateway components perform the same basic task,
importing and extracting messages to/from their Mail database, but
they operate quite differently from each other. Because the two
components operate independently, one may be functioning normally
while the other is not.
THE MACINTOSH GATEWAY COMPONENT
-------------------------------
The Macintosh gateway component is integrated with the AppleTalk Mail
server and is an "extension" of the server process. The AppleTalk Mail
server communicates with its loaded gateways via the MS Mail GW
Chooser extension. Gateway resources are extracted from the gateway
server by the MS Mail GW Chooser extension and are stored in the MS
Mail GW Cache file. The AppleTalk Mail server "triggers" the gateway
at the times specified in the Gateway Connect Times configuration
screen.
THE PC GATEWAY COMPONENT
------------------------
The PC component of the Mail Connection consists of a dedicated PC
running the MACGATE application. The "Macgate PC" must be connected
via the local-area network (LAN) to the PC Mail gateway postoffice and
the Connection store. The Macgate PC periodically checks for incoming
gateway message files in the MACTOPC directory and deposits any
outgoing gateway messages in the PCTOMAC directory. The MACGATE
application calls the Microsoft Mail File Format Application
Programming Interface (FFAPI) modules MACGET and MACPUT to import and
extract gateway messages to/from the PC Mail postoffice database.
Use the MSGATE.INI file and command-line options to configure the
MACGATE application.
DIRECTORY EXCHANGE
------------------
Directory exchange is controlled from the Macintosh side of the Mail
Connection using the Connection Name Utility (CNU). The CNU extracts
the AppleTalk Mail user list and sends it to the Macgate PC as a
special directory exchange mail message. The Macgate PC processes the
message and passes the AppleTalk Mail user list to the FFAPI
IMPORT.EXE program.
The CNU can also send a request message to the Macgate PC to request
the PC Mail user list. The Macgate PC extracts the PC Mail user list
by calling the FFAPI IMPORT.EXE program and mails the list to the
network manager of the gateway AppleTalk Mail server. If the CNU is
running, it intercepts the message, processes the list of PC Mail
addresses, and adds the address names to the AppleTalk Mail server as
gateway recipients (gateway recipients can be seen in the Define
Gateway Recipients screen). The CNU can also be used to remove the
AppleTalk Mail names from the PC Mail network, or to remove the PC
Mail names from the AppleTalk Mail server.
The Macintosh gateway component configuration screen contains a
section for configuring directory synchronization options. Directory
synchronization has not been implemented in this version of the Mail
Connection, so leave these fields blank. (Entering values in the
directory synchronization fields may cause the Mail Connection to stop
functioning.)
NOTE: Directory exchange messages are similar to regular gateway
messages and can be affected by many of the same problems that
would prevent a gateway message from being delivered. If you
experience problems with directory exchange, verify that regular
gateway messages are being delivered.
MONITORING THE MAIL CONNECTION
==============================
Use the following information to help you monitor the activity of the
Mail Connection Gateway. By tracking a message through the gateway,
you can determine where problems are occurring and which component is
responsible.
TRACKING A MESSAGE FROM PC MAIL TO APPLETALK MAIL
-------------------------------------------------
Messages that are composed by PC Mail users and addressed to AppleTalk
Mail recipients are written to the Mail Connection gateway mailbag
file. The messages remain in the gateway mailbag file until the
Macgate PC extracts them and deposits them in the PCTOMAC directory.
The PC Mail administrator can use the ADMIN.EXE program to check the
status of messages waiting in the gateway mailbag. A list of the
outgoing gateway messages can be viewed by selecting Queue from the
top menu bar and entering "MSMAIL" as the network name. The gateway
messages can be deleted or returned to the sender by the
administrator.
The Macgate PC periodically checks the Mail Connection gateway mailbag
on the postoffice and extracts any waiting gateway messages. Each
message is written as a separate file in the PCTOMAC directory of the
Connection store. The Macgate PC updates the status screen and
displays a summary of each gateway message it processes.
The gateway message files wait in the PCTOMAC directory until the
Macintosh gateway component retrieves them. The MS-DOS directory (DIR)
command can be used to display the contents of the PCTOMAC directory;
it shows the number of messages waiting to be delivered to AppleTalk
Mail users, the date and time the Macgate PC deposited them, and the
size of each message file.
The AppleTalk Mail server periodically executes the Macintosh
component of the Mail Connection gateway at the times defined in the
Gateway Connect Times configuration screen. The Macintosh gateway
component checks for new message files in the PCTOMAC directory. The
message files are imported by the Macintosh gateway component and are
passed to the AppleTalk Mail server via the MS Mail GW RDEV (resource
device). The Macintosh Gateway Services Monitor (GWS Monitor) can be
used to monitor the message traffic as it is passed from the gateway
component to the AppleTalk Mail server. (Launch the GWS Monitor and
choose Show Trace Window from the Trace menu.)
The AppleTalk Mail server delivers the gateway message to the
recipient's inbox and notifies the user of the new mail (if
notification is turned on).
TRACKING A MESSAGE FROM APPLETALK MAIL TO PC MAIL
-------------------------------------------------
Messages that are composed by AppleTalk Mail users and addressed to PC
Mail recipients are retained by the server in a special outbound
gateway queue. The network manager can view a list of the messages
waiting in the outbound gateway queue by launching the Mail Network
Administrator application and requesting a Global Server Report. The
Global Server Report displays the status of each mail server your
server is aware of and the status of the messages waiting in the
outbound gateway queue (at the bottom of the report). The network
manager can delete messages from the outbound gateway queue by
choosing Delete Queued Mail from the Admin menu of the Mail Network
Administrator application.
The AppleTalk Mail server triggers the Macintosh component of the Mail
Connection Gateway at the times specified in the Gateway Connect Times
configuration screen. The Macintosh gateway component uses the MS Mail
GW RDEV to extract the messages from the outbound gateway queue. The
Gateway Services Monitor can be used to monitor the message traffic as
it is passed from the AppleTalk Mail server to the gateway component.
The Macintosh gateway component deposits the extracted gateway
messages into the MACTOPC subdirectory of the Connection store. The MS-
DOS directory (DIR) command can be used to display the contents of the
MACTOPC directory; it shows the number of messages waiting to be
delivered to the PC Mail network, the date and time the Macintosh
gateway component deposited them, and the size of each message file.
The Macgate PC periodically checks the MACTOPC directory and retrieves
any new messages. Each new message is temporarily placed in the
Inqueue mailbag and the intended recipients are copied into a file in
the P1 directory. The Macgate PC or any other Message Transfer Agent
(MTA) processes the entries in the Inqueue mailbag and delivers the
gateway messages to the intended PC Mail recipients' mailbags or
external postoffice mailbags.
DIAGNOSING PROBLEMS
===================
Problems with the Mail Connection can often be isolated quickly by
checking for message files in the MACTOPC and PCTOMAC subdirectories
of the Connection store. Message files should not remain in the
Connection store directories for more than one gateway cycle, except
when there are more than 50 messages waiting to be processed. The Mail
Connection has a limit of 50 messages per processing cycle, so some
may be left over if more than 50 are waiting.
MESSAGES ARE NOT DELIVERED FROM APPLETALK MAIL TO PC MAIL
---------------------------------------------------------
If you suspect that the Mail Connection is not delivering messages
from AppleTalk Mail to PC Mail, check for message files in the MACTOPC
directory. If the gateway is not depositing message files in the
MACTOPC directory, verify the following:
- The Connection store volume is mounted on the AppleTalk Mail
server's desktop.
- The path to the Connection store is defined correctly in the
Gateway Configuration screen.
- Gateway connect times are configured to trigger the gateway.
- The MS Mail GW Chooser document has the correct gateway server
selected.
- The AppleTalk Mail server has sufficient access rights (read,
write, create, delete, and scan) to the Connection store volume.
- The MACTOPC directory exists in the Connection store.
If you find message files waiting in the MACTOPC directory that are
not being delivered by the gateway, verify the following:
- MACGATE.EXE is running.
- The Macgate PC has sufficient access rights to the PC Mail
postoffice and Connection store volumes.
- StorePath and/or StoreDrive are configured correctly in the
MSGATE.INI file.
- The postoffice INQUEUE.MBG and INQUEUE.KEY files exist with no
hidden attributes, have an owner (if you are using a Novell
network), and can be written to by the Macgate PC.
- If you are using a non-MS-NET or Novell network, make sure the file
sizes are the same on each platform.
- From the Macintosh, verify that the filenames on the Connection
store are all uppercase letters or all lowercase letters.
MESSAGES ARE NOT DELIVERED FROM PC MAIL TO APPLETALK MAIL
---------------------------------------------------------
If you suspect that the Mail Connection is not delivering messages
from PC Mail to AppleTalk Mail, first check for message files in the
PCTOMAC directory. If the gateway is not depositing message files in
the PCTOMAC directory, verify the following:
- MACGATE.EXE is running.
- The Macgate PC has sufficient access rights to the Connection store
volume to create and delete files.
- The PCTOMAC directory exists in the Connection store.
If the above items are correct, run the PC Mail ADMIN.EXE utility and
check the status of the gateway mailbag file by selecting Queue and
entering "MSMAIL" as the Network Type. It is possible that the Macgate
PC cannot deliver a bad message. If so, return the oldest gateway
message to the sender.
If you find message files waiting in the PCTOMAC directory that the
gateway is not delivering, verify the following:
- The Connection store volume is mounted on the AppleTalk Mail
server's desktop.
- The path to the Connection store is defined correctly in the
Gateway Configuration screen.
- Gateway Connect Times are configured to trigger the gateway.
- The MS Mail GW Chooser document has the correct gateway server
selected.
- The AppleTalk Mail server has sufficient access rights to the
Connection store volume to create and delete files.
- The MACTOPC directory exists in the Connection store.
SPECIFIC PROBLEMS AND SOLUTIONS
===============================
The following describes specific problems, possible causes, and their
solutions.
MACGATE.EXE
-----------
2 - Cannot verify logon user/admin ID. Authorization failure.
Bad parameter value. (110)
Possible cause: Admin password is incorrect in the MSGATE.INI
file.
The user and password defined in the MSGATE.INI file are used
by the Mail Connection gateway when importing and exporting
user lists. This user must have administrator privileges on the
postoffice.
Possible cause: The Enhanced Security feature is installed.
The Microsoft Mail Connection gateway is not compatible with
the Enhanced Security feature of PC Mail version 3.0. Remove
the Enhanced Security feature by running the UPDATE.EXE program
from the PC Mail 3.0 Server Version - Disk 1 (refer to page 11
of the "Microsoft Mail Administrator's Guide").
MSGATE.INI cannot be accessed. (125): No such file or directory.
Possible cause: The PC Mail postoffice volume is not at the
root of the postoffice directory structure.
The PC Mail postoffice volume must be at the root level of the
postoffice directory structure when the MACGATE.EXE program is
executed. Change to the postoffice drive and use the MS-DOS
"CD" command to set the default directory to the root of the
postoffice. (A directory of the root level of the postoffice
should contain the subdirectories ATT, FOLDERS, GLB, etc.)
Invalid gateway share directory. (130)
Possible cause: StoreDrive or StorePath is incorrect in the
MSGATE.INI file.
Verify that the StoreDrive and StorePath parameters in the
MSGATE.INI file are defined correctly. The StoreDrive is the
letter mapped to the root directory of the gateway store. The
StorePath is the path to the gateway store from the root of the
StoreDrive.
Possible cause: The PCTOMAC directory is missing or renamed.
Verify that the MSGATE\STORE directory contains a subdirectory
named PCTOMAC. If this subdirectory doesn't exist, create a new
one using the MS-DOS "MKDIR" command.
52 - A file open error has occurred.
Error while processing message: (114)
Possible cause: MACGATE cannot write or create files in the
MSGATE\STORE directory.
The PC running the MACGATE program must have sufficient access
rights to write and create temporary files in the MSGATE\STORE
directory structure.
The Macgate PC status screen shows that incoming messages are being
processed, but the messages are not being delivered.
Possible cause: The PC Mail postoffice P1 subdirectory is
missing or the Macgate PC does not have sufficient access
rights to create files in this directory.
Create the P1 subdirectory and grant all access rights to the
account the Macgate PC uses.
Possible cause: There are not enough file handles available to
deliver the message.
Edit the CONFIG.SYS file of the PC running the MACGATE.EXE
program and add a "FILES=20" line. Restart the PC after making
this change.
Error running FFAPI program: Not enough core
Error importing AppleTalk Mail directory to drive M:
Possible cause: IMPORT.EXE does not have enough conventional
memory available to import the AppleTalk Mail address list.
The MACGATE.EXE program spawns IMPORT.EXE when a directory
exchange message is received from the AppleTalk Mail network.
IMPORT.EXE requires as much conventional memory available as
possible to successfully import a large AppleTalk Mail address
list. Remove any unnecessary TSRs and device drivers, and load
the remaining drivers into high memory if possible. Use the MS-
DOS "MEM /C" command to see a summary of your memory
utilization.
Warning [ 1] Error obtaining message #:1 GWTRANS
Possible cause: There are not enough file handles available to
complete the directory import.
Edit the CONFIG.SYS file of the PC running the MACGATE.EXE
program and add a "FILES=20" line. Restart the PC after making
this change.
Error 940: Cannot add physical address
Possible cause: The Macgate PC is unable to write to the
MSMAIL.GLB file in the PC Mail postoffice GLB directory or the
MSMAIL.NME file in the NME directory.
Novell users should also confirm that these files are not
ownerless.
CONNECTION NAME UTILITY
-----------------------
Exporting Macintosh directory to PC Mail: Error Occurred: Out of
memory
Possible cause: The Connection Name Utility requires more
memory allocated to it.
The Connection Name Utility has a suggested memory allocation
of 384K. Increase this amount if you are exporting a large
number of Macintosh names to PC Mail. Increase the Connection
Name Utility's memory allocation in the Get Info box by
increasing the Current Size value.
Error Occurred: No Gateway Selected.
Possible cause: The gateway is not selected from within the
Connection Name Utility.
To define the gateway, choose Select Gateway from the File
menu. From the Select Gateway configuration screen, highlight
the installed Mail Connection Gateway and click the Select
button.
Gateway Error 4992 (When exporting AppleTalk Mail names to PC Mail
via the Connection Name Utility)
Possible cause: The MS Mail GW Cache file in the Preferences
folder may be corrupt.
Restart the AppleTalk Mail server and hold down the "M" key
while the server starts up (to prevent the Microsoft Mail
server from loading). Delete the MS Mail GW Cache file and
restart the server again (don't hold down the "M" key this
time). Open the Chooser and select the MS Mail GW Chooser
document. Choose the gateway Microsoft Mail server and close
the Chooser; this will create a new MS Mail GW Cache file
(System 6.x users will find the MS Mail GW Cache file in the
root level of the System Folder.)
APPLETALK MAIL
--------------
All gateway messages sent from AppleTalk Mail are being returned to
the sender as "Undeliverable Mail"
Possible cause: Mail Connection is configured to accept
messages only from users who have gateway accounts.
The network manager can configure the Mail Connection to accept
gateway messages only from specific users whose names have been
added to a gateway access account list. To add users to the
gateway account list, choose Gateway from the Mail menu, then
choose Accounts. If a non-gateway user tries to send a message
through the Mail Connection, the message will be returned as
"undeliverable mail." The Mail Connection is initially
configured (by default) to accept gateway messages from any
AppleTalk Mail user.
Only some of the PC Mail names appear in the AppleTalk Mail address
list.
Possible cause: The AppleTalk Mail server has insufficient
memory allocated to hold the entire PC Mail address list.
The network manager must increase the Server Memory Allocation
in the Server Setting Configuration screen and restart the
AppleTalk Mail server. Import the PC Mail address list again
with the Connection Name Utility.
All messages received from PC Mail users are prefixed by the
following error message:
This message was sent using a custom form that is not installed
on your server. Some information from the original message may
not be displayed. To view the complete message, ask your Network
Manager to install the form on your server.
Possible cause: The 80 Column message form is not installed on
the AppleTalk Mail server.
All messages received from PC Mail are delivered using the 80
Column message form. Use the Forms Installer HyperCard stack to
add the 80 Column form to your AppleTalk Mail server.
NOTE: This error message will always prefix directory exchange
messages that are sent to the network manager. If the
Connection Name Utility is running, these messages will be
intercepted from the network manager's mailbox.
PC MAIL
-------
PC Mail users are unable to see the AppleTalk Mail address list.
Possible cause: The PC Mail users do not have "External"
privileges.
The PC Mail administrator must grant External privileges to
users who are authorized to send messages through the Mail
Connection Gateway.
Messages that are sent from the PC Mail 3.0 Windows client and
contain a file attachment are returned to the sender with the
message "Error processing message - WINMAIL.DAT".
Possible cause: An older version of the Mail Connection gateway
is loaded on the AppleTalk Mail server.
Upgrade your Mail Connection gateway to version 1.0b. Use the
Update Gateway option of the Gateway Installer application to
install the updated Macintosh component of the Mail Connection.TO OBTAIN THIS APPLICATION NOTE
You can find WA0728.EXE, a self-extracting file, on the following
services:
- Microsoft's World Wide Web Site on the Internet
On the www.microsoft.com home page, click the Support icon.
Click Knowledge Base, and select the product.
Enter kbfile WA0728.EXE, and click GO!
Open the article, and click the button to download the file.
- Internet (anonymous FTP)
ftp ftp.microsoft.com
Change to the Softlib/Mslfiles folder.
Get WA0728.EXE
- The Microsoft Network
On the Edit menu, click Go To, and then click Other Location.
Type mssupport.
Double-click the MS Software Library icon.
Find the appropriate product area.
Locate and Download WA0728.EXE.
For additional information about downloading, please see the following
article in the Microsoft Knowledge Base:119591
How to Obtain Microsoft Support Files from Online Services
- If you are unable to access the source(s) listed above, you can have
this Application Note mailed to you by calling Microsoft
Product Support Services Monday through Friday, 6:00 A.M. to 6:00 P.M.
Pacific time at (800) 936-4400. If you are outside the United States,
contact the Microsoft subsidiary for your area. To locate your
subsidiary, call the Microsoft International Sales Information Center at
(206) 936-8661.