This document describes the CCL commands interpreted by Remote Access or Internet Connect.
This document describes the CCL commands interpreted by the Apple Remote Access program. The commands are presented in alphabetical order. Each command section contains a description of the command; the syntax of the command, including any parameters; and an example, if appropriate.
! Comment
To insert a comment or a blank line in the script, start the line with an exclamation point. Scripts used in Modem WorkShop may be a maximum of 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.
Syntax ! comment
Examples ! Turn echo off !
@ANSWER
@ANSWER marks the script entry point when the script plays in answer mode.
Syntax @ANSWER
@HANGUP
@HANGUP marks the script entry point when the script plays in hangup mode.
Syntax @HANGUP
@LABEL
@LABEL sets a numeric label in the script that can then be referenced from other script commands, such as JUMP, JSR, and IFTRIES. A script may include up to 128 labels, numbered 1 through 128. To make debugging easier, assign the labels in ascending sequence. They don't need to be consecutive.
Syntax @LABEL labelnum
Parameter labelnum -a value from 1 through 128 that specifies the label number
Example @LABEL 30
@ORIGINATE
@ORIGINATE marks the script entry point when the script plays in originate mode (that is, when initiating a call).
Syntax @ORIGINATE
ASK
ASK causes a dialog box to be displayed to obtain information from the user. The dialog box contains a prompt message, an optional data entry field, a Cancel button, and an OK button. You may need the ASK command if your telephone system uses special telecommunications equipment. This command is typically used in originate mode only. "String Formats" in Chapter 1 shows how to use the ASK string as part of another string. The ASK string is set if the user presses either the OK button or the Cancel button.
| Syntax | ASK maskflag " message" [jumpLabel] | |
| Parameters | maskflag | 0 to echo the user's input 1 to mask the user's input with bullets (····) 2 to not allow user input |
| message | the string to display in the dialog box as a prompt for the use | |
| jumpLabel | if supplied, the label to jump to, where execution continues when the Cancel button is pressed; if not supplied, or if the OK button is pressed, then execution continues at the next CCL line | |
| Examples | ASK 1 "Enter your password to access the network." |
|
| ASK 2 "When the remote modem answers, click OK, otherwise click Cancel to stop Manual Dialing." |
||
CHRDELAY
CHRDELAY allows you to specify a delay time between characters for all subsequent WRITE commands. This is useful for telecommunications equipment that requires data at a speed slower than the interface speed.
Syntax CHRDELAY x
Parameter x the delay time, in tenths of a second
Example CHRDELAY 8
COMMUNICATINGAT
For V.32bis modems with CTS/RTS hardware flow control cables (as described in Appendix B, "Cable Requirements") only: Use the COMMUNICATINGAT command to indicate the speed of the modem connection if the modem speed is different from the serial port speed. This is necessary because the Apple Remote Access application's internal timers are based on the modem speed.
Syntax COMMUNICATINGAT x
Parameter x the modem speed, in bits per second
Example COMMUNICATINGAT 4800
DECTRIES
DECTRIES decreases the variable tryCounter by one. The CCL interpreter maintains tryCounter, which you may set to a value and increase or decrease by one. See also the commands IFTRIES, INCTRIES, and SETTRIES.
Syntax DECTRIES
DTRCLEAR
DTRCLEAR clears (that is, deasserts) the Data Terminal Ready (DTR) signal on the RS-232 interface.
Syntax DTRCLEAR
DTRSET
DTRSET sets (that is, asserts) the Data Terminal Ready (DTR) signal on the RS-232 interface.
Syntax DTRSET
EXIT
EXIT terminates execution of the script and returns a result code along with an optional string.
| Syntax | EXIT result [" string"] | |
| Parameters | result | One of the CCL result codes listed in technical document 42659 "Remote Access: CCL Result Code Listing." |
| string | The message displayed to the user when a connection attempt fails; if you include a string for one of the standard result codes, it overrides the one that CCL would normally display | |
| Examples | EXIT -6022 | |
| EXIT -6002 "unable to communicate with PBX" | ||
FLUSH
FLUSH empties all characters from the serial driver input buffer.
Syntax FLUSH
HSRESET
HSRESET sets the serial port's flow control options. If you are using a standard modem cable, you will turn off flow control and leave it off. If you are using a CTS/RTS handshaking cable such as described in technical document 42660 "Remote Access: Modem Cable Requirements," you need only the outputCTS parameter. Turn all options off at hangup.
| Syntax | HSRESET outputXON/XOFF outputCTS XON XOFF inputXON/XOFF inputDTR | |
| Parameters | outputXON/XOFF XON/XOFF | Handshaking for output. For Apple Remote Access, it must be off |
| outputCTS | CTS hardware handshaking for output. For Apple Remote Access, if you are using a CTS/RTS handshaking cable, it should be on for originate and answer modes and off for hangup mode. For more information, see Inside Macintosh, volume 2 (no longer in print) or Inside Macintosh: Devices, available through the Apple Developer Catalog. | |
| XON | Specifies the XON character (DO NOT USE for Apple Remote Access) | |
| XOFF | Specifies the XOFF character (DO NOT USE for Apple Remote Access) | |
| inputXON/XOFF XON/XOFF | Handshaking for input. For Apple Remote Access, it must be off | |
| inputDTR | DTR hardware handshaking for input. For Apple Remote Access, it should be off. For more information, see Inside Macintosh, volume 4 (no longer in print) or Inside Macintosh: Devices, available through the Apple Developer Catalog. | |
| Example | HSRESET 0 1 0 0 0 0 | |
IFANSWER
If the script is playing in answer mode, IFANSWER causes execution to continue at the specified label.
Syntax IFANSWER jumpLabel
Parameter jumpLabel the label to jump to, where execution continues
Example IFANSWER 30
IFORIGINATE
If the script is playing in originate mode, IFORIGINATE causes execution to continue at the specified label.
Syntax IFORIGINATE jumpLabel
Parameter jumpLabel the label to jump to, where execution continues
Example IFORIGINATE 7
IFSTR
IFSTR compares two strings: one of the variable strings (varStrings, described in "Variable Strings (varStrings)" in technical document 42657 "Remote Access: Modem Script Basics") and one that you specify in the script. If the strings are equal, the script continues execution at the specified label.
| Syntax | IFSTR varStringIndex jumpLabel " compareString" | |
| Parameters | varStringIndex | The number of the variable string to compare |
| jumpLabel | The label to jump to, where execution continues | |
| compareString | The string to which the variable string is compared In the following example, if the modem speaker flag (varString 2) is on (1), execution jumps to label 55. Otherwise, the next command is executed. | |
| Example | IFSTR 2 55 "1" | |
IFTRIES
IFTRIES compares a parameter with the variable tryCounter. If the value of tryCounter is greater than or equal to the parameter, the script continues execution at the specified label. See also the commands DECTRIES, INCTRIES, and SETTRIES.
| Syntax | IFTRIES numTries jumpLabel | |
| Parameters | numTries | The parameter to compare with the variable tryCounter |
| jumpLabel | The label to jump to, where execution continues The following example checks to see if the value of tryCounter is greater than or equal to 3. If so, execution jumps to label 62 and continues. | |
| Example | IFTRIES 3 62 | |
INCTRIES
INCTRIES increases the variable tryCounter by one. See also the commands DECTRIES, IFTRIES, and SETTRIES.
Syntax INCTRIES
JSR
JSR causes script execution to jump to the subroutine located at the specific label, saving the address of the line following the JSR command. When a RETURN command is encountered, execution resumes at the line following the JSR command. JSR commands can be nested up to 16 deep.
Syntax JSR jumpLabel
Parameter jumpLabel the label to jump to, where execution continues
Example JSR 50
JUMP
JUMP causes script execution to continue at the specified label.
Syntax JUMP jumpLabel
Parameter jumpLabel the label to jump to, where execution continues
Example JUMP 59
LBREAK
LBREAK generates a long break (3.5 seconds) on the transmission line.
Syntax LBREAK
MATCHCLR
The CCL interpreter has a buffer that holds up to 32 strings loaded by the MATCHSTR command. The MATCHCLR command erases all strings in the buffer. Use MATCHCLR before loading each new group of strings. See also the commands MATCHREAD and MATCHSTR.
Syntax MATCHCLR
MATCHREAD
The CCL interpreter has a buffer that holds up to 32 strings loaded by the MATCHSTR command. MATCHREAD reads input from the serial driver and compares the input to the strings currently in the buffer. If a match is found within the specified MATCHREAD time, execution continues at the label associated with that match string (as defined by the MATCHSTR command that loaded the string). See also the commands MATCHCLR and MATCHSTR.
Syntax MATCHREAD time
Parameter time the time allowed for a match, in tenths of a second The following example searches for a match within 3 seconds.
Example MATCHREAD 30
MATCHSTR
The CCL interpreter has a buffer that holds up to 32 strings. MATCHSTR loads a string to the buffer, so that incoming strings can be matched against it by a MATCHREAD command. If an incoming string matches the stored string, script execution continues at the label specified in the MATCHSTR command. See also the commands MATCHCLR and MATCHREAD.
| Syntax | MATCHSTR matchNum matchLabel " matchStr" | |
| Parameters | matchNum | A value from 1 through 32 specifying which string in the buffer to replace |
| matchLabel | The label to jump to, where execution continues when a MATCHREAD command detects a matching string matchStr a string (1-255 characters) to compare against The following example loads the string "OK\\13\\10" into the buffer as string 1. If a subsequent MATCHREAD reads a string that matches this one, then execution jumps to label 8. | |
| Example | MATCHSTR 1 8 "OK\\13\\10" | |
NOTE
The NOTE command displays status and log information, passing the message string as a parameter. Optionally, you can set the message level to specify where the message should appear. Note: While in answer mode, NOTE does not write to the Activity Log or to the status window.
| Syntax | NOTE msgStr [ msgLevel] | |
| Parameters | msgStr | The message to display |
| msgLevel | The message level 1, 2, or 3 (default is 3) 1 send the message to the Activity Log only 2 send the message to the Apple Remote Access Status window only 3 send the message to both the Activity Log and the Apple Remote Access Status window The following examples show important places in which you should use the NOTE command. In the first example, the script logs outgoing calls by displaying the dialed phone number in the Apple Remote Access Status window and the Activity Log. In the second example, the script displays the speed of the connection in the Apple Remote Access Status window. | |
| Examples | NOTE "DIALING ^1" 3 NOTE "Communicating at 9600 bps." 2 | |
PAUSE
PAUSE causes script execution to halt for a specified period of time.
Syntax PAUSE time
Parameter time the time to pause, in tenths of a second The following example causes script execution to pause for 2 seconds.
Example PAUSE 20
RETURN
RETURN terminates a subroutine. Script execution continues with the line following the JSR command.
Syntax RETURN
SBREAK
SBREAK generates a short break (.5 seconds) on the transmission line.
Syntax SBREAK
SERRESET
SERRESET configures the serial port by passing values for baud rate, parity, data bits, and stop bits to the serial driver. Specifying a value other than the values listed below causes the default value to be used. The defaults for each parameter are listed below.
| Syntax | SERRESET baudRate, parity, dataBits, stopBits | |
| Parameters | baudRate | 300, 1200, 2400 (the default), 4800, 9600, 14,400, 19,200, 28,800, 38,400, or 57,600 |
| parity | 1 for odd parity 2 for even parity 0 or 3 for no parity (the default) |
|
| dataBits | 5, 6, 7, or 8 (the default) | |
| stopBits | 1 for 1 stop bit (the default) 2 for 2 stop bits 3 for 1.5 stop bits |
|
| Example | SERRESET 9600, 0, 8, 1 | Note: Apple Remote Access requires no parity, 8 data bits, and 1 stop bit. |
SETSPEED
SETSPEED sets the asynchronous serial interface speed to the specified speed. Use SETSPEED to set speeds other than those allowed in SERRESET.
Syntax SETSPEED interfacespeed
Parameter interfacespeed the serial interface speed
Example SETSPEED 24000
SETTRIES
SETTRIES initializes the tryCounter variable to the specified value. See also the commands DECTRIES, IFTRIES, and INCTRIES.
Syntax SETTRIES tries
Parameter tries the value to assign to the tryCounter variable
Example SETTRIES 0
USERHOOK
USERHOOK conveys information about the state of the modem to Apple Remote Access.
| Syntax | USERHOOK opcode | |
| Parameter | opcode | 1 to indicate that the script is answering a call and that a ring is indicated by the modem. This prevents other applications from using the serial port until after the call has terminated. 2 to report that the modem is doing error correction (other than MNP10, which is indicated by opcode 4). 3 to request that Apple Remote Access turn off its built-in data compression. 4 to report that the modem is doing MNP10 error correction. |
| Example | USERHOOK 1 | |
WRITE
WRITE writes the specified string to the serial driver.
Syntax WRITE message
Parameter message the message written to the serial driver
The following example sends to the serial driver the modem command ATDT followed by variable string 1 and a carriage return. (For more information, see "Variable Strings (varStrings)" in technical document 42657 "Remote Access: Modem Script Basics."
Example WRITE "ATDT^1\\13"