How to write a MHS Modem Definition File
                  Messaging Division, Novell, Inc.
                           June 23, 1993

  This document is intended to provide documentation on how to write
a Modem Definition File (MDF) for the MHS 2.x products, which includes
NetWare Global MHS (GMHS). The intended audience is anyone who needs to use a modem with these products and no MDF is available for that modem.

Novell, Inc. makes no representations or warranties with respect
to the contents or use of this manual, and specifically disclaims
any express or implied warranties of merchantability or fitness for
any particular purpose. Further, Novell, Inc. reserves the right
to revise this manual and to make changes to its content, at any
time, without obligation to notify any person or entity of such
revisions or changes.

Further, Novell, Inc. makes no representations or warranties with
respect to any NetWare software, and specifically disclaims any
express or implied warranties of merchantability or fitness for any
particular purpose. Further, Novell, Inc. reserves the right to
make changes to any and all parts of NetWare software, at any time,
without any obligation to notify any person or entity of such
changes.

Trademarks

Novell, NetWare and the N design are registered trademarks and
Global MHS, NetWare Global MHS, NetWare MHS, NetWare Remote MHS,
and Remote MHS are trademarks of Novell, Inc.

Hayes is a registered trademark of Hayes Microcomputer Products,
Inc.

Copyright (c) 1993 Novell, Inc. All rights reserved. No part of
this publication may be reproduced, photocopied, stored on a
retrieval system, or transmitted without the express written
consent of the publisher.


1.0 Introduction

  The Message Handling System (MHS) is a set of products that pickup
and deliver messages for users or applications or other messaging
services. These MHS products can define MHS hosts and MHS users
which can communicate with each other over phone lines, using
asynchronous serial ports and modems.

  MHS uses asynchronous, RS-232C serial ports to connect to modems.
GMHS uses the Asynchronous Input/Output (AIO) NLMs to control the
serial ports; RMHS uses an internal serial driver. AIO serial ports
can be COMx type ports or on intelligent multi-port serial adaptors;
RMHS serial ports can be only COMx type ports. MHS uses an internal
modem driver to control modems.

  MHS must configure, reset, initialize, dial, answer, connect, and
hangup modems, both in dial up and leased line environments. Since
there are many manufacturers and models of modems, with different
features and command sets, MHS needs a mechanism for interfacing with
each type of modem. This mechanism is the MDF and it works with the
internal MHS modem driver to control each type of modem. Refer to
section 2 for details on the MDF format and section 3 for details on
MDF usage.

  Although each MHS product supplies a variety of MDFs for a variety
of modem types, not all modem types can be defined by these supplied
MDFs. Additional MDFs will have to be created by third parties, using
this document and any ASCII-capable editor. Refer to appendix A for
general guidelines on creating a MDF, appendices B-D for examples of
MDFs, and appendices E-F for debugging MDFs.


2.0 Format

  A MDF is an ASCII file that defines a modem type using keywords
and their values. A MDF keyword and its value is the definition of
how MHS will control a modem for a specific task. There are 60
pre-defined MDF keywords, some for defining modem capabilities,
some for defining modem commands, and others for defining modem
responses.

  A MDF keyword is a pre-defined ASCII string, with or without
spaces, that begins each line in a MDF. An equal sign separates the
MDF keyword from its value. A value can be a single character, word,
number or it can be multiple characters, words, numbers or it can be
nothing. Some characters, words, and numbers are pre-defined. A value
is ended by carriage return, line feed(s).

  For single character or string values, ASCII control characters can
be represented by special two character sequences. These sequences
always begin with the ^ character, following the commonly used
representation for ASCII control characters. For example, ^J is the
representation for line feed and ^M is the representation for
carriage return.

  There is no restriction on the order of MDF keywords in a MDF file.
If the MDF keyword is irrelevant for defining how to control this
modem type, the MDF keyword can be left out of the MDF. If the MDF
keyword's default value already defines how to control this modem
type, the MDF keyword can be left out of the MDF. MDF keywords, and
pre-defined value strings, are treated as case insensitive. A
semicolon as the first character of a line indicates that this line
is a comment line and will be ignored.

2.1. MDF DESCRIPTION

  This keyword is used to describe the modem(s) supported by this
modem definition. The description is limited to 60 characters and
there is no default description. Currently, the description is not
used or displayed but should be included for documentation purposes.

2.2. MDF TYPE

  This keyword is used to designate Hayes type command and response
processing, i.e., send an ASCII command string and wait for a
pre-defined ASCII response string. The default value is HAYES. This
keyword is used to validate a MDF as compatible with an MHS product.
If an incompatible type is found, MHS reports an error and will not
use this MDF. Currently, the only compatible value is HAYES.

   Although MHS will use the default value if this keyword is not
found in the MDF, this keyword should be included in each MDF as
insurance against inappropriate behaviour by future versions of MHS
products.


2.3. MDF VERSION

  This keyword is used to assign a version to a MDF. Its value can
be from 1 to 65,535. The default value is currently 2. This keyword
is used to validate a MDF as compatible with an MHS product. If
an incompatible version is found, MHS reports an error and will not
use this MDF. The compatible values for current MHS products are 1
and 2; 1 was a beta version value that is no longer used.

   Although MHS will use the default value if this keyword is not
found in the MDF, this keyword should be included in each MDF as
insurance against inappropriate behaviour by future versions of MHS
products.

2.4. FLOW CONTROL

  This keyword is used to designate that this modem supports (or does
not support) the standard RTS/CTS hardware signalling for flow control
with this modem. Its value can be TRUE (support) or FALSE (not
support). The default value is FALSE.

  During modem protocol connections (see below), data transfers can
be temporarily disabled, by toggling CTS or RTS, to avoid data loss
when buffers become full due to resending of corrupted data or
expansion of compressed data. MHS enables flow control after receiving
a modem CONNECTion response (see below) and before initiating a modem
hangup (see below). MHS disables flow control while sending modem
commands and receiving modem responses.

