getinput

Avaya Logo

getinput

The getinput instruction receives touch-tone, dial-pulse, or spoken input from a caller.

Note:
The getinput instruction replaces the getdig instruction. Continued use of the getdig instruction is discouraged.

Synopsis

getinput(ctype.dst, type.number [, int.recognizer [, int.resource ]])

Description

The getinput instruction manages the process of starting speech recognizers, flushing speech, and collecting input. The behavior of getinput is summarized as follows:

Start all recognizers queued for recognition while prompting. See recog_start.
Flush (start output of) all queued speech or text. See say, talk, etc.
When speech or text output is complete, start all recognizers queued for start after prompting.
If at any point a recognizer successfully reports input, all remaining play and recognition activities are terminated and getinput returns with the number of characters placed on the input stream.

The argument ctype.dst is a character buffer where input data is to be copied. The argument type.number indicates the maximum number of input characters to copy to ctype.dst. The optional argument int.recognizer indicates the address of the integer value where the recognition type used to collect input is stored. Possible values include 0 for TT input or some positive integer indicating a recognizer such as IRD_WHOLE_WORD (see recog_start). The optional argument int.resource indicates the address of an integer where the resource used to perform recognition is stored.

When getinput is used with multiple simultaneous recognizers, all other recognizers are terminated upon receipt of input from any source and only the results from the first recognizer are reported back to the application. The getinput instruction assumes that DTMF (touch-tone) recognition is always on. DTMF recognition can be inhibited with the use of ttmask and ttintr.

The getinput instruction has a 10-second default initial digit wait time for input. If the caller does not enter a digit within the allotted time period, getinput returns the number of digits received before the timeout occurred. Use the tttime() instruction to specify desired wait times.

The getinput instruction is a wait-causing instruction. Therefore, it automatically forces out any pending or unfinished announcements from this channel.

Return values

The return value from getinput is placed in r.0 as follows:

Return value	Description
r.0 > 0	getinput successfully received r.0 digits and copied the input to ctype.dest
0	An initial timeout occurred for all recognizers.
-1	All resources are busy. This may include recognition resources or play resources if such operations were previously queued with the recog_start or talk instructions.
-2	No resources exists to perform the input operation. This may include recognition resources or play resources if such operations were previously queued with the recog_start or talk instructions.
-3	A system error has occurred.
-4	The system failed to obtain access to a memory location specified using an argument.

Example

In the following example, the script waits for the caller to enter up to 10 digits, then stores them in ch.ANS. The type of recognition used is stored in int.recognizer.

getinput(ch.ANS, 10, int.recognizer)