<catch>

Description

Catches events thrown by the VoiceXML application or the IP Media Server. The <catch> element associates a catch with a document, dialog (i.e., form or menu), or form item. It contains executable content.

The <catch> element catches an event with a name:

that matches exactly with the event attribute, OR
for which the event attribute is a prefix match. Being a prefix match means that the event attribute is a token prefix of the thrown event, where the dot is the token separator. For example, <catch event="telephone.disconnect"> is a prefix match for the event telephone.disconnect.transfer.

Please refer to the Event Handling reference for lists of events and errors.

Syntax


<catch
    event="event1 event2 ..."
    count="integer"
    cond="ECMAScript_Expression">
  child elements
</catch>

Attributes

Attribute	Description
event	The event or events to catch. A space-separated list of events may be specified to catch multiple events. The empty string or single dot matches everything. Optional. (Defaults to all events.)
count	The count attribute allows you to handle different occurrences of the same event differently. Each form, menu, and form item maintains a counter for each event that occurs while it is being visited; these counters are reset each time the menu or form item's form is re-entered. When there are more than one `<catch>` element catching the same event, the element in the closest scope with the highest count that is less than or equal to the current counter will be selected. Optional. (Defaults to 1.)
cond	An ECMAScript expression to be evaluated and used as a boolean condition. This `<catch>` element will only catch the event if the expression evaluates to `true`. Optional. (Defaults to true.)

Anonymous Variables

Two anonymous variables are available within the scope of any <catch> element:

_event - This contains the name of the event that was thrown.
_message - This contains the message string from the corresponding <throw>, <choice>, <link>, or <return> element, or a platform defined value for events thrown by the platform. If no message is specified, the value of this variable is ECMAScript undefined.

Some additional anonymous variables are available within the scope of the <catch> element for particular events:

Event	Anonymous Variable	Description
connection.disconnect.hangup/ telephone.disconnect.hangup	_disconnect_reason	(extension) If the disconnection was caused by a `<disconnect>`, this will contain the specified `reasonexpr`, or will be `undefined` if no reason was specified. If the disconnection was caused by an inbound call hangup, this will contain the disconnect reason (ISDN disconnect cause code) passed back from the SIP stack, or `undefined` if the reason is not available.
com.voicegenie.call.*	_channel	(extension) Contains the channel ID (i.e. the session/call ID) of the call that generated the event.
com.voicegenie.call.*	_disconnect_reason	(extension) Contains the disconnect reason (ISDN disconnect cause code) passed back from the SIP stack after the outbound call (initiated with `<call>`) disconnects.
com.voicegenie.call.disconnect	_duration	(extension) Contains the duration of the call in seconds.

Parents

Children

<assign>, <audio>, <clear>, <data>, <disconnect>, <enumerate>, <exit>, <foreach>, <goto>, <if>, <log>, <prompt>, <reprompt>, <return>, <script>, <submit>, <throw>, <value>, <var>, #PCDATA

extensions

Added _disconnect_reason anonymous variable.

Limitations/Restrictions

With the com.voicegenie.STRICTCONFORMANCE property set to FALSE), if a <catch> element is in a different page (ex. application root) from the page that the event was thrown in, relative URIs in the <catch> element are resolved relative to the page that catches the event.
The telephone.disconnect.hangup event can only be caught once during the execution of an application; see details.
See details on catching the telephone.disconnect.hangup event when the caller hangs up while a VoiceXML page is in the process of being fetched.

Example


<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <field name="field1" type="digits">
      <prompt> Please say some digits. </prompt>
      <catch event="noinput">
        I didn't hear you.
        <reprompt/>
      </catch>
      <filled>
        Thanks. You said <value expr="field1"/>. 
      </filled>
    </field>
  </form>
</vxml>