"Fossies" - the Fresh Open Source Software Archive

Member "bayonne-1.2.16/doc/script.tex" (16 Jul 2003, 113100 Bytes) of package /linux/misc/old/bayonne-1.2.16.tar.gz:

As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) TeX and LaTeX source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 \documentclass[a4paper,12pt]{article}
    2 \usepackage{html,a4}
    3 \usepackage[english]{babel}
    4 \usepackage{isolatin1}
    5 \usepackage{supertabular}
    6 \selectlanguage{english}
    8 \pagestyle{empty}
    9 \setlength{\parindent}{0pc}
   10 \setlength{\parskip}{\baselineskip}
   12 \date{2003-01-03}
   13 \title{GNU Bayonne Script Programming Guide}
   14 \author{
   15 David Sugar \\
   16 {\em Open Source Telecom.}\\
   17 {\normalsize sugar@gnu.org, http://www.gnu.org/software/bayonne} \\
   18 }
   20 \begin{document}
   21 \renewcommand{\thepage}{}
   23 \maketitle
   25 \tableofcontents
   27 \section{Introduction}
   29 GNU Bayonne is a script driven telephony application server.  As such, it 
   30 has it's own scripting language built by class extension from the GNU 
   31 ccScript interpreter.  Many people ask why GNU Bayonne has it's own 
   32 scripting language rather than using an existing one.  There are several 
   33 reasons for this. 
   35 First, GNU ccScript is deterministic.  In some scripting languages,
   36 expressions can be parsed and evaluated as arguments and mid-statement,
   37 including expressions that are long and have no fixed runtime duration.  
   38 GNU Bayonne requires realtime response and non-blocking behavior; it
   39 cannot directly execute things that have undetermined execution times. 
   41 To reduce system load and support a very high number of concurrent script
   42 sessions (up to 1000), we looked for being able to execute script
   43 statements on the leading edge of a callback event rather than requiring 
   44 a seperate thread to support each interpreter instance.  Most script
   45 interpreters, besides being non-deterministic in their behavior, also do 
   46 not support direct single stepping in that manner. 
   48 In GNU ccScript, it is also possible to effectivily isolate and seperate
   49 execution of statements that require extended duration to execute or that
   50 might block (such as I/O statements) from those that can be executed
   51 quickly from a callback handler in realtime.  A thread can then be used to
   52 support execution of a statement that may otherwise block or delay
   53 realtime response.  Most scripting languages do not directly support
   54 seperation of execution for "quick" and "slow" statements since they are
   55 not directly concerned with the effect of blocking operations. 
   57 Finally, we wanted to execute scripts immediately and from memory context.  
   58 The reason for this is that loading a script file from disk is of course a 
   59 potentially blocking operation, and is an operation that would need to be 
   60 frequently done in most scripting systems.  GNU ccScript forms a single 
   61 interpreter image by compiling all scripts at once directly into memory.  
   62 Furthermore, since we did not wish to have the server "down" to load a new 
   63 script image, we can maintain more than one such core image; when new 
   64 scripts are loaded, any calls currently in progress continue to use the 
   65 previously active script image from memory.  New calls are offered the 
   66 script a new image if the server has been asked to load one.  When the 
   67 last of the older calls complete, then the older image is purged from 
   68 memory.  This permits continual server uptime even while replacing 
   69 scripts that are held in memory. 
   71 \section{Statements and syntax}
   73 Each script statement is a single input line in a script file.  A script
   74 statement is composed of four parts; an event flag as appropriate, a
   75 script command statement, script command arguments, and keyword value
   76 pairs.  White spaces are used to seperate each part part of the command
   77 statement, and white spaces are also used to seperate each command
   78 argument. Each script file is considered a self contained application, 
   79 and may itself be broken down into named sections that are labelled and 
   80 individually referenced. 
   82 Line input is not limited to 80 characters.  Starting with ccScript 2.4.4, 
   83 it is not limited in any manner whatsoever.  However, to make it easy to 
   84 edit very long lines, they can be split up by using a \ at the end of a 
   85 line to join multiple lines together. 
   87 Script commands may be modified by a special .member to describe or
   88 activate a specific subfunction.  For example, a "foo.send" command, if it
   89 existed, would be different from but still related to a plain "foo"  
   90 command.  Members are often used for special properties, to specify an
   91 offset value, or the size of script symbols that are being created. 
   93 Command arguments are composed either of literal strings or of references 
   94 to symbols.  Symbols are normally referenced by starting with the ``\%'' 
   95 character and can be typed in a variety of ways explained below.  A group 
   96 of arguments may also appear within double quotes, and these will be 
   97 expanded into multiple arguments that are composed of literal string 
   98 constants and the substituted values of variables that are referenced.  
   99 Double quoted arguments are most often used to compose strings that are to 
  100 be parsed by other subsystems (such as sql statements) or to format output 
  101 for logging. 
  103 Since sometimes it is useful to refer to arguments that may appear as 
  104 strings or other forms of content, {}'s be used to enclose a literal 
  105 section.  A literal section is passed as a single string argument 
  106 regardless of the content it contains.  Hence, while ``my value is \%1'' 
  107 would form two string arguments, 'my value is ', and the value of \%1, the 
  108 literal expression {my value is \%1} would return a single string argument 
  109 in the form 'my value is \%1' unmodified.  {}'s may also be used to pass 
  110 character codes that are normally not supported as command arguments. 
  112 A complete script defines a labeled section of a script file, the script
  113 statements the labelled section contains, and the statements found in any
  114 event handlers associated with the label.  The script file itself has a
  115 default label under the name of the script, and any statements that appear
  116 before labels are used are associated with a label named by the script
  117 file itself. When event handlers are attached to labeled sections of a
  118 script, and control passes to the event handler, the script blocks all
  119 remaining events until a new script section is entered. 
  121 \section{Labels}
  123 Labels are used to segment script files into individual script entities.  
  124 These entities are all stored and referenced from a common hash table.  
  125 Script labels that are the default script code for a given .scr file are 
  126 stored under the name of the script itself.  Within the script, local
  127 labels may be used.  These local labels can be in the form ``::label'' or 
  128 ``label:''. 
  130 A script file that has commands which need to branch to a label can do so 
  131 by branching to the local script file name.  Hence, if there is a 
  132 ``test:'' entry in ``your.scr'', another script command can branch to the 
  133 test: entry directly by using ::test, as in ``goto ::test'', for example. 
  136 Labels within other script files, unless made private, may also be 
  137 referenced and branched to directly.  If myscr.scr has a script section 
  138 ``test:'', I can branch to it by refering to myscr::test.  Hence, I could 
  139 use ``goto myscr::test'' for example. 
  141 Script labels can be made private within a given script file using the
  142 ``.private'' directive.  This means that they can only be referenced from
  143 other scripts within the same file in the ``::xxx'' form, and not
  144 externally through ``yyy::xxx'' references.  By default all script labels 
  145 are public.   You can also use ``.public'' as a directive to convert the 
  146 next script labels in a file to public after using ``.private''. 
  148 Script labels may also be exported into another script.  This can be
  149 useful when making a script label private but wishing to make it available
  150 as or part of another script file.  This is done with the ``.export''
  151 directive.  Exported scripts are named, compiled, behave, and are
  152 referenced as if they appeared in the file named in the .export statement
  153 rather than the .scr file they appear in. 
  155 \section{Symbols}
  157 Bayonne scripting recognizes three kinds of symbols; constant "values"  
  158 (literals), \%variables, and @indirection.  In addition, Bayonne
  159 recognizes compile time substitutions, known as \$names, which can
  160 substitute to any of the above three.  A literal can be "string" literals,
  161 which are double quoted, numeric literals, such as 123, which are without
  162 quotes, and \{as-is string\} literals encased in \{\}'s.  (see Sec.2). 
  164 A \%variable can be defined either as having content that is alterable or
  165 that is constant.  Some \%variables are automatically initialized for each
  166 and every telephone call, while others may be freely created by scripts
  167 themselves.  However, all variables and values stored, with the exception
  168 of globals, are automatically cleared at the end of each telephone call. 
  170 Constant variables are declared with the ``const'' keyword.  Sometimes
  171 this is useful to have a non-modifiable variable when defining a value
  172 that may have an overiding default which can be asserted at an earlier
  173 point in the code.  This is especially important in subroutine calls and 
  174 argument passing, as will be explained later.  However, most often, 
  175 variables are used to store changable values. 
  177 Bayonne also recognizes symbol scope.  Local symbols are created
  178 within symbol scope, resulting in unique instances within subroutines.
  179 In addition, all local symbols in symbol scope are removed when
  180 returning from a subroutine.  global symbols are visible everywhere
  181 under the same instance.  A ``global'' symbol uses ``.'' notion, as in
  182 \%myapp.name, where a ``local'' symbol uses a simple name, as in
  183 \%name, for example.  Generally it is suggested that a given script
  184 should organize it's global symbols under a scriptname.xxx format to
  185 make it easier to read and understand. 
  187 A fourth class of symbol exists only at compile time, \$defined symbols
  188 are substituted when the script file is compiled, and usually reduce to a
  189 simple constant, though variables can be named for the compiler.  All
  190 constants are defined in the [script] section of bayonne.conf. 
  192 You can concatenate symbols and constant strings with either
  193 non-quoted whitespace or the comma operator.  For example, 
  195 \begin{verbatim}
  196 set %a ``a'' ``b'', ``c''
  197 \end{verbatim}
  199 results in \%a being set to ``abc''. 
  201 Finally, there is a shortcut notation to create global symbols that are 
  202 associated with a single script file.  If we have a script named foo.scr, 
  203 and wish to create a bunch of global symbols related to ``foo'', we do not 
  204 have to create \%foo.xxx, \%foo.yyy, etc.  Instead, we can refer to these 
  205 script global names simply as .xxx and .yyy.  These will be expanded at 
  206 compile time back to \%foo.xxx and \%foo.yyy.  When in another script 
  207 file, one can reference the full name, \%foo.yyy directly, while the 
  208 shortcut form can be used within the script file, or within things 
  209 exported as foo. 
  211 The following variables are commonly defined: 
  213 \begin{supertabular}{ll}
  214 \%script.error          & last error message \\
  215 \%script.token          & current token seperator character \\
  216 \%script.home           & same as \%session.home \\
  217 \%script.trigger        & name of armed symbol that was triggered \\
  218 \%return                & process exit value of last libexeced TGI script \\
  219 \%session.id            & global call identifier \\
  220 \%session.date          & current date \\
  221 \%session.time          & current time \\
  222 \%session.digits        & currently collected dtmf digits in the digit buffer \\
  223 \%session.count         & count of number of digits collected \\
  224 \%session.starttime     & time of call starting \\
  225 \%session.startdate     & date of call starting \\
  226 \%session.duration      & current call duration \\
  227 \%session.callerid      & generic identity of calling party \\
  228 \%session.calledid      & generic identity of how they called us \\
  229 \%session.home          & initial script invoked \\
  230 \%session.schedule      & script that was scheduled \\
  231 \%session.eventsenderid & port that sent a message with the ``send'' command \\
  232 \%session.eventsendermsg & the message given to the ``send'' command \\
  233 \%session.language      & current language in effect (default = "english") \\
  234 \%session.voice         & current voice library in effect (default = "UsEngM") \\
  235 \%session.joinid        & last port we successfully joined with. \\
  236 \%session.parent        & id of call session that started current one. \\
  237 \%session.pickupid      & last port that picked us up. \\
  238 \%session.transferid    & port that is being transferred to us. \\
  239 \%session.recallid      & port we successfully picked up. \\
  240 \%session.extension     & extension number call is part of. \\
  241 \%session.loginid       & effective user id for preferences database \\
  242 \%user.*                & preference database entries for this user \\
  243 \%line.*                & line settings we may have in effect \\
  244 \%driver.id             & driver timeslot associated with call session. \\
  245 \%driver.card           & physical card number associated with session. \\
  246 \%driver.span           & T1/E1 span number associated with session. \\
  247 \%driver.network        & Type of port switching; "none", "soft", or "tdm" \\
  248 \%pstn.dnid             & did/dnis number dialed if available \\ 
  249 \%pstn.clid             & ani or caller id  number if available \\
  250 \%pstn.name             & caller name if passed in callerid \\
  251 \%pstn.redirect         & if origin is a telco redirect \\
  252 \%pstn.ringid           & if distinctive ringing is available \\
  253 \%pstn.infodigits       & if telco infodigits were passed to us \\
  254 \%pstn.rings            & number of rings so far \\
  255 \%pstn.interface        & Type of pstn interface; analog, digital, etc. \\
  256 \%pstn.tone             & Last special pstn tone detected. \\
  257 \%policy.name           & name of policy for this session \\
  258 \%policy.member         & nth member of this policy \\
  259 \%policy.*              & various policy variables. \\
  260 \%audio.volume          & volume level in 0-100 for play and record. \\
  261 \%audio.extension       & default audio file extension (.au, .wav, etc) \\
  262 \%audio.format          & default audio format (ulaw, alaw, g721, etc) \\
  263 \%audio.annotation      & annotation of last played or for recorded file \\
  264 \%audio.played          & samples played from played file \\
  265 \%audio.recorded        & samples recorded to record file \\
  266 \%audio.created         & date played file was created \\
  267 \%audio.timeout         & timeout in a play wait \\
  268 \%audio.trim            & minimal number of samples to trim at end of file \\
  269 \%audio.offset          & sample offset of play or record at end of command \\
  270 \%audio.buffer          & driver specific buffering for computing offsets \\
  271 \%server.ports          & total ports on bayonne server \\
  272 \%server.version        & version of bayonne server \\
  273 \%server.software       & software identifier; "bayonne" \\
  274 \%server.driver         & which driver we are running \\
  275 \%server.node           & node id of our server \\
  276 \%rpc.status            & last posted rpc status result \\
  277 \%rpc.loginid           & rpc requestor's login identifier \\
  278 \%rpc.expires           & time period for rpc to complete by \\
  279 \%sql.driver            & name of loaded sql driver \\
  280 \%sql.rows              & number of rows returned in last query \\
  281 \%sql.cols              & number of cols returned in last query \\
  282 \%sql.database          & name of database connected to \\
  283 \%sql.error             & last sql error received \\
  284 \%sql.insertid          & id of last insert operation \\
  285 \end{supertabular}
  287 A special set of variables may be created by the application program under
  288 the name \%global.  global.xxx variables are shared and may be accessed
  289 directly between all running script instances in Bayonne.  The values
  290 stored in a global are also persistent for the duration of the server
  291 running. 
  293 In addition, DSO based functions will create variables for storing
  294 results under the name of the function call, and the DSO lookup
  295 module will create a \%lookup object to contain lookup results.  Also,
  296 server initiated scripts can pass and initialize variable arguments.  For 
  297 example, the fifo ``start'' command may be passed command line arguments,
  298 and these arguments then appear as initialized constants when the new
  299 script session is started. 
  301 \subsection{Symbol Types and Properties}
  303 While most symbols are stored as fixed length strings, there are a number
  304 of special types that exist.  "typed" symbols are not typed in the same
  305 way traditional typing occurs, however.  "typed" symbols are typically
  306 symbols that perform automatic operations each time they are referenced as 
  307 a command argument. 
  309 The ``counter'' symbol is used as a typed symbol that automatically 
  310 increments itself each time it is referenced.  This can be useful for 
  311 creating loop or error retry counters. 
  313 The ``stack'', ``sequence'', and ``fifo'' are symbols that can hold 
  314 multiple values.  A stack releases values each time it is referenced in 
  315 lifo order until it is empty again.  A fifo does this in fifo order.  The 
  316 sequence object repeats its contents when reaching the end of it's list.  
  317 Values are inserted into each of these types by using the special ``post'' 
  318 keyword.   ``stack'' and ``fifo'' may be used as global. objects to 
  319 create and script ACD-like functionality in Bayonne. 
  321 In addition to type behavior, symbols have properties that may be 
  322 associated with them.  These include a number of default properties, and 
  323 some that may be available through the loading of ccscript packages.  A 
  324 symbol's property may be extracted by adding a .property to the symbol 
  325 name.  One such property is the symbol "type".  Hence, to access the 
  326 symbol type of \%myvar in a script command argument, one might use 
  327 ``\%myvar.type''.  The following script properties are defined:
  329 \begin{supertabular}{lll}
  330 property        & requires      & description \\
  331 .type           & \---          & base symbol type in scripting \\
  332 .length         & \---          & length of symbol contents \\
  333 .size           & \---          & size of symbol entry \\
  334 .count          & \---          & number of members in array or stack \\
  335 .max            & \---          & maximum size of array or stack \\
  336 .value          & \---          & computed integer value of symbol contents \\
  337 .bool           & \---          & compute bool value of contents \\
  338 .dtmf           & (bayonne)     & returns dtmf representation of contents \\
  339 .upper          & .use string   & returns upper case text of contents \\
  340 .lower          & .use string   & returns lower case text of contents \\
  341 .capitalize     & .use string   & returns capitalized text of contents \\
  342 .trim           & .use string   & returns contents without lead or trailing spaces \\
  343 .url            & .use url      & decode url escaped content \\
  344 .bin            & .use url      & decode binhex content \\
  345 .each           & .use digits   & extracts content into a , seperated list of chars \\
  346 .date           & .use date     & returns date encoded values from content \\
  347 .year           & .use date     & returns integer year of a date variable \\
  348 .month          & .use date     & returns integer month of a date variable \\
  349 .weekday        & .use date     & returns weekday of a date variable \\
  350 .monthof        & .use date     & returns named month of a date \\
  351 .day            & .use date     & returns integer day of month of a date \\
  352 .time           & .use time     & returns time encoded values from content \\
  353 .hour           & .use time     & returns hour value from time \\
  354 .minute         & .use time     & returns minute value from time \\
  355 .second         & .use time     & returns second value from time \\
  356 \end{supertabular}
  358 Similarly, some properties may be used to set variables of a specific type 
  359 or to convert the values stored in a variable through a set command into a 
  360 specific format.  These are done by using ``set.xxx'' where xxx is a 
  361 specific property format.  For example, to url encode a string, one can 
  362 use ``set.url \%mystr ...contents...''.  A date variable to store the 
  363 current date may be similarly created with ``set.date \%myvar''. 
  365 \subsection{Arrays, lists, and Hashes}
  367 While not meant for intensive algorithmic work, Bayonne's scripting does 
  368 support a concept for both handling arrays and lists.  An array is 
  369 considered a numerically sequenced list of variables with access 
  370 controlled by a common .index property.  A list is a token packed list of 
  371 character strings.
  373 There are also other ways of creating array "effects".  One way to do this 
  374 is to use symbol indirection.  Symbol indirection means the symbol that is 
  375 referenced is found by examining the contents of another symbol.  For 
  376 example ``sim 1'' string will be logged after execution of this fragment: 
  378 \begin{verbatim}
  379         set %myref "mysim1"
  380         set %mysim1 "sim 1"
  381         slog @myref
  382 \end{verbatim}
  384 When using lists, Bayonne assumes by default that these are comma 
  385 seperated content in a symbol.  However, characters other than commas may 
  386 be used.  A list may be examined in a variety of ways.  Using the 
  387 ``string'' package, it is possible to build, extract, and organize the 
  388 contents of lists.  The ``foreach'' keyword can be used to look through 
  389 the contents of a list.  In each case, a special token= attribute may be 
  390 used to specify the seperator character being used if it is not a comma.
  392 The default list seperator token, ``,'', is stored in a special variable,
  393 \%script.token.  You may modify this single character variable to another 
  394 token.  The special .n properties can be used to access a part of a token 
  395 seperated list in a manner similar to how members of an array are 
  396 accessed.  List members are numbered from 1, so xxx.4 will access 4-th 
  397 member of xxx list. 
  399 Starting with ccScript 2.4.4, it is also possible to compute a variable 
  400 hash as part of a symbol name reference.  For example, a variable named
  401 ``\%var\#hash'' will be expanded to use the contents of \%hash to compute 
  402 the name as a componentized name.  Hash tables in this form may appear in 
  403 either local or global storage, and hence provide a means to componentize 
  404 local scope symbol names and store stack local arrays. 
  406 \subsection{Session Ids and References}
  408 Session ids are symbol values that are used to refer to a Bayonne port 
  409 that is running a call script.  These references are used so that scripts 
  410 in one port can, when needed, identify and reference scripts running in 
  411 another port.  The most common example of this is the start command, which 
  412 can return a variable that will hold the session id of the script and port 
  413 that a script was started on.  This can then be used to rendezvous two 
  414 script sessions for a ``join''.  Similarly, the child script could also 
  415 examine its \%session.parent to find out who started it to join. 
  417 The most basic reference id is simply a port number.  This reference is a 
  418 numeric id, and is the same as the value that \%driver.id returns.  The 
  419 disadvantage of using port numbers is that they are not aware of call 
  420 sessions.  Imagine I start a script on another port, say ``3'', and I 
  421 decide to join to it later.  In the interum, the call that was originally 
  422 started has disconnected, and an entirely new call has appeared on port 3.  
  423 I do not want to join to this new and unrelated call. 
  425 The second form of a session id is 14 bytes long.  It is composed of a 
  426 ``-'', a port number, another ``-'', and a call unique timestamp.  This is 
  427 known as a local session id.  Many generated ids, such as those stored in 
  428 \%session.pickupid and \%session.joinid, are passed in this form.  This 
  429 assures that the reference is not just to a specific port, but also to a 
  430 specific call that is occuring on that port. 
  432 The third form of a session id starts with a node name and a ``-'', 
  433 followed by a local session id.  This form is considered unique for all 
  434 call sessions on all server instances, assuming each server has a unique 
  435 call node.  These are best used when resolving activities that will be 
  436 spread over multiple servers, such as call detail that may be collected 
  437 into a single database. 
  439 \section{Events}
  441 The event flag is used to notify where a branch point for a given event
  442 occurs while the current script is executing.  Events can be receipt of
  443 DTMF digits in a menu, a call disconnecting, etc.  The script will
  444 immediately branch to an event handler designated line when in the "top"
  445 part of the script, but will not repeatedly branch from one event handler 
  446 to another; most event handlers will block while an event handler is 
  447 active. 
  449 The exception to this rule is hangup and error events.  These cannot be
  450 blocked, and will always execute except from within the event handlers
  451 for hangup and/or error themselves.  Event handlers can be thought of
  452 as being like "soft" signals. 
  454 In addition to marking script locations, the script "event mask" for the
  455 current line can also be modified.  When the event mask is modified,
  456 that script statement may be set to ignore or process an event that may
  457 occur. 
  459 The following event identifiers are considered "standard" for Bayonne: 
  461 \begin{center}
  462 \begin{supertabular}{|l|l|l|}
  463 identifier                      & default       & description \\
  464 \verb=^hangup= or \verb=^exit=  & detach        & the calling party has disconnected \\
  465 \verb=^error=                   & advance       & a script error is being reported \\
  466 \verb=^dtmf=                    & \---          & any unclaimed dtmf events \\
  467 \verb=^timeout=                 & advance       & timed operation timed out \\
  468 \verb=^0 to 9, a to d=          & \---          & dtmf digits \\
  469 \verb=^pound or \verb=\^star=   & \---          & dtmf "\#" or "*" key 
  470 hit \\
  471 \verb=^tone=                    & \---          & tone event heard on line \\
  472 \verb=^signal=                  & detach        & notify while waiting for other trunk \\
  473 \verb=^part= or \verb=^cancel=  & detach        & conference/join disconnected. \\
  474 \verb=^fail= or \verb=^invalid= & advance       & failed process \\
  475 \verb=^event=                   & \---          & event message received \\
  476 \verb=^child=                   & \---          & notify child exiting \\
  477 \verb=^pickup=                  & \---          & we are picked up by another session \\
  478 \verb=^answer=                  & \---          & call progress caller answered \\
  479 \verb=^busy=                    & \---          & call progress dialed line busy \\
  480 \verb=^noanswer=                & \---          & call progress call timed out \\
  481 \verb=^time=                    & \---          & call timer event trap \\
  482 \end{supertabular}
  483 \end{center}
  485 Some of these script events also have Bayonne ccScript variables which are 
  486 set when they occur.  When an event occurs and there is no handler 
  487 present, very often execution simply continues on the next statement, but 
  488 the variable that is set may still be examined.  The following event 
  489 related symbols may be referenced: 
  491 \begin{supertabular}{ll}
  492 \%script.error                  & last script ``error'' message. \\
  493 \%pstn.tone                     & name of last telephone tone received. \\
  494 \%session.eventsenderid         & trunk port that sent an \verb=^event= to us. \\
  495 \%session.eventsendermsg        & event message that is being sent. \\
  496 \%session.joinid                & trunk port we last joined with. \\
  497 \end{supertabular}
  499 \section{Loops and conditionals}
  501 Scripts can be broken down into blocks of conditional code.  To support 
  502 this, we have both if-then-else-endif constructs, and case blocks.  In 
  503 addition, blocks of code can be enclosed in loops, and the loops 
  504 themselves can be controlled by conditionals. 
  506 All conditional statements use one of two forms; either two arguments 
  507 seperated by a conditional test operator, or a test condition and a single 
  508 argument.  Multiple conditions can be chained together with the ``and'' 
  509 and ``or'' keyword. 
  511 Conditional operators include = (or -eq) and \verb|<>| (or -ne), which provide
  512 integer comparison of two arguments, along with \verb|>|, \verb|<|, \verb|<=|, and \verb|>=|, which
  513 also perform comparison of integer values.  A simple conditional
  514 expression of this form might be something like \verb|if %val < 3 ::exit|,
  515 which tests to see if \%val is less than 3, and if so, branches to ::exit.
  517 Conditional operators also include string comparisons.  These differ in
  518 that they do not operate on the interger value of a string, but on it's
  519 effective sort order.  The most basic string operators include == (or
  520 .eq.) and != (or .ne.) which test if two arguments are equal or not.  
  521 These comparisons are done case insensitive, hence ``th'' will be the same 
  522 as ``Th''. 
  524 A special operator, ``\$'', can be used to determine if one substring is
  525 contained within another string.  This can be used to see if the first
  526 argument is contained in the second.  For example, a test like ``th \$
  527 this'' would be true, since ``th'' is in ``this''.  Similar to perl, the
  528 ``~'' operator may also be used.  This will test if a regular expression
  529 can be matched with the contents of an argument.  To quickly test the
  530 prefix or suffix of a string, there is a special \verb|$<| and \verb|$>|
  531 operator.  These check if the argument is contained either at the start or
  532 the end of the second argument. 
  534 In addition to the conditional operators, variables may be used in special 
  535 conditional tests.  These tests are named -xxx, where ``-xxx argument'' 
  536 will check if the argument meets the specified condition, and ``!xxx 
  537 argument'', where the argument will be tested to not meed the condition.  
  538 The following conditional tests are supported: 
  540 \begin{supertabular}{ll}
  541 conditiona      & description \\
  542 -defined        & tests if a given argument is a defined variable \\
  543 -empty          & tests if the argument or variable is empty or not \\
  544 -script         & tests if a given script label is defined \\
  545 -module         & tests if a specific .use module is loaded \\
  546 -voice          & tests if a given voice exists in prompt directory \\
  547 -altvoice       & tests if a given voice exists in the alt prompt directory \\
  548 -sysvoice       & tests for a given system voice library \\
  549 -appvoice       & tests for a given application voice library \\
  550 -group          & tests if a specified trunk group exists \\
  551 -plugin         & tests if a specified plugin is loaded \\
  552 -service        & tests if the service level is set to a specific value \\
  553 -dtmf           & tests if a specific dtmf ``option'' setting is in effect \\
  554 -feature        & tests if the feature specified in argument exists \\
  555 -ext            & whether the argument refers to a valid extension number \\
  556 -station        &  whether refers to a station port extension number \\
  557 -virtual        & whether refers to a virtual extension entity \\
  558 -user           & whether the argument refers to a user profile id \\
  559 -dnd            & whether dnd is set for the extension argument \\
  560 -hunt           & whether the argument refers to a hunt group \\
  561 \end{supertabular}
  563 The -feature option can test for a number of features.  The features you 
  564 can test for include ``-feature join'' to test for join support, 
  565 ``switch'' for pbx support, ``spans'' for digital span support, and 
  566 various audio capabilities. 
  568 The ``if'' expression can take three forms.  It can be used as a ``if 
  569 ...expr... label'', where a branch occurs when an if expression is true. 
  570 it can be in the form ``if ...expr...'' followed by a ``then'' command
  571 on the following line.  The then block continues until an ``endif'' 
  572 command, and may support an ``else'' option as well.  This form is similar 
  573 to the bash shell if-then-fi conditional.  Finally, if the conditional is 
  574 needed for only one statement, there is a special case form that can be 
  575 entered on a single line, in the form ``if ...expr..  then command 
  576 [args]'', which allows a single statement to be conditional on the 
  577 expression. 
  579 The ``case'' statement is followed immediately by a conditional
  580 expression, and can be used multiple times to break a group of lines up
  581 until the ``endcase'' is used or a loop exits.  The ``otherwise'' keyword 
  582 is the same as the default case in C.  A set of ``case'' expressions and 
  583 ``otherwise'' may be enclosed in a ``do-loop'' to get behavior similar to 
  584 C switch blocks. 
  586 The ``do'' and ``loop'' statements each support a conditional expression.  
  587 A conditional can hence be tested for at both the top and bottom of a 
  588 loop.  The ``break'' and ``continue'' statements can also include a 
  589 conditional expression. 
  591 In addition to ``do-loop'' there is ``for-loop'', ``foreach-loop'' and,
  592 with ccscript 2.5.2 and later, ``fordata-loop''. The for statement
  593 assigns a variable from a list of arguments, much like how for works in
  594 bash.  foreach can be used to decompose a token seperated list variable.
  595 fordata is used to perform a ``read'' statement from data statements
  596 (such as a \#sql query result) directly in a loop. In all cases, break and
  597 continue can still be used within the loop.
  599 \section{Subroutines and symbol scope}
  601 Bayonne recognizes the idea of symbol scope.  Symbol scope occurs when 
  602 refering to variables that are either ``global'' in scope, and hence 
  603 universally accessable, or that are ``local''.  Local symbols exist on a 
  604 special heap, and a new local heap is created when a subroutine level is 
  605 called.
  607 Global scope symbols are those that have componentized names.  Hence 
  608 ``\%xxx\-.yyy'' is treated as a global symbol.  Local symbols do not have 
  609 componentized names.  Hence ``\%yyy'' is a local scope symbol.  This allows 
  610 one to determine scope purely from symbol name, rather than requiring 
  611 implicit commands to create a symbol that is local or global. 
  613 Bayonne scripting recognizes subroutines as invoked through either the 
  614 ``gosub'' or ``call'' script statements.  When a ``call'' statement is 
  615 used, execution is transfered to the given script, as a subroutine, and 
  616 that script can then return to continue script flow with a ``return''
  617 statement. 
  619 When invoking a subroutine through ``call'', it is possible to specify if 
  620 a new local variable heap will be created.  If a new heap is created, 
  621 local variables are created in the context of the subroutine only, and any 
  622 changes are lost when ``return'' is used to return back to the calling 
  623 script.  The ``return'' statement can be used to transfer values, 
  624 typically from a subroutine's local heap, back to a variable in the 
  625 calling script's context.  This is done with ``var=value'' lists that may 
  626 follow the return statement, as in ``return status=ok'', for example. 
  628 Subroutines may also be invoked with paramatric paramaters.  These
  629 paramaters are then inserted into the local heap of the newly called
  630 subroutine and become accessible as local variables.  This also is done
  631 with keyword value pairs, as in ``call ::mysub myvar=3'', for example.  
  632 When this is done, a local constant is created, known as \%myvar, that is
  633 then usable from ::mysub, and exists until ::mysub returns.  Since this is
  634 a constant, its value may not be altered within ::mysub. 
  636 Sometimes a subroutine can contain initialization values to use if no
  637 parametric value have been passed.  Since parametric values are constants, 
  638 they cannot be altered, and hence, one can do something like: 
  640 \begin{verbatim}
  641 ::mysub
  642         const %myvar 4
  643         ...
  644 \end{verbatim}
  646 And thereby define \%myvar locally as 4, unless there was a ``call 
  647 ::mysub'' with an alternate value being passed as a myvar=xxx. 
  649 Subroutines also support call by reference.  This can be used to permit a 
  650 subroutine to directly modify a local variable in the scope of the calling 
  651 script automatically.  Call by reference is done by using a keyword=\&var
  652 form of keyword.  Consider the example:
  654 \begin{verbatim}
  655 ...
  656         set %mysym "test"
  657         call ::mysub myref=&mysym
  658         slog %mysym
  659 ...
  661 ::mysub
  662         set %myref "tested"
  663         return
  665 \end{verbatim}
  667 In this case, the slog will show ``tested'' since \%myref in ::mysub 
  668 actually points back to \%mysym in the calling script. 
  670 It is possible to call a subroutine that uses the same local variables 
  671 directly, rather than having it create a new local context.  This can be 
  672 done either using the ``source'' statement, or ``call.local''.  It is also
  673 possible to have a subroutine that has no local variable context, and 
  674 hence always refers to the base global context.  This is done with a 
  675 ``call.global''. 
  677 \section{Transaction Blocks}
  679 In addition to subroutines, loops, and conditional statements, scripts may
  680 be gathered together under transaction blocks.  Normally each script 
  681 statement is step executed over a timed interval.  This is done to reduce 
  682 loading when deriving several hundred instances of Bayonne for a high 
  683 density voice solution.  However, some scripts either involve statements 
  684 that are trivial or that need to be executed together.  These can be done 
  685 using a ``begin'' and ``end'' block.  
  687 When a transaction block is used, all the statements within it are 
  688 executed as quickly as possible as if they were a single script step.  
  689 This allows one to go through a series of set or const definitions 
  690 quickly, for example. 
  692 In addition, ``begin'' may be used in front of a cascading case block, or 
  693 before an ``if'' statement.  This allows all the conditional tests within 
  694 the case or if to be executed together until the ``endif'' or 
  695 ``endcase'', rather than depending on stepping. 
  697 Transaction blocks only work for statements that do not involve scheduled 
  698 operations.  Things that schedule include sleep, playing and recording of 
  699 audio, and libexec statements.  When these appear within a transaction 
  700 block, the transaction block is suspended for those specific statements, 
  701 and then resumes on the next unscheduled statement. 
  703 Transaction blocks will automatically exit when a branch statement is 
  704 enountered, or when a ``end'', ``endif'', ``loop'', or ``endcase'' is 
  705 encountered.  Transaction blocks cannot encapsulate a loop, and they will 
  706 not operate with a subroutine call since calling a subroutine is a 
  707 branching operation. 
  709 \section{Files, paths, prompts, extensions, and directories}
  711 In the default configuration supplied with 1.2.0, there are three places 
  712 that audio prompts may be played from; a subdirectory of /var/\-lib/\-bayonne, 
  713 a subdirectory of /usr\-[/local]/\-share/\-bayonne, and a subdirectory of 
  714 /home/\-bayonne.  /var/\-lib/\-bayonne is meant to hold audio that is 
  715 manipulatable and recorded samples.  /usr/\-share/\-bayonne includes both 
  716 system and language specific prompts that are supplied by pre-installed or 
  717 packaged Bayonne applications.  /home/\-bayonne is meant to store both 
  718 scripts and audio prompts that are locally created by the system 
  719 administrator for site specific or custom applications. 
  721 To refer to an audio sample stored in a /var/\-lib/\-bayonne/\-xxx subdirectory, 
  722 all one needs to do is refer to the partial path as a filename, as in 
  723 xxx/\-yyy.au.  The play and record command, and others, also support a 
  724 ``prefix='' option, which can be used to specify the xxx subdirectory name 
  725 seperately.  This may be convenient when audio prompt filenames would need 
  726 to be otherwise constructed from concatenated symbols or strings.  The 
  727 special preprocessor directive, {\bf .prefix}, or {\bf .dir} may be 
  728 used to assure that the xxx subdirectory exists in /var/\-lib/\-bayonne. 
  729 Hence, if we wish to record messages into /var/\-lib/\-bayonne/\-msgs, we can 
  730 use either something like ``record prefix=msgs myfile'' or ``record 
  731 msgs/\-myfile''. 
  733 For audio that is stored in /var/\-lib/\-bayonne, a file extension is 
  734 automatically added if none is specified.  This default file extension is 
  735 set in the [script] section of bayonne.conf, and is stored in 
  736 \%audio.extension.  The default extension is typically set to .au, for sun 
  737 audio files.  However, you can either modify \%audio.extension in a 
  738 running script, and many commands allow you to override the default extension.  
  739 For example, to record msgs/\-myfile as a .wav file, this could be done with
  740 ``record prefix=msgs extension=.wav myfile''.  The extension can also be 
  741 specified directly as part of the filename, as in ``record 
  742 msgs/\-myfile.wav''. 
  744 When using the ``prefix='' modifier, there is a special prefix with a 
  745 pre-reserved meaning.  When using ``prefix=memory'', rather then using 
  746 audio for /var\-/lib/\-bayonne/memory, the audio files are actually stored on 
  747 the tmpfs, in ram (or swap), which usually is /dev/\-shm.  This can be used 
  748 to record special prompts that maybe need to be processed further.  It is 
  749 particularly useful when constructing a rotating ``feed'' which may be 
  750 recorded from one channel and listened to in realtime by multiple callers 
  751 on other channels. 
  753 When using simple filenames, as as ``test'' or ``1'' in ``play'' or 
  754 ``speak'' commands, a lot of special magic occurs to determine where the 
  755 audio file will be played from.  The first consideration is the current 
  756 voice setting.  Since audio samples are split into language specific voice 
  757 libraries, each with a seperate subdirectory in /usr/\-share/\-bayonne, the 
  758 directory looked at is the one that the current voice library is set for.  
  759 The default is usually UsEngM, and this is set in the [script] section 
  760 of bayonne.conf as well. 
  762 In addition to voice libraries, each application may have a seperate 
  763 subdirectory for it's own prompts under each voice.  The application 
  764 subdirectory is the same as the base name of the script file (or the 
  765 effective name if it has been .exported).  Hence, if we have an 
  766 application, "myapp.scr", and we try to use ``play myprompt'', then, the 
  767 first place examined would likely be 
  768 /usr/\-share/\-bayonne/\-UsEngM/\-myapp/\-myprompt.au.  If there is no application 
  769 specific directory, then the main voice library directory is used.  
  770 Hence, if we use ``play 1'', and there is no  
  771 /usr/\-share/\-bayonne/\-UsEngM/\-myapp subdirectory, then instead we will 
  772 retrieve and play /usr/\-share/\-bayonne/\-UsEngM/\-1.au. 
  774 The current voice libary may be found in \%session.voice.  While 
  775 \%session.voice may be changed directly, the ``options voice=xxx'' 
  776 script command is usually used to select a new voice because it will also 
  777 select the correct phrasebook language module to use with that voice.  The 
  778 default extension of voice library prompts is controlled by the driver, 
  779 and is usually either .au, for sun audio encoded mu-law files, or .al, for 
  780 raw a-law encoded copies of .au content.  Furture drivers may also make 
  781 use of .gsm or .adpcm for pre-encoded audio prompts. 
  783 Audio may be played directly from a URL when XML support has been enabled 
  784 in Bayonne.  URL audio is played at the moment only from a http: source.  
  785 hence, one can do something like ``play http:/audio/\-myaudio.au''.  If XML 
  786 support is not enabled, then `http:' prompts are ignored. 
  788 In addition to standard URL's, there are a number of special pseudo-urls's 
  789 that have special meanings.  These are in the form of xxx:yyy, where xxx 
  790 is a special url code, and yyy is an autoprompt, or pathname. 
  792 The following special url codes are defined: 
  794 {\bf alt:} \\
  795 This redirects prompt selection to /home/\-bayonne.  From that point, the
  796 actual prompt file is then selected based on the same voice library
  797 and script path selection rules as if it had been taken from a standard
  798 prompt stored through the default path.  Hence, a subdirectory of
  799 /home/\-bayonne named after the current voice library will be used. 
  801 {\bf app:} \\
  802 This refers to selecting audio from a subdirectory named the same as
  803 the application script name from a voice library subdirectory from
  804 /usr\-[/local]/\-share/\-bayonne.
  806 {\bf audio:} \\
  807 Somewhat related to {\bf music:}, the {\bf audio:} name refers to any
  808 .au or .al file that has been stored in /usr\-/[local]/\-share/\-bayonne/\-audio.  
  809 These audio samples can be any generic audio file that may be desired, 
  810 including sound effects, etc.
  812 {\bf mem:} \\
  813 This has the same effect as using the ``prefix=memory'' option, and refers
  814 to audio stored or retrieved from system memory as organized by the tmpfs.
  815 The tmpfs usually is mounted as /dev/\-shm.
  817 {\bf music:} \\
  818 This references audio samples stored as digital music.  Digital music is 
  819 typically used for playing of ``music on hold''.  Digital music is stored 
  820 in /var\-[/local]/\-share/\-bayonne/\-music.  It is stored in 8 bit encoded u-law 
  821 (and optionally in a-law) since 8bit 8khz files are actually smaller than mpeg 
  822 encoded high fidelity audio, and because the telephone network does not 
  823 support higher quality audio in the first place. 
  825 {\bf sys:} \\
  826 This refers to audio prompts stored in the non-language specific
  827 ``system'' voice library.  These are found in
  828 /usr\-[/local]/\-share/\-bayonne/\-sys.
  830 {\bf tmp:} \\
  831 This refers to audio that is stored (or recorded to) through the /tmp 
  832 filesystem.  This allows use of /tmp for audio storage.
  834 {\bf usr:} \\
  835 {\bf home:} \\
  836 This refers to audio stored in the alternate audio prefix (altprompts in
  837 bayonne.conf).  The alternate audio prefix is normally set to 
  838 /home/\-bayonne.  The actual file will either be loaded from an application
  839 specific subdirectory of /home/\-bayonne if a subdirectory exists to match
  840 the script filename, or directly from the /home/\-bayonne directory itself. 
  842 {\bf var:} \\
  843 This refers to a subdirectory of /var/\-lib/\-bayonne that is named the same
  844 as the current script file.  This provides a quick way for a script to
  845 organize it's recordable prompts under the same subdirectory of the 
  846 datapath.
  848 {\bf xxxx:} \\
  849 Any reference to a url that does not use any of the special keywords is 
  850 used to refer directly to a subdirectory of the system prompt directory.  
  851 This is often used to organize system audio prompts used in system support 
  852 scripts, such as playrec.  The actual location is found from 
  853 /usr\-[/local]/\-bayonne/\-sys/\-xxxx/.
  855 {\bf xxxx::} \\
  856 There are a number of other odd forms of pathnames used to select prompts 
  857 based on script names or so called export names. This translates roughly 
  858 to a language localized prompt based on the voice library name that is 
  859 found in /usr\-[/local]/\-share/\-bayonne.  This allows the xxxx name to be used 
  860 in place of the name of the current script file.
  862 {\bf ~/} \\
  863 When bayonne is used to host user driven scripts, this is done in a manner 
  864 somewhat anagelous to how apache hosts the ~/ path and user specific 
  865 content.  The audio prompt for these are assumed to exist in a 
  866 subdirectory of a user's home account, usually from \$HOME/.bayonne.
  868 \section{Pre-processor directives}
  870 Based on ccscript 2.5.0 and later, there are two types of pre-processor
  871 directives; those that are compile control directives, and those that
  872 involve compile-time symbol or token substitution.  Compile control
  873 directives start with ``.'' and are on a seperate line, along with any
  874 options or arguments, such as filenames.  An example of a compile control
  875 directive is ``.include xxx'', which can be used to insert include files. 
  877 Compile time symbols are given a value at the time the script is compiled, 
  878 and may be considered like a constant.  Some compile time symbols are 
  879 constants, and may be used to represent values found in the [script] 
  880 section of bayonne.conf.  For example, to insert the definition of 
  881 ``timeout'' that is found in [script], one might refer to it within 
  882 ccScript as ``\$timeout''. 
  884 With ccScript 2.5.0, we introduced three special compile time symbols to 
  885 help with debugging.  These are ``\$script.name'', ``\$script.file'', and 
  886 ``\$script.line''.  The first refers to the name code is currently being
  887 compiled under.  With the use of the ``.export'' directive, this may in 
  888 fact be different than the filename, which may be found with 
  889 ``\$script.file''.  The final symbol expands to the current statement line 
  890 number being compiled. 
  892 The following pre-processor directives exist: 
  894 {\bf .code} \\
  895 {\bf .data} \\
  896 {\bf .map} \\
  897         Define the next section of text in your source file either as script 
  898         (code), as a local embedded data block for use with a ``read'' statement, 
  899         or as a special embedded data block for use with the ``map'' statement.
  901 {\bf .default[nn]} {\it name [default-value]} \\
  902         This creates a definition for a user preference entry.  User
  903         preference entries are stored under /var/\-lib/\-bayonne/\-users/\-xxx,
  904         and contain persistent user information such as account passwords
  905         or telephone extension settings.  The default value, if present,
  906         is used to specify the default to fill a new user preference 
  907         record for this named entry when it is created.  These may be
  908         accessed through the \%user. global depending on the login state
  909         of a given call session.
  911 {\bf .define} {\it name value} \\
  912         Used to define the value of a pre-processor symbol that can then
  913         be referenced under \$name.
  915 {\bf .export} {\it name} \\
  916         This is used to export the remaining ::xxx script script sections
  917         as if they were compiled from a script source file that is named
  918         by the directive rather than the one they are compiled from.  
  919         Hence, the sections are compiled as name::xxx rather than the
  920         source file name that they are compiled from.  This can be used
  921         to override or insert a section script into another script file.
  923 {\bf .include} {\it filename ...} \\
  924         Insert text from another source file.  This can be used to insert
  925         constants such as {\bf .define} statements from a seperate header 
  926         file, for example.  The include directory is assumed to be the 
  927         same as the script source directory, although one can specify
  928         relative paths for subdirectories.
  930 {\bf .hunt[nn]} {\it name [default-value]} \\
  931         This is used to create persistent hunt group entries and 
  932         definitions that are used for pbx hunt groups, and that
  933         are saved under /var/\-lib/\-bayonne/\-hunting/\-xxx.  These are
  934         usually extrated through the huntinfo command in scripting.
  936 {\bf .initial[nn]} {\it name value ...} \\
  937         This is used to define script global symbols that need to be
  938         of a known size and initialized to a known value at the start
  939         of each call session before scripts are ran.  If you have a
  940         {\bf .initial} statement in test.scr for a variable named
  941         {\it save}, for example, a global variable named \%test.save
  942         will be initialized for each call.
  944 {\bf .languages} {\it language ...} \\
  945         Load Bayonne phrasebook module for a specified language if it is
  946         not already installed because the current script depends on it.
  948 {\bf .line[nn]} {\it name [default-value]} \\
  949         This is used to create an entry for port (line) persistant
  950         entries that may be used to save line properties that are
  951         modifyable.  These are typically accessed through the \%line.
  952         variables.
  954 {\bf .module} {\it modulename ...} \\
  955         Load the specified Bayonne ``module'' (.mod) if it is not already
  956         installed in memory because the given script depends on it being
  957         active.
  959 {\bf .prefix} {\it subdir ...} \\
  960 {\bf .dir} {\it subdir ...} \\
  961         Create the specified subdirectory in /var/\-lib/\-bayonne if it does 
  962         not exist because the current script requires it to store audio
  963         data.
  965 {\bf .private} \\
  966         Define any ::xxx scripts compiled from this point forward as 
  967         being private and only referencable from within the current script 
  968         file.  This means one cannot use yyy::xxx to invoke or reference a 
  969         local script.  The {\bf .public} directive can be used to 
  970         re-enable public access to compiled scripts in the current file.
  971         This directive only effects the current file, and is reset to
  972         public when the next source file is compiled.
  974 {\bf .public} \\
  975         Mark any scripts compiled from this point forward as being public.
  976         This is used to re-enable yyy::xxx scripts if a {\bf .private}
  977         directive has been used.
  979 {\bf .requires} {\it commandname} \\
  980         Tests to see if a specified and required script command exists in
  981         the current system.  If the required script is not found, then the
  982         current file cannot be compiled, and the system halts.
  984 {\bf .rpc} {\it rpcname} \\
  985         Bind the next script statement as a RPC named script service to be 
  986         invoked through Bayonne rpc services under the specified name.  
  987         This assumes the script returns a status message back to the rpc 
  988         server.
  990 {\bf .rule} {\it rulename rule} \\
  991 {\bf .english} {\it rulename rule} \\
  992 {\bf .lang...} {\it rulename rule} \\
  993         Define a phrasebook rule in your sourcefile.  This allows 
  994         in-source definition of rules that your script may use in the
  995         ``speak'' command, rather than having to define them seperately
  996         in a config file.  Rules that apply to all languages are defined
  997         with a single {bf .rule} directive, while language specific 
  998         varients, if needed, can also be specified by using the language
  999         name as a ``.'' preprocessor directive.
 1001 {\bf .safe} \\
 1002 {\bf .unsafe} \\
 1003         This is used to mark sections of code whether they should report
 1004         compile time syntax errors or not.  Unsafe code will report no
 1005         error, and may be used when loosly binding optional script 
 1006         keywords that work only when specific modules are present.
 1008 {\bf .template} {\it templatefile} \\
 1009         This allows a foreign script file to specify the event handlers 
 1010         that will be defined and used for the current script.  This allows
 1011         one to define a template script for common event handling shared
 1012         among a number of common scripts.
 1014 {\bf .use} {\it packagename ...} \\
 1015         Install a generic ccscript package module that the current script
 1016         requires, if it is not already installed.  These are normally 
 1017         found in /usr/\-lib/\-ccscript2.
 1019 {\bf .xml} {\it xml-modulename ...} \\
 1020         Load the specified Bayonne XML support module (,xml) if it is not
 1021         already installed.
 1023 \section{Command Reference}
 1025 \subsection{Variable declarations}
 1027 These commands describe the various means to create or initialize a 
 1028 symbols in the scripting language.  Symbols may be of specialized types 
 1029 that automatically perform operations when referenced, or generic symbols 
 1030 of a specific type or size. 
 1032 {\bf alias} {\it \%name value} \\
 1033         Create an alias symbol name that points to a real symbol name when
 1034         referenced.  The alias and target must be in the same scope, hence
 1035         local aliases cannot reference global objects in subroutines.
 1037 {\bf array[.size]} {\it count [values...]} \\
 1038 {\bf array} {\it size=size} {\it count=count} {\it \%var [value ...]} \\
 1039         Create a ccScript array composite object.  This creates a special
 1040         \%var.index to select a specific array element, and a bunch of
 1041         seperate variables named \%var.1 through \%var.count, one for
 1042         each array element.
 1044 {\bf cache[.size]} {\it count \%var [value ...]} \\
 1045 {\bf cache} {\it size=size} {\it count=count} {\it \%var [value ...]}
 1046         Create a ccScript fifo cache variable.  This creates a variable
 1047         that logs and returns content in reverse order.
 1049 {\bf clear} {\it \%var ...} \\
 1050         Clear (empty) one or more variables.  It does not
 1051         de-allocate.  This means that if you need to determine whether
 1052         a variable is ``there'' or not in a TGI script which is passed
 1053         the variable, the empty string is equivalent to a nonexistent
 1054         variable.
 1056 {\bf const} {\it \%var values...} \\
 1057 {\bf const} {\it var=value ...} \\
 1058         Set a constant which may not be altered later.  Alternately
 1059         multiple constants may be initialized.
 1061 {\bf counter} {\it \%var} \\
 1062         Create a variable that automatically increments as it is referenced.
 1064 {\bf fifo[.size]} {\it count \%var [value ...]} \\
 1065 {\bf fifo} {\it size=size} {\it count=count} {\it \%var [value ...]} \\
 1066         Create a ccScript fifo ``stack'' variable.  This creates a variable
 1067         that automatically unwinds from first in to last in when referenced.
 1069 {\bf init} {\it \%var values...} \\
 1070 {\bf init} {\it var=value ...} \\
 1071 {\bf init[.min|.max]} {\it [size=bytes]} {\it \%var [=] values...} \\
 1072 {\bf init[.size]} {\it \%var [=] values...} \\
 1073 {\bf init[.property]} {\it \%var values} \\ 
 1074         Initialize a new system variable with default values.  If the
 1075         variable already exists, it is skipped.  Optionally multiple
 1076         variables may be initialized at one.  Can also init a variable
 1077         to a minimum or maximum value of a set of values.  A property
 1078         plugin may also be initialized, such as initing a ".date" or
 1079         other specialized plugin type value.  The "xx = expr" form
 1080         can be used to initiate a numeric expression with basic
 1081         +, -, *, and / operators.
 1083 {\bf lifo[.size]} {\it count \%var [value ...]} \\
 1084 {\bf lifo} {\it size=size} {\it count=count} {\it \%var [value ...]} \\
 1085 {\bf stack[.size]} {\it count \%var [value ...]} \\
 1086 {\bf stack} {\it size=size} {\it count=count} {\it \%var [value ...]} \\
 1087         Create a ccScript ``stack'' variable.  Stack variables are lifo
 1088         objects and unwind automatically on reference.
 1090 {\bf list[.size]} {\it [size=bytes]} {\it [token=char]} {\it \%var} {\it values...} \\
 1091         List is used to quickly construct a token seperated packed
 1092         list variable which may then be used with the foreach loop,
 1093         referenced through the packed property index, or manipulated 
 1094         with the string command.
 1096 {\bf ref} {\it \%ref components ...} \\
 1097         This can be used by a subroutine to form a local instance of a
 1098         reference object that points to a real object in the public name
 1099         space by building a target public object name from components that
 1100         are then glued with ``.'' notation.  This is different from an
 1101         alias since a simple named alias can only reference the local 
 1102         scope in a subroutine.
 1104 {\bf sequence[.size]} {\it count \%var [value ...]} \\
 1105 {\bf sequence} {\it size=size} {\it count=count} {\it \%var [value ...]} \\
 1106         Create a ccScript repeating sequence variable.  This repeats content
 1107         of a sequence in the order set.
 1109 {\bf set} {\it \%var values...} \\
 1110 {\bf set} {\it var=value ...} \\
 1111 {\bf set[.min|.max]} {\it [size=bytes]} {\it [justify=format]} {\it \%var [=]  values...} \\
 1112 {\bf set[.size]} {\it [justify=format]} {\it \%var [=] values...} \\
 1113 {\bf set[.property]} {\it \%var values} \\
 1114         Set a variable to a known value.  Can also set multiple variables.
 1115         Can also set a variable to the minimum or maximum value of
 1116         a set of values.  A property plugin may also be directly set, such 
 1117         as initing a ".date" or other specialized plugin type value.  The 
 1118         "xx = expr" form can be used to set a symbol based on a 
 1119         simple numeric expression using basic +, -, *, and / operators.
 1120         A left, right, or "center" justification may also be used.  Please
 1121         note, in the future, the overloaded expression form may be 
 1122         seperated into a new "number" and "float" keyword.
 1124 {\bf size} {\it space \%var...} \\
 1125         Pre-allocate "space" bytes for the following variables.
 1127 \subsection{Symbol manipulation}
 1129 While {\bf set} is perhaps the most common way to both define and 
 1130 manipulate a symbol, there are a number of additional script commands that 
 1131 can be used for this purpose. 
 1133 {\bf arm} {\it \%var} \\
 1134         Arm a variable so that it will auto-branch if modified.
 1136 {\bf dec[.property]} {\it \%timevar [offset]} \\
 1137         Decrement a variable, perhaps with a specified offset, 
 1138         otherwise by "1".  When used with packages that set   
 1139         numeric properties, such as the ``date'' and ``time'' 
 1140         package, dec can adjust dates and times as well.
 1142 {\bf disarm} {\it \%var} \\
 1143         Disarm an armed variable.
 1145 {\bf dup} {\it \%var \%dest} \\
 1146         Duplicate an existing object into a new one.
 1148 {\bf inc[.property]} {\it \%timevar [offset]} \\
 1149         Increment a variable, perhaps with a specified offset,
 1150         otherwise by "1".  When used with packages that set
 1151         numeric properties, such as the ``date'' and ``time''
 1152         package, inc can adjust dates and times as well.
 1154 {\bf post} {\it \%var value ...} \\
 1155         Post one or more additional values into a stack, fifo, sequence,
 1156         or cache.
 1158 {\bf swap} {\it \%var} {\it \%var} \\
 1159         Exchange the contents of two variables with each other.  They
 1160         must both be of the same scope.
 1162 {\bf remove} {\it \%var value ...} \\
 1163         Remove a specific value entry from a stack, fifo, sequence, or
 1164         cache variable.
 1166 {\bf dirname} {\it \%var} \\
 1167         Much like the shell dirname, to extract a directory name
 1168         from a path.
 1170 {\bf basename} {\it \%var [extensions...]} \\
 1171         Reduce a variable to a simple base filename, and strip any
 1172         of the optionally listed extensions from it.
 1174 {\bf fullpath} {\it \%var fullpath} \\
 1175         If \%var is a partial pathname, then merge it with the passed
 1176         path to form a complete pathname.
 1178 \subsection{Script and Execution Manipulation}
 1180 There are a special category of script commands that directly deal with 
 1181 and manipulate the script images in active memory.  These include commands 
 1182 that operate on scripts by creating local template headers, or user 
 1183 session specific copies, of loaded scripts, which can then be selectivily 
 1184 modified in some manner.  The following script manipulation commands 
 1185 exist: 
 1187 {\bf begin} \\
 1188 {\bf end} \\
 1189         Mark the start or end of a script transaction block.
 1191 {\bf disable} {\it name=label} {\it trapids...} \\
 1192         This is used to disable specific \^... handlers within a live
 1193         script.  The script, when used, behaves as if there never was
 1194         a \^... handler programmed for it.  The {\bf enable} command can
 1195         be used to make the handlers active again.
 1197 {\bf enable} {\it name=label} {\it trapids...} \\
 1198         This is used to enable specific trap handlers within the body of
 1199         a script which may have been disabled.
 1201 {\bf gather} {\it \%var} {\it suffix} \\
 1202         Gather the number of instances of a given xxx::suffix scripts
 1203         that are found in the current compiled image, and store the
 1204         list of named scripts in the specified \%var.
 1206 {\bf lock[.wait|.unlock]} {\it id=value} \\
 1207         Attempt to create a global lock under the specified id.  If
 1208         successful, then no other active call will be able to claim
 1209         the same global lock until the current call session releases  
 1210         it, either through a {\bf lock.unlock} or by exiting.  If .wait is 
 1211         used, this command will block until the lock is aquired.  Global 
 1212         locks could be used for pin numbers, account ids, etc.
 1214 \subsection{Looping, Branching, and Conditionals}
 1216 {\bf break} {\it [value op value][ and | or ...]} \\
 1217         Break out of a loop.  Can optionally have a conditional test (see
 1218         if).
 1220 {\bf call[.public|.protected]} {\it value} {\it [var=value ...]} \\   
 1221 {\bf gosub[.public|.protected]} {\it value} {\it [var=value ..]} \\
 1222         Call a named script or event handler as a subroutine.  If the
 1223         call is successful, an optional list of variables can be
 1224         conditionally set.  ``.public'' can be used to specify that
 1225         the subroutine is ran without a local stack, and ``.protected''
 1226         can be used to share the current stack with the subroutine
 1227         directly rather than having it create a new local context.
 1228         Passed arguments are set in the local context of a new subroutine
 1229         as constants.  It is also possible to pass variables by reference
 1230         to a subroutine.
 1232 {\bf continue} {\it [value op value][ and | or ...]} \\
 1233         Continue a loop immediately.  Can optionally have a conditional
 1234         test (see if).
 1236 {\bf case} {\it [value op value][ and | or ...]} \\
 1237 {\bf otherwise} \\
 1238 {\bf endcase} \\
 1239         The case statement is a multiline conditional branch.  A single
 1240         case (or {\bf otherwise}) line can be entered based on a list
 1241         of separate case identifiers within a given do or for loop.  The
 1242         {\bf otherwise} statement is used to mark the default entry of
 1243         a case block.
 1245 {\bf do} {\it [value op value]} \\
 1246         Start of a loop.  Can optionally have a conditional test (see if).  A
 1247         do loop may include {\bf case} statements.
 1249 {\bf exit} \\
 1250         Terminate script interpreter or invoke the special ``::exit'' 
 1251         label in the current script.
 1253 {\bf for} {\it \%var values...} \\
 1254         Assign \%var to a list of values within a loop.  A for loop may
 1255         include {\bf case} statements.  For is similar to it's behavior
 1256         in ``bash''.
 1258 {\bf fordata} {\it source|table=source \%var ...} \\
 1259         Read ``data'' statements starting from a script referenced as
 1260         the ``source'' as part of a loop.  The loop will exit when all
 1261         data lines have been read.  This command could be used to create
 1262         a simple loop to read \#sql query results, for example.
 1263         ``fordata'' was introduced in ccscript 2.5.2.
 1265 {\bf foreach[.offset]} {\it \%var \%packed} \\
 1266         Assign \%var from items found in a packed list.  An optional
 1267         offset can be used to skip the first n items.  A foreach loop
 1268         may include {\bf case} statements.
 1270 {\bf goto} {\it label [var=value ...]} \\
 1271         Goto a named script or event handler in a script.  If the
 1272         goto is successful, an optional list of variables can be   
 1273         conditionally set.
 1275 {\bf if} {\it value op value [and | or ...] label [var=value ...]} \\ 
 1276         Used to test two values or variables against each other and
 1277         branch when the expression is found true.  There are both
 1278         "string" equity and "value" equity operations, as well as
 1279         substring tests, etc.  Optionally a set of variables can   
 1280         be initialized based on the conditional branch.  Multiple
 1281         conditions may be chained together using either {\bf and} or
 1282         {\bf or}.  In addition to simple values, ()'s may be used
 1283         to enclose simple integer expressions, the results of which
 1284         may be compared with operators as well.
 1286 {\bf if} {\it value op value [and | or ...]} {\bf then} {\it [script command]} \\
 1287         Used to test two values or variables against each other and    
 1288         execute a single statement if the expression is true.  Multiple
 1289         conditions may be chained together using either {\bf and} or
 1290         {\bf or}.  In addition to simple values, ()'s may be used  
 1291         to enclose simple integer expressions, the results of which
 1292         may be compared with operators as well.
 1294 {\bf if} {\it value op value [and | or ...] } \\
 1295 {\bf then} \\
 1296 {\bf else} \\
 1297 {\bf endif} \\
 1298         Used to test two values or variables against each other and
 1299         start a multi-line conditional block.  This block is enclosed
 1300         in a ``then'' line and completed with a ``endif'' line.  A
 1301         ``else'' statement line may exist in between.
 1303 {\bf label} {\it value ...} \\
 1304         Create a named local label to receive a skip command request.
 1306 {\bf loop} {\it [value op value][ and | or ...]} \\
 1307         Continuation of a for or do loop.  Can optionally have a   
 1308         conditional test (see if).
 1310 {\bf on} {\it trap label} \\
 1311         Allows one to test for a previously blocked signal and see if
 1312         it had occurred.  If the signal had occurred, then the branch
 1313         will be taken.
 1315 {\bf once label} \\
 1316         Within a single script, once is guaranteed to only goto a new
 1317         script (like a goto) "once", which can be used as protection
 1318         agains recursive invokation.
 1320 {\bf pop} \\
 1321         Pop a gosub off the stack.  This only has an effect when
 1322         returning.
 1324 {\bf repeat} {\it count} \\
 1325         Repeat a loop for the specified count number of times.
 1327 {\bf return[.exit]} {\it [label]} {\it variable=value ...} \\
 1328         Return from a gosub.  You can also return to a specific label or
 1329         \^ handler within the parent script you are returning to.  In
 1330         addition, you can use {\bf return} to set specific variables to
 1331         known values in the context of the returned script, as a means to
 1332         pass values back when returning.  Finally, the .exit option may
 1333         be used to exit the script if there is no script to return to.
 1335 {\bf select} {\it value match label [..match-label pairs] [var=val...]} \\
 1336         Select is used to branch to a new script based on matching a value
 1337         or variable to a list of possible values.  For each match, a different
 1338         script or event handler may be selected.  Options include
 1339         "select.prefix" to match string prefixes, "select.suffix" to match
 1340         by tailing values only, "select.length" to match by length,
 1341         and "select.value" to match by numeric value.  If a branch is
 1342         found, an optional list of variables can be conditionally set.
 1344 {\bf skip} {\it [label]} \\
 1345         Skip may be used alone to skip over a case statement.  This is
 1346         similar to what c/c++ does with cases if no intervening break is
 1347         present.  Since ccScript automatically behaves as if break is
 1348         present, skip is needed to flow into another case.  The second
 1349         use of skip is to branch to a local label as defined by the
 1350         {\bf label} keyword.
 1352 {\bf source} {\it label} \\
 1353         Source is used to invoke a subroutine which uses the current
 1354         stack context, and is somewhat similar in purpose and effect
 1355         to ``source'' in the bash shell.
 1357 {\bf try} {\it lables... [var=value ...]} \\
 1358         Attempt to goto one or more labels.  If the label is not found
 1359         in an existing script, the next one in the list will be tried.
 1360         If any branch attempt is successful, then optionally variables
 1361         may also be set.
 1363 {\bf tryeach[.offset]} {\it \%packed [var=value ...]} \\
 1364         Attempt to branch to a script based on the values held in a
 1365         packed list.  Each item will be tried in term, starting from
 1366         the offset if one is specified.  If a branch point exists
 1367         an optional list of variables may be conditionally initialized.
 1369 \subsection{Basic data sets and logging}
 1371 GNU ccScript supports some basic manipulation of embedded data tables 
 1372 within a script.  This has been extended in Bayonne to support retrieval
 1373 of multi-row queries that can then be examined in scripting. 
 1375 {\bf data} {\it values...} \\
 1376 {\bf data.mapindex} {\it label} {\it [variable=value] ...} \\
 1377         This can be used to embed compile time data tables into a script
 1378         file.  Some modules (such as sql query) generate data dynamically  
 1379         for the interpreter and then embed the results also as data 
 1380         statements.  the data statements can then either be mapped or
 1381         read by referencing the script label they appear under.  Each
 1382         data statement line is treated as a seperate row.
 1384 {\bf map[.prefix|.suffix|.value|.absolute]} {\it [table=label]} {\it value} \\
 1385         Map allows branching to a data.mapindex entry in the specified 
 1386         label, or within the current script label if none is specified.  A
 1387         match, either by value, or from start or end, may be made of the
 1388         given value, and if a matching data.mapindex entry is found, then
 1389         the label specified is branched to, with the optional initialized
 1390         variables, as if a goto had been used.
 1392 {\bf read} {\it [table=source]} {\it [row=row]} {\it [col=offset]} {\it \%var ...} \\
 1393         Read a row (line) of data from a data statement, either from the 
 1394         next row of the current table source, or from a specified table 
 1395         source or row offset.  The row is read into variables, one for
 1396         each column.  A column offset may be used to start from a 
 1397         specified column offset.  Data sources are always referenced by
 1398         a script label.  The special ``\#'' script label (and ``\#xxx''
 1399         entries) refer to Bayonne's dynamic script buffer when XML support
 1400         is enabled, and where query results of various types may be stored.
 1402 {\bf slog[.info|.err|.crit|.debug} {\it message...} \\
 1403         Post a message to  the system log as a SYSLOG  message.  The
 1404         logging level can be specified as part of the command.  If
 1405         Bayonne or the stand-alone ccScript interpreter are running on
 1406         a console or under initlog(8), the messages will be output on      
 1407         the standard error descriptor, not standard output.  Note that
 1408         you cannot use \% characters in the strings to be outputted.
 1410 \subsection{Package based extensions}
 1412 A number of interesting script commands are available through the use of 
 1413 external ccscript "packages".  These are typically saved in 
 1414 /usr/\-lib/\-ccscript2, and are installed into the interpreter with the .use 
 1415 command.  The following extension based commands can be available: 
 1417 {\bf chop[.offset]} {\it [offset=bytes]} {\it \%var} {\it bytes} \\
 1418         This is used to chop out a specific count of digits from within
 1419         a string.  This is available with the ``digits'' package.
 1421 {\bf delete[.offset]} {\it [offset=bytes]} {\it \%var} {\it values...} \\
 1422         Delete specific digit values from the specified variable if they
 1423         exist at the offset specified.  For example, to remove a lead
 1424         ``1800'' from a phone number, one might use: 
 1425         ``delete.0 \%phone 1800''.  If the specified pattern is not
 1426         found, it is not removed.  The offset can be a number, or
 1427         ``end'', to specify removal of values from the end of the
 1428         \%var involved.  This is available with the ``digits'' package.
 1430 {\bf insert[.offset]} {\it [offset=bytes]} {\it \%var} {\it value...} \\
 1431         Insert digit values starting at a known offset in an existing
 1432         variable.  This is available with the ``digits'' package.
 1434 {\bf prefix[.offset]} {\it [offset=bytes]} {\it \%var} {\it value...} \\
 1435         If the specified prefix value does not exist at the specified
 1436         offset, then it is inserted.  This is available with the
 1437         ``digits'' package.
 1439 {\bf random.range} {\it [seed=seed]} {\it [count=count]} {\it [offset=offset]} {\it [min=value]} {\it [max=\-value]} {\it [reroll=count]} {\it \%var ...} \\
 1440         The ``random'' package offers a fairly complex number of options
 1441         for creating or storing pseudo-random digits into symbols.  These
 1442         include things that simulate various dice behavior, such as a 
 1443         known sum (count) of a known range of values, and even the ability
 1444         to specify minimum or maximum values that can be generated. 
 1446 {\bf random.seed} {\it seedvalue} \\
 1447         Seed the pseudo-random number generator.  This is used with the
 1448         ``random'' package.
 1450 {\bf replace[.offset]} {\it [offset=bytes]} {\it \%var} {\it find replace ...} \\
 1451         This is used to replace a specific digit pattern with a new value
 1452         if the digit pattern is found at the specified offset in \%var.
 1453         This is available with the ``digits'' package.
 1455 {\bf scale.precision} {\it scale} {\it \%var...} \\
 1456         The ``scale'' package enables basic floating point multiplication.
 1457         This can be used to rescale a known variable by a floating point
 1458         value, and storing the result to a known digit precision.  For
 1459         example, to scale a variable by 40\%, we could use:
 1460         ``scale.2 0.4 \%myvar''.
 1462 {\bf sort[.reverse]} {\it [token=char]} {\it [size=bytes]} {\it \%var} \\
 1463         The ccScript ``sort'' package allows one to sort either
 1464         packed string arrays, which use a token to seperate content,
 1465         or the contents of a ``sequence'', ``stack'', or ``fifo''.    
 1466         Sorting can be in forward or reverse order.
 1468 {\bf string.cut|.chop} {\it [token=char]} {\it [offset=items]} {\it \%string} {\it \%var ...} \\
 1469         This is functionally similar to {\bf string.unpack} except that 
 1470         as each item is unpacked into a target variable, it is also 
 1471         removed from the original packed list.
 1473 {\bf string.pack|.clear} {\it [token=char]} {\it [offset=item]} {\it \%string} {\it [size=bytes]} {\it [prefix=text]} {\it [suffix=\-text]} {\it [mask=format]} {\it [fill=text]} {\it values...} \\
 1474         Create a packed string from a list of items, using the specified 
 1475         token to seperate each item (or the default token, ',').  If the 
 1476         string already exists, you can pack items from a specified offset.
 1477         If the variable doesn't exist, the size can be used to specify
 1478         the size of the new variable.  Prefix and suffix allow each item
 1479         to have a prefix or suffix in addition to the token.  An existing
 1480         variable may also be appended to or cleared.  A special mask may
 1481         also be used to preformat data in a specific way, such as to 
 1482         filter and field numeric values, zero fill, etc.  A fill string
 1483         can be specified to fill to the remaining end of the object.  This
 1484         keyword is supported with the ``string'' package.
 1486 {\bf string.unpack} {\it [token=char]} {\it [offset=item]} {\it \%string} {\it \%var...} \\
 1487         This can be used to unpack a tokenized string into seperate 
 1488         variables.  One may specify the item number to start from rather 
 1489         than the start of the list.  This is available with the ``string''
 1490         package.
 1493 {\bf trim[.offset]} {\it [offset=bytes]} {\it \%var} {\it bytes} \\
 1494         This is used to trim leading and trailing digits outside of
 1495         the range of count and offset specified.  It's the inverse of
 1496         chop.  This is available with the ``digits'' package.        
 1498 \subsection{Bayonne call processing commands}
 1500 This covers the basic set of call processing script command extensions 
 1501 that are common and are generally usable with all Bayonne drivers.  Some
 1502 of these commands may depend on specific bayonne plugins or extensions
 1503 to be installed. 
 1505 {\bf answer} {\it [rings [ringtime]]} {\it [fax=label]} {\it [station=id]} \\
 1506 {\bf answer} {\it [maxRing=rings]} {\it [maxTime=ringtime]} \\
 1507         Answer the line if it has not been answered yet.  Optionally wait
 1508         for a specified number of rings before answering, and allow a
 1509         maximum inter-ring timeout before considering that ringing has
 1510         "stopped".  If the rings are stopped before the count has been
 1511         reached, then the call is treated as a hangup (abandon).  If a
 1512         fax tone is detected, it is possible to branch to an alternate
 1513         label, as well as to present a fax station id, assuming the
 1514         driver supports fax.
 1516 {\bf audit[.log|.clear|.post]} {\it key1=value1 key2=value2 ...} \\
 1517         Declare or post a CDR record.  When a cdr record is declared,
 1518         it is written when the call terminates using the audit plugin.
 1519         When posted, it is written immediately through the audit plugin
 1520         to a seperate auditing data spool.  If a cdr record had been
 1521         set earlier, it may be cleared with .clear, in which case no
 1522         cdr will be posted when the call session terminates.
 1524 {\bf busy.port|.group|.span|.card} {\it id=ports} \\
 1525         This is an admin priviledged command that is used to busy out
 1526         a series of ports other than the current one.  The effect of
 1527         busy can be countered with applying the idle command to the
 1528         same ports.
 1530 {\bf cleardigits[.count]} {\it [label [var=value ...]]} \\
 1531         Clear a specified number of digits from the dtmf input buffer, and 
 1532         then optionally branch to a specified label as if a {\bf goto}
 1533         statement has been executed.  In place of count, one can use
 1534         ``.all'', to clear all digits from the input buffer or ``.last''
 1535         to clear just the last input digit.  Furthermore, ``.pop'' may
 1536         be used to pop off the first input digit only, and ``.trap''
 1537         may be used to perform dtmf trap handlers after branching or 
 1538         within the current script.
 1540 {\bf collect[.clear|.trim]} {\it digits [timeout [term [ignore]]]} \\
 1541 {\bf collect[.clear|.trim]} {\it [var=\&sym] [count=digits] [exit=term] [ignore=ignore]} \\ 
 1542         Collect up to a specified number of DTMF digits from the user.
 1543         A interdigit timeout is normally specified.  In addition, certain
 1544         digits can be listed as "terminating" digits (terminate input),
 1545         and others can be "ignored".  The .clear option can be used to
 1546         clear the input buffer before collecting, otherwise any pending
 1547         digits in the dtmf session buffer may be processed as input prior
 1548         to waiting for additional digits.  The .trim option can be used to
 1549         strip out any additional digits that may still be in the buffer
 1550         after collection count.
 1552 {\bf control} {\it command [arguments]} \\
 1553         A priviledged command which allows a script to directly insert any
 1554         valid fifo control command to the Bayonne server.
 1556 {\bf debug message..} \\
 1557         Send a message to the debugging monitor if one is installed 
 1558         through the plugins.
 1560 {\bf dial} {\it [timeout=cptimeout] [origin=telnbr] [prefix=prefixcode]} {\it number...} \\
 1561         This performs dialing with something that is a standard 
 1562         international number, as in "+1 800 555 1212", for example.  These
 1563         can be in symbols, or other places, and are dialed on the public
 1564         network as a network number through the driver.  Normal numbers
 1565         may also be passed, and either may appear in a symbol, as a 
 1566         literal, or composed from multiple values.
 1568 {\bf dial.dtmf|.pulse|.mf} {\it {prefix=digits]} {\it number...} \\
 1569         This is used to perform ``soft'' dialing operations, which are 
 1570         used to emit dtmf digits and special dialing characters directly
 1571         as synthesised audio with timed pauses, and to do so without any
 1572         call progress detection.
 1574 {\bf dial.int|.nat|.loc} {\it [timeout=cptimeout] [origin=telnbr] [prefix=prefixcode]} \-{\it number...} \\
 1575         This makes use of the trunk group definitions of special prefixes 
 1576         and codes for international, national, and local dialing, to 
 1577         produce a final valid phone number.  The phone number is then 
 1578         dialed through the network, and call progress is used to determine
 1579         the results.
 1581 {\bf erase} {\it [prefix=path]} {\it filename} \\
 1582         Erase a specified file from a /var/\-lib/\-bayonne prefixed path.
 1584 {\bf examine[.ext|.trk|.tie]} {\it id=callid} {\it \%var} \\
 1585         This is used to copy the contents of variables from another
 1586         call session into the local call session.  The use of .ext, .trk,
 1587         or .tie occur only when used with a PBX capable driver.
 1589 {\bf flash offtime ontime} \\
 1590 {\bf flash} {\it offhook=offtimer} {\it onhook=ontimer} \\
 1591         Flash the line a specified number of milliseconds (offtime) and
 1592         then wait for ontime.  If dialtone occurs, then may be used as
 1593         a branch.
 1595 {\bf hangup[.self]} \\
 1596         This is essentially the same as the ccScript ``exit'' command.
 1598 {\bf hangup.port|.span|.card|.group} {\it id=ports} \\
 1599         This is used to hangup on an active call on another port.  A
 1600         specific port or a specific group of ports may be specified.
 1602 {\bf idle.port|.group|.span|.card} {\it id=ports} \\
 1603         This is an admin priviledged command that is used to reset to
 1604         idle a series of ports other than the current one.
 1606 {\bf libexec[.once|.play]} {\it timeout program [query-parms=value ...]} \\
 1607         Execute an external application or system script file thru the 
 1608         Bayonne TGI service.  This can be used to run Perl scripts,       
 1609         shell scripts, etc.  A timeout specifies how long to wait for  
 1610         the program to complete.  A timeout of 0 can be used for
 1611         starting "detached" commands.  Optionally one can set libexec
 1612         to execute only one instance within a given script, or use
 1613         .play to run an external tgi that will generate an audio file
 1614         which will then be played and removed automatically when the
 1615         tgi exits.
 1617 {\bf move} {\it [prefix=path]} {\it source destination} \\
 1618         Move or rename an individual file in the /var/\-lib/\-bayonne prefixed
 1619         path.
 1621 {\bf options} {\it option=value ...} \\
 1622         The options command is an odd command.  It can include common
 1623         options that affect script processing, and also options that may
 1624         be driver specific.  An option is set by option name, with a 
 1625         specified value.  The common generic options include dtmf, which
 1626         can specify dtmf handling, either as on, off, line (default), or
 1627         script global.  Another important option is result=, as this is
 1628         used to send a result back from a rpc initiated script to a
 1629         web service.  The logging= option sets the default logging level.
 1630         The options keyword can also set a new voice, and when voice= is
 1631         used, the correct phrasebook language module is also activated.
 1633 {\bf [alt]play[.any|.all|.one|.tmp]} {\it [prefix=path] [offset=samples] [limit=sam\-ples] [gain=db] [pitch=freq-adjust] [speed=slow|fast] [volume=\%vol] [text=mes\-sage] [voice=voicelib] [extension=fileextension]} {\it audiofile(s)} \\
 1634         Play one or more audio files in sequence to the user.  Bayonne   
 1635         supports raw samples, ".au" samples, and ".wav" files.  Different
 1636         telephony cards support different codecs, so it's best to use 
 1637         ulaw/alaw files if you expect to use them on any Bayonne server.
 1638         Optionally one can play any of the messages found, or only the
 1639         first message found, or a temp file which is then erased after
 1640         play.  The {\bf altplay} version of this command is used in
 1641         conjunction with {\bf say}, and plays only if there is no
 1642         tts system installed.
 1644 {\bf record[.append]} {\it [prefix=path] [gain=db] [volume=\%vol] [trim=samples] [minSize=samples] [text=message] [maxTime=maxrectime] [exit=termdigits] [enco\-ding=audio-format] [annotation=text] [extension=fileext] [save=savename] [offset=samples]} {\it audiofile} \\
 1645         Record user audio to a file, up to a specified time limit, and
 1646         support optional abort digits (DTMF).  Optionally one can
 1647         append to an existing file, or record into part of an existing
 1648         file by offset.  Record with save= option means the file is saved 
 1649         or moved to the specified name if recording is successful, 
 1650         replacing what was previously there.
 1652 {\bf record} {\it [prefix=path] [maxTime=timelimit] frames=count} {\it filename} \\
 1653         This version of record is used to create a looping audio feed that 
 1654         can be used to share an audio source with multiple listeners on 
 1655         different call sessions.
 1657 {\bf redirect[.digitcount]} {\it label} \\
 1658         This is a special marker token.  When a \^handler is followed
 1659         immediately by a redirect statement, the specified number of
 1660         digits are cleared from the input buffer, and the script branches
 1661         immediately to the specified label, rather than step executing.  
 1662         This allows for an immediate branch execution, rather than the
 1663         extra step delay required when a goto immediately follows a
 1664         \^handler.  The redirect command also behaves as a cleardigits
 1665         command.
 1667 {\bf say} {\it [gain=db] [volume=\%level] [voice=ttsname]} {\it text...} \\
 1668         If there is a tts module installed in Bayonne, or an external one
 1669         has been made active, then the say command may be used to generate
 1670         synthesised speech.  This command is ignored if there is no tts
 1671         service present, and so may be used in conjunction with
 1672         {\bf altplay} and {\bf altspeak}.
 1674 {\bf send.copy} {\it id|gid|ext|trk|tie=id} {\it \%var...} \\
 1675         This is used to copy the contents of current variables into the
 1676         global variable space of another selected call session.
 1678 {\bf send.digits} {\it id|gid|ext|trk|tie=id} {\it digits...} \\
 1679         This is used to send digits into the \%session.digits input
 1680         buffer of another call session, to thereby act as if dtmf
 1681         digits were detected.
 1683 {\bf send[.message]} {\it id|gid|ext|trk|tie=id} {\it message=text} \\
 1684         This is used to post a message from the current call session to
 1685         either a specific call session by id, or to a series of active
 1686         call sessions under a common trunk group.  The message recipient
 1687         branches to a \^event handler, receives \%session.eventsenderid 
 1688         with the id of the sending call, and \%session.eventsendermsg with 
 1689         the message text.
 1691 {\bf send.post} {\it id|gid|ext|trk|tie=id} {\it \%varname value ...} \\
 1692         This is used to post values into the contents of variables in
 1693         another call session.
 1695 {\bf service} {\it level} \\
 1696         This is an admin priviledged command which is used to set the 
 1697         service level of the server as a whole, either up, down, or
 1698         under a special service condition.
 1700 {\bf sleep} {\it timeout [rings]} \\
 1701 {\bf sleep} {\it [maxtime=timeout]} {\it [maxRing=rings]} \\
 1702         Sleep a specified number of seconds.  Can also sleep until the  
 1703         specified number of rings have occurred.  Millisecond timeouts
 1704         may also be specified using ms, as in ``100ms''.
 1706 {\bf [alt]speak[.any|.all]} {\it [language=langmodule] [voice=voicelib] [gain=db] [pitch\-=adjust] [speed=fast|slow] [volume=\%level] [text=message] [extension=fileext] {\it phrasebook-rules words...} \\
 1707         Used to implement phrasebook rules based prompt generation.  The
 1708         {\bf altspeak} version exists to speak a phrase only if there is
 1709         no tts system installed, and is meant to be used after a {\bf say}
 1710         command.  The current voice library and language module options 
 1711         may be used, or new ones may be specified on the command line for
 1712         the current command only.
 1714 {\bf start[.offset|.group|.ext|.trunk|.tie|.span|.wait]} {\it [var=\&symbol]\-[maxTime=timeout] [submit=vars-to-copy]} {\it [expire] offset|group script [parms]} \\
 1715         start a script on another trunk port as offset from the current
 1716         port \%id or by issuing a request against another trunk group.
 1717         Hence "start 1 test" starts script test on the port next to the   
 1718         current one, for example.  Normally, a large offset like
 1719         "start 24 test" might be used to start a script on the next
 1720         T span.  Start can start a script immediately, or time delayed as
 1721         a queued request with the timeout specified in maxTime. A 
 1722         ``var=\&varname'' can be used to save the started session id to a 
 1723         variable.
 1725 {\bf statinfo} {\it id=groupname} {\it [capacity=\&var] [incoming=\&var] [outgoing=\&var] [us\-ed=\&var] [avail=\&var]} \\
 1726         This command is used to collect active call statistics from a 
 1727         known trunk group entry.  This can be used to determine how many
 1728         calls are in process for a given group, for example.  The 
 1729         specific named stat item entries are stored into specified 
 1730         variable names that are passed as part of keyword symbols.
 1732 {\bf sync.exit} {\it [time=seconds]} \\
 1733         Set the exit timer for this call session based on the start time
 1734         of the call.  If no timeout is specified, then the exit timer is
 1735         cleared.  When an exit timer expires, and there is no \^time
 1736         handler, the call session exits.
 1738 {\bf sync.start|.current} {\it time=seconds]} \\
 1739         This is used to set a call event timer, which will invoke the 
 1740         \^time handler in a script, at a specified number of seconds
 1741         from the original start time of the call, or for a number of
 1742         seconds after the current time.  If no time is specified, then
 1743         any previously set timer is cleared.
 1745 {\bf sync} {\it time=duration} {\it [maxRing=rings]} \\
 1746         Sleep the current call until the total time since the start of
 1747         call is equal to the specified duration.  This is like a sleep
 1748         call, but scheduled from start of the call rather than from
 1749         the current time.  A version of sleep.start may be added later
 1750         to also do this.
 1752 {\bf tone} {\it [count=repeat] [timeout=intertone]} {\it name} \\
 1753         Play a named tone, as defined in the bayonne.conf file.  The tone
 1754         can be repeated a specified number of times.
 1756 {\bf tone} {\it [count=repeat] [timeout=intertone]} {\it frequency=freq [amplitude=amp]} {length\-=duration} \\
 1757         Play a dynamically constructed monofrequency tone on the fly.
 1759 {\bf tone} {\it [count=repeat] [timeout=intertone]} {\it freq1=freq freq2=freq [ampl1=amp] [am\-pl2\-=amp]} {length=duration} \\
 1760         Play a dynamically constructed dual frequency tone on the fly.
 1762 \subsection{Bayonne Preference and User Session Management}
 1764 These commands deal with management of various persistant databases and
 1765 the concept of user sessions in Bayonne.  User sessions are based on the
 1766 idea that a given call session may be logged in under a specified login
 1767 id.  Login id's may be used for any purpose, including PBX extensions,
 1768 voice mailboxes, pins for debit systems, etc. 
 1770 {\bf change} {\it id=usertag value=newvalue} \\
 1771         Change a user property in the preferences database for the 
 1772         currently logged in user to the specified value.  The actual 
 1773         change is stored with {\bf commit}.
 1775 {\bf commit} \\
 1776         Commit may be used to commit changes made to user preferences
 1777         through the change or password command so that they are 
 1778         permenantly stored.  This only is effective when logged in under
 1779         a user id session.
 1781 {\bf huntinfo} {\it id=pilot} {\it tag=\&var ...} \\
 1782         While hunt groups are primarily used in scripting PBX systems,
 1783         they could be used generically in bayonne for other purposes.  A
 1784         hunt group is a persistant data record under a known pilot number
 1785         who's script defined tags and values may be extracted with a 
 1786         simple script interface.
 1788 {\bf login} {\it id=userid} {password=password} \\
 1789         Attempt to set the current call session under a specified user
 1790         id.  This will be successfull if the correct password is used.
 1792 {\bf logout} \\
 1793         Logs out of the current active user session.
 1795 {\bf password} {[id=userid]} {\it password} \\
 1796         This is used to change the password of the preference and login
 1797         for the currently logged in user id.  If the current user is
 1798         priviledged, it may change the password of other users as well.
 1800 {\bf reset} {\it id=usertag} \\
 1801         Resets a user property in the preferences database for the 
 1802         currently logged in user to it's default.  The actual change
 1803         is stored with {\bf commit}.
 1805 {\bf userinfo} {\it id=userid} {infokey=\&var} \\
 1806         This command is used to extract information about foreign user
 1807         id's that are stored in the preference system.  The currently
 1808         logged in user's info is accessed through \%user.xxx.
 1810 \subsection{Driver specific commands}
 1812 The exact availability and behavior of a number of script commands do 
 1813 depend on specific features or capabilities that must be provided for by 
 1814 specific telephony drivers.  These capabilities and features may not be
 1815 universally available since some drivers will be missing features or 
 1816 capabilities that might be found in others.  These driver specific Bayonne 
 1817 script commands are described here: 
 1819 {\bf accept} {\it label} \\
 1820         Some Bayonne cti drivers support ISDN (pri) hardware where call
 1821         accepting may be manually controlled.  When call accpetance is
 1822         manually controlled, intercept messages may be played back to
 1823         users, and these are unbilled.  The billing clock is only enabled
 1824         from the perspective of the telco if the call has been accepted,
 1825         and this can be done with the accept command.  The accept command
 1826         then branches to a new script because the \^hangup handler of this
 1827         type of script must use {\bf reject} to reject the call if he has
 1828         hung up before it has been accepted.
 1830 {\bf answer.intercom|.trunk|.parent|,pickup} {\it label} \\
 1831         Drivers with PBX support have an enhanced version of the answer
 1832         command that enables answer to be used as a reply to inter-call
 1833         session intercom dialing and pickup requests.  This is used to
 1834         notify the intercom dialer or pickup requestor that an answer
 1835         response has occured on a given extension or line.  On successful
 1836         answer completion, a branch is taken.
 1838 {\bf dial.intercom} {\it ringback=tone} {\it count=rings} {\it [transfer=referer]} {\it [name=display]} {\it station ...} \\
 1839         Drivers capable of PBX support introduce a new and special form
 1840         of the dial command.  This special dial is used for intercom 
 1841         dialing, and supports the idea of being in a special intercom
 1842         dial state.  The extension engaged in intercom dialing receives
 1843         an artificial ringback signal, and each station in the possible
 1844         list of stations is dialed until it is picked up, or the specified
 1845         count of rings has been waited.
 1847 {\bf join[.hangup]} {\it id=port [waitTime=retrytimer] [maxTime=totallimit]} \\
 1848         This is the join command represented in most telephony drivers
 1849         which have either TDM support or the ability to do soft joins.
 1850         Join attempts to connect the channel to the port specified in a
 1851         private full duplex conversation.  If .hangup is used, then both
 1852         ends hang up (exit) when the join completes.  A join is normally
 1853         a one time join attempt, but may be retried over a time interval
 1854         if a waittimer is specified.  The value of \%script.error is set
 1855         based on the reasons that join was parted.  The .parent option
 1856         refers to the call session that started this one if it happened
 1857         through a start command.  Other options, such as .pickup and
 1858         .intercom, are only available in PBX capable drivers.
 1860 {\bf join.parent|.transfer|.pickup|.recall} {\it [waitTime=retrytimer] [maxTime\-=totallimit]} \\
 1861         This version of join joins to trunk call state session identifiers.
 1862         .parent refers to the \%session.parent, while the others are are
 1863         used in PBX drivers only.
 1865 {\bf pickup.incoming|.hold|.intercom|.trunk|.parent|.recall} {\it label} \\
 1866         Pickup is used to send messages to a specified port identifer
 1867         or incoming call source that are translated to \^pickup handlers
 1868         which may then be answered or joined to.  This can be used to
 1869         interupt a voice mail session when the station user originally 
 1870         called picks up the line, for example.  This feature is only
 1871         available in PBX drivers.
 1873 {\bf reject} \\
 1874         This is used in conjunction with the {\bf accept} command in a
 1875         script, and is usually used as a \^hangup handler, as it rejects
 1876         the call, terminating it without billing.  See {\bf accept} for
 1877         further details.
 1879 {\bf ring.start} {\it [group=trunkgroup] [source=othercallsession]} {\it extensionids...} \\
 1880         This is a PBX driver feature to initiate station ringing on
 1881         behalf of another trunk or station.  Source can be used to
 1882         indicate the ring is being started on behalf of another
 1883         station, and hence acts as an alternate means of doing a blind
 1884         transfer.  A trunk or port group may also be used or referenced
 1885         to do ringing for a group.
 1887 {\bf ring.stop} {\it [group=trunkgroup]} {\it extensions...} \\
 1888         This is a PBX driver feature to turn of station ringing for the
 1889         specified stations.
 1891 {\bf ring.clear} \\
 1892         This is a PBX driver feature to clear all pending ring requests
 1893         against the current station.
 1895 {\bf wait[.hangup]} {\it [id=session]} {\it maxTime=waittimer} \\
 1896         This is the generic version of wait used by all drivers with
 1897         TDM or soft join support,  A station that is waiting can wait
 1898         for a join either from any station that attempts to join it, or
 1899         from a specific station.  It can also wait up to a specific
 1900         time interval for the join to occur.  The .hangup option is
 1901         used to indicate hangup will occur when the join is over.  
 1902         Otherwise \%script.error will hold the reason that the join ended.
 1904 {\bf wait.parent|.transfer|.pickup|.recall} {\it maxTime=retrytimer} \\
 1905         This version of wait waits for a join from a specific trunk by
 1906         the call state session identifiers.  .parent refers to the 
 1907         \%session.parent, while the others are are used in PBX drivers         
 1908         only.
 1910 \subsection{XML support based plugins}
 1912 There are a number of Bayonne script commands that are based on or 
 1913 involved with the presense of XML support, when it has been enabled for 
 1914 bayonne.  A number of specialized plugins also exist and may be used only 
 1915 when XML support has been enabled.  The effected script commands include: 
 1917 {\bf assign} {\it var=name [size=bytes] [value=value]} \\
 1918         While the assign command is built into Bayonne regardless of
 1919         whethere XML support is enabled or not, it is most often used
 1920         for supporting XML plugins which contain scripting languages that
 1921         need to set or modify session symbols.  It may be viewed as an
 1922         alternative to {\bf set}.
 1924 {\bf bayonnexml} {\it url=http:xxxx [submit=vars] [maxTime=timeout]} \\
 1925         When the BayonneXML plugin is installed, the bayonnexml command
 1926         can be used as a convenient shortcut script command that sets
 1927         the xml parser to the BayonneXML dialect, and then performs a
 1928         http ``get'' request to retrieve a BayonneXML document from a
 1929         web server, using the query variables passed in submit.  If such
 1930         a document is successfully retrieved and parsed, then it is
 1931         executed.
 1933 {\bf dir[.reverse]} {\it prefix=subdir [var=\&count] [extension=fileext] [match=prefix]} \\ 
 1934         The directory plugin creates a special {\bf dir} command which
 1935         can be used to scan the contents of a specified subdirectory
 1936         from /var/\-lib/\-bayonne.  The contents are returned as multi-row
 1937         data that can then be examined with the {\bf read} command.  The
 1938         columns returned includes filename, sample size, and annotation 
 1939         for audio files.  Matches can be done by name prefix and/or by
 1940         specific file extensions.  A variable can be specified to receive
 1941         the total directory count.
 1943 {\bf sql} {\it [query=string] [maxTime=timelimit]} {query...} \\
 1944         Issue a SQL query through the selected sql plugin driver.  The
 1945         driver returns a multi-row data result that can then be examined
 1946         with the ``read'' command.  The data tuples are in table source
 1947         ``\#sql'' and the header can be read from ``\#header''.
 1949 \section{Troubleshooting ccScripts and TGIs}
 1951 The collect command {\bf adds} to \%session.digits, it doesn't overwrite
 1952 it.  Make sure that you're clearing \%session.digits before each
 1953 collect (unless you really do intend to append).
 1955 Don't use '=', use '-eq' to check for equality.  Also, '==' is broken
 1956 in older versions of Bayonne.  Use '.eq.' instead.
 1958 Are you confusing the name of a script (like ``foo'') with a label
 1959 name (like ``::foo'')?
 1961 Remember that the pound sign is used as a comment character.  Things
 1962 like ``dial \#'' don't work because ccscript thinks you're starting a
 1963 comment.  Quote the ``\#'' character instead.
 1965 Make sure you are using the *::foo syntax when playing prompts, and
 1966 that you have \%application.language set properly.  ``play foo'' is
 1967 almost certainly not going to do what it looks like it should do.  Use
 1968 ``play *::foo'' instead.
 1970 Make sure that if you use a variable returned by a TGI script that the
 1971 TGI script defined it.  Otherwise bayonne dumps core (as of 0.6.4).
 1973 Did the ccscript engine print out any interesting error messages
 1974 during startup or 'bayctrl compile'?  Perhaps you should review them.
 1976 Did you remember to run 'bayctrl compile' or to restart bayonne after
 1977 you modified your script?
 1979 If you do things like "goto script", and script.scr looks like this:
 1981 \begin{verbatim}
 1982 ::start
 1983 do stuff
 1984 do stuff 
 1986 ^event
 1987 ^event
 1988 goto script
 1989 \end{verbatim}
 1991 The goto will fail.  Instead, say "goto script::start".
 1993 Make sure that after you deal with an event, the script jumps
 1994 somewhere.  If the path of execution falls off the bottom of the file
 1995 (or hits another label), then the script engine will jump back to the
 1996 beginning of the file (or the current label) ad infinitum.  Keep in mind
 1997 that you are developing a telephony application, and you must 
 1998 be constantly interacting with the user or they think you've hung up
 1999 on them.
 2001 When jumping as the result of a conditional (like "if \%return -eq 1
 2002 goto main"), you don't say ``goto''.  State it in the form "if \%return -eq 1
 2003 main".  The goto is implied after the if conditional.
 2005 If you're using Perl and it's DBI module for doing database accesses
 2006 through TGI, here's one way you can retrieve data from the database
 2007 via fetchall\_arrayref().  The syntax seems to be easily forgettable
 2008 for some reason.
 2010 \begin{verbatim}
 2011 $ref = $sth->fetchall_arrayref();
 2012 $row0_col0 = $$ref[0][0];
 2013 $row1_col1 = $$ref[1][1];
 2014 $row0_col1 = $$ref[0][1];
 2015 \end{verbatim}
 2017 The standard way to get digits so the caller can interrupt the message is:
 2019 \begin{verbatim}
 2020 clear %session.digits
 2022 play *::1 # "Press 1 for foo, press 2 for baz,
 2023           # press 3 for gronk..."
 2024 sleep 60
 2026 ^dtmf
 2027         collect 1 5 "*#" "ABCD"
 2028         if %session.digits -eq 1 ::label1
 2029         if %session.digits -eq 2 ::label2
 2030         goto ::invalid
 2031 \end{verbatim}
 2033 The standard way to get digits so the caller can't interrupt the message is:
 2035 \begin{verbatim}
 2036 clear %session.digits
 2038 play *::1 # "Press 1 for foo, press 2 for baz, 
 2039           # press 3 for gronk..."
 2040 collect 1 5 "*#" "ABCD"
 2041 if %session.digits -eq 1 ::label1
 2042 if %session.digits -eq 2 ::label2
 2043 goto ::invalid
 2044 \end{verbatim}
 2046 * A note on event traps:
 2048 They are order sensitive.  If you have 
 2050 \begin{verbatim}
 2052 ^dtmf
 2053         goto ::foo
 2054 ^pound
 2055         goto ::bar
 2056 \end{verbatim}
 2058 You will never be able to reach bar.  \^dtmf takes precedence.  Also, traps do not work within traps.
 2060 \begin{verbatim}
 2061 ^dtmf
 2062         ^star
 2063                 goto ::foo
 2064         ^pound
 2065                 goto ::bar
 2066 \end{verbatim}
 2068 Will not work.  Dtmf detect is always turned off in the script step
 2069 following a dtmf trap, with the exception of the collect command.
 2071 It's a good idea to document your TGI return values in your program
 2072 header.  Make a template for all your TGI programs and stick to it.
 2073 Make sure there's a section for the return values in the headers and
 2074 use it.  One convention seen around the OST code is to use 1 for a
 2075 successful call, 0 for an unsuccessful call, and -1 for an internal
 2076 script error.
 2078 Remember that the value of the \%return variable is persistent.  If you
 2079 aren't careful, your TGI scripts will fall through without setting a
 2080 return value.  This is especially annoying if you forget to set a
 2081 return value which means "operation successful" If you don't see a
 2082 line like this in the server logs:
 2084 \begin{verbatim}
 2085 fifo: cmd=SET&2&return&1
 2086 \end{verbatim}
 2088 Then your TGI script isn't setting a return value.  The ccscript
 2089 that's executing your TGI will then use the return value from the last
 2090 ccscript you executed, which is just hours of debugging fun.
 2091 Especially when one of your TGIs is working just fine (but doesn't set
 2092 a return value) and your ccscript checks the return value to see if an
 2093 error occurred, and guess what, it's the return value from the TGI
 2094 script you called before the current one.  Chances are that that
 2095 return value doesn't have anything to do with the return value from
 2096 the TGI script you just executed, which leads to very confusing
 2097 results.
 2099 Document your database schema.  Make sure that you put the column
 2100 indexes into the database schema document, and you include a Big Fat
 2101 Warning that tells any potential modifiers of said document that if
 2102 they touch the document, they get to audit any database access code
 2103 that uses hard-coded column indexes.  The idea is that if they change
 2104 the database schema, those column indexes may no longer be valid.  An
 2105 even better solution (if your TGI language supports it) is to define a
 2106 set of symbolic constants for the database columns in one file and
 2107 include the constant definitions in all the database access code.
 2109 \section{Phrasebook Rules}
 2111 \subsection{Introduction}
 2112 Bayonne is provided with a standard "prompt" library which supports
 2113 prompts for letters and numbers as needed by the "phrasebook" rules
 2114 based phrase parser. The phrasebook uses named rules based on the 
 2115 current language in effect, as held in "\%language" in ccscript.
 2117 Phrase rules can be placed in bayonne.conf proper under the appropriate
 2118 language and in application specific conf files as found in
 2119 /etc/\-bayonne.d.  English "rules" are found under section [english] in 
 2120 the .conf files, for example.
 2122 Phrasebook prompts are used to build prompts that are effected by content.
 2123 Lets take the example of a phrase like "you have ... message(s) waiting".
 2124 In english this phrase has several possibilities.  Depending on the
 2125 quantity involved, you may wish to use a singular or plural form of
 2126 message.  You may wish to substitute the word "no" for a zero quantity.
 2128 In Bayonne phrasebook, we may define this as follows:
 2130 in your script command:
 2132 \begin{verbatim}
 2133         speak &msgswaiting %msgcount no msgwaiting msgswaiting
 2134 \end{verbatim}
 2136 We would then define under [english] something like:
 2138 \begin{verbatim}
 2139 msgswaiting = youhave &number &zero &singular &plural
 2140 \end{verbatim}
 2142 This assumes you have the following prompt files defined for your
 2143 application:
 2144 \begin{itemize}
 2145         \item youhave.au "you have" 
 2146         \item no.au "no" 
 2147         \item msgwaiting.au "message waiting" 
 2148         \item msgswaiting.au "messages waiting" 
 2149 \end{itemize}
 2150 The system will apply the remaining rules based on the content of
 2151 \%msgcount.  In this sense, phrasebook defined rules act as a kind of
 2152 "printf" ruleset.  You can also apply rules inline, though they become
 2153 less generic for multilingual systems.  The assumption is that the base
 2154 rules can be placed in the [...] language area, and that often the
 2155 same voice prompts can be used for different effect under different
 2156 target languages.
 2158 The speaking of numbers itself is held in the default Bayonne
 2159 distribution, though the default prompt list can also be replaced with
 2160 your own.  Rules can also appear "within" your statement, though this
 2161 generally makes them non-flexible for different languages.
 2163 Speaking of currency "values" have specific phrasebook rules.  Currency
 2164 values are also subject to the "\&zero" rule, so for example:
 2166 balance=youhave \&cy \&zero remaining
 2168 and using:
 2170 speak \&balance \%balance nomoney
 2172 can use the alternate "no monay" .au prompt rather than saying "0
 2173 dollars".
 2175 \subsection{English}
 2176 The following default phrasebook rules are or will be defined for english:
 2178 \begin{supertabular}{ll}
 2179 \&number        & speak a number unless zero \\
 2180 \&unit          & speak a number as units; zero spoken \\
 2181 \&order         & speak a "order", as in 1st, 2nd, 3rd, etc. \\
 2182 \&skip          & skip next word if spoken number was zero. \\
 2183 \&ignore        & always ignore the next word (needed to match multilingual). \\
 2184 \&use           & always use the next word (needed to match multilingual). \\
 2185 \&spell         & spell the word or speak individual digits of a number. \\
 2186 \&zero          & substitute a word if value is zero else skip. \\
 2187 \&single        & substitute word if last number spoken was 1. \\
 2188 \&plural        & substitute word if last number spoken was not 1. \\
 2189 \&date          & speak a date. \\
 2190 \&day           & speak only day of the week of a date. \\
 2191 \&weekday       & speak the current day of the week. \\
 2192 \&time          & speak a time. \\
 2193 \&primary       & speak primary currency value (dollar(s) and cent(s)) \\
 2194 \&local         & speak local currency \\
 2195 \&duration      & speak hours, minutes, and seconds, for duration values. \\
 2196 \&cy            & speak default currency (either primary, local, or both) \\
 2197 \end{supertabular}
 2199 \subsubsection{Number Prompts}
 2200 0, 1, 2, 3, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 30, 40, 50, 60, 70, 80, 90, hundred, thousand, million, billion, point
 2202 \subsubsection{Order Prompts}
 2203 1st, 2nd, 3rd, 4th, 5th, 6th, 7th, 8th, 9th, 10th, 11th, 12th, 13th, 14th, 15th, 16th, 17th, 18th, 19th, 20th, 30th, 40th, 50th, 60th, 70th, 80th, 90th
 2205 \subsubsection{Date/Time Prompts}
 2206 sunday, monday, tuesday, wednesday, thursday, friday, saturday \\
 2207 january, february, march, april, may, june, july, august, September, october, november, december \\
 2208 am, pm
 2210 \subsubsection{Currency Prompts}
 2211 dollar, dollars, cent, cents, and, or
 2213 \section{Copyright}
 2214 Copyright (c) 2003 David Sugar.
 2216 Permission is granted to copy, distribute and/or modify this document
 2217 under the terms of the GNU Free Documentation License, Version 1.2 or any
 2218 later version published by the Free Software Foundation;
 2219 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts
 2221 \end{document}