< Previous PageNext Page > Hide TOC

CCL Command Reference

This chapter describes the CCL commands interpreted by Mac 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.

In this section:

Comments
Labels and Sections
CCL Commands

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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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"

< Previous PageNext Page > Hide TOC