readme.script

multi-line Adjunct Communication Server

The ACS scripting language is built around a series of named text files.
Each text (script) file has a series of lines, each of which represent
a script 'step' within the file.  Each script can also contain 'keytraps',
which are essentially marked lines where execution will continue if the
specified dtmf key is pressed during the execution of the script.

Keytraps do not interrupt the processing of a current keytrap.  Hence, if
a branch was forced to a keytrap in a script, pressing a DTMF key while in
the 'trap' portion of the script will not force execution to jump to a new
place.

Script steps are composed of a command statement and one or more 'command
arguments', each separated by white spaces.  A 'comment' is a script step
or line that begins with the "#" character, and is ignored when the
scripts are compiled. 

All the script files are compiled together into a 'collection' and the
script commands are resolved to individual execution points within the ACS
state event engine.  This collection is accessible through a hash table
that is referenced by the same "name" the script file appeared as.  Hence,
the script file "morning.scr" would be invoked as "morning" in the script
collection.

A new script collection can be compiled while ACS is actively executing
calls.  The current script collection is held in memory and used until all
calls currently in progress complete, and is then removed.  Calls newly
offered to ACS are offered the newly compiled script collection.

The following limited script commands are currently implemented:

if a op b scr	if test based on sym1 compared to sym2.  If matched, then
		the specified script step or name is invoked.  operations
		include standard numeric =, <>, >, <, >=, <=.  In addition
		== does a string match, != does a string non-match, and
		$ tests to see if a is contained in b.  $< tests the left
		most digits of b for a, and $> tests the right-most.
select sym ...	select a specified symbol or constant, and test it against
		a list.  The list is composed of values to match and
		script names to "start" when a match is found, in pairs.
prefix sym ...	very similar to select.  Used to match the first xx
		digits against a pattern and branch, rather than the
		whole string.
exists fn xx	if the specified filename exists, then start script xx.
sleep secs [rg]	sleep a specified number of seconds, and also until xx
		rings.  If a ring count is used and the specified number
		of rings fails to occur, then the call is terminated.
wait  secs	wait (sleep) until the n'th second in the call.  This
		can be used to time synchronize script execution.
answer [r [t]]  answer the current line.  can be told to answer after
		"r" rings have occured, and to wait up to "t" seconds
		for each ring.
log ...		create a log file entry with ... as the content.
play msg(s)	play one or more audio prompt files.
say word(s)	word oriented natural speaking of "prompts".
start [xx]	restart the 'scheduled' script or start (goto) a named
		script in the active collection or to a short branch
		point such as '^' label entry or a #line number.
trap [xx]	either clear the current trap, or specify a label to
		jump to when a call is disconnected.  This can be used
		to invoke a cleanup script when callers hangup.
call [xx]	invoke a named script as a subroutine.
return		return from subroutine.
pop		kill subroutine return from the stack.
hangup		return to idle state.
busyout		busy out the port.
clear [-][n]	clear the DTMF collection buffer.  Optionally can
		clear the first "n" digits of the buffer, or the last
		"n" digits.
collect n t [x]	collect n digits with t timeout and x terminating keys.
record msg max	record an audio file with a max record time
set varn ...	set var0 thru var9 to concatinated values that follow
		If any name other than varn is used, a port specific
		symbol will be created.
init syn ...	used to initialize a port specific symbol and assign
		it a value if the symbol is currently undefined.
libexec to ...	a shell command back to back with an exwait handler.
		Rather than a timeout, either "trap" or "detach" may
		be specified.  With trap, a detached script is
		executed and the current trap is cleared.  With detach
		the script is not waited on and no exit status can be
		returned.  Finally, libexec can now be used asychronously
		with "libexec start ..." and "libexec exit".
trace [on|off]  used to turn tracing of script execution on or off.
		Tracing is logged as debug messages to syslog.
dial str	dial a dtmf string of digits.
flash t1 t2	flash the hook status, onhook t1 msecs, back off t2 msecs.
define sym val	define a global symbol and set it's value.
initialize	compile-time "define" to specify initial value for
		a global symbol (unless already set in environ).
add [-]dig	insert digits to the start or end of digit buffer.
trim [-]d	trim specified pattern of digits from the start or end
		of the digit buffer if found.
insert t k var	insert value from variable into dbi table.
delete t k	delete key from dbi table.
update t k var	replace value from variable in dbi table.
search t k var	search for key in dbi table and store in variable.
mailbox nbr	access specified mailbox.
extension nbr	access mailbox for specified extension.
commit		commit mailbox updates.
deliver msg ...	deliver a voice message to a mailbox.
list arry ...	add items to the designated array.
first [v] arry	find first item in named array.
last [v] arry	find last item in named array.
next [v] arry	find next item in named array.
prev [v] arry	find prev item in named array.
erase		used to remove select recordings in /var/ACS/...
move		used to move select messages in /var/ACS/...
link		used to link select messages in /var/ACS/...
messages fldr	select mailbox folder.
save		save current mailbox message.
drop		delete current mailbox message.
skip [..]	skip in mailbox folder.

In addition, for commands that accept "arguments" (such as sleep, play,
etc), an 'argument' can be one of several types:

$arg	A "$arg" is a symbol that is replaced with the value of the
	matching symbol found in the [script] portion of umd.conf.
	This can be used to provide arguments that themselves use
	whitespaces.  This substitution occurs at script compile time.

%arg	This refers to 'special' content which is passed from values
	held in the script event engine for that channel.  The following
	special contents are currently defined:

	%date		current date (yyyymmdd)
	%time		current time (hhmmss)
	%logdate	formatted date
	%logtime	formatted time
	%digits		content of DTMF digit collection buffer
	%count		count of DTMF digits in collection buffer
	%status		exit status of last shell request.
	%script		substitute name of current script, can be useful
			when symlinking identical scripts.
	%extension	default audio extensions used.
	%version	version of ACS.
	%release	major release id of ACS.
	%offset		current offset of last play event.
	%id		port id
	%cid		caller id string
	%ring		current ring count
	%var0 .. %var9	return port script 'variable'
	%empty		return an empty string
	%runtime	return diff between current and starting time
	%temp..		return session unique temporary filenames.
	%item		return item number of current list.
	%mailbox	current mailbox number.
	%extension	current mailbox extension.
	%password	current mailbox password.
	%term		current mailbox terminating script.
	%user		current mailbox user interface script.
	%#record	current mailbox msg recording size default.
	%#new		current mailbox new msg count.
	%#old		current mailbox old msg count.
	%#saved		current mailbox saved msg count.
	%message	current mailbox message.	

	Any unrecognized argument, such as "%xxx", is treated as a port
	specific symbol name and may be used for variable storage.  These
	variables are stored in environment space for the process, can be
	manipulated through TGI, and hold values persistant between
	telephone calls for the given port.

@arg	This refers to a global symbol value shared by all ports.  These
	symbols may be created either with the "define" command, or by
	TGI applications.  They may also be placed in the environment
	before ACS is started by the shell.  All "arg" environment
	symbols are treated as being in upper case.

The current script compiler does very limited syntax checking.  In
particular, it does not in any way verify the number of arguments are
correct for each given command or prevent one from doing 'illogical'
commands and arguments together, such as "play %offset".  Badly written
scripts will be allowed to execute badly...

While there is no conditional or looping statements as such at this point,
looping is achieved automatically within a named script.  That is, a named
script will always loop back to the first step of the script unless it is
terminated with a hangup, a "start xxx" link to a new script, or a
busyout.

Script commands that require a phone to be off-hook to operate will
automatically pick up the line if the line is currently onhook.