What is it?
The Apple Modem Script Generator is an unsupported tool that provides a relatively easy way to enter the specific information about a modem and then generate a modem script that can be used by both Apple Remote Access (ARA) and Open Transport/PPP (OT/PPP). Apple does not guarantee that the scripts generated will work in all situations, or that the application will be updated in the future.

When should I use it?
Only use the Apple Modem Script Generator (Generator) if you need it. Apple already provides many modem scripts that are installed with ARA and Open Transport/PPP. If you cannot find your modem on the list of scripts in the Remote Access Setup panel (for ARA) or the Modem control panel (for OT/PPP) , then you may need to use the Generator. First, try some other script by the same manufacturer, if possible. Second, check on the Internet if possible because someone may have already created the script you need and posted it there. (See "How can I post my script for others?" below)

Why use scripts with modems?
Modems share an "AT" command set for many commands. The Generator takes care of these common commands without help from you. However, manufacturers tend to use different characters for several settings like speed, result codes, and so forth. There are even examples where one manufacturer will use different characters in different models! Modem scripts are used by the Apple products ARA and OT/PPP to unify the behavior of modems, at least from the perspective of those applications. If one of these applications requests "turn off data compression", the modem script is used to translate that general request into a specific command for the chosen modem.

How do I install a script that I generate?
Put it in the folder described by the path "System Folder:Extensions:Modem Scripts:". This is the default folder selected by the Generator when you click the Create button. You do not need to restart the computer after adding a modem script. ARA 2.1 and OT/PPP both will recognize a new script placed in this folder (in older ARA versions, you must quit the application and restart). After you have placed the script in the folder, it should show up on the appropriate popup menu in ARA or OT/PPP. Remember to choose it there!

What is a modem script? How can I edit a script?
A modem script is a text file, but one which does not have the "file type" of a text file. A modem script can be viewed and edited with any word processor which has an option to open "any file", regardless of file type. (Alternatively, you can change the file type to TEXT with ResEdit, and open with any text editor.) The purpose of the Generator, however, is to spare you from having to edit the nuts-and-bolts text. The text in scripts is written in the "CCL" language that is described in Apple developer documents. Another application by Apple, the Apple Remote Access Modem Toolkit, has more editing features and is available from Apple ( call 800 282 2732 or 716 871 6555 ). Note that the Toolkit v.2.0 is geared for ARA scripts, not for OT/PPP. A revision is planned for the Toolkit.

Can I hurt anything by trying a new script?
Generally speaking, modem scripts are safe because they cannot physically harm any hardware. At worst, a script could configure a modem incorrectly, but turning the modem off and then back on will generally reset the modem to its factory settings. Apple applications cannot be harmed by a script mistake; they are programmed to issue error messages to help identify mistakes within scripts.

What values should I enter into the Generator?
You'll need to find about several pieces of information from your modem manual. Modems are always accompanied by a manual describing their commands, in our experience. See the descriptions below for details about each piece of information that you need. Note: You can click on the label of a field in the Generator, like "Base Speed", to make the help text scroll immediately to information on that item. Finally, click on the Create button to save your newly generated script in the Modem Scripts folder. Then try it out!

Script Type:
Serial Modem is the only script type currently supported.

Modem Name:
Enter the model name of the modem. This information is used to identify the file, but not used in commands. Example: Durendal Screamer 288

Manufacturer :
Enter the manufacturer's name, the name of the company which made the modem. This information is used to identify the file, but not used in commands. The field may be left blank.

Modem Initialization String:
Enter the combination of commands which will make the settings in your modem as listed below. The individual commands are combined on one line to create a "string" of characters to be issued when the modem is used by ARA or OT/PPP. In the descriptions that follow, the examples are taken from a manual for a US Robotics Courier modem. The example commands are enclosed within quote signs which are not included in the final initialization string.

1. Reset the modem to factory default settings, usually "&F". This should be the first command in the string. If any of the following settings are already part of the factory settings, they can be omitted from the initialization string. However, since manuals can be wrong, it may be safer to be redundant.

2. Disable command echo, usually "E0"

3. Enable data compression and error correction if your modem has these capabilities, in this case by factory default. These settings are usually turned on by factory default. (Note: be sure to supply the disable commands for data compression and error correction as described in separate sections below. Data compression and error correction are under the control of a checkbox in OT/PPP, but are always turned off in ARA, under the scheme "on at initialization, off by disable command.") If there are problems with the script, experiment with this part of the initialization string since this is a problematic area

4. Lock the serial port speed (IMPORTANT!), in this case "&B1". This is the default case for many modems. This issue is described in some manuals as "Negotiation of modem-to-modem (DCE) speeds" or "BPS rate adjust", etc. During a connection between two modems, the modems may renegotiate their communication speed. Whatever happens between the modems, we want the modem-to-computer (DTE) speed to remain constant.

5. Enable hardware flow control ("handshaking" CTS/RTS), in this case "&H1&R1". This is the default case for many modems.

6. Disable software flow control (handshaking XOFF/XOFF), in this case by factory default. This is the default case for many modems.

7. Enable "verbose result codes", in this case by factory default (usually "Q0").

8. Enable result codes for compression and protocol changes, in this case "&A3".

9. Set so that CONNECT returns DCE speed (IMPORTANT!), usually "X4".

10. Disable auto-answer, usually "S0=0"

11. Enable return-to-command-mode on DTR toggle (optional), in this case "&D2".

