Introduction

With the Bayonne package a brand new scripting system, ccscript, has been
introduced.  ccscript differs in a number of fundimental ways from other
scripting systems in that it is designed for single-step timed execution
from a callback event thread.  ccscript is therefore a scripting
interpreter that models and controls the behavior of near realtime  
sequenced state-event engines such as the Bayonne server.

ccscript itself offers a programming model that is easy to embed in C++,
that is fully thread safe, and that can be extended thru C++ class
inheritence.  It also offers extremely low call overhead, and has a two
phase compile/memory resident runtime environment.  Finally, ccscript
allows direct runtime reloading of script images without displacing
currently executing scripts.

In the case of Bayonne, we extend ccscript to support telephony functions
of the server.  The main server offers extensions to the core ccscript
language, and each driver can also bind it's own driver specific commands.
In some cases plugins other than drivers will also bind extensions to the
script interpreter.

When the server is started, or when a new "compile" request is made, the
server builds the core memory script image.  While runtime replacement
will happen in a live Bayonne server, it will only occur when a "compile"
request is made thru the fifo interface.

Each script is composed of three parts; an event flag as appropriate,
a script command statement, and script command arguments.

Events

The event flag is used to notify where a branch point for a given event
occurs while the current script is executing.  Events can be receipt of
DTMF digits in a menu, a call disconnecting, etc.  The script will
immediately branch to an event handler designated line when in the "top"
part of the script, but will not repeably branch from one event handler to
another; most event handlers will block while an event handler is active.

The exception to this rule is hangup and error events.  These cannot be
blocked, and will always execute except from within the event handlers
for hangup and/or error themselves.  Event handlers can be thought of
as being like "soft" signals.

In addition to marking script locations, the script "event mask" for the
current line can also be modified.  When the event mask is modified,
that script statement may be set to ignore or process an event that may
occur.

The following event identifiers are considered "standard" for Bayonne:

identifier		default		description

^hangup or ^exit	detach		the calling party has disconnected
^error			advance		a script error is being reported
^dtmf			---		any unclaimed dtmf events
^timeout		advance		timed operation timed out
^0 to ^9, ^a to ^d	---		dtmf digits
^pound or ^star		---		dtmf "#" or "*" key hit
^dialtone		---		dialtone heard on line
^busytone		---		busytone heard on line

Symbol Notation

ccscript recognizes three kinds of symbols; constant "values", %variables,
and @indirection.  A %variable has content that is alterable.  Some
%variables are automatically initialized for each and every telephone
call, while others may be freely created by scripts themselves.

A fourth class of symbol exists only at compile time, $defined symbols are
substituted when the script file is compiled, and usually reduce to a
simple constant, though variables can be named for the compiler.  All
constants are defined in the [script] section of bayonne.conf.

The following variables are commonly defined:

%id		id, timeslot, or trunk device number
%digits		currently collected dtmf digits in the digit buffer
%count		count of number of digits collected
%starttime	time of call starting
%startdate	date of call starting
%duration	current call duration
%did		did number if available
%ani		ani number if available
%callerid	caller id number if callerid
%callername	caller name if passed in callerid
%rings		number of rings
%start		script that was initially started
%schedule	script that was scheduled
%group		trunk group of line
%language	current language in effect (default = "english")
%voice		current voice library in effect (default = "UsEngM")
%volume		volume level in 0-100 for play and record.
%extension	default audio file extension (.au, .wav, etc)
%format		default audio format (ulaw, alaw, g721, etc)
%login		used for mailbox login session management
%annotation	annotation of last played or for recorded file
%played		samples played from played file
%recorded	samples recorded to record file
%created	date played file was created
%trim		minimal number of samples to trim at end of file

In addition, DSO based functions will create variables for storing
results under the name of the function call, and the DSO lookup
module will create a %lookup object to contain lookup results.  Also,
server initiated scripts can pass and initialize variable arguments.

Basic Commands

There are a number of commands that are part of the core ccscript library
itself, and these are documented here.

set %var values...
	Set a variable to a known value.

clear %var
	Clear (empty) a variable.  It does not de-allocate.

init %var values...
	Initialize a new system variable with default values.  If
	the variable already exists, it is skipped.

size space %var...
	Pre-allocate "space" bytes for the following variables

select value match label [..match-label pairs]
	Select is used to branch to a new script based on matching
	a value or variable to a list of possible values.  For each
	match, a different script or event handler may be selected.

inc %var [offset]
	Increment a variable, perhaps with a specified offset, otherwise
	by "1".

dec%var [offset]
	Decrement a variable, perhaps with a specified offset, otherwise
	by "1".

goto value
	Goto a named script or event handler in a script

gosub value
call value
	Call a named script or event handler as a subroutine

return
	Return from a gosub

pop
	Pop a gosub off the stack

if value op value label
	Used to test two values or variables against each other and
	branch when the expression is found true.  There are both
	"string" equity and "value" equity operations, as well as
	substring tests, etc.

