Asterisk: The Future of Telephony, 2nd Edition

Name

Macro() — Calls a previously defined dialplan macro

Synopsis

Macro(macroname,arg1,arg2...)

Executes a macro defined in the context named macro- macroname, jumping to the s extension of that context and executing each step, then returning when the steps end.

The calling extension, context, and priority are stored in ${MACRO_EXTEN}, ${MACRO_CONTEXT}, and ${MACRO_PRIORITY}, respectively. Arguments arg1, arg2, etc. become ${ARG1}, ${ARG2}, etc. in the macro context.

Macro() exits abnormally if any step in the macro exited abnormally or indicated a hangup. If ${MACRO_OFFSET} is set at termination, this application will attempt to continue at priority MACRO_OFFSET+n+1 if such a step exists, and at n+1 otherwise. (In both cases, n stands for the current priority.)

If you call the Goto() application inside of the macro to specify a context outside of the currently executing macro, the macro will terminate and control will go to the destination of the Goto().

; define a macro to count down from the specified value
[macro-countdown]
exten => s,1,Set(COUNT=${ARG1})
exten => s,2,While($[ ${COUNT} > 0])
exten => s,3,SayNumber(${COUNT})
exten => s,4,Set(COUNT=$[ ${COUNT} - 1 ])
exten => s,5,EndWhile()

; call our macro with two different values
[example]
exten => 123,1,Macro(countdown,10)exten => 124,1,Macro(countdown,5)

Note

While a macro is being executed, it becomes the current context. This means that if a hangup occurs, for instance, the macro will be searched for an h extension, not the context from which the macro was called. So, make sure to define all appropriate extensions in your macro (you can use catch in AEL).

Warning

Because of the way Macro() is implemented (it executes the priorities contained within it via sub-engine), and a fixed per-thread memory stack allowance, macros are limited to seven levels of nesting (macro calling macro calling macro, etc.); It may be possible that stack-intensive applications in deeply nested macros could cause Asterisk to crash earlier than this limit.

See Also

MacroExit(), Goto(), Gosub(), Chapter 6