12. Set register S7 to allow enough wait time for international calls, usually "S7=60". An international call can require 60 to 120 seconds of waiting for the remote server to answer. Most modems default between 30 and 60 seconds.

The summation of these commands for our example modem is Example: &FE0&B1&H1&R1X4&A3S0=0&D2S7=60

Base Speed:
Select the speed for the computer's serial port that is closest to, but greater than, your modem's maximum, uncompressed speed . You are setting the speed for communication between the computer and the modem. We call this setting "base speed" to contrast with "compressed speed" described in the next paragraph. Determine your modem's maximum, uncompressed speed from its manual or its model name. Most modems are clearly marked or named with their maximum, uncompressed speed, like 9600, 14.4K, or 28.8K. For example, a modem like an Express Modem 14400 has a maximum, uncompressed speed of 14.4K (14400) and should use a base speed in the computer's serial port of 19200. A modem with a 28.8K (28800) base rate should use a 38400 rate, etc.

Example: 19200

Compressed Speed:
Select the speed for the computer's serial port that is approximately double the modem's maximum, uncompressed speed (in most cases). This setting is used by OT/PPP, not ARA. Some modems can do data compression within the modem itself. In those cases, the computers must communicate faster with the modems, usually at double the base speed. Some modem manuals say to use quadruple the base speed, but we have rarely seen the actual compression ratio get above two. If your modem does not offer data compression, just use the times-two formula for the setting. Note: the computer's serial port has a maximum speed of 115200 on newer models, and below that on some older models, so there is a physical limitation on the speed that the computer can communicate with the modem. A modem with a 14.4K (14400) maximum, uncompressed speed and the ability to compress data in the modem should use a setting of 2 x 14400= 28800, so choose the next greater setting, 38400, for the Compressed speed setting of the serial port.

Example: 38400

Disable Error Correction:
Enter the command which will turn off error correction in the modem. Only modems which have the ability to do error correction will have enable/disable commands.

Disable Data Compression:
Enter the command which will turn off data compression in the modem. Only modems which have the ability to do data compression will have enable/disable commands.

Command Buffer Size:
Use the default of 40 characters unless you have a relatively old modem, perhaps an older 9600-baud model or older. If so, enter the size of the modem's command buffer from the manual. This buffer size is the number of characters that can be sent to the modem in one command line. For example, our example initialization string above is 27 characters. The command buffer must be at least 27 characters long for this string to fit. If the command buffer is small, the applications will split up longer command strings to send in pieces, if possible. Any spaces within a string are usually discarded and do not occupy space in the buffer.

Use Data Tone:
The use of a data tone is a feature of modern modems. You may need to turn off the use of data tones if the usual command for using a data tone, the carat symbol "^", is not understood by your modem. Data tones are useful in one situation: a modem answering at the other end of a connection may be capable of detecting a human voice (and switching to voice mail instead of data). So the calling modem must indicate, for those modems, that the call is a data call. The calling modem emits a "data tone" for this purpose.

Special Characters:
Commands required by a modem may include non-printing or special characters which may be interpreted incorrectly unless these characters are "escaped". The Generator handles three special characters automatically for you: the backslash ("\"), the caret symbol ("^"), and the double quote ("""). These are "escaped" for you when you click the Create button. You just enter them like other characters. In the unlikely case that a modem needs a character which must be escaped, you must use a text editor to do so (see section on "What is a modem script? How do I edit it?"). The escape character for the CCL language is the backslash, so entering a character with an ASCII decimal code of 14 would be "\14".

Troubleshooting:
1. Check both the modem and its connections by using any of "terminal window" communication program like ClarisWorks® or MicrophoneTM. (There are many freeware and shareware communications programs also. Many modem ship with such software.) Programs like these do not use any modem script files. Follow the instructions for setting up one of these programs, and then type in "AT" (no quotes) and hit the return key. Check that the modem is communicating properly with the computer: it should respond "Ok" to the command "AT". Remember to quit the program when you're finished or it will continue to occupy the serial port, prohibiting other tests.

2. Check that expected factory default settings are actually in place. Sometimes the factory defaults are documented to configure the modem in a given way, but in fact the documentation is obsolete. Try issuing these commands explicitly in the initialization string. This is especially possible for error correction (reliability) and data compression commands.

3. Check error correction & data compression, which are optional in OT/PPP, but should be turned off in ARA: Connect to a PPP server which has a modem capable of error correction/data compression using OT/PPP with error correction turned on via the checkbox in the Options dialog. Watch for the error correction and data compression negotiation report as in the status box (the text which confirms this fact flashes by pretty fast during connection; that text is recorded in the log only in Administration mode.) Connect to an ARA server using ARA and watch the serial data or the modem's error correction light, if available. The modem should always connect without error correction and data compression.

4. Check that your modem handles the "Data Tone" command by unchecking this option in the Generator. (See the description of Data Tone above.) A symptom for problems with the Data Tone command would be a 'No Carrier' response when dialing.

5. Compare the script you generated with the script installed by OT/PPP, using a text editor. Note: ARA 2.1 installs some older scripts which turn off error correction/data compression in the initialization string. OT/PPP updates these scripts.

Click here to download Apple Modem Script Generator

Click here for a screenshot

Disclaimer:
This is an unsupported tool. Apple makes no warranty or representation, express or implied, with respect to this program, its quality, performance, or fitness for a particular purpose.

Taken from the apple Technical Information Library. Original article located @ http://til.info.apple.com/techinfo.nsf/artnum/n30730