2.5. MODEM SPEEDS

  This keyword is used to specify the modem speeds that can be used
with this modem. It is used during configuration of a MHS product
to check for errors, e.g., a 2400 bps modem should not be configured
for 9600 bps. Each speed must be separated by a comma. The default
is 300, 1200, 2400, 9600.

  There is no restriction on the order of speeds. If an unsupported
speed is found, MHS reports an error, stops processing the speed
values, but retains the already processed speeds. The supported
speeds are 300, 1200, 2400, 9600, and 14400.

2.6. MAX SPEED

  This keyword is used to specify the maximum serial port speed
that will be attempted when communicating to this modem. Its value
can be any serial speed, from 50 to 115200. It is also used during
configuration of a MHS product to check for errors, e.g., older 2400
bps modems may not support speeds higher than 2400. The default value
is 2400.

  If no serial speed is specified during configuration, MHS will
use either this value or the highest serial speed supported by the
driver/hardware attached to this modem, whichever is smaller. For
modem protocol connections (see below), it is important to have the
serial speed greater than the modem speed, for better throughput.


2.7. ADJUST SPEED

  This keyword is used to designate that this modem supports (or
does not support) the adjustment of the serial speed after the modem
CONNECTion response. Its value can be TRUE (support) or FALSE (not
support). The default value is TRUE.

  However, if the PROTOCOL ON keyword is specified and used, this
keyword is ignored because the serial speed is assumed to be fixed,
i.e., the serial speed should not be changed after the modem
CONNECTion response.

2.8. COMMAND BEGIN

  This keyword is used to specify the beginning of command strings
that are sent to this modem. Its value can be any sequence of ASCII
characters, including control characters, with a total length not
exceeding 10 characters. The default value is AT.

2.9. COMMAND END

  This keyword is used to specify the end of command strings that
are sent to this modem. Its value can be any sequence of ASCII
characters, including control characters, with a total length not
exceeding 2 characters. The default value is ^M, i.e., carriage
return.

2.10. MAX COMMAND

  This keyword is used to specify the length of the maximum command
string that can be sent to this modem. This length does not include
the COMMAND BEGIN and the COMMAND END strings. Its value can be from
1 to 255. The default value is 40.

2.11. RESET

  This keyword is used to specify the command string, not including
COMMAND BEGIN and COMMAND END, that will be sent to this modem to
reset it. This command is sent prior to initialization and after
hangup. Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 40 characters.
The default value is Z.

2.12. RESET TIME

  This keyword is used to specify the amount of time, in seconds, to
wait for a modem response after sending a RESET command. Its value
can be from 3 to 30 seconds. The default value is 4 seconds.


2.13. INIT (first)

  This keyword is used to specify the command string, not including
COMMAND BEGIN and COMMAND END, that will be sent to this modem to
initialize it. No valid modem response is required. This command is
sent after the RESET command. Its value can be any sequence of ASCII
characters, including control characters, with a total length not
exceeding 40 characters. The default value is
EQV1X4S0=0S2=43S3=13S4=10S7=254S12=50.

2.14. INIT (second)

  This keyword is used to specify the command string, not including
COMMAND BEGIN and COMMAND END, that will be sent to this modem to
continue initializing it. A valid modem response is required. This
command is sent after the first INIT command. Its value can be any
sequence of ASCII characters, including control characters, with a
total length not exceeding 40 characters. There is no default value.

  If this modem does not require the serial speed to be adjusted
after a modem CONNECTion response, i.e., ADJUST SPEED is FALSE, then
the commands to maintain a fixed serial speed should be specified
in the second or third INIT strings. For modem protocol connections
(see below) and for mismatched speeds between modems, it is important
to have the serial speed greater than the modem speed, for better
throughput.

2.15. INIT (third)

  This keyword is used to specify the command string, not including
COMMAND BEGIN and COMMAND END, that will be sent to this modem to
continue initializing it. A valid modem response is required. This
command is sent after the second INIT command. Its value can be any
sequence of ASCII characters, including control characters, with a
total length not exceeding 40 characters. There is no default value.

2.16. SPEAKER ON

  This keyword is used to specify the command string, not including
COMMAND BEGIN and COMMAND END, that will be sent to this modem to
turn the modem speaker on. No valid modem response is required. This
command is sent after the last INIT command. Its value can be any
sequence of ASCII characters, including control characters, with a
total length not exceeding 40 characters. The default value is M1.

2.17. SPEAKER OFF

  This keyword is used to specify the command string, not including
COMMAND BEGIN and COMMAND END, that will be sent to this modem to
turn the modem speaker off. No valid modem response is required. This
command is sent after the last INIT command. Its value can be any
sequence of ASCII characters, including control characters, with a
total length not exceeding 40 characters. The default value is M.


2.18. PROTOCOL ON

  This keyword is used to specify the command string, not including
COMMAND BEGIN and COMMAND END, that will be sent to this modem to
attempt a modem protocol (error-control and data compression)
connection. Modem protocol connections are only attempted if specified
by the MHS configuration. The remote modem will also have to attempt a
modem protocol connection for this modem to actually establish a modem
protocol connection. No valid modem response is required.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 40 characters.
There is no default value because not all modems support this type of
functionality.

2.19. PROTOCOL OFF

  This keyword is used to specify the command string, not including
COMMAND BEGIN and COMMAND END, that will be sent to this modem to
not attempt a modem protocol (error-control and data compression)
connection. No valid modem response is required.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 40 characters.
There is no default value because not all modems support this type
of functionality.

2.20. LEASED DIAL

  This keyword is used to specify the command string, not including
COMMAND BEGIN and COMMAND END, that will be sent to this modem to
select leased line, dial operation. The remote modem will have to
select leased line, answer operation for this modem to go on-line.
Leased line operation is only selected if specified by the MHS
configuration. A valid modem response is required, eventually.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 40 characters.
There is no default value because not all modems support this type
of functionality. If this keyword is specified, the LEASED ANSWER
keyword must also be specified.

