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