Previous Page: Customizing PPP Login Scripts  Next Page: Optimizing

Using Modem Description Files

This topic discusses the use of modems with the Novell® Internet Access Server 4.1 routing software. It contains the following sections:


Customizing a Modem Description File

The Novell Internet Access Server 4.1 routing software provides a Windows-based utility that enables you to create a customized modem description file. To create, edit, or install a modem description file, start the WMDMMGR utility the same way you would start any Windows 3.1, Windows 95, or Windows NT utility. This utility can be run only at a Windows workstation and cannot be run from the DOS prompt.

WMDMMGR is located in the SYS:\SYSTEM\UTILS directory on your server. Three sample modem description files, with an .MDC extension, are provided in the SYS:\SYSTEM directory of your router. These files contain modem scripts that are certified by the Novell LabsTM group (NIASCERT.MDC), as well as scripts for commonly used modems (NIASMDM1.MDC and NIASMDM2.MDC). You can modify these modem scripts to meet your requirements, although this is not recommended for scripts in the NIASCERT.MDC file.

To create a new modem description file, select New from the File menu. To modify an existing login script, select Open from the File menu. After editing the modem description file as described in the online help, save your changes by selecting Save or Save As from the File menu. To edit existing files, copy the files to the SYS:\SYSTEM directory. If you have any problems editing or using existing modem description files, refer to Using the WMDMMGR Utility in the Modems and DTR-Controlled Devices documentation.

The remaining sections in this topic provide the background information you need to understand the operation of modem description files.


Limited Public-Switched Telephone Support

This topic describes the pseudopermanent connection feature supported by the router using dial-up synchronous modems. The dial-up synchronous connection is established automatically by the modems when the routers at both ends are turned on. The connection is terminated when either of the two routers is turned off or otherwise stopped.


Pseudopermanent Link Operation

The pseudopermanent link is a dial-up link established over the Public Switched Telephone Network (PSTN) using a pair of synchronous modems. By its very nature, this connection is asymmetrical because one modem originates the call and the other modem answers the call. Therefore, the calling end needs to be programmed to automatically dial the stored telephone number of the remote modem, and the remote modem needs to be programmed to automatically answer the incoming call.


Initial Connection Establishment

When the routers are turned off, the Data Terminal Ready (DTR) signal is set low, thereby prohibiting any connection between the modems. When the router at the calling end is turned on, it turns on the DTR, triggering the modem to automatically dial and establish a connection. When the calling modem detects the DTR off-to-on transition, it goes off-hook, dials the remote modem, and waits for the connection to occur. If, after a certain programmed period (in units of number of rings), the connection fails to materialize, the modem goes on-hook and terminates the connection. If the connection does occur (that is, the remote end answers), the modem turns on the carrier, exchanges a training sequence, and reaches a ready state. These events are indicated by the modem turning on the Data Set Ready (DSR), Data Carrier Detect (DCD), and Clear-to-Send (CTS) signals, in that order.

The answering modem waits for an incoming call and answers it, if the local router has set the DTR signal high. Here again, the modem turns on DSR, DCD, and CTS signals to indicate call connection, carrier detect, and ready state.


Call Disconnection and Reconnection

Call disconnection can occur because of telephone line failure, because one of the routers was turned off or was taken down, or because of a power failure. Each modem detects the call disconnection by the absence of the carrier. Following this detection, the modem disconnects the call and turns off the DSR, DCD, and CTS signals.

The modem signals DSR, DCD, and CTS are tracked by the router, and the router, in turn, turns off the DTR when any of these signals are off. The router keeps the DTR low for a few seconds to allow the modem to complete the actions needed for terminating the call, and raises the DTR to trigger redialing. When the modem detects the DTR off-to-on transition, it goes through the procedure for reconnection; on successful reconnection, the modem raises the DSR, DCD, and CTS signals. Should the reconnection attempt fail, the modem resets any signals it might have raised during the reconnection.

