EVAL_SUB()¶

Synopsis¶

Executes a Gosub and provides its return value as a string

Description¶

The EVAL_SUB function executes up a dialplan location by context,extension,priority, with optional arguments and returns the contents of the Return statement. The arguments to 'EVAL_SUB' are exactly like they are with 'Gosub'.

This function is complementary to 'EVAL_EXTEN'. However, it is more powerful, since it allows executing arbitrary dialplan and capturing some outcome as a dialplan function's return value, allowing it to be used in a variety of scenarios that do not allow executing dialplan directly but allow variables and functions to be used, and where using 'EVAL_EXTEN' would be difficult or impossible.

Consequently, this function also allows you to implement your own arbitrary functions in dialplan, which can then be wrapped using the Asterisk function interface using 'EVAL_SUB'.

While this function is primarily intended to be used for executing Gosub routines that are quick and do not interact with the channel, it is safe to execute arbitrary, even blocking, dialplan in the called subroutine. That said, this kind of usage is not recommended.

This function will always return, even if the channel is hung up.

Example: Record whether a PSTN call is local

[islocal]
exten => _X!,1,ExecIf($[${LEN(${EXTEN})}<10]?Return(1))
same => n,Set(LOCAL(npanxx)=${EXTEN:-10:6})
same => n,ReturnIf(${EXISTS(${DB(localcall/${npanxx})})}?${DB(localcall/${npanxx})})
same => n,Set(LOCAL(islocal)=${SHELL(curl "https://example.com/islocal?npanxx=${EXTEN:-10:6}")})
same => n,Set(LOCAL(islocal)=${FILTER(A-Z,${islocal})})
same => n,Set(DB(localcall/${npanxx})=${islocal})
same => n,Return(${islocal})

[outgoing]
exten => _1NXXNXXXXXX,1,Set(CDR(toll)=${IF($["${EVAL_SUB(islocal,${EXTEN},1)}"="Y"]?0:1)})
same => n,Dial(DAHDI/1/${EXTEN})
same => n,Hangup()

This example illustrates an example of logic that would be difficult to capture in a way that a single call to 'EVAL_EXTEN' would return the same result. For one, conditionals are involved, and due to the way Asterisk parses dialplan, all functions in an application call are evaluated all the time, which may be undesirable if they cause side effects (e.g. making a cURL request) that should only happen in certain circumstances.

The above example, of course, does not require the use of this function, as it could have been invoked using the Gosub application directly. However, if constrained to just using variables or functions, 'EVAL_SUB' would be required.

Syntax¶

EVAL_SUB(context,extensions,priority)

Arguments¶

context
extensions
priority

Generated Version¶

This documentation was generated from Asterisk branch 20 using version GIT