for %var values...
	Assign %var to a list of values within a loop

do [value op value]
	Start of a loop.  Can optionally have a conditional test (see if)

loop [value op value]
	Continuation of a for or do loop.  Can optionally have a
	conditional test (see if).

continue [value op value]
	Continue a loop immediately.  Can optionally have a conditional
	test (see if).

break [value op value]
	Break out of a loop.  Can optionally have a conditional test (see
	if).

ilog message...
	Port a message to  the system log as a SYSLOG_INFO message.

slog message...
	Post a message to the system log.

elog message...
	Post a message to the system log implicitly as an error message.

exit
	Terminate script interpreter.

Bayonne Server Commands

The Bayonne server adds a number of additional ccscript commands:

hangup
	This is the same as exit, though it can be "trapped" with a
	^hangup handler.

function name [args]
	Used to invoke a function from a DSO loaded module.  The result
	of the function will be stored in a variable named %name, based
	on the function name invoked.

alog message...
	Post a message immediately into the audit log.

cdr message...
	Declaire a CDR record which will be written to the audit log when
	the call terminates.

import %var ...vars
	Import a variable value from "global" name space.  Normally each
	Bayonne trunk has it's own private name space.

export %var ..vars
	Export one or more variables into the "global" name space.

debug message..
	Send a message to the debuging monitor.

sleep timeout [rings]
	Sleep a specified number of seconds.  Can also sleep until the
	specified number of rings have occurred.

wait timeout [rings]
	Wait for a specific number of seconds from the time the call
	was initiated.  This is a time synchronized form of "sleep".
	A specific number of rings can also be waited for.

pack %var values...
	Form comma seperated content in a packed %var.

unpack %var targets
	Unpack a comman seperated variable object into seperate variables.
	Sometimes operations like "lookup" will return a list of values
	or data fields.

packed char
	Allows one to specify an alternate delimiter for packing and
	unpacking data fields.

once label
	Within a single script, once is gaurenteed to only goto a new
	script (like a goto) "once".

on trap label
	Allows one to test for a previously blocked signal and see if
	it had occured.  If the signal had occured, then the branch
	will be taken.

answer [rings [ringtime]]
	Answer the line if it has not been answered yet.  Optionally wait
	for a specified number of rings before answering, and allow a
	maximum inter-ring timeout before considering that ringing has
	"stopped".  If the rings are stopped before the count has been
	reached, then the call is treated as a hangup (abandon).

collect digits [timeout [term [ignore]]]
	Collect up to a specified number of DTMF digits from the user.
	A interdigit timeout is normally specified.  In addition, certain
	digits can be listed as "terminating" digits (terminate input),
	and others can be "ignored".

flash offtime ontime
	Flash the line a specified number of milliseconds (offtime) and
	then wait for ontime.  If dialtone occurs, then may be used as
	a branch.

play audiofile(s)
	Play one or more audio files in sequence to the user.  Bayonne
	supports raw samples, ".au" samples, and ".wav" files.  Different
	telephony cards support different codec's, so it's best to use
	ulaw/alaw files if you expect to use them on any Bayonne server.

record audiofile [timelimit [abort]]
	Record user audio to a file, up to a specified time limit, and
	support optional abort digits (DTMF).

append audiofile [timelimit [abort]]
	Append to an existing recorded file, up to a specified time limit,
	and support optional abort digits (DTMF).

dial number [..more digits]
	Dial the specified telephone number.  A "F" may be used to flash
	the line, and a "W" to specify a wait for dialtone.

transfer number [..more digits]
	Dial the specified telephone number and then exit.  This is in
	effect a "blind" transfer/call release, and should use appropriate
	digits to achieve this effect.

pause milliseconds
	A short script pause.

map mapname keyvalue [prefix..]
	lookup a key value in a named map table.  Optionally strip off
	a "prefix" from the keyvalue before searching if the prefix
	value is found.  When the key is found in the map table, the
	specified script is executed with map variables set.

request expires group script [parms]
	post a request for processing by a named trunk group.  This request
	will be processed by an idle port in the specified group, or when
	such a port becomes available.  The expiration allows requests
	to become "stale" afer a certain timeperiod if never processed
	due to no available ports.

libexec timeout program [query-parms]
	Execute an external application or system script file thru the
	Bayonne TGI service.  This can be used to run perl scripts,
	shell scripts, etc.  A timeout specifies how long to wait for
	the program to complete.  A timeout of 0 can be used for
	starting "detached" commands.

libonce timeout program [query-parms]
	Similar to libexec.  However, only one instance of libonce
	will ever execute within a given script.

speak phrasebook-rules words...
	Used to impliment phrasebook rules based prompt generation.  See
	PROMPTS.TXT.

tone tone-name [duration-msec [repeat]]
	This can be used to emit tones defined from the bayonne.conf file.

has keyword label
	Perform a branch operation if a specified keyword exists (as in
	a test for a bound module).

missing keyword label
	Perform a branch operation if a specified keyword is missing.