2.21. LEASED ANSWER

  This keyword is used to specify the command string, not including
COMMAND BEGIN and COMMAND END, that will be sent to this modem to
select leased line, answer operation. The remote modem will have to
select leased line, dial operation for this modem to go on-line.
Leased line operation is only selected if specified by the MHS
configuration. A valid modem response is required, eventually.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 40 characters.
There is no default value because not all modems support this type
of functionality. If this keyword is specified, the LEASED DIAL
keyword must also be specified.


2.22. LEASED EXTERNAL

  This keyword is used to designate that this modem does not require
any modem commands to be sent to it to select leased line operation,
i.e., this is done externally, usually with physical switches. Its
value can be TRUE (external, don't send modem commands) or FALSE (not
external, send modem commands). The default is FALSE.

  The LEASED DIAL and LEASED ANSWER keywords should still be
specified, but with no values, to indicate that this modem supports
leased line operation.

2.23. LEASED RESPONSE

  This keyword is used to designate that this modem does not return
any command responses when leased line operation is selected or when
the modems have successfully made a leased line connection. Instead,
a successful leased line connection is indicated by an active DCD
signal. Its value can be TRUE (response expected) or FALSE (no
response). The default is TRUE.

  The LEASED DIAL and LEASED ANSWER keywords should still be
specified, but with no values, to indicate that this modem supports
leased line operation.

2.24. DIAL TONE

  This keyword is used to specify the command string, not including
COMMAND BEGIN and COMMAND END, that will be sent to this modem to
tone dial a telephone number. The telephone number is specified by
the MHS configuration. Valid modem response(s) are required, ending
with one of the CONNECT responses (see below).

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 40 characters.
The default value is DT.

2.25. DIAL PULSE

  This keyword is used to specify the command string, not including
the COMMAND BEGIN and COMMAND END, that will be sent to this modem to
pulse dial a telephone number. The telephone number is specified by
the MHS configuration. Valid modem response(s) are required, ending
with one of the CONNECT responses (see below).

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 40 characters.
The default value is DP.


2.26. DIAL ESCAPE

  This keyword is used to specify the character that will be added to
the end of a DIAL TONE/PULSE command when breaking up a phone number
that exceeds the MAX COMMAND length. It is placed at the end of a
DIAL TONE/PULSE command string, just before the COMMAND END, to
instruct this modem to return to the command state immediately after
dialing, without breaking the connection. This allows for another
command string to follow, with the remaining phone number.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 40 characters.
The default value is a semicolon.

2.27. DIAL 300

  This keyword is used to specify the command string, not including
COMMAND BEGIN and COMMAND END, that will be sent to this modem to
attempt to initiate a connection at 300 bps. A valid modem response
is required. This command is sent before the DIAL TONE/PULSE
commands.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 40 characters.
There is no default value because not all modems support this type of
functionality.

2.28. DIAL 1200

  This keyword is used to specify the command string, not including
COMMAND BEGIN and COMMAND END, that will be sent to this modem to
attempt to initiate a connection at 1200 bps. A valid modem response
is required. This command is sent before the DIAL TONE/PULSE
commands.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 40 characters.
There is no default value because not all modems support this type
of functionality.

2.29. DIAL 2400

  This keyword is used to specify the command string, not including
COMMAND BEGIN and COMMAND END, that will be sent to this modem to
attempt to initiate a connection at 2400 bps. A valid modem response
is required. This command is sent before the DIAL TONE/PULSE
commands.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 40 characters.
There is no default value because not all modems support this type
of functionality.


2.30. DIAL 9600

  This keyword is used to specify the command string, not including
COMMAND BEGIN and COMMAND END, that will be sent to this modem to
attempt to initiate a connection at 9600 bps. A valid modem response
is required. This command is sent before the DIAL TONE/PULSE
commands.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 40 characters.
There is no default value because not all modems support this type
of functionality.

2.31. DIAL 14400

  This keyword is used to specify the command string, not including
COMMAND BEGIN and COMMAND END, that will be sent to this modem to
attempt to initiate a connection at 14400 bps. A valid modem response
is required. This command is sent before the DIAL TONE/PULSE
commands.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 40 characters.
There is no default value because not all modems support this type
of functionality.

2.32. ANSWER

  This keyword is used to specify the command string, not including
COMMAND BEGIN and COMMAND END, that will be sent to this modem to
answer a telephone call. Valid modem response(s) are required, ending
with one of the CONNECT responses (see below). This command is sent
after receiving a RING response.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 40 characters.
The default value is A.

2.33. ESCAPE

  This keyword is used to specify the command string, not including
COMMAND BEGIN and COMMAND END, that will be sent to this modem to
return it to the command state. A valid modem response is not
required. This command is sent before the HANGUP command.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 40 characters.
The default value is +++.

2.34. ESCAPE TIME

  This keyword is used to specify the amount of time, in seconds, to
wait before and after sending the ESCAPE command. Its value can be
from 1 to 30 seconds. The default value is 1 second.


2.35. HANGUP

  This keyword is used to specify the command string, not including
COMMAND BEGIN and COMMAND END, that will be sent to this modem to
hangup a telephone call. A valid modem response is not required. This
command is sent after the ESCAPE command.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 40 characters.
The default value is H.

2.36. HANGUP TIME

  This keyword is used to specify the amount of time, in seconds, to
wait for a modem response after sending a HANGUP command. Its value
can be from 2 to 30 seconds. The default value is 10 seconds.

2.37. DTR TIME

  This keyword is used to specify the amount of time, in seconds,
to drop the DTR signal after sending the HANGUP command. Dropping the
DTR signal, for the correct amount of time, is an attempt to add more
reliability to modem hangup. Its value can be from 1 to 3 seconds.
The default value is 2 second.

