Merged revisions 77424,77429 via svnmerge from
[asterisk/asterisk.git] / doc / tex / channelvariables.tex
1 \section{Introduction}
2
3 There are two levels of parameter evaluation done in the Asterisk
4 dial plan in extensions.conf.
5 \begin{enumerate}
6 \item The first, and most frequently used, is the substitution of variable
7   references with their values. 
8 \item Then there are the evaluations of expressions done in \$[ .. ]. 
9   This will be discussed below.
10 \end{enumerate}
11 Asterisk has user-defined variables and standard variables set
12 by various modules in Asterisk. These standard variables are
13 listed at the end of this document.
14
15 \section{Parameter Quoting}
16 \begin{verbatim}
17 exten => s,5,BackGround,blabla
18 \end{verbatim}
19 The parameter (blabla) can be quoted ("blabla"). In this case, a 
20 comma does not terminate the field. However, the double quotes
21 will be passed down to the Background command, in this example.
22
23 Also, characters special to variable substitution, expression evaluation, etc
24 (see below), can be quoted. For example, to literally use a \$ on the 
25 string "\$1231", quote it with a preceding \textbackslash. Special characters that must
26 be quoted to be used, are [ ] \$ " \textbackslash. (to write \textbackslash itself, use \textbackslash). 
27
28 These Double quotes and escapes are evaluated at the level of the
29 asterisk config file parser. 
30
31 Double quotes can also be used inside expressions, as discussed below.
32
33 \section{Variables}
34
35 Parameter strings can include variables. Variable names are arbitrary strings. 
36 They are stored in the respective channel structure. 
37
38 To set a variable to a particular value, do: 
39 \begin{verbatim}
40     exten => 1,2,Set(varname=value)
41 \end{verbatim}
42 You can substitute the value of a variable everywhere using \${variablename}.
43 For example, to stringwise append \$lala to \$blabla and store result in \$koko, 
44 do: 
45 \begin{verbatim}
46    exten => 1,2,Set(koko=${blabla}${lala})
47 \end{verbatim}
48
49 There are two reference modes - reference by value and reference by name. 
50 To refer to a variable with its name (as an argument to a function that 
51 requires a variable), just write the name. To refer to the variable's value, 
52 enclose it inside \${}. For example, Set takes as the first argument 
53 (before the =) a variable name, so: 
54 \begin{verbatim}
55   exten => 1,2,Set(koko=lala)
56   exten => 1,3,Set(${koko}=blabla)
57 \end{verbatim}
58 stores to the variable "koko" the value "lala" and to variable "lala" the 
59 value "blabla". 
60
61 In fact, everything contained \${here} is just replaced with the value of 
62 the variable "here". 
63
64 \section{Variable Inheritance}
65
66 Variable names which are prefixed by "\_" will be inherited to channels 
67 that are created in the process of servicing the original channel in 
68 which the variable was set.  When the inheritance takes place, the 
69 prefix will be removed in the channel inheriting the variable.  If the 
70 name is prefixed by "\_\_" in the channel, then the variable is 
71 inherited and the "\_\_" will remain intact in the new channel.
72
73 In the dialplan, all references to these variables refer to the same 
74 variable, regardless of having a prefix or not.  Note that setting any 
75 version of the variable removes any other version of the variable, 
76 regardless of prefix.
77
78 \subsection{Example}
79 \begin{verbatim}
80 Set(__FOO=bar) ; Sets an inherited version of "FOO" variable 
81 Set(FOO=bar)   ; Removes the inherited version and sets a local 
82                ; variable.
83
84 However,
85
86 NoOp(${__FOO}) is identical to NoOp(${FOO})
87 \end{verbatim}
88
89
90 \section{Selecting Characters from Variables}
91
92 The format for selecting characters from a variable can be expressed as:
93 \begin{verbatim}
94   ${variable_name[:offset[:length]]}
95 \end{verbatim}
96 If you want to select the first N characters from the string assigned
97 to a variable, simply append a colon and the number of characters to
98 skip from the beginning of the string to the variable name.
99 \begin{verbatim}
100   ; Remove the first character of extension, save in "number" variable
101   exten => _9X.,1,Set(number=${EXTEN:1})
102 \end{verbatim}
103 Assuming we've dialed 918005551234, the value saved to the 'number' variable
104 would be 18005551234. This is useful in situations when we require users to 
105 dial a number to access an outside line, but do not wish to pass the first 
106 digit.
107
108 If you use a negative offset number, Asterisk starts counting from the end 
109 of the string and then selects everything after the new position. The following
110 example will save the numbers 1234 to the 'number' variable, still assuming
111 we've dialed 918005551234.
112 \begin{verbatim}
113   ; Remove everything before the last four digits of the dialed string
114   exten => _9X.,1,Set(number=${EXTEN:-4})
115 \end{verbatim}
116 We can also limit the number of characters from our offset position that we
117 wish to use. This is done by appending a second colon and length value to the
118 variable name. The following example will save the numbers 555 to the 'number'
119 variable.
120 \begin{verbatim}
121   ; Only save the middle numbers 555 from the string 918005551234
122   exten => _9X.,1,Set(number=${EXTEN:5:3})
123 \end{verbatim}
124 The length value can also be used in conjunction with a negative offset. This
125 may be useful if the length of the string is unknown, but the trailing digits
126 are. The following example will save the numbers 555 to the 'number' variable,
127 even if the string starts with more characters than expected (unlike the
128 previous example).
129 \begin{verbatim}
130   ; Save the numbers 555 to the 'number' variable
131   exten => _9X.,1,Set(number=${EXTEN:-7:3})
132 \end{verbatim}
133 If a negative length value is entered, Asterisk will remove that many characters
134 from the end of the string.
135 \begin{verbatim}
136   ; Set pin to everything but the trailing #.
137   exten => _XXXX#,1,Set(pin=${EXTEN:0:-1})
138 \end{verbatim}
139
140 \section{Expressions} 
141
142 Everything contained inside a bracket pair prefixed by a \$ (like \$[this]) is 
143 considered as an expression and it is evaluated. Evaluation works similar to 
144 (but is done on a later stage than) variable substitution: the expression 
145 (including the square brackets) is replaced by the result of the expression 
146 evaluation. 
147
148 For example, after the sequence:
149 \begin{verbatim}
150 exten => 1,1,Set(lala=$[1 + 2])
151 exten => 1,2,Set(koko=$[2 * ${lala}])
152 \end{verbatim}
153 the value of variable koko is "6".
154
155 and, further:
156 \begin{verbatim}
157 exten => 1,1,Set,(lala=$[  1 +    2   ]);
158 \end{verbatim}
159 will parse as intended. Extra spaces are ignored.
160
161
162 \subsection{Spaces Inside Variables Values}
163
164 If the variable being evaluated contains spaces, there can be problems.
165
166 For these cases, double quotes around text that may contain spaces
167 will force the surrounded text to be evaluated as a single token.
168 The double quotes will be counted as part of that lexical token.
169
170 As an example:
171
172 \begin{verbatim}
173 exten => s,6,GotoIf($[ "${CALLERID(name)}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
174 \end{verbatim}
175
176 The variable CALLERID(name) could evaluate to "DELOREAN MOTORS" (with a space)
177 but the above will evaluate to:
178
179 \begin{verbatim}
180 "DELOREAN MOTORS" : "Privacy Manager"
181 \end{verbatim}
182
183 and will evaluate to 0.
184
185 The above without double quotes would have evaluated to:
186
187 \begin{verbatim}
188 DELOREAN MOTORS : Privacy Manager
189 \end{verbatim}
190
191 and will result in syntax errors, because token DELOREAN is immediately
192 followed by token MOTORS and the expression parser will not know how to 
193 evaluate this expression, because it does not match its grammar.
194
195 \subsection{Operators}
196
197 Operators are listed below in order of increasing precedence.  Operators
198 with equal precedence are grouped within { } symbols.
199
200 \begin{itemize}
201   \item \verb!expr1 | expr2!
202
203        Return the evaluation of expr1 if it is neither an empty string
204        nor zero; otherwise, returns the evaluation of expr2.
205
206   \item \verb!expr1 & expr2!
207
208        Return the evaluation of expr1 if neither expression evaluates to
209        an empty string or zero; otherwise, returns zero.
210
211   \item \verb+expr1 {=, >, >=, <, <=, !=} expr2+
212
213        Return the results of floating point comparison if both arguments are
214        numbers; otherwise, returns the results of string comparison
215        using the locale-specific collation sequence.  The result of each
216        comparison is 1 if the specified relation is true, or 0 if the
217        relation is false.
218
219   \item \verb!expr1 {+, -} expr2!
220
221        Return the results of addition or subtraction of floating point-valued
222        arguments.
223
224   \item \verb!expr1 {*, /, %} expr2!
225
226        Return the results of multiplication, floating point division, or
227        remainder of arguments.
228
229   \item \verb!- expr1!
230
231        Return the result of subtracting expr1 from 0.
232        This, the unary minus operator, is right associative, and
233        has the same precedence as the ! operator.
234
235   \item \verb+! expr1+
236
237        Return the result of a logical complement of expr1.
238        In other words, if expr1 is null, 0, an empty string,
239        or the string "0", return a 1. Otherwise, return a 0.
240        It has the same precedence as the unary minus operator, and
241        is also right associative.
242
243   \item \verb!expr1 : expr2!
244
245        The `:' operator matches expr1 against expr2, which must be a
246        regular expression.  The regular expression is anchored to the
247        beginning of  the string with an implicit `\^'.
248
249        If the match succeeds and the pattern contains at least one regular 
250        expression subexpression `\(...\)', the string corresponing 
251        to `\textbackslash1' is returned; otherwise the matching operator
252        returns the number of characters matched.  If the match fails and
253        the pattern contains a regular expression subexpression the null
254        string is returned; otherwise 0.
255
256        Normally, the double quotes wrapping a string are left as part
257        of the string. This is disastrous to the : operator. Therefore,
258        before the regex match is made, beginning and ending double quote
259        characters are stripped from both the pattern and the string.
260
261    \item \verb!expr1 =~ expr2!
262
263        Exactly the same as the ':' operator, except that the match is
264        not anchored to the beginning of the string. Pardon any similarity
265        to seemingly similar operators in other programming languages!
266        The ":" and "=\~" operators share the same precedence.
267
268    \item \verb!expr1 ? expr2 :: expr3!
269
270        Traditional Conditional operator. If expr1 is a number
271        that evaluates to 0 (false), expr3 is result of the this
272        expression evaluation.  Otherwise, expr2 is the result.
273        If expr1 is a string, and evaluates to an empty string,
274        or the two characters (""), then expr3 is the
275        result. Otherwise, expr2 is the result.  In Asterisk, all
276        3 exprs will be "evaluated"; if expr1 is "true", expr2
277        will be the result of the "evaluation" of this
278        expression.  expr3 will be the result otherwise. This
279        operator has the lowest precedence.
280 \end{itemize}
281
282 Parentheses are used for grouping in the usual manner.
283
284 Operator precedence is applied as one would expect in any of the C
285 or C derived languages.
286
287 \subsection{Floating Point Numbers}
288
289 In 1.6 and above, we shifted the \$[...] expressions to be calculated
290 via floating point numbers instead of integers. We use 'long double' numbers
291 when possible, which provide around 16 digits of precision with 12 byte numbers. 
292
293 To specify a floating point constant, the number has to have this format: D.D, where D is 
294 a string of base 10 digits. So, you can say 0.10, but you can't say .10 or 20.-- we hope
295 this is not an excessive restriction!
296
297 Floating point numbers are turned into strings via the '%g'/'%Lg' format of the printf
298 function set. This allows numbers to still 'look' like integers to those counting
299 on integer behavior. If you were counting on 1/4 evaluating to 0, you need to now say
300 TRUNC(1/4). For a list of all the truncation/rounding capabilities, see the next section.
301
302
303 \subsection{Functions}
304
305 In 1.6 and above, we upgraded the \$[] expressions to handle floating point numbers.
306 Because of this, folks counting on integer behavior would be disrupted. To make
307 the same results possible, some rounding and integer truncation functions have been
308 added to the core of the Expr2 parser. Indeed, dialplan functions can be called from
309 \$[..] expressions without the \$\{...\} operators. The only trouble might be in the fact that
310 the arguments to these functions must be specified with a comma. If you try to call
311 the MATH function, for example, and try to say 3 + MATH(7*8), the expression parser will
312 evaluate 7*8 for you into 56, and the MATH function will most likely complain that its 
313 input doesn't make any sense.
314
315 We also provide access to most of the floating point functions in the C library. (but not all of them).
316
317 While we don't expect someone to want to do Fourier analysis in the dialplan, we
318 don't want to preclude it, either.
319
320 Here is a list of the 'builtin' functions in Expr2. All other dialplan functions
321 are available by simply calling them (read-only). In other words, you don't need to
322 surround function calls in \$[...] expressions with \$\{...\}. Don't jump to conclusions,
323 though! -- you still need to wrap variable names in curly braces!
324
325 \begin{enumerate}
326 \item COS(x) x is in radians. Results vary from -1 to 1. 
327 \item SIN(x) x is in radians. Results vary from -1 to 1.
328 \item TAN(x) x is in radians.
329 \item ACOS(x) x should be a value between -1 and 1.
330 \item ASIN(x) x should be a value between -1 and 1.
331 \item ATAN(x) returns the arc tangent in radians; between -PI/2 and PI/2.
332 \item ATAN2(x,y) returns a result resembling y/x, except that the signs of both args are used to determine the quadrant of the result. Its result is in radians, between -PI and PI.
333 \item POW(x,y) returns the value of x raised to the power of y.
334 \item SQRT(x) returns the square root of x.
335 \item FLOOR(x) rounds x down to the nearest integer.
336 \item CEIL(x) rounds x up to the nearest integer.
337 \item ROUND(x) rounds x to the nearest integer, but round halfway cases away from zero.
338 \item RINT(x) rounds x to the nearest integer, rounding halfway cases to the nearest even integer.
339 \item TRUNC(x) rounds x to the nearest integer not larger in absolute value.
340 \item REMAINDER(x,y) computes the remainder of dividing x by y. The return value is x - n*y, where n is the value x/y, rounded to the nearest integer.
341 If this quotient is 1/2, it is rounded to the nearest even number.
342 \item EXP(x) returns e to the x power.
343 \item EXP2(x) returns 2 to the x power.
344 \item LOG(x) returns the natural logarithm of x.
345 \item LOG2(x) returns the base 2 log of x.
346 \item LOG10(x) returns the base 10 log of x.
347 \end{enumerate}
348
349 \subsection{Examples}
350
351 \begin{astlisting}
352 \begin{verbatim}
353  "One Thousand Five Hundred" =~ "(T[^ ]+)"
354    returns: Thousand
355
356  "One Thousand Five Hundred" =~ "T[^ ]+"
357    returns: 8
358
359  "One Thousand Five Hundred" : "T[^ ]+"
360    returns: 0
361
362  "8015551212" : "(...)"
363    returns: 801
364
365  "3075551212":"...(...)"
366    returns: 555
367
368  ! "One Thousand Five Hundred" =~ "T[^ ]+"
369    returns: 0 (because it applies to the string, which is non-null,
370                     which it turns to "0", and then looks for the pattern
371                     in the "0", and doesn't find it)
372
373  !( "One Thousand Five Hundred" : "T[^ ]+" )
374    returns: 1  (because the string doesn't start with a word starting
375                      with T, so the match evals to 0, and the ! operator
376                      inverts it to 1 ).
377
378  2 + 8 / 2
379    returns 6. (because of operator precedence; the division is done first, then the addition).
380
381  2+8/2
382    returns 6. Spaces aren't necessary.
383
384 (2+8)/2
385    returns 5, of course.
386
387 (3+8)/2
388    returns 5.5 now.
389
390 TRUNC((3+8)/2)
391    returns 5.
392
393 FLOOR(2.5)
394    returns 2
395
396 FLOOR(-2.5)
397    returns -3
398
399 CEIL(2.5)
400    returns 3.
401
402 CEIL(-2.5)
403    returns -2.
404
405 ROUND(2.5)
406    returns 3.
407
408 ROUND(3.5)
409    returns 4.
410
411 ROUND(-2.5)
412    returns -3
413
414 RINT(2.5)
415    returns 2.
416
417 RINT(3.5)
418    returns 4.
419
420 RINT(-2.5)
421    returns -2.
422
423 RINT(-3.5)
424    returns -4.
425
426 TRUNC(2.5)
427    returns 2.
428
429 TRUNC(3.5)
430    returns 3.
431
432 TRUNC(-3.5)
433    returns -3.
434
435 \end{verbatim}
436 \end{astlisting}
437
438 Of course, all of the above examples use constants, but would work the
439 same if any of the numeric or string constants were replaced with a
440 variable reference \${CALLERID(num)}, for instance.
441
442
443 \subsection{Numbers Vs. Strings}
444
445 Tokens consisting only of numbers are converted to 'long double' if possible, which
446 are from 80 bits to 128 bits depending on the OS, compiler, and hardware.
447 This means that overflows can occur when the
448 numbers get above 18 digits (depending on the number of bits involved).  Warnings will appear in the logs in this
449 case.
450
451 \subsection{Conditionals}
452
453 There is one conditional application - the conditional goto : 
454
455 \begin{verbatim}
456   exten => 1,2,GotoIf(condition?label1:label2)
457 \end{verbatim}
458
459 If condition is true go to label1, else go to label2. Labels are interpreted
460 exactly as in the normal goto command.
461
462 "condition" is just a string. If the string is empty or "0", the condition
463 is considered to be false, if it's anything else, the condition is true. 
464 This is designed to be used together with the expression syntax described 
465 above, eg : 
466
467 \begin{verbatim}
468   exten => 1,2,GotoIf($[${CALLERID(all)} = 123456]?2|1:3|1)
469 \end{verbatim}
470
471 Example of use : 
472
473 \begin{verbatim}
474 exten => s,2,Set(vara=1)
475 exten => s,3,Set(varb=$[${vara} + 2])
476 exten => s,4,Set(varc=$[${varb} * 2])
477 exten => s,5,GotoIf($[${varc} = 6]?99|1:s|6)
478 \end{verbatim}
479
480 \subsection{Parse Errors}
481
482 Syntax errors are now output with 3 lines.
483
484 If the extensions.conf file contains a line like:
485
486 \begin{verbatim}
487 exten => s,6,GotoIf($[ "${CALLERID(num)}"  = "3071234567" & &  "${CALLERID(name)}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
488 \end{verbatim}
489
490 You may see an error in /var/log/asterisk/messages like this:
491 \begin{verbatim}
492 Jul 15 21:27:49 WARNING[1251240752]: ast_yyerror(): syntax error: parse error, unexpected TOK_AND, expecting TOK_MINUS or TOK_LP or TOKEN; Input:
493 "3072312154"  = "3071234567" & & "Steves Extension" : "Privacy Manager" 
494                                ^
495 \end{verbatim}
496
497 The log line tells you that a syntax error was encountered. It now
498 also tells you (in grand standard bison format) that it hit an "AND"
499 (\&) token unexpectedly, and that was hoping for for a MINUS (-), LP
500 (left parenthesis), or a plain token (a string or number).
501
502 The next line shows the evaluated expression, and the line after
503 that, the position of the parser in the expression when it became confused,
504 marked with the "\^" character.
505
506 \subsection{NULL Strings}
507 Testing to see if a string is null can be done in one of two different ways:
508 \begin{verbatim}
509   exten => _XX.,1,GotoIf($["${calledid}" != ""]?3) 
510
511   exten => _XX.,1,GotoIf($[foo${calledid} != foo]?3) 
512 \end{verbatim}
513
514 The second example above is the way suggested by the WIKI. It will 
515 work as long as there are no spaces in the evaluated value.
516
517 The first way should work in all cases, and indeed, might now
518 be the safest way to handle this situation.
519
520 \subsection{Warning}
521
522 If you need to do complicated things with strings, asterisk expressions
523 is most likely NOT the best way to go about it. AGI scripts are an
524 excellent option to this need, and make available the full power of
525 whatever language you desire, be it Perl, C, C++, Cobol, RPG, Java,
526 Snobol, PL/I, Scheme, Common Lisp, Shell scripts, Tcl, Forth, Modula,
527 Pascal, APL, assembler, etc.
528
529 \subsection{Incompatabilities}
530
531 The asterisk expression parser has undergone some evolution. It is hoped
532 that the changes will be viewed as positive. 
533
534 The "original" expression parser had a simple, hand-written scanner,
535 and a simple bison grammar. This was upgraded to a more involved bison
536 grammar, and a hand-written scanner upgraded to allow extra spaces,
537 and to generate better error diagnostics. This upgrade required bison
538 1.85, and part of the user community felt the pain of having to
539 upgrade their bison version.
540
541 The next upgrade included new bison and flex input files, and the makefile
542 was upgraded to detect current version of both flex and bison, conditionally
543 compiling and linking the new files if the versions of flex and bison would
544 allow it.
545
546 If you have not touched your extensions.conf files in a year or so, the
547 above upgrades may cause you some heartburn in certain circumstances, as
548 several changes have been made, and these will affect asterisk's behavior on 
549 legacy extension.conf constructs.  The changes have been engineered
550 to minimize these conflicts, but there are bound to be problems.
551
552 The following list gives some (and most likely, not all) of areas
553 of possible concern with "legacy" extension.conf files:
554
555 \begin{enumerate}
556 \item Tokens separated by space(s).
557    Previously, tokens were separated by spaces. Thus, ' 1 + 1 ' would evaluate
558    to the value '2', but '1+1' would evaluate to the string '1+1'. If this
559    behavior was depended on, then the expression evaluation will break. '1+1'
560    will now evaluate to '2', and something is not going to work right.
561    To keep such strings from being evaluated, simply wrap them in double 
562    quotes: '  "1+1" '
563
564 \item The colon operator. In versions previous to double quoting, the
565    colon operator takes the right hand string, and using it as a 
566    regex pattern, looks for it in the left hand string. It is given
567    an implicit \^ operator at the beginning, meaning the pattern 
568    will match only at the beginning of the left hand string. 
569    If the pattern or the matching string had double quotes around
570    them, these could get in the way of the pattern match. Now,
571    the wrapping double quotes are stripped from both the pattern 
572    and the left hand string before applying the pattern. This
573    was done because it recognized that the new way of
574    scanning the expression doesn't use spaces to separate tokens,
575    and the average regex expression is full of operators that 
576    the scanner will recognize as expression operators. Thus, unless
577    the pattern is wrapped in double quotes, there will be trouble.
578    For instance,      \${VAR1} : (Who|What*)+
579    may have have worked before, but unless you wrap the pattern
580    in double quotes now, look out for trouble! This is better:
581          "\${VAR1}" : "(Who|What*)+"
582    and should work as previous.
583
584 \item Variables and Double Quotes
585    Before these changes, if a variable's value contained one or more double
586    quotes, it was no reason for concern. It is now!
587
588 \item LE, GE, NE operators removed. The code supported these operators,
589    but they were not documented. The symbolic operators, $<$=, $>$=, and !=
590    should be used instead.
591
592 \item  Added the unary '-' operator. So you can 3+ -4 and get -1.
593
594 \item  Added the unary '!' operator, which is a logical complement.
595     Basically, if the string or number is null, empty, or '0',
596     a '1' is returned. Otherwise a '0' is returned.
597
598 \item  Added the '=~' operator, just in case someone is just looking for
599     match anywhere in the string. The only diff with the ':' is that
600     match doesn't have to be anchored to the beginning of the string.
601
602 \item  Added the conditional operator  'expr1 ? true\_expr :: false\_expr'
603     First, all 3 exprs are evaluated, and if expr1 is false, the 'false\_expr'
604     is returned as the result. See above for details. 
605
606 \item  Unary operators '-' and '!' were made right associative.
607 \end{enumerate}
608
609 \subsection{Debugging Hints}
610
611 There are two utilities you can build to help debug the \$[ ] in
612 your extensions.conf file.
613
614 The first, and most simplistic, is to issue the command:
615
616 make testexpr2
617
618 in the top level asterisk source directory. This will build a small
619 executable, that is able to take the first command line argument, and
620 run it thru the expression parser. No variable substitutions will be
621 performed. It might be safest to wrap the expression in single
622 quotes...
623
624 testexpr2 '2*2+2/2'
625
626 is an example.
627
628 And, in the utils directory, you can say:
629
630 make check\_expr
631
632 and a small program will be built, that will check the file mentioned
633 in the first command line argument, for any expressions that might be
634 have problems when you move to flex-2.5.31.  It was originally
635 designed to help spot possible incompatibilities when moving from the
636 pre-2.5.31 world to the upgraded version of the lexer.
637
638 But one more capability has been added to check\_expr, that might make
639 it more generally useful. It now does a simple minded evaluation of
640 all variables, and then passes the \$[] exprs to the parser. If there
641 are any parse errors, they will be reported in the log file. You can
642 use check\_expr to do a quick sanity check of the expressions in your
643 extensions.conf file, to see if they pass a crude syntax check.
644
645 The "simple-minded" variable substitution replaces \${varname} variable
646 references with '555'. You can override the 555 for variable values,
647 by entering in var=val arguments after the filename on the command
648 line.  So...
649
650  check\_expr /etc/asterisk/extensions.conf CALLERID(num)=3075551212 DIALSTATUS=TORTURE EXTEN=121
651
652 will substitute any \${CALLERIDNUM} variable references with
653 3075551212, any \${DIALSTATUS} variable references with 'TORTURE', and
654 any \${EXTEN} references with '121'.  If there is any fancy stuff
655 going on in the reference, like \${EXTEN:2}, then the override will
656 not work. Everything in the \${...} has to match. So, to substitute
657 \${EXTEN:2} references, you'd best say:
658
659  check\_expr /etc/asterisk/extensions.conf CALLERID(num)=3075551212 DIALSTATUS=TORTURE EXTEN:2=121
660
661 on stdout, you will see something like:
662
663 \begin{verbatim}
664  OK -- $[ "${DIALSTATUS}"  = "TORTURE" | "${DIALSTATUS}" = "DONTCALL" ] at line 416
665 \end{verbatim}
666
667 In the expr2\_log file that is generated, you will see:
668
669 \begin{verbatim}
670  line 416, evaluation of $[  "TORTURE"  = "TORTURE" | "TORTURE" = "DONTCALL"  ] result: 1
671 \end{verbatim}
672
673 check\_expr is a very simplistic algorithm, and it is far from being
674 guaranteed to work in all cases, but it is hoped that it will be
675 useful.
676
677 \section{Asterisk standard channel variables}
678
679 There are a number of variables that are defined or read
680 by Asterisk. Here is a list of them. More information is
681 available in each application's help text. All these variables
682 are in UPPER CASE only.
683
684 Variables marked with a * are builtin functions and can't be set,
685 only read in the dialplan.  Writes to such variables are silently 
686 ignored.
687
688 \begin{verbatim}
689 ${CDR(accountcode)}    * Account code (if specified)
690 ${BLINDTRANSFER}         The name of the channel on the other side of a blind transfer
691 ${BRIDGEPEER}            Bridged peer
692 ${CALLERID(ani)}       * Caller ANI (PRI channels)
693 ${CALLERID(all)}       * Caller ID
694 ${CALLERID(dnid)}      * Dialed Number Identifier
695 ${CALLERID(name)}      * Caller ID Name only
696 ${CALLERID(num)}       * Caller ID Number only
697 ${CALLERID(rdnis)}     * Redirected Dial Number ID Service
698 ${CALLINGANI2}         * Caller ANI2 (PRI channels)
699 ${CALLINGPRES}         * Caller ID presentation for incoming calls (PRI channels)
700 ${CALLINGTNS}          * Transit Network Selector (PRI channels)
701 ${CALLINGTON}          * Caller Type of Number (PRI channels)
702 ${CHANNEL}             * Current channel name
703 ${CONTEXT}             * Current context
704 ${DATETIME}            * Current date time in the format: DDMMYYYY-HH:MM:SS 
705                          (Deprecated; use ${STRFTIME(${EPOCH},,%d%m%Y-%H:%M:%S)})
706 ${DB_RESULT}             Result value of DB_EXISTS() dial plan function
707 ${EPOCH}               * Current unix style epoch
708 ${EXTEN}               * Current extension
709 ${ENV(VAR)}              Environmental variable VAR
710 ${GOTO_ON_BLINDXFR}      Transfer to the specified context/extension/priority
711                          after a blind transfer (use ^ characters in place of
712                          | to separate context/extension/priority when setting
713                          this variable from the dialplan)
714 ${HANGUPCAUSE}         * Asterisk cause of hangup (inbound/outbound)
715 ${HINT}                * Channel hints for this extension
716 ${HINTNAME}            * Suggested Caller*ID name for this extension
717 ${INVALID_EXTEN}         The invalid called extension (used in the "i" extension)
718 ${LANGUAGE}            * Current language (Deprecated; use ${LANGUAGE()})
719 ${LEN(VAR)}            * String length of VAR (integer)
720 ${PRIORITY}            * Current priority in the dialplan
721 ${PRIREDIRECTREASON}     Reason for redirect on PRI, if a call was directed
722 ${TIMESTAMP}           * Current date time in the format: YYYYMMDD-HHMMSS 
723                          (Deprecated; use ${STRFTIME(${EPOCH},,%Y%m%d-%H%M%S)})
724 ${TRANSFER_CONTEXT}      Context for transferred calls
725 ${FORWARD_CONTEXT}       Context for forwarded calls
726 ${UNIQUEID}            * Current call unique identifier
727 ${SYSTEMNAME}          * value of the systemname option of asterisk.conf
728 \end{verbatim}
729
730 \subsection{Application return values}
731
732 In Asterisk 1.2, many applications return the result in a variable
733 instead of, as in Asterisk 1.0, changing the dial plan priority (+101).
734 For the various status values, see each application's help text.
735 \begin{verbatim}
736 ${AGISTATUS}         * agi()
737 ${AQMSTATUS}         * addqueuemember()
738 ${AVAILSTATUS}       * chanisavail()
739 ${CHECKGROUPSTATUS}  * checkgroup()
740 ${CHECKMD5STATUS}    * checkmd5()
741 ${CPLAYBACKSTATUS}   * controlplayback()
742 ${DIALSTATUS}        * dial()
743 ${DBGETSTATUS}       * dbget()
744 ${ENUMSTATUS}        * enumlookup()
745 ${HASVMSTATUS}       * hasnewvoicemail()
746 ${LOOKUPBLSTATUS}    * lookupblacklist()
747 ${OSPAUTHSTATUS}     * ospauth()
748 ${OSPLOOKUPSTATUS}   * osplookup()
749 ${OSPNEXTSTATUS}     * ospnext()
750 ${OSPFINISHSTATUS}   * ospfinish()
751 ${PARKEDAT}          * parkandannounce()
752 ${PLAYBACKSTATUS}    * playback()
753 ${PQMSTATUS}         * pausequeuemember()
754 ${PRIVACYMGRSTATUS}  * privacymanager()
755 ${QUEUESTATUS}       * queue()
756 ${RQMSTATUS}         * removequeuemember()
757 ${SENDIMAGESTATUS}   * sendimage()
758 ${SENDTEXTSTATUS}    * sendtext()
759 ${SENDURLSTATUS}     * sendurl()
760 ${SYSTEMSTATUS}      * system()
761 ${TRANSFERSTATUS}    * transfer()
762 ${TXTCIDNAMESTATUS}  * txtcidname()
763 ${UPQMSTATUS}        * unpausequeuemember()
764 ${VMSTATUS}          * voicmail()
765 ${VMBOXEXISTSSTATUS} * vmboxexists()
766 ${WAITSTATUS}        * waitforsilence()
767 \end{verbatim}
768
769 \subsection{Various application variables}
770 \begin{verbatim}
771 ${CURL}                 * Resulting page content for curl()
772 ${ENUM}                 * Result of application EnumLookup
773 ${EXITCONTEXT}            Context to exit to in IVR menu (app background())
774                           or in the RetryDial() application
775 ${MONITOR}              * Set to "TRUE" if the channel is/has been monitored (app monitor())
776 ${MONITOR_EXEC}           Application to execute after monitoring a call
777 ${MONITOR_EXEC_ARGS}      Arguments to application
778 ${MONITOR_FILENAME}       File for monitoring (recording) calls in queue
779 ${QUEUE_PRIO}             Queue priority
780 ${QUEUE_MAX_PENALTY}      Maximum member penalty allowed to answer caller
781 ${QUEUESTATUS}            Status of the call, one of:
782                           (TIMEOUT | FULL | JOINEMPTY | LEAVEEMPTY | JOINUNAVAIL | LEAVEUNAVAIL)
783 ${RECORDED_FILE}        * Recorded file in record()
784 ${TALK_DETECTED}        * Result from talkdetect()
785 ${TOUCH_MONITOR}          The filename base to use with Touch Monitor (auto record)
786 ${TOUCH_MONITOR_FORMAT}   The audio format to use with Touch Monitor (auto record)
787 ${TOUCH_MONITOR_OUTPUT} * Recorded file from Touch Monitor (auto record)
788 ${TXTCIDNAME}           * Result of application TXTCIDName
789 ${VPB_GETDTMF}            chan_vpb
790 \end{verbatim}
791
792 \subsection{The MeetMe Conference Bridge}
793 \begin{verbatim}
794 ${MEETME_RECORDINGFILE}     Name of file for recording a conference with 
795                             the "r" option
796 ${MEETME_RECORDINGFORMAT}   Format of file to be recorded
797 ${MEETME_EXIT_CONTEXT}      Context for exit out of meetme meeting
798 ${MEETME_AGI_BACKGROUND}    AGI script for Meetme (zap only)
799 ${MEETMESECS}             * Number of seconds a user participated in a MeetMe conference
800 \end{verbatim}
801
802 \subsection{The VoiceMail() application}
803 \begin{verbatim}
804 ${VM_CATEGORY}      Sets voicemail category
805 ${VM_NAME}        * Full name in voicemail
806 ${VM_DUR}         * Voicemail duration
807 ${VM_MSGNUM}      * Number of voicemail message in mailbox
808 ${VM_CALLERID}    * Voicemail Caller ID (Person leaving vm)
809 ${VM_CIDNAME}     * Voicemail Caller ID Name
810 ${VM_CIDNUM}      * Voicemail Caller ID Number
811 ${VM_DATE}        * Voicemail Date
812 ${VM_MESSAGEFILE} * Path to message left by caller
813 \end{verbatim}
814
815 \subsection{The VMAuthenticate() application}
816 \begin{verbatim}
817 ${AUTH_MAILBOX}   * Authenticated mailbox
818 ${AUTH_CONTEXT}   * Authenticated mailbox context
819 \end{verbatim}
820
821 \subsection{DUNDiLookup()}
822 \begin{verbatim}
823 ${DUNDTECH}       * The Technology of the result from a call to DUNDiLookup()
824 ${DUNDDEST}       * The Destination of the result from a call to DUNDiLookup()
825 \end{verbatim}
826
827 \subsection{chan\_zap}
828 \begin{verbatim}
829 ${ANI2}               * The ANI2 Code provided by the network on the incoming call. 
830                         (ie, Code 29 identifies call as a Prison/Inmate Call)
831 ${CALLTYPE}           * Type of call (Speech, Digital, etc)
832 ${CALLEDTON}          * Type of number for incoming PRI extension
833                         i.e. 0=unknown, 1=international, 2=domestic, 3=net_specific, 
834                         4=subscriber, 6=abbreviated, 7=reserved 
835 ${CALLINGSUBADDR}     * Called PRI Subaddress
836 ${FAXEXTEN}           * The extension called before being redirected to "fax" 
837 ${PRIREDIRECTREASON}  * Reason for redirect, if a call was directed
838 ${SMDI_VM_TYPE}       * When an call is received with an SMDI message, the 'type'
839                         of message 'b' or 'u'
840 \end{verbatim}
841
842 \subsection{chan\_sip}
843 \begin{verbatim}
844 ${SIPCALLID}         * SIP Call-ID: header verbatim (for logging or CDR matching)
845 ${SIPDOMAIN}         * SIP destination domain of an inbound call (if appropriate)
846 ${SIPUSERAGENT}      * SIP user agent (deprecated)
847 ${SIPURI}            * SIP uri
848 ${SIP_CODEC}           Set the SIP codec for a call  
849 ${SIP_URI_OPTIONS}   * additional options to add to the URI for an outgoing call
850 ${RTPAUDIOQOS}         RTCP QoS report for the audio of this call
851 ${RTPVIDEOQOS}         RTCP QoS report for the video of this call
852 \end{verbatim}
853
854 \subsection{chan\_agent}
855 \begin{verbatim}
856 ${AGENTMAXLOGINTRIES}  Set the maximum number of failed logins
857 ${AGENTUPDATECDR}      Whether to update the CDR record with Agent channel data
858 ${AGENTGOODBYE}        Sound file to use for "Good Bye" when agent logs out
859 ${AGENTACKCALL}        Whether the agent should acknowledge the incoming call
860 ${AGENTAUTOLOGOFF}     Auto logging off for an agent
861 ${AGENTWRAPUPTIME}     Setting the time for wrapup between incoming calls
862 ${AGENTNUMBER}       * Agent number (username) set at login
863 ${AGENTSTATUS}       * Status of login ( fail | on | off )
864 ${AGENTEXTEN}        * Extension for logged in agent
865 \end{verbatim}
866
867
868 \subsection{The Dial() application}
869 \begin{verbatim}
870 ${DIALEDPEERNAME}     * Dialed peer name
871 ${DIALEDPEERNUMBER}   * Dialed peer number
872 ${DIALEDTIME}         * Time for the call (seconds)
873 ${ANSWEREDTIME}       * Time from dial to answer (seconds)
874 ${DIALSTATUS}         * Status of the call, one of:
875                         (CHANUNAVAIL | CONGESTION | BUSY | NOANSWER 
876                         | ANSWER | CANCEL | DONTCALL | TORTURE)
877 ${DYNAMIC_FEATURES}   * The list of features (from the [applicationmap] section of
878                         features.conf) to activate during the call, with feature
879                         names separated by '#' characters
880 ${LIMIT_PLAYAUDIO_CALLER}  Soundfile for call limits
881 ${LIMIT_PLAYAUDIO_CALLEE}  Soundfile for call limits
882 ${LIMIT_WARNING_FILE}      Soundfile for call limits
883 ${LIMIT_TIMEOUT_FILE}      Soundfile for call limits
884 ${LIMIT_CONNECT_FILE}      Soundfile for call limits
885 ${OUTBOUND_GROUP}          Default groups for peer channels (as in SetGroup)
886                            * See "show application dial" for more information
887 \end{verbatim}
888
889 \subsection{The chanisavail() application}
890 \begin{verbatim}
891 ${AVAILCHAN}          * the name of the available channel if one was found  
892 ${AVAILORIGCHAN}      * the canonical channel name that was used to create the channel
893 ${AVAILSTATUS}        * Status of requested channel
894 \end{verbatim}
895
896 \subsection{Dialplan Macros}
897 \begin{verbatim}
898 ${MACRO_EXTEN}        * The calling extensions
899 ${MACRO_CONTEXT}      * The calling context
900 ${MACRO_PRIORITY}     * The calling priority
901 ${MACRO_OFFSET}         Offset to add to priority at return from macro
902 \end{verbatim}
903
904 \subsection{The ChanSpy() application}
905 \begin{verbatim}
906 ${SPYGROUP}           * A ':' (colon) separated list of group names.
907                         (To be set on spied on channel and matched against the g(grp) option)
908 \end{verbatim}
909
910 \subsection{OSP}
911 \begin{verbatim}
912 ${OSPINHANDLE}          OSP handle of in_bound call
913 ${OSPINTIMELIMIT}       Duration limit for in_bound call
914 ${OSPOUTHANDLE}         OSP handle of out_bound call
915 ${OSPTECH}              OSP technology 
916 ${OSPDEST}              OSP destination
917 ${OSPCALLING}           OSP calling number
918 ${OSPOUTTOKEN}          OSP token to use for out_bound call
919 ${OSPOUTTIMELIMIT}      Duration limit for out_bound call
920 ${OSPRESULTS}           Number of remained destinations
921 \end{verbatim}