System information

Macros

are a very useful construct designed to avoid repetition in the dialplan. They

also help in making changes to the dialplan. To illustrate this point, let’s look at our

sample dialplan again. If you remember the changes we made for voicemail, we ended

up with the following for John’s extension:

exten => 101,1,Dial(${JOHN},10)

same => n,GotoIf($["${DIALSTATUS}" = "BUSY"]?busy:unavail)

same => n(unavail),VoiceMail(101@default,u)

same => n,Hangup()

same => n(busy),VoiceMail(101@default,b)

same => n,Hangup()

Now imagine you have a hundred users on your Asterisk system—setting up the ex-

tensions would involve a lot of copying and pasting. Then imagine that you need to

make a change to the way your extensions work. That would involve a lot of editing,

and you’d be almost certain to have errors.

Instead, you can define a macro that contains a list of steps to take, and then have all

of the phone extensions refer to that macro. All you need to change is the macro, and

everything in the dialplan that references that macro will change as well.

If you’re familiar with computer programming, you’ll recognize that

macros are similar to subroutines in many modern programming

languages. If you’re not familiar with computer programming, don’t

worry—we’ll walk you through creating a macro.

The best way to appreciate macros is to see one in action, so let’s move right along.

Defining Macros

Let’s take the dialplan logic we used to set up voicemail for John and turn it into a

macro. Then we’ll use the macro to give John and Jane (and the rest of their coworkers)

the same functionality.

§ Although Macro() seems like a general-purpose dialplan subroutine, it has a stack overflow problem that

means you should not try to nest Macro() calls more than five levels deep. If you plan to use a lot of macros

within macros (and call complex functions within them), you may run into stability problems. You will know

you have a problem with just one test call, so if your dialplan tests out, you’re good to go. We also recommend

that you take a look at the GoSub() and Return() applications (see “GoSub()” on page 207), as a lot of macro

functionality can be implemented without actually using Macro(). Also, please note that we are not suggesting

that you don’t use Macro(). It is fantastic and works very well; it just doesn’t nest efficiently.

204 | Chapter 10: Deeper into the Dialplan