2.38. VERBAL RESPONSE

  This keyword is used to designate that this modem will return
command responses that are verbal versus numeric. Its value can be
TRUE (verbal) or FALSE (numeric). The default value is TRUE.

2.39. RESPONSE BEGIN

  This keyword is used to specify the beginning of command responses
that are received from this modem. Its value can be any sequence of
ASCII characters, including control characters, with a total length
not exceeding 2 characters. The default value is ^M^J, i.e., carriage
return and line feed.

2.40. RESPONSE END

  This keyword is used to specify the end of command responses that
are received from this modem. Its value can be any sequence of ASCII
characters, including control characters, with a total length not
exceeding 2 characters. The default value is ^M^J, i.e., carriage
return and line feed.

2.41. RESPONSE TIME

  This keyword is used to specify the amount of time, in seconds, to
wait for a modem response after sending a command string. This is the
default response time for commands that do not have pre-defined
response time keywords. Its value can be from 2 to 30 seconds. The
default value is 3 seconds.


2.42. OK

  This keyword is used to specify the command response that indicates
that a command or command string was executed by this modem. This
response will be the result of a successful RESET, INIT, PROTOCOL
ON/OFF, DIAL ESCAPE, DIAL 300/1200/2400/9600/14400, or ESCAPE
commands.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 25 characters.
The default value is OK.

2.43. RING

  This keyword is used to specify the command response that indicates
that this modem has detected a ring signal. It will only be used
after completing reset and all initializations, for non-leased line
operations, when MHS is monitoring for incoming calls.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 25 characters.
The default value is RING.

2.44. RINGING

  This keyword is also used to specify the command response that
indicates that this modem has detected a ring signal. However, unlike
the RING command response above, this command response is ignored.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 25 characters.
The default value is RINGING.

2.45. NO CARRIER

  This keyword is used to specify the command response that indicates
that no carrier signal was detected by this modem, or that the
carrier signal was lost. This response could be the result of an
unsuccessful DIAL TONE/PULSE, ANSWER, or LEASED DIAL/ANSWER command
or a successful HANGUP command.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 25 characters.
The default value is NO CARRIER.

2.46. ERROR

  This keyword is used to specify the command response that indicates
that this modem has received an invalid command or there was an error
in the command string. This response is not expected by MHS, which if
received when a modem response is required, will abort the connection.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 25 characters.
The default value is ERROR.


2.47. NO DIALTONE

  This keyword is used to specify the command response that indicates
that no dial tone was detected when this modem went off hook. This
response could be the result of an unsuccessful DIAL TONE/PULSE or
ANSWER command.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 25 characters.
The default value is NO DIALTONE.

2.48. BUSY

  This keyword is used to specify the command response that indicates
that this modem detected a busy signal when it attempted to connect
with the remote modem at the telephone number dialed. This response
could be the result of an unsuccessful DIAL TONE/PULSE command.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 25 characters.
The default value is BUSY.

2.49. NO ANSWER

  This keyword is used to specify the command response that indicates
that no silence was detected by this modem when dialing a system not
providing a dial tone. This response is the result of including the
@ dial modifier in the telephone number of an unsuccessful DIAL
TONE/PULSE command.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 25 characters.
The default value is NO ANSWER.

2.50. VOICE

  This keyword is used to specify the command response that indicates
that this modem detected a (human) voice when it attempted to connect
with the remote modem at the telephone number dialed. This response
could be the result of an unsuccessful DIAL TONE/PULSE command.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 25 characters.
The default value is VOICE.


2.51. CARRIER

  This keyword is used to specify the command response that indicates
that this modem detected a carrier signal when it attempted to make
a modem protocol connection. This response is the result of sending a
DIAL TONE/PULSE, ANSWER, or LEASED DIAL/ANSWER command. Although this
response is currently only used for informational purposes, its
detection and reporting allows for debugging improper MHS
configurations and incorrect MDF command strings.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 25 characters.
The default value is CARRIER.

2.52. PROTOCOL A

  This keyword is used to specify the command response that indicates
that this modem successfully negotiated a modem protocol connection.
This response is the result of sending a DIAL TONE/PULSE, ANSWER, or
LEASED DIAL/ANSWER command. Although this response is currently only
used for informational purposes, its detection and reporting allows
for debugging improper MHS configurations and incorrect MDF command
strings.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 25 characters.
The default value is PROTOCOL: LAP-M.

2.53. PROTOCOL B

  This keyword is used to specify the command response that indicates
that this modem successfully negotiated a modem protocol connection.
This response is the result of sending a DIAL TONE/PULSE, ANSWER, or
LEASED DIAL/ANSWER command. Although this response is currently only
used for informational purposes, its detection and reporting allows
for debugging improper MHS configurations and incorrect MDF command
strings.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 25 characters.
The default value is /ARQ.

2.54. COMPRESSION

  This keyword is used to specify the command response that indicates
that this modem successfully negotiated a modem data compression
connection. This response is the result of sending a DIAL TONE/PULSE,
ANSWER, or LEASED DIAL/ANSWER command. Although this response is
currently only used for informational purposes, its detection and
reporting allows for debugging improper MHS configurations and
incorrect MDF command strings.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 25 characters.
The default value is COMPRESSION.


2.55. CONNECT

  This keyword is used to specify the command response that
indicates that this modem successfully completed a connection with
a remote modem. This response is the result of sending a DIAL
TONE/PULSE, ANSWER, or LEASED DIAL/ANSWER command. It is used
in conjunction with the CONNECT 300/1200/2400/9600/14400 responses
(see below) to determine the modem connection speed.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 25 characters.
The default value is CONNECT.

2.56. CONNECT 300

  This keyword is used to specify the command response that indicates
that this modem successfully completed a 300 bps connection with a
remote modem. It is used in conjunction with the CONNECT response to
indicate that a 300 bps serial speed is required if no modem protocol
connection was attempted and ADJUST SPEED is TRUE.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 25 characters.
The default value is nothing, i.e., no characters.

