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"