C-Worthy (R) Help Librarian Data File Version 1.0 COPYRIGHT (C) 1985 - 1989. All Rights Reserved. Custom Design Systems, Inc. Orem, Utah USA. 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. 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 descriptions are stored in files with the extension .MDC. These files contain all the information, initialization strings, and responses for a set of modems. The manufacturer string value may be up to 80 characters in length. Currently this value is not directly used by modem control components, but is provided for use by modem vendors. The copyright string value may be up to 80 characters in length. Currently this value is not directly used by modem control components, but is provided for use by modem vendors. The version numbers may have numeric values from zero to 255. Currently these values are not directly used by modem control components, but are provided for use by modem vendors. Version information should be added to allow tracking of additions or corrections to description information. The version numbers may have numeric values from zero to 255. Currently these values are not directly used by modem control components, but are provided for use by modem vendors. Version information should be added to allow tracking of additions or corrections to description information. This is a list of all the modem descriptions within the selected file. 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. 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. this is descr form The modem name string value may be up to 39 characters in length. This name 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 may be found that the 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 period, it is possible to create two descriptions. Modem Name = "XYZ Ultra Xxxx" Modem Name = "XYZ Ultra Xxxx (Slow Init)" 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 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." this is the modem name file field this is modemname field this is options field 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 the modem response strings can be recognized. This script causes the modem to disconnect any call that might be in progress. (i.e. place the modem "on hook") This script should specifiy all needed operations to ensure the call is disconnected, irrespective of the current modem state. 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]". 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. 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. 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 the connection initiation and detect when the connection is complete and data transfer may begin. 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. 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 option. 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. 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 file only specifies the preferred method to be used. Through monitoring of negotiation process responses the modem control components can be informed of the characteristics of the method activated. 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.R0 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 scripts are defined: Responses Substring 1 Substring 2 Substring 3 Substring 4 The first script 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. 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. This script is executed when a 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. this is responses prompt fieldX9 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: Toggle Break Toggle DTR Flush Buffers Wait for Input (must match) Conditional Input (optional match) Output string Output w/ delay (delay between characters) Quiet Wait (idle time on DTE) Pause Change Data Rate (change DTE interface rate)l< Toggle Break: 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 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. Toggle DTR: 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. If a time value is not given then the default DTR off time of one half second will be used. Set Interface Data Rate: 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. 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: 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 flush operation can be set to flush any combination of input and output buffers. Input String: 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 `conditional match' The operation 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. Also needed is a delimiter character. This is the character which sets the beginning and end of the input string. The delimiter is a character which is not used in the actual text of the input string. 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: 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. There are two types of output operations, a `straight output' and `output w/ delay'. If it is necessary to insert a delay between characters the `output w/ delay' 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 "ATD[T][N]'M" where [T] is replaced with 'T' or 'P' and [N] is replaced with a dial number..N Only a limited number of substitution tags are defined, and the substituted strings are not variable by modem type. The pre-defined tags are: T dial tone/pulse modifiers: `T' or `P' N dial phone number: supplied by application R ring count: used on initialization 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: 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. A time value can be given which determnes how long (in tenths of a second) the pause will last. If a time value is not given then the default time value of one second is used (time = 10). Quiet: 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. A time value can be given which determnes how long (in tenths of a second) the pause will last. If a time value is not given then the default time value of one second is used (time = 10). This 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. 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. Status Report Status; may terminate scanning. Rate Bit rate of connection. Features Reports an enabled feature for this connection. Chaining Continues scanning of the response in the selected substring. Status Meanings: 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: Status Values none IGNORE INFO1 INFO2 INFO3 INFO4 OK RING RRING CONNECT BUSY NO ANSWER NO CARRIER ERROR NO DIALTONE VOICE UNKNOWN Rate Meanings: 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 -value selection. This will match any speed response from the modem, and capture that value to return it in the rate definition command. Rate Values 50 75 110 134.5 150 300 600 1200 1800 2000 2400 3600 4800 7200 9600 19200 38400 57600 115200 -Value Features Meanings 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: Features none error control MNP 5 V.42bis unbalanced 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 substring. This permits the multi-stage matching that is so useful with complex sets of responses like negotiation progress messages. For the example response string : "PROTOCOL: ERROR-CONTROL" The first string is part of the first stage matching string formed from the Responses list. 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 Subtring1 list. Modem control begins repeatedly checking the remainder of the input string against the Substring1 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, error control, is enabled for this connection. When a modem operation specifies use of a 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. this is the defaultrate field 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. 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). 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 the modem control should wait between outputting characters. There are two script operations for output: one inserting delays between characters and the other not delaying between characters. If this option is not specified the default delay will be zero (and thus no delay at all). This option appends a basic set of Hayes responses to a list of all possible responses. The description of the modem selected off the list of the available modems will be copied onto the descriptions of any modems selected from this list. Use F5 to mark/unmark the selections, and Esc to return to the list of available modems when finished (or cancelling). A confirmation message will appear to verify the requested operation.