2.57. CONNECT 1200

  This keyword is used to specify the command response that indicates
that this modem successfully completed a 1200 bps connection with a
remote modem. It is used in conjunction with the CONNECT response
to indicate that a 1200 bps serial speed is required if no modem
protocol connection was attempted and ADJUST SPEED is TRUE.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 25 characters.
The default value is 1200.

2.58. CONNECT 2400

  This keyword is used to specify the command response that indicates
that this modem successfully completed a 2400 bps connection with a
remote modem. It is used in conjunction with the CONNECT response
to indicate that a 2400 bps serial speed is required if no modem
protocol connection was attempted and ADJUST SPEED is TRUE.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 25 characters.
The default value is 2400.


2.59. CONNECT 9600

  This keyword is used to specify the command response that indicates
that this modem successfully completed a 9600 bps connection with a
remote modem. It is used in conjunction with the CONNECT response
to indicate that a 9600 bps serial speed is required if no modem
protocol connection was attempted and ADJUST SPEED is TRUE.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 25 characters.
The default value is 9600.

2.60. CONNECT 14400

  This keyword is used to specify the command response that indicates
that this modem successfully completed a 14400 bps connection with a
remote modem. It is used in conjunction with the CONNECT response
to indicate that a 14400 bps serial speed is required if no modem
protocol connection was attempted and ADJUST SPEED is TRUE.

  Its value can be any sequence of ASCII characters, including
control characters, with a total length not exceeding 25 characters.
The default value is 14400.


3.0 Usage

  MDFs are used by the MHS products when they are referenced as the
Modem Type in the MHS configuration. MHS uses the MDF to configure,
reset, initialize, dial, answer, connect, and hangup modems, both in
dial up and leased line environments. In the case of GMHS, MDFs can
be referenced by more than one serial port.

  The information in a MDF is used in various stages of MHS execution
and for different MHS configurations. These stages can be divided
into MDF initialization, MDF verification, serial port initialization,
modem initialization, modem dialing, modem answering, modem
connection, leased line connection, and modem hangup. GMHS also uses
MDFs slightly differently from RMHS. The following sections will
present these stages and these differences.

3.1 MDF Initialization

  When the MDF is first referenced, it is processed, i.e., the MDF is
is opened, memory is allocated and initialized with the default MDF
keyword values, MDF keywords are read and their values are checked and
extracted, and then the MDF is closed. If an error occurs due to an
invalid MDF keyword and/or value, an error may be logged and displayed
and the MDF keyword and/or value will be ignored.

3.2 MDF Verification

  MDFs can be used for validation of modem configuration. GMHS
validates the following information using the MDF:

  o Is the Modem Speed valid for this modem, i.e., is it in the list
    of MODEM SPEEDS? If this MDF keyword is not specified, only speeds
    of 300, 1200, 2400, and 9600 are allowed.

  o If configured for Yes, is Modem Negotiation valid for this modem,
    i.e., are PROTOCOL ON and PROTOCOL OFF specified?

  o If configured for Yes, is Leased Line valid for this modem, i.e.,
    are LEASED DIAL and LEASED ANSWER specified?

  o If Optional Modem Commands are specified, do they exceed the
    MAX COMMAND length?

  RMHS does little to verify modem configurations; the only check is
to verify that the configured speed does not exceed the MAX SPEED
specified by the MDF. This condition is made unlikely by the RSETUP
program, which only allows users to pick from a list of valid speeds.


3.3 Serial Port Initialization

  Both GMHS and RMHS initializes a serial port for 8 data bits, 1
stop bit, no parity, the configured speed, and with RTS/CTS flow
control disabled. The RTS and DTR signals are also raised. After a
modem connection (see below), both GMHS and RMHS monitor for an
active DCD signal from a modem, and if FLOW CONTROL is TRUE, also
the CTS signal.

  The maximum data rate supported varies, depending on the type of
serial port (COMx or intelligient multi-port serial adaptors), type
of CPU, clock speed, etc. GMHS, which uses AIO, generally is limited
to 2400 bps for COMx ports and 38.4K bps for serial adaptors. RMHS
is limited to 115K bps.

3.4 Modem Initialization

  The modem is only initialized and used when a connection to another
MHS host is required. In the case of GMHS, if a modem is configured
for a Modem Mode of Answer or Answer/Dial, the modem will be
initialized and monitored immediately for incoming calls. Otherwise,
modem initialization is done before modem dialing (see below).

  First, a check is made for a previous off-hook, active connection
which may need to be hung up. Active connections are recognized by an
active DCD signal, which causes modem hangup to be initiated (see
below). Second, if Modem Negotiation is configured for Yes or ADJUST
SPEED is FALSE, the serial speed will be changed to either the MAX
SPEED or the maximum speed of the serial port, whichever is smaller.

  Third, the RESET command is sent, waiting up to RESET TIME + 1
seconds for a response. If there is no response, the speed will be
changed to 1200 bps and the RESET command resent. A valid response is
not required to continue initialization. Fourth, the first INIT
command is sent, waiting up to RESPONSE TIME seconds for a response.
If there are no or error responses, this command is resent; a valid
response is not required.

  At this point, the modem should be initialized properly and should
respond properly. If there are second and third INIT commands, they
are sent one at a time, waiting up to RESPONSE TIME seconds for each
response. If there are no or error responses, these commands are
resent. If there are still no or error responses, this modem will not
be used for a configured delay and an error may be logged and
displayed.

  If there are valid responses, initialization continues with the
speaker and protocol commands. If Modem Speaker is configured for On,
the SPEAKER ON command is sent; otherwise, the SPEAKER OFF command is
sent. If Modem Negotiation is configured for Yes, the PROTOCOL ON
command is then sent; otherwise, the PROTOCOL OFF command is then
sent. There is a wait of RESPONSE TIME seconds for responses. If
there are no or error responses, these commands are resent; valid
responses for speaker and protocol commands are not required.


