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.
This specification defines how modem vendors can create modem description files that allow their modems to work with Novell's products.
Novell's most recent products and those in development are designed to be "modem independent". This allows new modems to be supported by these Novell products without a new version of the software being released. All that the end user is required to do, is to load the appropriate modem description file onto his system.
These Novell products can interpret modem description files. They
execute scripts 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.
This document describes the format and content of the information present in the modem description files. The method of defining capabilities of a modem is specified and the process of constructing scripts to accomplish modem operations is outlined. Multiple examples illustrate uses of the details presented in this specification.
Modem description files are created by the modem vendors using this
specification. Test programs will be provided by Novell Labs allowing vendors to check that the modem description functions correctly. When the vendor is satisfied that the modem description file is correct, the file and modem can be certified by Novell Labs . It will then be made available to our mutual customers as a supported modem. It may also be integrated into future releases of Novell products.
When Novell's 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 will be presented in these lists for the user to select.
Description File Format
Overview
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.
The vendor information begins with the vendor's name, which identifies the company creating the description file. A copyright notice can be included to protect the company's rights. Version information should be added to allow tracking of additions or corrections to description information.
Each file can describe more than one modem. 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 of the "XYZ Ultra Xxxx" models. It is suggested that all modems manufactured by a vendor be located in a small number of files.
Modem description information begins with a line specifying the modem
name. This name must be unique within the entire set of modem names
known to Novell, and thus should include some form of the vendor's name to avoid conflicting with any other vendor's descriptions. The modem name will be used in lists presented to users and may be up to 39 characters in length. Only one definition of a modem can exist across all modem description files; duplicates will produce unpredictable results.
The description for a modem continues with a line supplying information regarding the features, capabilities, and default values for the modem. This information is needed by the modem control components to determine which logical operations may be performed. Such information would include the highest interface bit rate possible to the modem, whether the modem can be used with leased lines, whether it supports use of hardware flow control, and so forth. These details are supplied explicitly using the OPTIONS keyword.
The modem scripts that perform particular operations must be specified next. These scripts are simply strings encoding sub-operations to be
executed which together accomplish the desired operation. Multiple lines can be combined if required.
The final section of a modem description will contain the strings used to decode a modem's responses to commands and operations. For instance, the string returned by a modem when a command is successful must be associated with the meaning "OK". Additional response recognition allows modem control components to handle call origination and answering.
These strings contain pairs of subsections, the first subsection giving the input to be recognized, and the second specifying the meaning of that input.
The modem description files that are delivered to the customer are in a binary format that is obtained by processing the ASCII text, as described in this document, by a conversion program to be supplied by Novell Labs to the modem vendor. Novell Labs is also writing an interactive program that will allow the editing and creation of these modem description files. The concepts described here apply equally well to both methods of creating the description file. Chapter 4 describes these tools and their use.
Description Line Format
Specification lines are given in the form of a keyword followed by an
equals sign and then one or more values. For most of the keywords there will be only one string value. Other keywords, such as the OPTIONS keyword, can take multiple values which can be identifiers, numbers, and strings.
Strings are delimited using double quotes and control characters are
included by prefixing with a reverse apostrophe, e.g. `M is used to enter a control-M.
ASCII Null characters (\x00) must not be included in strings. Also, script strings cannot contain the ASCII characters '[' and ']', except as noted below.
Specification line length should be limited to less than 160 characters. In any case, where more information needs to be specified for a keyword than will fit on one line it is permissible to use multiple lines, where each line repeats the keyword. Each such string will be appended to the previous to form one continuous string in the description. This will be seen in the examples later.
Comments can be included in the description text file. Whole line
comments are created by making the first character of the line a semicolon.
Vendor Description
The following keywords are valid in the vendor section:
o MANUFACTURER Descriptive name of modem vendor
o COPYRIGHT Vendor's copyright notice
o MAJOR_VER Version number of modem description(s)
o MINOR_VER Revision number of modem description(s)
The manufacturer and copyright string values may be up to 80 characters in length. The version numbers may have numeric values from zero to 99.
Currently none of these values are directly used by modem control
components, but are provided for use by modem vendors. Examine the
later examples to see typical uses of these keywords.
Modem Description
-----------------
Modem Name
The modem name string value may be up to 39 characters in length. As
noted before, this name must be unique within the entire set of modem
names known to Novell. The MODEM keyword begins a new modem
description.
There can be multiple descriptions for the same modem with each
appropriate for distinct circumstances. For instance, it may 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.
MODEM = "XYZ Ultra Xxxx"
MODEM = "XYZ Ultra Xxxx (Slow Init)"
Modem Options
The OPTIONS keyword permits the definition of the capabilities of the
modem. Some options have a value associated with them, others indicate the presence or absence of a modem capability. Options that have parameters are defined as shown here:
OPTIONS = DEFAULTRATE=19200, MAXRATE=57600
OPTIONS = FIXEDRATE=19200, DELAY=1
The following options require values to be defined:
o DEFAULTRATE Best 'normal' bit rate to modem
o DELAY Delay between command characters
o FIXEDRATE Best bit rate for use with fixed rate usage
o MAXRATE Maximum bit rate to modem
DEFAULTRATE
When a modem operation specifies use of fixed rate mode, the
FIXEDRATE option supplies the bit rate to be used to communicate to the modem. When that mode is not selected, modem control uses this option to determine the default bit rate for the interface to the modem.
DELAY
Some modems require a greater amount of time to process complex
commands. Experience has shown that complex commands that are output
to these modems one character at a time will be successful. This option supplies the amount of time to insert between characters on selected commands.
The numeric value is the time in tenths of seconds that modem control
should wait between outputting characters. There are two script
operations for output: one inserting delays between characters with the other not delaying between characters. If this option is not specified the default delay will be zero (and thus no delay at all).
FIXEDRATE
Modems can be initialized to use one unchanging bit rate between
themselves and the DTE. This bit rate is usually set to a value high enough to permit use of compression no matter what line speed is used on a connection. The numeric value is the bit rate to be used when the modem is put into fixed rate mode.
Note: This option also implies that fixed rates are supported by the modem (see FIXED script).
MAXRATE
The set of interface bit rates that can be used to communicate from the DTE to a modem usually has an upper bound. This option supplies the maximum interface bit rate to be used with a modem. The numeric value for this option is the maximum rate in bits per second.
Modem Options - Capabilities
These options inform the modem control components about the capabilities and restrictions of the modem. This is needed so that operation requests for these features can either be accepted, modified or rejected. The presence of a modem option indicates that a particular feature is supported; there is usually a corresponding script to activate that feature.
o ARQ Error control protocol(s)
o AUTOANSWER Automatic call answering
o COMPRESSION Compression protocol(s)
o DIALOUT Call origination
o FIXEDSINGLE Only one rate possible for fixed rate usage
o HAYES Append common responses subset
o HWFC Hardware flow control
o LEASED May be connected to leased-lines
o MANUAL Manual call origination/answering
OPTIONS = HAYES, FIXED, HWFC
OPTIONS = AUTOANSWER, LEASEDLINE
OPTIONS = ARQ, COMPRESSION
In many cases these options have one or more corresponding scripts that implement the options. As a convenience, it is not necessary to explicitly declare an option - the presence of a script will implicitly infer that the capability exists. For example, the presence of a DIAL script will enable the DIALOUT option. These associations will be noted in the script descriptions.
ARQ
This option specifies that the modem implements one or more error control protocols such as MNP or V.42. While error control may not be active on all connections, a modem initialization operation can request that error control be permitted for the next connection.
AUTOANSWER
This option specifies that the modem may be put into a mode where it can automatically answer incoming calls. When the modem begins answering, modem control will monitor the modem responses for connection parameters.
COMPRESSION
This option specifies that the modem implements one or more data
compression methods such as MNP or V.42bis. It is understood that
compression may not be active on all connections, and that compression
may require simultaneous use of error control protocols and/or other
modes such as fixed rate. This option informs modem control that the
compression feature is supported by the modem.
DIALOUT
This option specifies that the modem can originate calls when requested by commands. The phone number and other information supplied will be inserted in the dial command as indicated in the dial script.
FIXEDSINGLE
Some modems permit use of the fixed rate feature, but with only one
allowable bit rate. Presence of this option specifies that this restriction is true for this modem.
HAYES
Presence of this option informs modem control that this modem's
responses include those in a set of common, industry-standard responses.
Modem control will append this set of responses to any supplied in the description's response strings. These common responses are summarized here:
o BUSY Call origination: remote telephone was busy
o CONNECT Connection completed: interface rate is 300bps
o CONNECT <R> Connection completed: interface bit rate is 'R'
o ERROR Last command failed
o NO ANSWER Call origination: remote never answered
o NO CARRIER Modem detected absence of carrier signal
o NO DIALTONE Call origination: telephone line had no dial tone
o OK Last command executed successfully
o REMOTE RING Call origination: remote telephone is ringing
o RING Telephone line has given a 'ring' indication
The associated meanings accompany the responses and will be shown in
later examples.
HWFC
This option specifies that the modem permits the use of hardware flow
control between modem and interface. Some type of flow control is often necessary with modems that implement error control and/or compression; hardware flow control is superior to software flow control in that it does not interfere with the data being transmitted.
LEASED
This option specifies that the modem can be connected to leased (non-
switched) telephone lines. When specified, modem control will permit the initialization of the modem into leased-line mode. Call origination and answering will employ different scripts than normal dial operations.
MANUAL
This option specifies that the modem can be used in situations where the user or operator will manually originate or answer telephone calls.
Modem Scripts
A modem script is a text string that is sent to the modem to cause a
particular activity. They are associated with a particular modem capability and are transmitted to the modem when the application software wishes to invoke that operation.
More information on the content and creation of modem scripts will be
given in a later section, "Script Operations". Individual scripts are summarized here:
o ARQ Enable error control protocol(s)
o AUTOANSWER Place modem into auto-answer mode
o COMPRESSION Enable data compression method(s)
o DIAL Originate a call on a switched line
o FIXED Place modem into fixed interface rate mode
o HANGUP Disconnect any call in progress
o HWFC Place modem in hardware flow controlled mode
o INIT Initialize the modem to a known state
o LEASEDLINE Place modem into leased line mode
o LSDANS Accept a leased line connection
o LSDORG Originate a leased line connection
o MANANS Accept manually answered switched connection
o MANORG Originate manually dialed switched connection
ARQ
This script enables the use of any of the error correcting protocols
implemented by a modem when the next data connection is begun. Since
which protocols may be activated depends on the remote modem, this
script only specifies that the best possible for each connection be used.
Through monitoring of negotiation progress responses the modem control components can be informed of the characteristics of the protocol
activated.
ARQ = "O:AT&Q5S36=7S46=0S48=7`M:I:OK:"
AUTOANSWER
This script places the modem in the mode of automatically answering
incoming telephone calls. A connection can begin without intervention by modem control. Modem control will monitor the progress of connection initiation and detect when the connection is complete and data transfer may begin.
AUTOANSWER = "O:ATS0=[R]`M:I:OK:"
COMPRESSION
This script enables the use of any of the data compression methods
implemented by the modem when the next data connection is begun. Since the particular compression method employed depends partly on the remote modem, this script only specifies the preferred method to be used.
Through monitoring of negotiation progress responses the modem control components can be informed of the characteristics of the method activated.
COMPRESSION = "O:AT&Q5S36=7S46=2S48=7`M:I:OK:"
DIAL
This script is executed when a call origination operation is requested on a switched line. The operation request parameters include whether the dialing should use pulse or touch-tone signaling, and the destination telephone number. These parameters are inserted into the dial script string using the substitution tags, "[T]" and "[P]". These tags are described more fully in a later section.
DIAL = "O:ATD[T][P]`M:"
FIXED
This script places a modem into fixed interface bit rate mode. This allows the interface to be programmed to one bit rate that can be used for all subsequent connections. The actual rate used will be determined by the associated FIXEDRATE and FIXEDSINGLE options.
FIXED = "O:ATS36=3`M:I:OK:"
HANGUP
This script causes the modem to disconnect any call that might be in
progress. (i.e.. place the modem "on hook") This script should specify all needed operations that to ensure the call is disconnected, irrespective of the current modem state.
HANGUP = "O:`M:P10O:+++:P10i25:OK:D10"
HANGUP = "O:ATE1H0`M:Q"
HWFC
This script places a modem into hardware flow controlled mode. In this mode data transfer between modem and interface is controlled through the use of the RS-232 signals Request-to-Send (RTS) and Clear-to-Send (CTS). Each signal controls data transfer in one direction.
HWFC = "O:AT&K3`M:I:OK:"
INIT
This script causes a modem to be initialized to a known state. This state must have all optional features disabled. That is, the purpose of the INIT script is to put the modem into a state where any of the other features can then be added by individually executing scripts.
The INIT script is usually the first script executed when a modem
operation is begun; the only script that could precede it might be the
HANGUP script to disconnect a call in progress. The INIT script can
make no assumptions about the previous state of the modem. Indeed, the previous user of a modem may not have been Novell's modem control, and so not even modem control will know the state of a modem.
The script must reset everything that can be affected by modem commands.
This would include features like echo, call progress, result code, modem signal usage, flow control modes, and so forth. The script must set the correct modes so that modem response strings can be recognized.
INIT = "o:`MATZ`M:i25:OK:Q"
INIT = "O:ATE0Q0V1X4F1&C1&D2&L0&M0`M:I:OK:"
INIT = "O:ATS0=0S7=[W]S10=20S12=25`M:I:OK:"
LEASED
When a modem initialization operation is requested and the leased line feature is requested, this script is executed to place the modem into leased line mode. In some cases this feature is not under control by commands, but rather some switches must be set. In this case the script may be absent.
LEASED = "O:AT&L1`M:I:OK:"
or
;LEASED line is set by hardware switch
LSDANS
This script is executed when a call answer operation is requested on a leased line. The modem should attempt to connect to the remote modem
using answering frequencies. Once this script is completed modem control will monitor the local modem's responses to detect when a connection has begun.
LSDANS = "o:`MATA`M:"
LSDORG
This script is executed when call origination is requested on a leased line.
The modem should attempt to connect to the remote modem using
origination frequencies. Once this script is completed modem control will monitor the local modem's responses to detect when a connection has begun.
LSDORG = "o:`MATD`M:"
MANANS
This script is executed when a manual call answer operation is requested.
The modem should attempt to connect to the remote modem using
answering frequencies. Once this script is completed modem control will monitor the local modem's responses to detect when a connection has begun.
MANORG
This script is executed when manual call origination is requested. The modem should attempt to connect to the remote modem using origination frequencies. Once this script is completed modem control will monitor the local modem's responses to detect when a connection has begun.
Modem Responses
The response strings in a modem description allow recognition and
interpretation of data sent from the modem to the DTE. This informs the modem control software of the success or failure of a command. It also lets 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 sub strings, 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 multi-stage matching of response strings.
As an example, when using negotiation progress monitoring to capture
added information about connections, the PROTOCOL response can be
received. The first stage of recognition would identify the input as the PROTOCOL message. The second stage of recognition would then
identify the particular sub strings that may be present in this message.
Modem control will accumulate 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.
The following response string keywords are defined:
o RESPONSES
o RESPONSES1
o RESPONSES2
o RESPONSES3
o RESPONSES4
The first keyword provides the first stage matching information. Part of the meanings information can specify that input matching for a message is to continue using information found in one of the other four response string keywords.
RESPONSES = ":OK:S6:RING:S7:ERROR:S13"
RESPONSES = ":COMPRESSION:S0M1"
RESPONSES1 = ":NONE:F0:CLASS 5:F2:V.42bis:F3"
Further information on response matching is given in the section "Response Strings" below.
Script Operations
A modem script contains a sequence of nano-operations that tell modem
control 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 may be string and/or time values, or other modifiers for that basic operation. The
operations are summarized below:
o 'B' Control asynchronous 'break' signal
o 'D' Control DTR signal
o 'F' Flush Transmit /Receive buffers
o 'I' Check for modem input (must match)
o 'i' Check for conditional modem input (optional match)
o 'O' Output characters to modem
o 'o' Output characters to modem with delay
o 'Q' Wait for end of input
o 'P' Pause script execution
o 'R' Set new interface rate
Control Break - 'B'
This operation is used to turn on the asynchronous 'break' signal
momentarily. This might be used to get a modem's attention to switch it into command mode. The format is "B{time}" where {time} is the
optional break on duration.
The break operation character may be followed by a decimal number giving the length of time in tenths of seconds for which break is to be turned on.
If a time value is not given then the default break on time of one half second will be used.
Control DTR - 'D'
This operation is used to control the DTR signal to the modem. The DTR signal will be turned off momentarily and then turned on again. Turning off this signal might be used to get the attention of a modem when it is in data transfer mode. The format is "D{time}" where {time} is the optional duration in tenths of seconds for the DTR signal to be turned off.
If a time value is not given then the default DTR off time of one half second will be used.
Set Interface Data Rate - 'R'
This operation allows scripts to change the data rate used to communicate with the modem. This is used with modems that do not automatically resynchronize interface data rates after switching back to command mode from data transfer mode.
The format is "Rrate" where rate is the required decimal number specifying a rate in bits per second. The permitted values are:
Rate Rate Rate Rate Rate
50 75 110 134 150
300 600 1200 1800 2000
2400 3600 4800 7200 9600
19200 38400 57600 115200
After execution of this operation any further output or input through the interface will use this data rate. Some asynchronous equipment must flush one or both of the input and output streams when changing data rates.
Flush Buffers - 'F'
Characters that have been buffered for output or input but not yet
processed may be discarded by this operation. This might be useful when modem responses up to a point may safely be ignored, or if prior output should be discarded when starting new commands. The format is
"F{B | I | O}"
The flush operation character must be followed by another character
indicating which stream(s) should be flushed. The character is either 'B' which flushes both input and output streams, 'I' to flush just the input stream, or 'O' to flush only the output stream.
Input String - 'I' or 'i'
This operation allows a script to check for a specific string to be received from a modem. For example, after most modem commands a script should check for the returned indication of success, usually 'OK'. There are two variants : 'must match' or 'optional match'. The format for these is "(I | i){time}:string:" where the nano-operation character may be 'I' for the 'must match' or 'i' for the 'optional match' variants, respectively.
The operation character can optionally be followed by a decimal number specifying the maximum time to wait for this response. This value is specified in tenths of a second. If it is not given the default value of five seconds is used.
The next script character is used as a string delimiter and an input match string is collected. This string may contain control characters formatted as for the output string operation.
Modem control continues receiving characters from the modem until one
of two occurrences. If a matching string from the modem is completed the nano-operation finishes and the script continues. If a match is not completed and the time-out period has elapsed since the last character was received from the modem, then an input time-out is declared.
If this was a 'must match' input string operation the time-out causes the script to be terminated with a 'bad modem response' error code.
Otherwise the time-out simply terminates the optional match operation and continues with the rest of the script.
Output String 'O' or 'o'
This operation allows output of character strings from the script to a modem. The output string may contain any non-nul, non-control ASCII
characters. The format of this operation is "(O | o):string:" where the operation may be coded using either 'O' or 'o' followed by the string to be output. If it is necessary to insert a delay between characters the 'o' operation will use the delay time specified using the DELAY option.
The string to be output is bounded by some character chosen by the script creator. The character directly following the operation code will be used to locate the end of the string. The script creator should choose a string delimiter character which will not be used for any interactions with the modem. The character should not be one of the alphanumerics as this would make reading descriptions difficult. A survey of several modems has identified the many punctuation characters that are used within modem commands and responses. This leaves the following set as the characters recommended for use: '<^_{}|:', by convention a colon is used (":").
As noted in section "Description Line Format", control characters may be inserted into output strings using the accent-grave or reverse apostrophe.
Variable strings may be substituted into output or input strings by use of an substitution marker. A substitution is indicated by a substitution tag name surrounded by [ and ] characters. For example, substitution of the "tone" or "pulse" modifier and the phone number into a dial-out command might be coded as "O:ATD[T][N]'M:" where [T] is replaced with 'T' or 'P' and [N] is replaced with a dial number.
Only a limited number of substitution tags are defined, and the substituted strings are not variable by modem type. The pre-defined tags are:
o T dial tone/pulse modifiers: 'T' or 'P'
o N dial phone number: supplied by application
o R ring count: used on initialization
o W ring count: used on initialization
Care should be taken that the longest command sent to a modem does not exceed what the modem can handle. Many modems are limited to a
maximum of 40 command characters excluding the leading 'AT', spaces,
hyphens, and final carriage return. The input command can be used to
break up long command output sequences.
Pause 'P'
This operation allows a script to pause execution for a period of time. This is useful when modems may require some time to complete complicated modem commands. The format is "P{time}" where {time} is the optional pause time in tenths of seconds. If a time value is not given then the default time value of one second is used (time = 10).
Quiet Wait 'Q' This is used to skip all the responses from a previous command before issuing a new command. It causes a wait until the modem remains continuously quiet for the specified time.
The format is "Q{time}" where the wait time is optional. When present this time value is in tenths of seconds. If a time value is not given then the default time value of one second is used (time = 10).
This nano-operation will throw away any data received from the modem.
Whenever a character is received the elapsed time timer will be reset to zero. When the elapsed time timer reaches the specified wait time value the nano-operation completes successfully. An additional timer records the total time since the nano-operation began. If this timer reaches the sum of the specified wait time plus five seconds then a time-out is declared and the nano-operation completes unsuccessfully causing the script to be terminated with an error.
Response Strings
Match Strings
The first of each pair of strings in the RESPONSES string is known as the match string. As noted above, when modem control is monitoring modem responses, characters received from a modem are collected until a carriage return is received. The input string is then compared (case insensitive) against all the match strings found in RESPONSES keyword strings. This matching operation proceeds in the same order as the RESPONSES string occurred in the description file.
Match strings do not need to be the entire response string to declare a match. Only the initial characters of a response must match the match string. Thus the match string "ERR" will match both the response strings "ERROR" and "ERRONEOUS" but not "ERASE". However, this may make the order that match strings are tried even more important.
Match and meanings strings are delimited by any character that the
description creator chooses. Whatever character begins the first
RESPONSES string is the delimiter for all the RESPONSES strings. In
the interests of clarity a non-alphanumeric character should be used. The colon character (':') is used in our examples.
Here are some example match and meanings strings:
:CARRIER <R>:R*S0:CONNECT <R>:S9
:OK:S6:RING:S7:NO CAR:S12:ERROR:S13
:PROTOCOL:S0M1
:NONE:F0:ERROR-CONTROL:F1:LAP-M:F1
Response Meanings
The second string of each pair of strings is known as the meanings string.
The interpretation of this string defines what the recognized response means to modem control. This includes whether the response is a success, failure, or some intermediate indication. When certain optional connection features are recognized they can be signaled to modem control by this method. Finally, this is the way that bit rates are given to modem control.
There are four types of meanings information: status, feature, rate, and match chaining. The status and feature values are decimal indices into tables used by modem control. The rate decimal value is the actual data rate in bits per second. The match chaining value will be described later.
Character Type Meaning
--------- ---- ---------
'S' STATUS Reports a status; may terminate scanning
'R' RATE Reports a data rate
'F' FEATURE Reports an enabled feature for this connection
'M' CHAINING Continues scanning using another 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. The following status index values are defined:
Value Meaning Value Meaning
----- ------- ----- -------
0 NONE 11 NO_ANSWER
1-5 RESERVED 12 NO_CARRIER
6 OK 13 ERROR
7 RING 14 NO_DIALTONE
8 RRING 15 VOICE
9 CONNECT 16 UNKNOWN
10 BUSY
Rate Meaning
The rate meaning is used to tell 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>:R*S9 or CONNECT <R>:R*S0. This will match any speed response from the
modem, and capture that value to return it in the rate definition command.
Rate Rate Rate Rate Rate
---------------------------------
50 75 110 134 150
300 600 1200 1800 2000
2400 3600 4800 7200 9600
12000 14400 16800 19200 21600
24000 26400 28800 38400 57600
115200
Features Meaning
The feature values indicate to modem control when optional connection
features have been enabled on the current connection. Information on
which features are enabled or disabled is made available to applications.
Applications can use this to determine whether they must independently perform error control or data compression for a connection. The features values are summarized below:
Value Feature Value Feature
----- ------- ----- -------
0 NONE 3 COMPR_V42
1 ARQ 4 UNBALANCED
2 COMPR_MNP 5 SYNC
Match Chaining
The match chaining meaning 'M' directs modem control to continue
matching using the remainder of the input string (after the initially matched portion) and using a different RESPONSES string. This permits the multi-stage matching that is so useful with complex sets of responses like negotiation progress messages. The following example will illustrate:
RESPONSES = ":PROTOCOL:S0M1"
RESPONSES1 = ":NONE:F0:ERROR-CONTROL:F1:LAP-B:F1"
Input 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 done using the RESPONSES1 string.
Modem control begins repeatedly checking the remainder of the input
string against the RESPONSES1 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 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, ARQ, is enabled for this connection.
A new modem description is begun with the MODEM keyword; in this
case we are describing the modem "Hayes Smartmodem 2400". The name
includes the vendor name, a reference to the modem family, and the
particular designation for this model. This name will appear in lists in Novell's configuration programs.
The first OPTIONS keyword line defines the default and maximum
interface data rates that can be used with this modem. The second declares that the common set of modem responses can be expected from this modem. It also specifies that, when requested, a delay of one tenth of a second should be inserted between characters output to the modem.
The INIT keyword lines define the script to be executed by modem control in order to initialize the modem to the "all features off" state. Additionally this script causes the modem to generate verbose return codes which will match those defined for the HAYES option. All of the INIT keyword line values are combined to form one INIT script string in the modem description.
Note: The first output uses the 'o' form when presenting the modem with the "ATZ" command; this will add a delay between output characters. Further output uses the 'O' form as we expect that the modem will respond to following commands without trouble.
The third INIT keyword line illustrates use of the 'W' substitution marker.
In this case we are inserting the connection wait time value into the last initialization command output to the modem.
The HANGUP keyword script illustrates the extent to which we try to
force an ongoing call to be disconnected. We try several techniques as we can not assume what prior state we may have been in. First a carriage return is output in case we had sent a partial modem command. We then try to escape from data mode by using this modem's established method for doing so: pause for a one second, output "+++", then pause for another second. We then accept and ignore the "OK" response if we escaped data mode. As a final attempt to capture the modem's attention and switch it into command mode we turn off DTR for one second and then turn it on again. We now assume we have the modem in command mode and so output the hang-up command.
The DIAL keyword script illustrates the use of two more substitution
markers, "[T]" and "[N]". Depending on the configured setting modem
control will either substitute a 'T' or 'P' character in place of "[T]".
Modem control will substitute the dial operation telephone number string in place of the "[N]" marker. Once this script is executed modem control will begin monitoring responses from the modem for connection status.
The LEASED keyword script illustrates the situation where a modem can
be placed into leased line mode by means of a command. Some modems
are put into leased line modem only through the use of switches on the modem. In that case this script would be absent.
The MANORG and MANANS keyword scripts demonstrate one method that enables many modems to be used with manual dial and answer operation.
Note: The presence of the DIAL, AUTOANSWER, LEASED, and MANORG/MANANS scripts implicitly informs modem control that these features are supported by this modem.
When the OPTIONS keyword option HAYES was used, modem control was told to append the RESPONSES strings that would recognize the common set of industry-standard responses. Since no other RESPONSES strings were defined in this description only the appended strings will be present in the description. This will be equivalent to the following:
This is a description of a more complex modem. This modem implements
several more features, such as fixed rates, hardware flow control, and negotiation progress responses. Much of this description is similar to the previous description. Only interesting differences will be discussed here.
Note: Lines starting with a semicolon are treated as comments.
The INIT keyword script explicitly enables the negotiation progress
responses. In this way modem control can capture the maximum
information about the data connection.
This modem implements both error control protocols and data
compression; the ARQ and COMPRESSION scripts will be used to enable
these features if requested in the modem initialization operation.
This modem uses many more responses than are provided in the common
set of modem responses; all responses to be recognized from this modem are explicitly defined by the RESPONSES keywords. Because of the
complexity of negotiation progress responses, multi-stage recognition is used.
The RESPONSES strings that match "CARRIER" responses illustrate one
situation where the order of match strings is very important. If the
"CARRIER <R>" string were not last it would match either "CARRIER
1200/75" or "CARRIER 75/1200" responses, as the "<R>" would match
the rate values preceding the '/'. This would cause connection information to be missed, in this case that the connection is using unbalanced data rates.
Note: Using the "CONNECT" match string will match all of the balanced rate responses. If an unbalanced CONNECT occurs the first two match strings will be matched. If the response for connections at 300 bps (which does not have a data rate value) occurs the last match string will match.
Environments
Novell's modem control is being implemented in multiple environments. A short description of how modem description files are used in each
environment is given here.
NetWare Server
Modem description files on a Novell NetWare server are placed in a
subdirectory accessible to NLMs (NetWare Loadable Modules). At
present there are two such products on NetWare servers: NetWare
Connect and NetWare MultiProtocol Router.
NetWare Connect
The modem control components of NetWare Connect exist in an NLM
called SYS:SYSTEM\AIO. All files containing compiled modem
descriptions are copied to this subdirectory. When AIO is loaded it
searches this subdirectory for files with the extension MDC (*.MDC). AIO then creates a list of all modem names defined in these files and which file contains the description for each. When one of NetWare Connect's services attempts a modem operation on a port, AIO determines which modem is attached to that port and ensures that 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.
NetWare MultiProtocol Router
The MultiProtocol Router uses uncompiled modem definition files that are placed in the SYSTEM directory. It interprets these files as needed for modem control
DOS
Modem description files in the DOS environment are usually installed in the same directory with the DOS program that uses them. One such program is DIALCON, the connection establishment utility for the NetWare Remote Node (NRN) product in NetWare Connect.
DIALCON is executed by users when they wish to connect or disconnect
the telephone line. DIALCON is also used to configure the parameters for using asynchronous connections; these parameters include the currently selected modem. This information is saved in the NET.CFG file also used by other client network programs.
When a user starts DIALCON, it looks up the current modem name and
then locates the file containing that modem description. The description is loaded into memory and the modem control components perform modem operations using the description. After the requested operations are complete, DIALCON terminates and the in-memory modem description is discarded.
Development & Testing Tools
Novell Labs is in the process of creating development and testing tools for vendors implementing modem description files. They will be made available to developers as they are completed, together with example modem description files.
Novell Labs will also be offering a certification service for modems; the details of which are still being decided.
Please contact Novell Labs at (408) 577-7201 for up-to-date information.
