Asterisk cmd Gosub

Gosub

Jump to a particular priority, extension, or context, saving the return address.

Synopsis

Since: Asterisk 1.2

Asterisk 1.2, 1.4

  Gosub([[[[context|]extension|]priority)

Asterisk 1.6

  Gosub([[[[context|]extension|]priority(arg1,arg2,...))

Asterisk 10

  Gosub([[context,]exten,]priority[(arg1[,...][,argN])])

Description

Set the priority to the specified value, optionally setting the extension and optionally the context as well. Please note that the LEADING arguments to Gosub() are optional, not the trailing arguments. Anything in the following parentheses are user passed in parms (${ARG1}, ${ARG2},…). These are optional and depend on your coding of the Gosub function.

Variants

Gosub(context,extension,priority)
Gosub(extension,priority)
Gosub(priority)

Gosub(context,extension,priority(arg1,arg2))

Return Codes

Returns 0, or -1 if the given context, extension, or priority is invalid.
1.6 if return is called with a value it is stored in ${GOSUB_RETVAL}

Notes

Inserting a space after commas separating the parameters will result in unexpected results.
e.g.

Gosub(confexisting, 1, 1)

will look for an extension ” 1″, i.e. with a preceding space character.

Q: If you GoTo out of the Macro context, the Macro will terminate and control will return at the location refered to by the Goto.
I thought I might convert the Macro to a GoSub routine, but the documentation doesn’t mention what happens if you GoTo out. It does however mention that the return address gets pushed onto the stack, so I’m a little concerned about the state of the stack if I simply GoTo out. Should I call StackPop first?

A: Yes, that is the purpose of the StackPop function: to remove the last stack frame without returning to the Gosub location. Note that if you had any LOCAL() variables (or arguments), those will additionally all be cleared with the execution of the StackPop application (and the previous values, if any, will return).

Examples

exten => _NXX-XXXX,1,Gosub(setcid)
exten => _NXX-XXXX,2,Dial(Zap/g0/${EXTEN})
exten => _NXX-XXXX,3,Congestion
exten => _NXX-XXXX,4(setcid),Set(CALLERID(all)=My Company <2345678901>)
exten => _NXX-XXXX,5,Return

======

exten => 1234,n,Gosub(stdexten,s,1(1234,${GLOBAL(CONSOLE)}))
exten => 1234,n,NoOP(${GOSUB_RETVAL})

[stdexten]

Standard extension subroutine:
${ARG1} – Extension
${ARG2} – Device(s) to ring
${ARG3} – Optional context in Voicemail (if empty, then “default”)

Note that the current version will drop through to the next priority in the case of their pressing ‘#’. This gives more flexibility in what do to next: you can prompt for a new extension, or drop the call, or send them to a
general delivery mailbox, or…

The use of the LOCAL() function is purely for convenience. Any variable initially declared as LOCAL() will disappear when the innermost Gosub context in which it was declared returns. Note also that you can declare a LOCAL() variable on top of an existing variable, and its value will revert to its previous value (before being declared as LOCAL()) upon Return.

exten => s,1,NoOp(Start stdexten)
exten => s,n,Set(LOCAL(ext)=${ARG1})
exten => s,n,Set(LOCAL(dev)=${ARG2})
exten => s,n,Set(LOCAL(cntx)=${ARG3})

exten => s,n,Set(LOCAL(mbx)=”${ext}”$[“${cntx}” ? “@${cntx}” :: “”])
exten => s,n,Dial(${dev},20) ; Ring the interface, 20 seconds maximum
exten => s,n,Goto(s-${DIALSTATUS},1) ; Jump based on status (NOANSWER,BUSY,CHANUNAVAIL,CONGESTION,ANSWER)
. . .
exten => s,n,Return

===========

This works with Asterisk 1.6 – Use for call screening

exten => _91NXXNXXXXXX,1,Dial(SIP/trunk/${EXTEN:1},,U(screen))
exten => _91NXXNXXXXXX,2,CONGESTION

[screen]
exten => s,1(screen),set(GOSUB_RESULT=CONGESTION)
exten => s,2,BackGround(wish-to-continue&press-1)
exten => s,3,waitexten(5)
exten => s,4,Return
exten => 1,1,set(GOSUB_RESULT=)
exten => 1,2,Return
exten => h,1,Return
exten => i,1,Return

See also

• GosubIf: Conditional Gosub (new in v1.2)
• Return: Return from a subroutine (new in v1.2)
• Goto: Jump to a context/extension/priority
• GotoIf: Conditional jump to a context/extension/priority

Asterisk | Applications | Functions | Variables | Expressions | Asterisk FAQ