3.5 Modem Dialing

  When an outgoing call is requested, the following steps are
followed. In the case of GMHS, if the modem was being monitored for
incoming calls and the configuration of Modem Negotiation is
different, either the PROTOCOL ON or PROTOCOL OFF command are sent.
GMHS waits up to RESPONSE TIME seconds for responses. If there are no
or error responses, GMHS resends these commands; a valid response is
not required.

  If ADJUST SPEED is TRUE, GMHS will then change the serial speed to
the configured or maximum speed of the serial port, whichever is
smaller. If ADJUST SPEED is FALSE, GMHS will then send the DIAL
command that corresponds to the configured or maximum speed of the
serial port, whichever is smaller.

  In the case of RMHS, it will change the serial speed to the
configured or maximum speed of the serial port, whichever is smaller.
Both GMHS and RMHS will then send any Optional Modem Commands that
have been configured, waiting up to RESPONSE TIME seconds for a
response. If there are no or error responses, these commands are
resent; a valid response is not required.

  Finally, the configured prefix and telephone number strings are
combined with either the DIAL TONE or DIAL PULSE dial command,
depending on the configuration. Both GMHS and RMHS will send this
combined dial command string, waiting up to the configured time for
a modem connection (see below). If the MAX COMMAND length is reached,
the DIAL ESCAPE character is used to break up a prefix + telephone
number string into multiple dial command strings, which are sent one
after another, waiting for valid responses in between dial commands.

  RMHS also supports a configured calling card string, which is added
after the prefix and telephone number strings, before sending the dial
command. RMHS also supports two types of manual dialing, keyboard and
telephone.

  For keyboard manual dialing, RMHS reads digits from the keyboard,
sending them to the modem as separate dial commands, each command
followed by the DIAL ESCAPE character. The user completes keyboard
manual dialing by hitting the carriage return key, which sends a dial
command with no number and no DIAL ESCAPE character. For telephone
manual dialing, RMHS waits for the user to manually dial the
telephone number using the telephone keypad and then hit the carriage
return key, before sending a dial command with no number and no
DIAL ESCAPE character.


3.6 Modem Answering

  GMHS supports incoming calls and therefore, must answer modems;
RMHS does not support incoming calls. If a modem is configured for
a Modem Mode of Answer or Answer/Dial, GMHS will continually monitor
the modem for incoming calls, i.e., it will poll the modem for the
RING response. When a RING response has been received, GMHS sends
the ANSWER command, waiting up to 60 seconds for a modem connection
(see below).

  If an unknown or error response is received, the serial port and
modem will be reset and re-initialized and if successful, GMHS will
again start polling for the RING response.

3.7 Modem Connection

  After modem dial, modem answer, or leased line commands are sent,
both GMHS and RMHS poll for a CONNECT response. Some modems will
return informational responses before the CONNECT response, i.e.,
RINGING, CARRIER, COMPRESSION, and PROTOCOL A/B. Some modems will
also return these informational responses as part of the CONNECT
response. All these cases are handled.

  In case of errors, modems will also return responses like ERROR,
NO CARRIER, NO DIALTONE, BUSY, NO ANSWER, and VOICE. All these cases
are handled. After receiving the CONNECT response, if ADJUST SPEED
is TRUE and the current serial speed does not match the CONNECT speed,
the serial speed will be changed to the CONNECT speed.

  After modem connection, if FLOW CONTROL is TRUE, the RTS/CTS flow
flow control is enabled. Both GMHS and RMHS also start monitoring for
an inactive DCD to indicate lost carrier/connection. If DCD is
inactive, modem hangup will be initiated (see below).

3.8 Leased Line Connection

  GMHS supports leased lines and therefore, must initialize and
monitor modems for leased line connections; RMHS does not support
leased lines. If Leased Line is Yes, GMHS sends either the LEASED
ANSWER or the LEASED DIAL command at the end of modem initialization,
depending on if Modem Mode is Answer or Dial respectively. GMHS thens
polls for a modem connection (see above) indefinitely.

  There are two special cases for leased line modems. If LEASED
EXTERNAL is TRUE, GMHS does not send the LEASED ANSWER or LEASED DIAL
commands; this modem was setup externally for leased line operation,
usually with physical switches. If LEASED RESPONSE is FALSE, GMHS does
not poll for modem connection responses; instead, the modem is polled
for an active DCD signal to indicate a modem connection.


3.9 Modem Hangup

  If FLOW CONTROL is TRUE, the RTS/CTS flow control mechanism is
disabled. Then, the COMMAND END characters are sent, finishing any
previous modem commands. To make certain the modem is in its command
state, a delay of ESCAPE TIME seconds is initiated, then the ESCAPE
command is sent, and then an additional delay of ESCAPE TIME seconds
plus a minimum of RESPONSE TIME seconds or a maximum of 30 seconds
for no responses is initiated.

  Finally, the HANGUP command is sent, waiting up to HANGUP TIME
seconds for a response. To ensure that hangup will occur, the DTR
signal is also dropped and after DTR TIME seconds, the DTR signal is
raised.


Appendix A. General Guidelines for Creating a MDF

  There are some general guidelines that should be followed when
