CCL Command Reference
This chapter describes the CCL commands interpreted by OS X. 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.
Comments
To insert a comment or a blank line in the script, start the line with an exclamation point.
- Syntax:
! comment
- Examples:
! Turn echo off
!
Labels and Sections
@ANSWER
The @ANSWER
section label marks the script entry point when the script is executed in answer mode.
- Syntax:
@ANSWER
@CCLSCRIPT
Available only in OS X.
The @CCLSCRIPT
section label marks the start of a CCL script. The label is optional and has no functional purpose..
- Syntax:
@CCLSCRIPT
@HANGUP
The @HANGUP
section label marks the script entry point when the script is executed in hangup mode.
- Syntax:
@HANGUP
@LABEL
The @LABEL
command 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–128 that specifies the label number.
- Example:
@LABEL 30
@ORIGINATE
The @ORIGINATE
section label marks the script entry point when the script plays in originate mode (that is, when initiating a call).
- Syntax
@ORIGINATE
CCL Commands
ASK
The ASK
command 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
Echo the user's input/
- 1
Mask the user's input with bullets (••••).
- 2
Do not allow user input.
message
The string to display in the dialog box as a prompt for the user.
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.
- Example
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
The CHRDELAY
command 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 delay |
- Parameter
delay
The delay time, in tenths of a second.
- Example
CHRDELAY 8
COMMUNICATINGAT
For V.32bis devices that support RTS/CTS hardware flow control (including modems with an appropriate cable, as described in Cable Specifications), 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 OS X’s internal timers are based on the connection speed.
- Syntax
COMMUNICATINGAT baud
- Parameter
baud
The modem speed, in bits per second.
- Example
COMMUNICATINGAT 4800
DECTRIES
The DECTRIES
command 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
The DTRCLEAR
command clears (that is, deasserts) the Data Terminal Ready (DTR) signal on the RS-232 interface.
- Syntax
DTRCLEAR
DTRSET
The DTRSET
command 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.
If the script executes successfully, have it return a result code of
0
.If the script fails for any reason, it should return the appropriate error result code, as listed in Result Codes
To give the user a nonstandard error message, use result code -6002 and use the string parameter to pass the nonstandard error message.
- Syntax
EXIT result ["string"]
- Parameters
result
-
One of the CCL result codes listed in Appendix A, "Result Codes".
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 message that OS X 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
The HSRESET
command 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 device that supports RTS/CTS handshaking, 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 OS X, it must be off.
outputCTS
CTS hardware handshaking for output. For a modem, if you are using a cable that supports RTS/CTS handshaking, it should be on for originate and answer modes and off for hangup mode.
XON
Specifies the XON character. (DO NOT USE with OS X.)
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 executing in answer mode, the IFANSWER
command causes execution to continue at the specified label.
- Syntax
IFANSWER jumpLabel
- Parameter
jumpLabel
The label to which execution should conditionally jump.
- Example
IFANSWER 30
IFORIGINATE
If the script is executing in originate mode, the IFORIGINATE
command causes execution to continue at the specified label.
- Syntax
IFORIGINATE jumpLabel
- Parameter
jumpLabel
The label to which execution should conditionally jump.
- Example
IFORIGINATE 7
IFSTR
The IFSTR
command compares two strings: one of the variable strings (described in Variable Strings (varStrings)) and a literal string 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 which execution should conditionally jump.
compareString
The string to which the variable string is compared.
In the following example, if the modem speaker flag (varString2
) is on (1
), execution jumps to label 55
. Otherwise, the next command is executed.
- Example
IFSTR 2 55 "1"
IFTRIES
The IFTRIES
command 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 commandsDECTRIES
, INCTRIES
, and SETTRIES
.
- Syntax
IFTRIES numTries jumpLabel
- Parameters
numTries
The parameter to compare with the variable
tryCounter
.jumpLabel
The label to which execution should conditionally jump.
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. If not, the next instruction is executed.
- Example
IFTRIES 3 62
INCTRIES
The INCTRIES
command increases the variable tryCounter
by one. See also the commands DECTRIES
, IFTRIES
, and SETTRIES
.
- Syntax
INCTRIES
JSR
The JSR
command 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 where execution should continue after the jump.
- Example
JSR 50
JUMP
The JUMP
command causes script execution to continue at the specified label.
- Syntax
JUMP jumpLabel
- Parameter
jumpLabel
The label where execution should continue after the jump.
- Example
JUMP 59
LBREAK
The LBREAK
command 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 the MATCHCLR
command before loading each new group of strings. See also the MATCHREAD
and MATCHSTR
commands.
- Syntax
MATCHCLR
MATCHREAD
The CCL interpreter has a buffer that holds up to 32 strings loaded by the MATCHSTR
command. 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 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 MATCHCLR
and MATCHSTR
commands.
- 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. The MATCHSTR
command 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–32 specifying which string in the buffer to replace.
matchLabel
The label where execution should continue when a
MATCHREAD
command detects a matching string.matchStr
A string (1–255 characters in length) 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"
MONITORLINE
Available only in OS X.
Enables or disables Data Carrier Detect (DCD).
- Syntax
MONITORLINE monitor
- Parameters
monitor
0
Disable DCD (soft carrier mode).
1
Enable DCD (hard carrier mode).
The following example enables data carrier detect.
- Example
MONITORLINE 1
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.
- Syntax
NOTE msgStr [msgLevel]
- Parameters
msgStr
The message to display.
msgLevel
The message level (the default level is 3).
- 1
Send the message to the activity log only.
- 2
Send the message to the Internet Connect status window only.
- 3
Send the message to both the activity log and the Internet Connect 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 Internet Connect status window and the activity log. In the second example, the script displays the speed of the connection in the Internet Connect 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
The RETURN
command terminates a subroutine. Script execution continues with the line following the JSR
command.
- Syntax
RETURN
SBREAK
The SBREAK
command generates a short break (.5 seconds) on the transmission line.
- Syntax
SBREAK
SERRESET
The SERRESET
command 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
,14400
,19200
,28800
,38400
,57600
, and so on.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
SETSPEED
The SETSPEED
command 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 OS X.
- Syntax
USERHOOK opcode
- Parameter
opcode
The user hook to execute.
1
Indicates 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
Reports that the modem is doing error correction (other than MNP10, which is indicated by opcode 4).
3
Requests that OS X turn off its built-in data compression.
4
Reports 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 device.
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).)
- Example
WRITE "ATDT^1\13"
Copyright © 2007 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2007-06-28