Even when the reconnection attempt fails, the router has the DTR on for approximately two minutes before taking it down. This delay spaces the reattempts to connect two minutes apart, preventing excessive telephone traffic. If the connection does occur, the DTR remains on indefinitely, and the dialed connection then simulates a permanent connection.

The router actions remain the same, whether the router is connected to a calling modem or an answering modem. Hence, the router code is unaware of the asymmetry in the dialed connection.

Note that although the preceding description is based on the experience gained from using Hayes* smart modems, it is valid for a wide variety of compatible modems.


Modem Requirements

Following are the dial-up synchronous modem requirements:


Modem Programming Example

The following example illustrates the programming needed to set the Hayes ULTRA* 14,400-bps modem for dialed synchronous operation. To do this, connect the modem to a terminal device or PC with a terminal emulation program. The router provides a method of addressing the modem through the CPECFG program (refer to "Configuring Modems and DTR-Controlled Devices" on page 87 for information about using CPECFG).


Dip Switch Setting

The left dip switch (sw 1 , seen when the front cover is removed) has the following settings:

This switch is set to DOWN after the modem is configured for autodial/ autoanswer. This prevents the synchronous data from accidentally being interpreted as commands (for example, when the DTR is turned off).


Modem Script for Call Originating Modem
AT&F; &F - Recall Factory settingsAT&Z0=<dest tel no>; &Z0 - store no to be calledAT&Q2&C1&D2; &Q2 - Stored No redial on DTR OFF -> ON; &C1 - Track status of DCD; &D2 - Track DTR, DTR ON -> OFF go to cmd stateATS37=11 S37=11 - Connect to remote modem at 14400bps speedATE0Q1&Y0&W0 E0 - Disable character echoing; Q1 - DO not return result codes; &Y0 - Select profile `0' as power on config; &W0 - store as profile `0'
Modem Script for Call Answering Modem
AT&F; &F - Recall Factory settingsAT&Q1&C1&D2S0=2; &Q1 - Sync mode 1 (async to sync on connect); &C1 - Track status of DCD (don't ignore); &D2 - Monitor DTR, DTR ON -> OFF enter cmd stateCall automatically answered only if DTR is ON; S0=2 Auto Answer after 2 ringsATS37=11; S37=11 - Connect to remote modem at 14400bps speedATE0Q1&Y0&W0; E0 - Disable character echoing; Q1 - DO not return result codes; &Y0 - Select profile `0' as power on config; &W0 - store as profile `0'
Reprogramming the Modem

Should the need arise to reprogram the modem (for example, to change the destination telephone number), the following procedure should be adopted. Because character echoing and result code returns have been disabled, the modem does not respond to a user's attempt to communicate with it (in asynchronous mode). To reprogram the modem, complete the following steps:

  1. Turn off the modem.

  2. Set dip switch 1 to the UP (smart mode) position.

  3. Turn on the modem.

  4. Enter the following modem command:

    ATE1Q0; E1 - Enable character echoing

    ; Q0 - Enable returning of result codes


Modem Description Files

Novell's most recent products, and those in development, are designed to be modem independent . This enables new modems to be supported by these Novell products without a new version of the software being released. All that is required is to load the appropriate modem description file onto the specified system.

Novell products can interpret modem description files and execute script commands in the files to perform modem operations as the application requires. Neither the modem control components nor the software products themselves are specific to any one modem or set of modems. Any details specific to modems are contained in the modem description files.

When Novell products are installed, modem description files are copied along with other product files. As users configure the software, they identify the modems to be used from lists of modem names. Any modem that has a modem description is presented in these lists for the user to select.

When a port is configured from the Network Interfaces screen of the Novell Internet Access Server Configuration utility (NIASCFG), the type of modem attached to the port is specified in the Modem/DCE Device field. This option enables you to select a modem initialization script that is specified in the compiled NIASCERT.MDC, NIASMDM1.MDC, and NIASMDM2.MDC files in the SYS:SYSTEM directory.

Because these files are compiled, they require a special modem script editing tool, WMDMMGR, to read them and make changes to them. Multiple *.MDC (Modem Definition Compiled) files can exist in SYS:SYSTEM; however, if a description of a particular type of modem appears in multiple *.MDC files, there is no guarantee as to which description is used. To avoid confusion, a modem description should appear in only one *.MDC file. When Novell Internet Access Server 4.1 is installed, any previously installed *.MDC files are moved to the SYS:SYSTEM\BACKUP directory. Only files included in Novell Internet Access Server 4.1 remain in the SYS:SYSTEM directory.

If you create new modem description files, copy them to the SYS:SYSTEM directory so that they are available to the routing software. If the routing software is running, issue the REINITIALIZE SYSTEM command to have the modem script changes take effect

This section discusses the format and content of the information present in the modem description files. The method of defining the capabilities of a modem is specified, and the process of constructing scripts to accomplish modem operations is outlined. Several examples illustrate uses of the details presented.


Modem Description File Information

A modem description file includes information describing both a modem vendor and individual modems. The information about the modem vendor is specified first, with from one to many descriptions of modems following.

One way to organize modem descriptions is to collect information about all modems from one vendor into a single file. This makes it easy to register the single filename with Novell. Another possibility is to group modems by family, as might be done with all the XYZ Xxxx sample models. We suggest that all modems manufactured by a vendor be located in a small number of files.

A typical modem description file includes the following:


Modem Description File Components

This section describes the components that can be used in modem description files.


Vendor Description

The following fields are part of the vendor description:

The manufacturer and copyright string values can be up to 80 characters long. The version numbers can have numeric values from 0 to 99. Currently, the values are not used directly by modem control components, but they are provided for use by modem vendors.


Modem Description

This section explains the modem keywords and how to use them.


Modem Name

The modem name string value can be up to 39 characters and must be unique within the entire set of modem names known to Novell.

There can be multiple descriptions for the same modem, with each appropriate for distinct circumstances. For instance, it might be found that most revisions of a particular modem can be initialized quickly, but that some ROM levels require delays between output characters. Rather than force all users to wait for a lengthy initialization operation, it is possible to create two descriptions, as follows:

XYZ Modem XxxxXYZ Modem Xxxx (Slow Init)
Rate Options

The following rate options require values to be defined:


Other Options

Depending on how your modem is being used, two of the following options might have to be configured. The first two of the following options are configurable; the last two options are not configurable. These options are described as follows:


Modem Scripts (Control Strings)

Modem scripts are text strings that are sent to the modem to cause a particular behavior. They are associated with a particular modem capability and are transmitted to the modem when the application software wants to invoke that operation.

More information on the content and creation of modem scripts is given later in Script Operations Individual scripts are summarized here:


Script Operations

A modem script contains a sequence of nano-operations that inform modem control about which actions to perform. These actions include output of ASCII characters, controlling interface signals, checking for expected input, and so forth. There is no facility for conditional execution of nano-operations; the entire script is executed unless an error occurs.

Each nano-operation consists of an alphabetic character optionally followed by parameters for that operation. These values can be string or time values, or other modifiers for that basic operation.

Following are the operations summaries:


Modem Responses

The response strings in a modem description allow recognition and interpretation of data sent from the modem to the DTE. Response strings inform the modem control software of the success or failure of a command. These strings also let modem control detect when a call is arriving.

As the responses generated differ between modems, the modem vendor must supply information to allow modem control to recognize responses. Response strings contain from one to many pairs of substrings, the first giving the input string to be recognized and the second representing the standard meaning of the string.

With the ever more complex responses found in newer modems, it is sometimes necessary to perform multistage matching of response strings. An example would be when the modem is using negotiation progress monitoring to capture added information about connections. When the PROTOCOL response is received, the first stage of recognition would identify the input as the PROTOCOL message. The second stage of recognition would then identify the particular substrings that might be present in this message. This progression from one stage to the next is called chaining.

Modem control accumulates ASCII characters received from a modem until a carriage return character (\x0D or decimal 13 ) is received; all other control characters are ignored. The accumulated string is then compared to the match strings in the RESPONSES keyword string. When a match is found, the meaning is interpreted and the appropriate action is taken.


Modem Response Strings

Modem response strings can comprise two string elements: the match string and the meanings string .


Status Meaning

Status information is used to notify modem control when something of significance has been discovered in a response, or to report that scanning should continue. Possible status types are as follows:

NONE

CONNECT

RESERVED 1

BUSY

RESERVED 2

NO_ANSWER

RESERVED 3

NO_CARRIER

RESERVED 4

ERROR

RESERVED 5

NO_DIALTONE

OK

VOICE

RING

UNKNOWN

RRING

 


Rate Meaning

The rate meaning tells modem control what the current line data rate is in bits per second. For most modems that implement negotiation progress messages, this rate value can be captured from the CARRIER response by using the <R> construct, as in CARRIER <R> or CONNECT <R> . This construct matches any speed response from the modem and captures that value to return it in the rate definition command.


Feature Meaning

The feature values indicate to modem control when optional connection features have been enabled on the current connection. Information about which features are enabled or disabled is made available to applications. Applications can use this information to determine whether they must independently perform error control or data compression for a connection. The features are as follows:.

NONE

V.42BIS

ERROR_CONTROL

UNBALANCED

MNP5

SYNCHRONOUS


Match Chaining

The match chaining directs modem control to continue matching using the remainder of the input string (after the initially matched portion) and using a different modem response string. This permits the multistage matching that is so useful with complex sets of responses, such as negotiation progress messages. The following example illustrates this approach:

RESPONSE = PROTOCOLRESPONSES STRING 1 = ERROR-CONTROLInput from modem: PROTOCOL: ERROR-CONTROL/LAP-B

The first string is part of the first stage matching string formed from all the RESPONSES keyword strings. Modem control interprets it to mean that the response beginning with PROTOCOL is not a final response; rather, that additional matching must be performed using RESPONSES STRING 1 .

Modem control begins checking the remainder of the input string repeatedly against the RESPONSES STRING 1 match strings. Each time the match strings are used up, modem control advances to the next character in the input string and tries again. This process continues until all the characters in the input string have been exhausted. In this manner, modem control finds the ERROR-CONTROL substring and notes that feature one, ERROR CONTROL , is enabled for this connection.


Environments

Novell's modem control is implemented in multiple environments. This section briefly describes how modem description files are used in each environment.

Modem description files on a NetWare server are placed in a subdirectory accessible to NetWare Loadable ModuleTM (NLMTM ) files. The files for both the routing and the remote access components of Novell Internet Access Server 4.1 are located in the SYS:SYSTEM directory. You should work in this directory when adding new scripts, editing existing scripts, and compiling scripts. Novell Internet Access Server 4.1 uses all compiled scripts with the .MDC extension that exist in the SYS:SYSTEM directory.


Novell Internet Access Server 4.1 Remote Access Software

The modem control components of the remote access software exist in a subdirectory called SYS:SYSTEM. All files containing compiled modem descriptions are copied to this subdirectory. When NetWare Asynchronous I/O (AIO) is loaded, it searches this subdirectory for files with the extension .MDC. AIO then creates a list of all modem names defined in these files and indicates which file contains the description for each modem. When one of the remote access services attempts a modem operation on a port, AIO determines which modem is attached to that port and ensures that the modem's description has been read into memory. AIO then starts the execution of the operation using the service's request parameters and the modem description.

The standard set of scripts that are included in the remote access software are contained in the following three files:


Novell Internet Access Server 4.1 Routing Software

The routing software uses modem definition files that are placed in the SYS:SYSTEM directory. It interprets these files as required for modem control. The standard set of scripts that are included in the routing software are contained in the following three files:



  Previous Page: Customizing PPP Login Scripts  Next Page: Optimizing