creating a MDF:

  (1) Do not modify a released MDF; instead, create a separate MDF.

  (2) Assume that the modem is in an unknown state prior to its use.

  (3) Try not to use &F (recall factory profile) because you may
      override a feature not specified in the MDF.

  (4) Try not to use &W (write active profile to memory) because you
      may affect a previous/future modem configuration and the NVRAM
      memory has a limited number of writes before it is unusable.

  (5) Don't rely on the Z (RESET) command to recall a previously
      saved modem configuration since this may have been overwritten
      by a previous user/application.

  (6) Only use the pre-defined keywords that are relevant to this
      modem and whose default's are not sufficient for this modem.

  (7) Where appropriate, use comment lines thoughout the MDF.

  (8) Each MDF name is limited to the eight character maximum of
      DOS and the NetWare file systems. MDF names should be as
      descriptive as possible since current MHS products only
      display the MDF filename for selecting a Modem Type. Generally,
      the first part of the name should be an abbreviation for the
      manufacturer of the modem, e.g., "HAYES", and the second part
      the abbreviation of model number or maximum speed, e.g., "96".
      If the eight character maximum name has not been reached, a
      single character abbreviation should be added to denote a
      series or capability, e.g., "v" for V-series or "e" for
      error-control. The extension is always MDF.

  (9) The MDFs must reside in special subdirectories, which are
      different for each MHS product. GMHS requires the MDFs to be
      in the <NGM-root-dir>\ASYNC\MODEMDEF directory. RMHS requires
      the MDFs to be in the <MHS-root-dir>\MHS\SYS directory.


Appendix B. Example MDF for a Hayes Smartmodem 2400

MDF DESCRIPTION=Hayes Smartmodem 2400 and compatibles
MDF VERSION=2
MDF TYPE=HAYES
MODEM SPEEDS=300,1200,2400
MAX SPEED=2400
MAX COMMAND=40
INIT=EQV1X4S0=0S2=43S3=13S4=10S7=254S12=50
INIT=&C1&D3&L
LEASED DIAL=&L1D
LEASED ANSWER=&L1A

Appendix C. Example MDF for a Hayes V-series ULTRA Smartmodem 9600

MDF DESCRIPTION=Hayes V-series ULTRA Smartmodem 9600
MDF VERSION=2
MDF TYPE=HAYES
MODEM SPEEDS=300,1200,2400,9600
MAX SPEED=38400
MAX COMMAND=255
FLOW CONTROL=TRUE
ADJUST SPEED=FALSE
INIT=EQV1X4S0=0S2=43S3=13S4=10S7=254S12=50
INIT=N1W1&C1&D3&K3&L
INIT=S30=0S37=0S49=8S50=16S95=32
DIAL 300=S37=3
DIAL 1200=S37=5
DIAL 2400=S37=6
DIAL 9600=S37=9
LEASED DIAL=&L1D
LEASED ANSWER=&L1A
PROTOCOL ON=&Q5S36=7S38=20S46=2S48=7
PROTOCOL OFF=&Q6
PROTOCOL A=PROTOCOL: LAP-M
PROTOCOL B=PROTOCOL: ALT


Appendix D. Example MDF for a USRobotics Courier HST

MDF DESCRIPTION=USRobotics Courier HST, HST dual standard, and V.32bis
MDF VERSION=2
MDF TYPE=HAYES
MODEM SPEEDS=300,1200,2400,9600,14400
MAX SPEED=38400
MAX COMMAND=40
FLOW CONTROL=TRUE
ADJUST SPEED=FALSE
INIT=EQV1X6S0=0S2=43S3=13S4=10S7=255S12=50
INIT=BC1F1&A1&C1&D2&B1&H1&L&N0&R2S19=0
LEASED DIAL=
LEASED ANSWER=
LEASED EXTERNAL=TRUE
LEASED RESPONSE=TRUE
PROTOCOL ON=&K2&M4
PROTOCOL OFF=&M
PROTOCOL A=/ARQ
;
; For leased line operation, do the following steps:
; 1.  Set your terminal or communications software to 38.4K bps.
; 2.  Send the modem the following command: AT&B1&S2&H1&L1&W
; 3.  Set the modem to load NVRAM settings at power-on, DIP switch 10 UP.
; 4.  If this is the answering modem, set the modem to Auto Answer,
;     DIP switch 5 UP. If this is the calling modem, set the modem to
;     Auto Answer suppressed, DIP switch 5 DOWN.
; 5.  Power off the modem.
; 6.  On the NetWare server, select a 38.4K bps capable port and
;     attach it to the modem.
; 7.  Configure this port for leased line operation and for a USRHST.
; 8.  Repeat these or similiar steps for the remote modem.
; 9.  Turn on the calling modem first, followed by the answering modem.
; 10. The modems should then go off hook and establish the connection.
; 11. If unsuccessful, repeat step 9.


Appendix E. Debugging MDFs with NetWare Global MHS

  This section contains information to assist in debugging MDFs
using the GMHS product and its NGMAMP.NLM program, which can display
information on the screen as well as in log file(s) when modem
interactions take place. This information takes the form of events,
either connection, modem, port, or error events. Events are further
divided into major events, minor events, and error codes; the
important ones for debugging MDFs are listed below. The screen
display is enabled by loading the NGMAMP.NLM with the -S command
line option.

  The GMHS log files can be found in a <NGM-root-dir>\LOGS directory,
referenced by the day of the week. The size of an individual log file
is controlled by an option in the GMHS configuration file, which can
be found in a SYS:\SYSTEM\NGM.CFG file. This option, Maximum-Log-Size,
has a default of 200K and GMHS will start overwriting a log file when
this maximum has been reached.

  The NGMAMP log files are further referenced by the type of serial
ports used to interface to the configured modems. For example, the
events for the COM1 serial port can be found in the 01-00-00 file.
The number of events is generally influenced by the verbosity level,
which can be set using another option, Log-Verbosity, in a NGM.CFG
file or via the GMHS administration program NGMADMIN.NLM.

  The default setting for NGMAMP is verbosity level 6, which displays
connection and error events. A verbosity level of 9 displays these
events as well as (serial) port and modem events. When debugging
modem (and MDF) problems, set the verbosity level to 9.

1) Connection Events

  The major events are OutboundCall, PollingCall, and InboundCall.
