b892556c690348cc5b27955f3ee5a559a0a30437
[asterisk/asterisk.git] / doc / README.variables
1 EXTENSION LOGIC : 
2
3 There are two levels of parameter evaluation done in asterisk in 
4 extensions.conf.
5 The first, and most frequently used, is the substitution of variable
6 references with their values. 
7
8 Then there are the evaluations done in $[ .. ]. This will be
9 discussed below.
10
11 ___________________________
12 PARAMETER QUOTING: 
13 ---------------------------
14
15 exten => s,5,BackGround,blabla
16
17 The parameter (blabla) can be quoted ("blabla"). In this case, a 
18 comma does not terminate the field. However, the double quotes
19 will be passed down to the Background command, in this example.
20
21 Also, characters special to variable substitution, expression evaluation, etc
22 (see below), can be quoted. For example, to literally use a $ on the 
23 string "$1231", quote it with a preceding \. Special characters that must
24 be quoted to be used, are [ ] $ " \. (to write \ itself, use \\). 
25
26 These Double quotes and escapes are evaluated at the level of the
27 asterisk config file parser. 
28
29 Double quotes can also be used inside expressions, as discussed below.
30
31
32 ___________________________
33 VARIABLES: 
34 ---------------------------
35
36 Parameter strings can include variables. Variable names are arbitrary strings. 
37 They are stored in the respective channel structure. 
38
39 To set a variable to a particular value, do : 
40
41     exten => 1,2,SetVar,varname=value
42
43 You can substitute the value of a variable everywhere using ${variablename}.
44 For example, to stringwise append $lala to $blabla and store result in $koko, 
45 do: 
46
47    exten => 1,2,SetVar,koko=${blabla}${lala}
48
49 There are also the following special variables: 
50
51 ${ACCOUNTCODE}  Account code (if specified)
52 ${CALLERID}     Caller ID
53 ${CALLERIDNAME} Caller ID Name only
54 ${CALLERIDNUM}  Caller ID Number only
55 ${CALLINGPRES}  PRI Caller ID presentation for incoming calls
56 ${CHANNEL}      Current channel name
57 ${CONTEXT}      Current context
58 ${DATETIME}     Current date time in the format: YYYY-MM-DD_HH:MM:SS
59 ${DNID}         Dialed Number Identifier
60 ${ENUM}         Result of application EnumLookup
61 ${EPOCH}        Current unix style epoch
62 ${EXTEN}        Current extension
63 ${ENV(VAR)}     Environmental variable VAR
64 ${HANGUPCAUSE}  Asterisk hangup cause
65 ${INVALID_EXTEN}The invalid called extension (used in the "i" extension)
66 ${LANGUAGE}     Current language
67 ${LEN(VAR)}     String length of VAR (integer)
68 ${MEETMESECS}   Number of seconds a user participated in a MeetMe conference
69 ${PRIORITY}     Current priority
70 ${RDNIS}        Redirected Dial Number ID Service
71 ${SIPCALLID}    SIP Call-ID: header verbatim (for logging or CDR matching)
72 ${SIPDOMAIN}    SIP destination domain of an inbound call (if appropriate)
73 ${SIPUSERAGENT} SIP user agent 
74 ${TIMESTAMP}    Current date time in the format: YYYYMMDD-HHMMSS
75 ${TXTCIDNAME}   Result of application TXTCIDName
76 ${UNIQUEID}     Current call unique identifier
77 ${PRIREDIRECTREASON} Reason for redirect, if a call was directed
78
79 The dial() application sets the following variables:
80
81 ${DIALEDPEERNAME} Dialed peer name
82 ${DIALEDPEERNUMBER} Dialed peer number
83 ${DIALEDTIME}   Total time for the call in seconds (Network time).
84 ${ANSWEREDTIME} Time from answer to end of call in seconds (Billable time).
85 ${DIALSTATUS}   Status of the call, one of:
86                 CHANUNAVAIL | CONGESTION | BUSY | NOANSWER | ANSWER | CANCEL
87
88 The agent channel uses the following variables:
89 ${AGENTMAXLOGINTRIES}   Set the maximum number of failed logins
90 ${AGENTUPDATECDR}       Whether to update the CDR record with Agent channel data
91 ${AGENTGOODBYE}         Sound file to use for "Good Bye" when agent logs out
92 ${AGENTACKCALL}         Whether the agent should acknowledge the incoming call
93 ${AGENTAUTOLOGOFF}      Auto logging off for an agent
94 ${AGENTWRAPUPTIME}      Setting the time for wrapup between incoming calls
95 ${AGENTNUMBER}          Agent number (username) set at login
96 ${AGENTSTATUS}          Status of login ( fail | on | off )
97 ${AGENTEXTEN}           Extension for logged in agent
98
99 The queue() application uses the following variables:
100 ${MONITOR_FILENAME}     File for monitoring (recording) calls in queue
101 ${QUEUE_PRIO}           Queue priority
102
103
104 The following variables can be set to change certian behaviour:
105 ${TOUCH_MONITOR}        The filename base to use with Touch Monitor (auto record)
106 ${EXITCONTEXT}          A context to consider in lieu of the curent context when
107                         dropping out of an attempted call into a 1 digit extension.
108
109 The monitor application sets the following variable:
110 ${MONITOR}              Set to "true" if the channel is/has been monitored.
111
112 There are two reference modes - reference by value and reference by name. 
113 To refer to a variable with its name (as an argument to a function that 
114 requires a variable), just write the name. To refer to the variable's value, 
115 enclose it inside ${}. For example, SetVar takes as the first argument 
116 (before the =) a variable name, so: 
117
118 ;exten => 1,2,SetVar,koko=lala
119 ;exten => 1,3,SetVar,${koko}=blabla
120
121 stores to the variable "koko" the value "lala" and to variable "lala" the 
122 value "blabla". 
123
124 In fact, everything contained ${here} is just replaced with the value of 
125 the variable "here". 
126
127 ___________________________
128 EXPRESSIONS: 
129 ---------------------------
130
131 Everything contained inside a bracket pair prefixed by a $ (like $[this]) is 
132 considered as an expression and it is evaluated. Evaluation works similar to 
133 (but is done on a later stage than) variable substitution: the expression 
134 (including the square brackets) is replaced by the result of the expression 
135 evaluation. The arguments and operands of the expression MUST BE separated 
136 by at least one space. 
137
138
139 For example, after the sequence: 
140
141 exten => 1,1,SetVar,"lala=$[1 + 2]";
142 exten => 1,2,SetVar,"koko=$[2 * ${lala}]";
143
144 the value of variable koko is "6".
145
146 And, further:
147
148 exten => 1,1,SetVar,"lala=$[1+2]";
149
150 will not work as you might have expected. Since all the chars in the single 
151 token "1+2" are not numbers, it will be evaluated as the string "1+2". Again,
152 please do not forget, that this is a very simple parsing engine, and it
153 uses a space (at least one), to separate "tokens".
154
155 and, further:
156
157 exten => 1,1,SetVar,"lala=$[  1 +    2   ]";
158
159 will parse as intended. Extra spaces are ignored.
160
161 ___________________________
162 SPACES INSIDE VARIABLE
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 exten => s,6,GotoIf($[ "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
173
174 The variable CALLERIDNAME could evaluate to "DELOREAN MOTORS" (with a space)
175 but the above will evaluate to:
176
177 "DELOREAN MOTORS" : "Privacy Manager"
178
179 and will evaluate to 0.
180
181 The above without double quotes would have evaluated to:
182
183 DELOREAN MOTORS : Privacy Manager
184
185 and will result in syntax errors, because token DELOREAN is immediately
186 followed by token MOTORS and the expression parser will not know how to 
187 evaluate this expression.
188
189 _____________________
190 OPERATORS
191 ---------------------
192 Operators are listed below in order of increasing precedence.  Operators
193 with equal precedence are grouped within { } symbols.
194
195      expr1 | expr2
196              Return the evaluation of expr1 if it is neither an empty string
197              nor zero; otherwise, returns the evaluation of expr2.
198
199      expr1 & expr2
200              Return the evaluation of expr1 if neither expression evaluates to
201              an empty string or zero; otherwise, returns zero.
202
203      expr1 {=, >, >=, <, <=, !=} expr2
204              Return the results of integer comparison if both arguments are
205              integers; otherwise, returns the results of string comparison
206              using the locale-specific collation sequence.  The result of each
207              comparison is 1 if the specified relation is true, or 0 if the
208              relation is false.
209
210      expr1 {+, -} expr2
211              Return the results of addition or subtraction of integer-valued
212              arguments.
213
214      expr1 {*, /, %} expr2
215              Return the results of multiplication, integer division, or
216              remainder of integer-valued arguments.
217
218      expr1 : expr2
219              The `:' operator matches expr1 against expr2, which must be a
220              regular expression.  The regular expression is anchored to the
221              beginning of  the string with an implicit `^'.
222
223              If the match succeeds and the pattern contains at least one regu-
224              lar expression subexpression `\(...\)', the string correspond-
225              ing to `\1' is returned; otherwise the matching operator
226              returns the number of characters matched.  If the match fails and
227              the pattern contains a regular expression subexpression the null
228              string is returned; otherwise 0.
229
230 Parentheses are used for grouping in the usual manner.
231
232 The parser must be parsed with bison (bison is REQUIRED - yacc cannot 
233 produce pure parsers, which are reentrant) 
234
235 ___________________________
236 CONDITIONALS
237 ---------------------------
238
239 There is one conditional operator - the conditional goto : 
240
241 ;exten => 1,2,gotoif,condition?label1:label2
242
243 If condition is true go to label1, else go to label2. Labels are interpreted
244 exactly as in the normal goto command.
245
246 "condition" is just a string. If the string is empty or "0", the condition
247 is considered to be false, if it's anything else, the condition is true. 
248 This is designed to be used together with the expression syntax described 
249 above, eg : 
250
251 exten => 1,2,gotoif,$[${CALLERID} = 123456]?2|1:3|1
252
253
254 Example of use : 
255
256 exten => s,2,SetVar,"vara=1"
257 exten => s,3,SetVar,"varb=$[${vara} + 2]"
258 exten => s,4,SetVar,"varc=$[${varb} * 2]"
259 exten => s,5,GotoIf,"$[${varc} = 6]?99|1:s|6";
260
261 ___________________________
262 PARSE ERRORS
263 ---------------------------
264
265 Syntax errors are now output with 3 lines.
266
267 If the extensions.conf file contains a line like:
268
269 exten => s,6,GotoIf($[ "${CALLERIDNUM}"  = "3071234567" & "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
270
271 You may see an error in /var/log/asterisk/messages like this:
272
273 May  3 15:58:53 WARNING[1234455344]: ast_yyerror(): syntax error: parse error; Input:
274  "3072312154"  : "3071234567" & & "Steves Extension" : "Privacy Manager"
275  ^^^^^^^^^^^^^^^^^^^^^^^^^^^
276                                   ^
277
278 The first line shows the string passed to the expression parser. This
279 string is the result of the variable replacements, etc. This way, you
280 can see the actual string that went into the parser.
281
282 The second line usually shows a string of '^' chars, that show what's
283 been legally parsed so far.
284
285 And the third line shows where the parser was (lookahead token lexing,
286 etc), when the parse hit the rocks. A single '^' here. The error is
287 going to be somewhere between the last '^' on the second line, and the
288 '^' on the third line. That's right, in the example above, there are two
289 '&' chars, separated by a space, and this is a definite no-no!
290
291
292 ___________________________
293 NULL STRINGS
294 ---------------------------
295
296 Testing to see if a string is null can be done in one of two different ways:
297
298 exten => _XX.,1,GotoIf($["${calledid}" != ""]?3) 
299
300 exten => _XX.,1,GotoIf($[foo${calledid} != foo]?3) 
301
302
303 The second example above is the way suggested by the WIKI. It will 
304 work as long as there are no spaces in the evaluated value.
305
306 The first way should work in all cases, and indeed, might now
307 be the safest way to handle this situation.
308
309 ___________________________
310 WARNING
311 ---------------------------
312
313 If you need to do complicated things with strings, asterisk expressions
314 is most likely NOT the best way to go about it. AGI scripts are an
315 excellent option to this need, and make available the full power of
316 whatever language you desire, be it Perl, C, C++, Cobol, RPG, Java,
317 Snobol, PL/I, Scheme, Common Lisp, Shell scripts, Tcl, Forth, Modula,
318 Pascal, APL, assembler, etc.
319