Remote Access: Modem Script Basics

This document details conventions used in creating or modifying a modem script for use with Remote Access under Mac OS 9 or Internet Connect under Mac OS X.

This document explains the conventions your Apple Remote Access modem script must follow and describes the basic tasks it must perform. For detailed descriptions of the modem scripting commands, see technical document 42658 "CCL Command Glossary."

What is a modem script? A modem script is a set of instructions that tells a computer how to interact with a modem so that calls can be initiated and received. To establish a connection, a script typically configures and then connects the modem. To terminate a connection, the script disconnects the modem by hanging up and then restores the modem settings that were in effect before the call. Each type of modem used with Apple Remote Access or Internet Connect requires a modem script. Many scripts are provided with the software (see the Modem control panel or the Modem tab in the Network pane in System Preferences). If no script is provided for your modem, you must write or modify one using Communication Command Language (CCL), a programming language that configures and controls your modem. Existing scripts can be edited in most text editors. For Mac OS 9 and earlier the file type may need to be changed after modifying the document. The file type is "mlts" and can be changed with many disk utilities including ResEdit. This document describes the basic elements and structure of a CCL file.

Script conventions

The following sections describe CCL script conventions for



Instructions
Each line of CCL code consists of one instruction that is made up of a command and its parameters, if any. Modem commands are used as parameters of CCL commands. For example, the command write "ATDT^1\\13" includes the following:
write -a CCL command
ATDT -a modem command
^1\\13 -a modem command parameter

This command tells the CCL interpreter to send to the modem the modem command ATDT followed by variable string 1, and a carriage return (ASCII code 13). The CCL interpreter reads scripts from left to right and from top to bottom. It reads straight through, from beginning to end, unless you tell it otherwise (for example, by using the JUMP command).

Comments
You can insert explanatory comments into your script. To enter a comment, start the line with an exclamation point (!).
!  This is a sample comment and would be ignored by the script.
!
You may also want to use a blank comment line to make your script more readable; to do so, type an exclamation point with no text and press Return.

Capitalization
The CCL interpreter is not case-sensitive. Therefore,
@LABEL 1
@Label 1
@label 1
@laBel 1
are all valid instructions.

Labels
Labels are used to mark locations in the script. Other script commands, such as JUMP, transfer control to locations in the script marked by the @LABEL command. For instance, JUMP 13 tells the CCL interpreter to jump to label 13 and start executing the commands after the @LABEL 13 command. A script may use up to 128 labels, numbered 1 to 128.

Script resources
A modem script may contain an optional mlts resource with resource ID 0. This resource contains data that tells the CCL interpreter the characteristics of the modem. An mlts resource contains five unsigned bytes indicating the modem's error correction and command string limitations.

Byte 1 Indicates the modem's error correction capability:


Byte 2 Reserved by Apple.

Byte 3 Indicates the maximum length of the first dial string fragment (in varString7; for details, see "Variable Strings (varStrings)" later in this chapter) passed to the script by the CCL interpreter. Check your modem documentation to determine the maximum number of characters your modem can accept in an AT command.

Byte 4 Indicates the maximum length of the second dial string fragment (in varString8) passed to the script by the CCL interpreter.

Byte 5 Indicates the maximum length of the third dial string fragment (in varString9) passed to the script by the CCL interpreter. If your script has no mlts resource (for example, if it is an Apple Remote Access 1.0 script), the CCL interpreter assumes a maximum length of 30 characters for each of the dial string fragments, and it assumes that the modem cannot negotiate a reliable link.

To create a script resource, follow the instructions in 42661 "How to Create an "mlts" Resource."

