## "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}
7
8 \pagestyle{empty}
9 \setlength{\parindent}{0pc}
10 \setlength{\parskip}{\baselineskip}
11
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 }
19
20 \begin{document}
21 \renewcommand{\thepage}{}
22
23 \maketitle
24
25 \tableofcontents
26
27 \section{Introduction}
28
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.
34
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.
40
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.
47
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.
56
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.
70
71 \section{Statements and syntax}
72
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.
81
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.
86
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.
92
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.
102
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.
111
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.
120
121 \section{Labels}
122
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:''.
129
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.
134
135
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.
140
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''.
147
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.
154
155 \section{Symbols}
156
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). 163 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. 169 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. 176 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. 186 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.
191
192 You can concatenate symbols and constant strings with either
193 non-quoted whitespace or the comma operator.  For example,
194
195 \begin{verbatim}
196 set %a a'' b'', c''
197 \end{verbatim}
198
199 results in \%a being set to abc''.
200
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.
210
211 The following variables are commonly defined:
212
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 \\
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}
286
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.
292
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.
300
301 \subsection{Symbol Types and Properties}
302
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.
308
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.
312
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.
320
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:
328
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}
357
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''.
364
365 \subsection{Arrays, lists, and Hashes}
366
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.
372
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:
377
378 \begin{verbatim}
379         set %myref "mysim1"
380         set %mysim1 "sim 1"
381         slog @myref
382 \end{verbatim}
383
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.
391
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.
398
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.
405
406 \subsection{Session Ids and References}
407
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.
416
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.
424
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.
431
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.
438
439 \section{Events}
440
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.
448
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.
453
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.
458
459 The following event identifiers are considered "standard" for Bayonne:
460
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 \\
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}
484
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:
490
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}
498
499 \section{Loops and conditionals}
500
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.
505
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.
510
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.
516
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''.
523
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.
533
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:
539
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}
562
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.
567
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.
578
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.
585
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.
590
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.
598
599 \section{Subroutines and symbol scope}
600
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.
606
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.
612
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.
618
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.
627
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.
635
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:
639
640 \begin{verbatim}
641 ::mysub
642         const %myvar 4
643         ...
644 \end{verbatim}
645
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.
648
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:
653
654 \begin{verbatim}
655 ...
656         set %mysym "test"
657         call ::mysub myref=&mysym
658         slog %mysym
659 ...
660
661 ::mysub
662         set %myref "tested"
663         return
664
665 \end{verbatim}
666
667 In this case, the slog will show tested'' since \%myref in ::mysub
668 actually points back to \%mysym in the calling script.
669
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''.
676
677 \section{Transaction Blocks}
678
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.
686
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.
691
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.
696
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.
702
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.
708
709 \section{Files, paths, prompts, extensions, and directories}
710
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.
720
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''.
732
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''.
743
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.
752
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.
761
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.
773
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.
782
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.
787
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.
791
792 The following special url codes are defined:
793
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.
800
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.
805
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.
811
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.
816
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.
824
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.
829
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.
833
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.
841
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.
847
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/.
854
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.
861
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. 867 868 \section{Pre-processor directives} 869 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. 876 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''.
883
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.
891
892 The following pre-processor directives exist:
893
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.
900
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.
910
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. 914 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. 922 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. 929 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. 935 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. 943 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. 947 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. 953 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. 958 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. 964 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. 973 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. 978 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. 983 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. 989 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. 1000 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. 1007 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. 1013 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. 1018 1019 {\bf .xml} {\it xml-modulename ...} \\ 1020 Load the specified Bayonne XML support module (,xml) if it is not 1021 already installed. 1022 1023 \section{Command Reference} 1024 1025 \subsection{Variable declarations} 1026 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. 1031 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. 1036 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. 1043 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. 1048 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. 1055 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. 1060 1061 {\bf counter} {\it \%var} \\ 1062 Create a variable that automatically increments as it is referenced. 1063 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. 1068 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. 1082 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. 1089 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. 1095 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. 1103 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. 1108 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. 1123 1124 {\bf size} {\it space \%var...} \\ 1125 Pre-allocate "space" bytes for the following variables. 1126 1127 \subsection{Symbol manipulation} 1128 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. 1132 1133 {\bf arm} {\it \%var} \\ 1134 Arm a variable so that it will auto-branch if modified. 1135 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. 1141 1142 {\bf disarm} {\it \%var} \\ 1143 Disarm an armed variable. 1144 1145 {\bf dup} {\it \%var \%dest} \\ 1146 Duplicate an existing object into a new one. 1147 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. 1153 1154 {\bf post} {\it \%var value ...} \\ 1155 Post one or more additional values into a stack, fifo, sequence, 1156 or cache. 1157 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. 1161 1162 {\bf remove} {\it \%var value ...} \\ 1163 Remove a specific value entry from a stack, fifo, sequence, or 1164 cache variable. 1165 1166 {\bf dirname} {\it \%var} \\ 1167 Much like the shell dirname, to extract a directory name 1168 from a path. 1169 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. 1173 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. 1177 1178 \subsection{Script and Execution Manipulation} 1179 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: 1186 1187 {\bf begin} \\ 1188 {\bf end} \\ 1189 Mark the start or end of a script transaction block. 1190 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. 1196 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. 1200 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. 1205 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. 1213 1214 \subsection{Looping, Branching, and Conditionals} 1215 1216 {\bf break} {\it [value op value][ and | or ...]} \\ 1217 Break out of a loop. Can optionally have a conditional test (see 1218 if). 1219 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. 1231 1232 {\bf continue} {\it [value op value][ and | or ...]} \\ 1233 Continue a loop immediately. Can optionally have a conditional 1234 test (see if). 1235 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. 1244 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. 1248 1249 {\bf exit} \\ 1250 Terminate script interpreter or invoke the special ::exit'' 1251 label in the current script. 1252 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''. 1257 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. 1264 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. 1269 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. 1274 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. 1285 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. 1293 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. 1302 1303 {\bf label} {\it value ...} \\ 1304 Create a named local label to receive a skip command request. 1305 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). 1309 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. 1314 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. 1319 1320 {\bf pop} \\ 1321 Pop a gosub off the stack. This only has an effect when 1322 returning. 1323 1324 {\bf repeat} {\it count} \\ 1325 Repeat a loop for the specified count number of times. 1326 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. 1334 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. 1343 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. 1351 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. 1356 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. 1362 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. 1368 1369 \subsection{Basic data sets and logging} 1370 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. 1374 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. 1383 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. 1391 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. 1401 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. 1409 1410 \subsection{Package based extensions} 1411 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: 1416 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. 1420 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. 1429 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. 1433 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. 1438 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. 1445 1446 {\bf random.seed} {\it seedvalue} \\ 1447 Seed the pseudo-random number generator. This is used with the 1448 random'' package. 1449 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. 1454 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''. 1461 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. 1467 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. 1472 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. 1485 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. 1491 1492 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. 1497 1498 \subsection{Bayonne call processing commands} 1499 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. 1504 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. 1515 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. 1523 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. 1529 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. 1539 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. 1551 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. 1555 1556 {\bf debug message..} \\ 1557 Send a message to the debugging monitor if one is installed 1558 through the plugins. 1559 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. 1567 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. 1573 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. 1580 1581 {\bf erase} {\it [prefix=path]} {\it filename} \\ 1582 Erase a specified file from a /var/\-lib/\-bayonne prefixed path. 1583 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. 1588 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. 1594 1595 {\bf hangup[.self]} \\ 1596 This is essentially the same as the ccScript exit'' command. 1597 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. 1601 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. 1605 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. 1616 1617 {\bf move} {\it [prefix=path]} {\it source destination} \\ 1618 Move or rename an individual file in the /var/\-lib/\-bayonne prefixed 1619 path. 1620 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. 1632 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. 1643 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. 1651 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. 1656 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. 1666 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}. 1673 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. 1677 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. 1682 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. 1690 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. 1694 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. 1699 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''. 1705 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. 1713 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. 1724 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. 1731 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. 1737 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. 1744 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. 1751 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. 1755 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. 1758 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. 1761 1762 \subsection{Bayonne Preference and User Session Management} 1763 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. 1769 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}. 1774 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. 1780 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. 1787 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. 1791 1792 {\bf logout} \\ 1793 Logs out of the current active user session. 1794 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. 1799 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}. 1804 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. 1809 1810 \subsection{Driver specific commands} 1811 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: 1818 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. 1829 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. 1837 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. 1846 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. 1859 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. 1864 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. 1872 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. 1878 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. 1886 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. 1890 1891 {\bf ring.clear} \\ 1892 This is a PBX driver feature to clear all pending ring requests 1893 against the current station. 1894 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. 1903 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. 1909 1910 \subsection{XML support based plugins} 1911 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: 1916 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}. 1923 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. 1932 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. 1942 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''. 1948 1949 \section{Troubleshooting ccScripts and TGIs} 1950 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). 1954 1955 Don't use '=', use '-eq' to check for equality. Also, '==' is broken 1956 in older versions of Bayonne. Use '.eq.' instead. 1957 1958 Are you confusing the name of a script (like foo'') with a label 1959 name (like ::foo'')? 1960 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. 1964 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. 1969 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). 1972 1973 Did the ccscript engine print out any interesting error messages 1974 during startup or 'bayctrl compile'? Perhaps you should review them. 1975 1976 Did you remember to run 'bayctrl compile' or to restart bayonne after 1977 you modified your script? 1978 1979 If you do things like "goto script", and script.scr looks like this: 1980 1981 \begin{verbatim} 1982 ::start 1983 do stuff 1984 do stuff 1985 1986 ^event 1987 ^event 1988 goto script 1989 \end{verbatim} 1990 1991 The goto will fail. Instead, say "goto script::start". 1992 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. 2000 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. 2004 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. 2009 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}
2016
2017 The standard way to get digits so the caller can interrupt the message is:
2018
2019 \begin{verbatim}
2020 clear %session.digits
2021
2022 play *::1 # "Press 1 for foo, press 2 for baz,
2023           # press 3 for gronk..."
2024 sleep 60
2025
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}
2032
2033 The standard way to get digits so the caller can't interrupt the message is:
2034
2035 \begin{verbatim}
2036 clear %session.digits
2037
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}
2045
2046 * A note on event traps:
2047
2048 They are order sensitive.  If you have
2049
2050 \begin{verbatim}
2051
2052 ^dtmf
2053         goto ::foo
2054 ^pound
2055         goto ::bar
2056 \end{verbatim}
2057
2058 You will never be able to reach bar.  \^dtmf takes precedence.  Also, traps do not work within traps.
2059
2060 \begin{verbatim}
2061 ^dtmf
2062         ^star
2063                 goto ::foo
2064         ^pound
2065                 goto ::bar
2066 \end{verbatim}
2067
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.
2070
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.
2077
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:
2083
2084 \begin{verbatim}
2085 fifo: cmd=SET&2&return&1
2086 \end{verbatim}
2087
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.
2098
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.
2108
2109 \section{Phrasebook Rules}
2110
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.
2116
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.
2121
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.
2127
2128 In Bayonne phrasebook, we may define this as follows:
2129
2131
2132 \begin{verbatim}
2133         speak &msgswaiting %msgcount no msgwaiting msgswaiting
2134 \end{verbatim}
2135
2136 We would then define under [english] something like:
2137
2138 \begin{verbatim}
2139 msgswaiting = youhave &number &zero &singular &plural
2140 \end{verbatim}
2141
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.
2157
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.
2162
2163 Speaking of currency "values" have specific phrasebook rules.  Currency
2164 values are also subject to the "\&zero" rule, so for example:
2165
2166 balance=youhave \&cy \&zero remaining
2167
2168 and using:
2169
2170 speak \&balance \%balance nomoney
2171
2172 can use the alternate "no monay" .au prompt rather than saying "0
2173 dollars".
2174
2175 \subsection{English}
2176 The following default phrasebook rules are or will be defined for english:
2177
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}
2198
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
2201
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
2204
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
2209
2210 \subsubsection{Currency Prompts}
2211 dollar, dollars, cent, cents, and, or
2212
`