There are many possible minor events but the important ones are
Opening, Dialing, ModemControl, LoggingIn, CallerID, LoggingOut,
HangingUp, and Closed. These events track the high level actions
that cause MHS to access serial ports and modems. Refer to the GMHS
Codes and Messages manual for details on these events.

2) Modem Events

  The major event is Modem. The minor events are Definition, Command,
Response, Reset, Initialize, Dial, Answer, Ring, Hangup, Connect,
Leased, and Speed. A period in a Response event string implies a 1
second period of time when no characters were received. These events
track the low level actions of MHS modem control. Refer to the GMHS
Codes and Messages manual for details on these events.


3) (Serial) Port Events

  The major event is Port. The minor events are PortNames, AcquirePort,
ReleasePort, ChangeSpeed, ChangePort, FlowControl, and SetDTR. These
events track the low level actions of MHS serial port control. Refer
to the GMHS Codes and Messages manual for details on these events.

4) Error Events

  The major events are SevereError, MajorError, Error, InternalErr,
Warning, and Advisory. The modem errors are identified with #326,
followed by the range #19000 to #19999. The port errors are identified
with #256, followed by the range #20000 to #20999. Refer to the GMHS
Codes and Messages manual for details on these errors.


Appendix F. Debugging MDFs with NetWare Remote MHS

  This section contains information to assist in debugging MDFs
using the RMHS product, which can display information on the screen
as well as in a log file when modem interactions take place. This
information takes the form of events, either status, informational,
warning, error, or trace. The number of events is generally
influenced by the verbosity level, which can be set using the -V
command line option.

  The default setting for RMHS is verbosity level 8, which displays
status, informational, warning, and error events. A verbosity level
of 9, the maximum, displays these events as well as trace events.
Status events are always displayed in the second line from the bottom
of a RMHS screen.

  The RMHS.LOG file can be found in a <MHS-root-dir>\MHS\MAIL\PUBLIC
directory.

1) Status Line Events

  The following is a list of these events and some comments as to
their meaning:

Waiting for modem connection ...
  Appears on the status line while RMHS is waiting for a CONNECT
  response from the modem.

Hanging up modem ...
  Appears on the status line while RMHS is sending HANGUP commands
  to the modem.

Dialing ...
  Appears on the status line while RMHS is sending DIAL commands to
  the modem.

Initializing modem ...
  Appears on the status line while RMHS is sending INIT commands to
  the modem.

Resetting modem ...
  Appears on the status line while RMHS is sending a RESET command to
  the modem.


2) Informational, Warning, and Error Events

  The following is a list of these events and some comments as to
their meaning:

E2550 Error in modem definition file.
  MDF file contains some syntactic error.

E2553 Timeout waiting for modem response.
  Modem failed to respond to a command with the expected OK response
  within the RESPONSE TIME seconds.

E2554 Unsupported modem speed (%lu bps).
  Modem speed set in user interface or modem speed parsed out of
  CONNECT response from modem does not fall within parameters set in
  the MDF file.

E2555 Modem is not responding.
  Modem repeatedly failed to respond to a command with the expected
  OK response.

E2556 Invalid modem response.
  Modem failed to respond to a command with the expected OK response;
  instead, modem responded with an unrecognizable string.

W2557 Modem indicates an error has occurred.
  Modem has responded to a command with the ERROR response instead of
  the expected OK response.

W2558 Adjusting modem speed to %lu bps.
  ADJUST SPEED is TRUE and the modem CONNECT response indicated a speed
  change was required.

W2559 Carrier still active, hangup failed.
  HANGUP command failed.

W2560 Speaker command failed.
  Modem failed to respond to a SPEAKER ON/OFF command with the
  expected OK response.

E2561 Protocol command failed.
  Modem failed to respond to a PROTOCOL ON/OFF command with the
  expected OK response.

E2563 Initialization command failed.
  Modem failed to respond to an INIT command with the expected OK
  response.

E2565 One or more modem commands failed.
  Modem failed to respond to some modem command with the expected OK
  response.


E2566 Could not change modem speed to %lu bps.
  ADJUST SPEED is TRUE and the modem CONNECT response indicated a speed
  change was required, but the speed change failed.

E2568 Out of memory in modem layer.
  When reading a MDF file into memory, RMHS ran out of heap space.

E2570 Modem dial failed.
  Modem failed to respond to a DIAL PULSE/TONE command with the
  expected CONNECT response.

W2574 Modem could not detect carrier.
  Modem detected a NO CARRIER response.

W2575 Modem could not detect dialtone.
  Modem detected a NO DIALTONE response.

W2576 Modem detected a busy signal.
  Modem detected a BUSY response.

W2577 Called server is not answering.
  Modem timed out waiting for CONNECT response and last response was
  RINGING response.

W2578 Modem detected human voice instead of carrier.
  Modem detected a VOICE response.

E2579 The modem attached to COM%d: is bad, does not exist, is
incorrectly configured, or is incorrectly cabled.
  Modem is not responding to commands.

I2581 High-speed connection established.
  Modem speed parsed out of CONNECT response from modem is above
  38.4K bps.

I2582 High-speed connection with protocol established.
  Modem speed parsed out of CONNECT response from modem is above
  38.4K bps and PROTOCOL A/B response detected.

I2583 Established %lu bps connection.
  CONNECT response detected at indicated speed.

I2584 Established %lu bps connection with protocol.
  CONNECT and PROTOCOL A/B responses detected at indicated speed.

E2585 Could not establish modem connection.
  Modem timed out waiting for CONNECT response.


3) Trace Events

  Trace events are the actual commands sent to a modem and the actual
responses received from a modem; these events are NOT placed in the
RMHS.LOG file. An example of these events are as follows (note that
trace events are mixed in with other non-trace events):

ATZ
OK
ATEQV1X4S0=0S2=43S3=13S4=10S7=254S12=50
OK
AT&C1&D3&L
OK
I2569 Dialing OUTBOUND at 2400 bps, tone dial, negotiation off.
ATDT123-4567
OK