String formats
To delimit a string in CCL code, you can use single quotation marks (') or double quotation marks ("). If you do not start the string with a single or double quotation mark, any of the following characters determines the end of the string: space, return, tab, comma, or semicolon.

CCL strings may include references to variable strings (varStrings). See "Variable Strings (varStrings)" later in this document for details.

CCL strings may include nonprinting characters such as null, tab, and return. To specify one of these characters in a string, precede it by an escape character. The CCL interpreter recognizes two escape characters: the backslash (\\) and the caret (^).

The backslash is used to include a character by specifying the decimal representation of the ASCII character (decimal numbers 00 to 99 are valid), or to include the backslash or caret character in a string.

The caret is used to insert a variable string or an ASK string into another string. (For details, see "Variable Strings (varStrings)" later in this document.) Here are some examples of how the backslash and caret are used:


Here are some string examples:
'this is a test' yields this is a test
thisisatest yields thisisatest
"this is a test" yields this is a test
this is a test yields this
"this \\34\\73\\83\\34 a test" yields this "IS" a test

If variable string 1 is 555-1212, then
"ATDT^1" yields ATDT555-1212

Variable strings (varStrings)
CCL strings may include references to variable strings (varStrings), which are strings passed to the script as parameters. VarStrings 1- 4 and 6 are defined by Remote Access or the Network panel VarStrings 7-9 are defined by the CCL interpreter based on varString1 and bytes 3-5 of the mlts resource. VarString5 is reserved for future use by Apple.

Apple Remote Access uses the following varStrings:
varString1 the complete dial string (the telephone number to dial, with the necessary prefixes and suffixes)

varString2 the modem speaker flag 0 speaker off 1 speaker on

varString3 the tone/pulse dialing selector T tone dialing P pulse dialing

varString4 the modem error correction flag 0 script should not try to use modem error correction 1 script should try to use modem error correction 2 script should try to establish MNP10 error correction

varString6 the dialing mode flag 0 normal dialing 1 blind dialing (that is, have the modem begin dialing without confirmation of dial tone detection) 2 manual dialing (that is, have the script assume that the user has already picked up the phone and dialed the remote number)

varStrings7-9 varStrings 7-9 break a long dial string into shorter strings for use with modems that can accept only a limited command string size. They are automatically generated by Apple Remote Access. varString7 contains the first characters of varString1. Its maximum length is defined by byte 3 of the mlts resource (see "Script Resources" earlier in this document). If varString7 contains all the characters included in varString1, varString8 contains a blank string (ASCII 20 hex). If varString1 includes more characters than can be contained in varString7, varString8 contains some or all of the additional characters. Its maximum length is defined by byte 4 of the mlts resource. If varString7 and varString8 contain all the characters included in varString1, varString9 contains a blank string. If varString1 includes more characters than can be contained in varString7 and varString8, varString9 contains some or all of the additional characters. Its maximum length is defined by byte 5 of the mlts resource. Note: If you do not create an mlts resource for your script (as described in "Creating an mlts Resource" in the Apple Remote Access Modem WorkShop User's Guide), the CCL interpreter assumes a maximum length of 30 characters for each of the dial string fragments.

All eight varStrings are passed to the script when it is running in originate mode. The modem speaker flag (varString2) and the error correction flag (varString4) are passed to the script when it is running in answer mode.

Match strings
The CCL interpreter has a buffer that can hold up to 32 strings loaded by the MATCHSTR command. The MATCHCLR command erases the contents of the buffer. The MATCHREAD command reads input from the serial driver and compares the input to the strings currently in the buffer. If a match is found in the specified time, execution continues at the label associated with that match string. A recommended strategy for sending commands to the modem is as follows:



Script size
Scripts used in Modem WorkShop may be a maximum of 30 kilobytes. (You can write quite a detailed script in 30 kilobytes.) If your script is too large, you may be able to make it small enough by minimizing the number and length of comments.

Tasks your script must perform
A modem script executes in one of three possible modes, each with a separate entry point. The modes are as follows:
originate used when a call is initiated
answer used when call answering is enabled
hangup used to terminate every connection, whether in originate or answer mode, and whether or not the connection was successful

Figure 1 below provides an overview of the tasks your script must perform in each mode. The remainder of this document describes these tasks.



Figure 1 Script tasks for each mode

Initiating a call
When you signal the Apple Remote Access program to initiate a call, it plays the script starting at the @ORIGINATE entry point. The script must perform the following tasks to initiate a call:

  1. Configure your computer's serial port. Use the SERRESET command to reset the serial port's communication parameters. Set the speed of the connection to the maximum speed of the modem. (You may change the serial port speed later in the script.) Set the number of bits to be used for stop, start, and parity. Use the HSRESET command to turn off the serial port's flow control options. (You will turn on the appropriate options later in the script.)

     

  2. Configure the modem. Following is a list of standard steps for configuring a modem. Check the documentation that came with your modem to determine whether it requires different steps.
    1. Recall the factory default configuration settings.
    2. If your modem has a speed of 14,400 bit/s or higher, you need to set up the modem for CTS/RTS handshaking and an appropriate cable must be used, as described in technical document 42660 "Remote Access: Cable Requirements." Do not turn on hardware handshaking until the connection has been made.
    3. Configure the modem for DTR usage.
    4. Turn local echo off. When local echo is on, the modem sends commands it receives back to the computer.
    5. Set the modem to return detailed result codes including the speed of the connection and the results of error correction and data compression negotiation.
    6. If the modem can do error correction, set error correction according to varString4. If varString4 is set to 0, turn error correction off. If varString4 is set to 1, have the modem negotiate the best available error correction with the remote modem. If no error correction can be established, have the modems remain connected without error correction. If varString4 is set to 2, have the modem try to establish MNP10 error correction with the remote modem. If MNP10 negotiation fails, have the modems remain connected without error correction. Note: If the modem uses a proprietary error correction protocol, make sure that it will try to negotiate standard protocols if it is unable to negotiate the proprietary protocol. If not, disable error correction. Note: Do not disable Trellis error protocol, which is part of the V.32 standard.
    7. Apple Remote Access is generally more efficient than a modem at compressing data. If you believe you have a special situation in which modem data compression is preferable, have the script set up the modem to negotiate data compression.
    8. Turn the modem speaker on or off according to the value of varString2.

     

  3. Dial the phone number.

     

    1. Have the script check whether the dial string extends into varString8 (then varString9) by using the IFSTR command to check for a blank string. If the entire dial string fits in varString7, have the script issue a single dial command. If the dial string is longer than varString7, have the script issue multiple modem dial commands referencing varStrings 7 and 8, and if necessary, varString9.

       

    2. Set tone or pulse dialing in the modem dial command according to the value of varString3.

       

    3. If varString6 is set to 1, have the modem begin dialing without confirmation of dial tone detection. This is useful when the phone system provides a nonstandard dial tone that can't be recognized by the modem's tone detection circuitry. If varString6 is set to 2, the user will already have dialed the remote number. Have the script cause the modem to retrain with the remote modem. This is useful when the dialing sequence is too complex or interactive for the modem script to navigate.

       

    4. Display the dialed phone number in the Apple Remote Access Status window and the Activity Log. Use varString1 in log messages rather than a concatenation of varStrings 7-9.

     

  4. Wait for the modem response.

     

  5. If the call fails, return an error result code indicating what happened. For example, use error result code -6022 if the line is busy. (See technical document 42659 "Remote Access: CCL Result Code Listing," for a complete list.)

     

  6. If the call is successful, indicate that a connection has been established. Display a message such as "Communicating at 9600 bit/s" in the Apple Remote Access Status window. Also display messages indicating the results of error correction and data compression negotiation, if applicable. If you were successful in establishing modem error correction, issue USERHOOK 4 (for MNP10 error correction) or USERHOOK 2 (for all other error correction) to advise Apple Remote Access that a reliable link was established. If you were successful in establishing data compression, issue USERHOOK 3 to advise Apple Remote Access to turn off its built-in data compression.

     

  7. Configure the serial port based on the modem speed and the connection. If your modem has a speed of 14,400 bit/s or higher and if you are using a CTS/RTS handshaking cable (see technical document 42660 "Remote Access: Cable Requirements"), use the HSRESET command to set flow control for outputCTS. Use the COMMUNICATINGAT command to tell Apple Remote Access the connection speed so that it can set its timers appropriately. If your modem has a speed of 9600 bit/s or slower, use the SERRESET command to reset the serial port speed to the speed of the connection.

     

  8. Exit the script so that the Apple Remote Access program can continue with its internal execution.


Answering a call
To answer a call, the Apple Remote Access program plays the script starting at the @ANSWER entry point. The script must perform the following tasks to answer a call:

  1. Configure your computer's serial port. Use the SERRESET command to reset the serial port's communication parameters. Set the speed of the connection to the maximum speed of the modem. (You may change the serial port speed later in the script.) Set the number of bits to be used for stop, start, and parity. Use the HSRESET command to turn off the serial port's flow control options. (You will turn on the appropriate options later in the script.)
  2. Configure the modem. It will require several modem commands to completely configure the modem. To prevent calls being answered before the configuration is complete, disable auto-answering in the first modem command the script issues. (You will enable it in step 3.) For additional details about configuring the modem, see step 2 of "Initiating a Call" earlier in this document.
    1. Recall the factory default configuration settings.
    2. If your modem has a speed of 14,400 bit/s or higher, set up the modem for CTS/RTS handshaking and use an appropriate cable, as described in technical document 42660 "Remote Access: Cable Requirements"
    3. Configure the modem for DTR usage.
    4. Turn local echo off.
    5. Set the modem to return detailed result codes including the speed of the connection and the results of error correction and data compression negotiation.
    6. If the modem can do error correction, set error correction according to varString4.
    7. Apple Remote Access is generally more efficient than a modem at compressing data. If you believe you have a special situation in which modem data compression is preferable, have the script set up the modem to negotiate data compression.
    8. Turn the modem speaker on or off according to the value of varString2.
  3. Enable auto-answering and wait for the result. On an incoming call, the modem issues a RING result code.
  4. If the call fails, return an error result code indicating what happened. For example, use error result code -6021 if the modem cannot detect a carrier signal on the phone line. (See technical document 42659 "Remote Access: CCL Result Code Listing" for a complete list.)
  5. If the call is successful, indicate that a connection has been established. Display a message such as "Communicating at 9600 bit/s" in the Apple Remote Access Status window. Also display messages indicating the results of error correction and data compression negotiation, if applicable. If you were successful in establishing modem error correction, issue USERHOOK 4 (for MNP10 error correction) or USERHOOK 2 (for all other error correction) to advise Apple Remote Access that a reliable link was established. If you were successful in establishing data compression, issue USERHOOK 3 to advise Apple Remote Access to turn off its built-in data compression.
  6. Configure the serial port based on the modem speed and the connection. Issue the USERHOOK 1 command. The USERHOOK 1 command informs Apple Remote Access that the serial port is busy answering a call, which prevents the serial port from being given up to another application. If your modem has a speed of 14,400 bit/s or higher and if you are using a CTS/RTS handshaking cable (as described in Appendix B, "Cable Requirements"), use the HSRESET command to set flow control for outputCTS. Use the COMMUNICATINGAT command to tell Apple Remote Access the connection speed so that it can set its timers appropriately. If your modem has a speed of 9600 bit/s or slower, use the SERRESET command to reset the serial port speed to the speed of the connection.
  7. Exit the script so that the Apple Remote Access program can continue with its internal execution.



Terminating a call
To terminate a call, the Apple Remote Access program plays the script starting at the @HANGUP entry point. The hangup part of the script is played to terminate a connection whenever the @ORIGINATE or @ANSWER parts of the script have been played, regardless of the result. The hangup part of the script is also played when Apple Remote Access terminates answer mode because another application gains control of the serial driver or the system is shut down.

Note: Apple Remote Access has a callback feature (see the Apple Remote Access Personal Server User's Guide or the Apple Remote Access Client User's Guide for more information). For callback to work, the script must hang up the modem and prepare it for the return call within 15 seconds, which is the minimum time that the answering side will wait before issuing the callback. The maximum time the calling side (that is, your computer) will wait for a callback is 80 seconds. The script must perform the following tasks to terminate a call:

  1. If hardware handshaking is used in the @ORIGINATE or @ANSWER part of the script, turn off hardware handshaking. Use the HSRESET command to turn off hardware handshaking.
  2. If possible, cause the modem to enter command mode. Before you issue a hangup command, you may need to get the attention of the modem by, for example, issuing a short break, a long break, or the attention sequence "+++," or by toggling DTR. Consult your modem documentation for the appropriate method.
  3. Issue a modem hangup command.
  4. Recall the factory default configuration settings. Since you recalled the default settings at the beginning of the script, this is not necessary if the only communications application you use is Apple Remote Access; however, recalling the default settings at the end of your script is recommended in case the next communications application that you use does not take care of this itself.
  5. Turn off auto-answering. This prevents the modem from answering the phone until call answering is enabled.
  6. Exit with an appropriate message. If successful, return a result code of 0. If unsuccessful, return the appropriate error result code as listed in technical document 42659 "Remote Access: CCL Result Code Listing."



Related software downloads

30729 Apple Modem Script Generator 1.0a1 Document and Software

Published Date: Feb 20, 2012