NOVELL TECHNICAL INFORMATION DOCUMENT TITLE: GLBMDM.TXT MHS Modem Definition File DOCUMENT ID: TID200001 DOCUMENT REVISION: A DATE: 31AUG93 ALERT STATUS: Yellow INFORMATION TYPE: Issue README FOR: GLBMDM.TXT NOVELL PRODUCT and VERSION: NetWare Global MHS 2.0 ABSTRACT: This file describes how to write a Modem Definition File (MDF) for NetWare Global MHS (GMHS). The intended audience is anyone who needs to develop an MDF to a modem for which no MDF exists. _________________________________________________________________ DISCLAIMER THE ORIGIN OF THIS INFORMATION MAY BE INTERNAL OR EXTERNAL TO NOVELL. NOVELL MAKES EVERY EFFORT WITHIN ITS MEANS TO VERIFY THIS INFORMATION. HOWEVER, THE INFORMATION PROVIDED IN THIS DOCUMENT IS FOR YOUR INFORMATION ONLY. NOVELL MAKES NO EXPLICIT OR IMPLIED CLAIMS TO THE VALIDITY OF THIS INFORMATION. _________________________________________________________________ ISSUE 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. Global MHS (GMHS) is the flagship member of the MHS product family. Throughout this document, MHS will be used when referring to the MHS technology and product family in general, GMHS will refer to the specific implementation of Global MHS. MHS uses asynchronous, RS-232C serial ports to connect to modems. GMHS uses the Asynchronous Input/Output (AIO) NLMs to control the serial ports. AIO serial ports can be COMx type ports or on intelligent multi-port serial adapters. MHS uses an internal modem driver to control modems. MHS must configure, reset, initialize, dial, answer, connect, and hang-up 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. For GMHS, this mechanism is the MDF and it works with the internal GMHS modem driver to control each type of modem. The MDF file provides the GMHS modem driver with the specific parameters for particular modems so that the driver can perform these functions. Refer to section 2 for details on the MDF format and section 3 for details on MDF usage. Although the GMHS 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, GMHS will report an error and will not use this MDF. Currently, the only compatible value is HAYES. Although GMHS 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 behavior 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, GMHS will report 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 GMHS 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 behavior 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 signaling 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. GMHS enables flow control after receiving a modem CONNECTion response (see below) and before initiating a modem hang-up (see below). GMHS 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 GMHS 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, GMHS 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 GMHS 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, GMHS 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 hang-up. 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 GMHS 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 GMHS 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 GMHS 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 GMHS 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 GMHS 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 HANG-UP 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. HANG-UP This keyword is used to specify the command string, not including COMMAND BEGIN and COMMAND END, that will be sent to this modem to hang-up 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. HANG-UP TIME This keyword is used to specify the amount of time, in seconds, to wait for a modem response after sending a HANG-UP 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 HANG-UP command. Dropping the DTR signal, for the correct amount of time, is an attempt to add more reliability to modem hang-up. 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., carriagereturn 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 GMHS 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 HANG-UP 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 GMHS, 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 GMHS 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 GMHS 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 GMHS 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 GMHS 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 GMHS when they are referenced as the Modem Type in the MHS configuration. GMHS uses the MDF to configure, reset, initialize, dial, answer, connect, and hang-up modems, both in dial up and leased line environments. With 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 hang-up.3.1 MDF Initialization When the MDF is first referenced, it is processed, i.e., the MDF 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: * 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. * If configured for Yes, is Modem Negotiation valid for this modem, i.e., are PROTOCOL ON and PROTOCOL OFF specified? * If configured for Yes, is Leased Line valid for this modem, i.e., are LEASED DIAL and LEASED ANSWER specified? * If Optional Modem Commands are specified, do they exceed the MAX COMMAND length? 3.3 Serial Port Initialization GMHS 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), GMHS monitors 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 intelligent multi-port serial adapters), 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 adapters. 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 hang-up 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 validresponse 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 anddisplayed. 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 isnot 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. GMHS 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 areresent; 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. GMHS 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. 3.6 Modem Answering GMHS supports incoming calls and therefore, must answer modems. 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, GMHS polls 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 CONNECTresponse. 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 control is enabled. GMHS also starts monitoring for an inactive DCD to indicate lost carrier/connection. If DCD is inactive, modem hang-up 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. 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 then 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 Hang-up 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 HANG-UP command is sent, waiting up to HANG-UP TIME seconds for a response. To ensure that hang-up 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 \ASYNC\MODEMDEF 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 similar 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 \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. y