Data gathering instructions

The data gathering instructions get information from a caller or from a stored database. This section describes the data gathering instructions and provides examples of those type of instructions. A sample script at this end of this section illustrates how these instructions might be used in an application.

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

  The getinput instruction receives information entered by a calling party using touch tones or speech input.

  The instruction getinput replaces getdig. Continued use of getdig is discouraged.

  The argument ctype.dst is a character buffer where input data is to be copied to. The argument type.number indicates the maximum number of input characters to copy to ctype.dst. The argument int.recognizer is optional, it 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. The argument int.resource is optional, it indicates the address of an integer where the resource used to perform recognition is stored.

  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 any pending or unfinished announcements to be played from this channel.

• tttime (type.firstdig,type.interdig)

  The tttime instruction allows a script to set the time-out values for receiving touch tones. The firstdig argument specifies the maximum number of seconds the script should wait to receive the first touch-tone digit after executing a getinput instruction. The interdig argument specifies the maximum number of seconds to wait between two consecutive touch-tone digits.

  There is no limit to the timeout values. The default values are 10 and 10.

  The tttime instruction is related to the getinput instruction. If the firstdig time is exceeded, r.0 is set to 0 and the getinput instruction terminates. If the interdig time is exceeded, r.0 is set to the number of digits that are received, transferred to the script buffer, and the getinput instruction terminates.

  In the following tttime example, the script waits approximately ten seconds for the first touch tone and two seconds between touch tones.

  tttime(10,2)

• setttfl(type.flg)

  The setttfl instruction allows the script to change the way TSM handles the touch-tone buffer. Normally, TSM gets rid of any touch tones it has received for the script when the speech buffer is flushed and speech is played. The setttfl instruction disables the TSM action of clearing the touch-tone buffer whenever speech is played.

  If the type.flg argument is 1, touch-tone flushing is turned on. If the setttfl instruction is not used, the default condition sets touch-tone flushing on.

  If the type.flg argument is 0, touch-tone flushing is turned off and playing speech does not cause the touch-tone buffer to be cleared. Another effect of turning off touch-tone flushing is that any phrases queued in the phrase buffer are cleared if talkoff is enabled on the channel instead of being played whenever an instruction that normally causes the phrases to be played is executed. This is done because phrases that are in the buffer are assumed to be part of the prompt that the talkoff touch tones affect. With talkoff enabled, phrases that are already queued are not heard. Instead, the script advances to the appropriate point based on the touch-tone input received.

• ttclear()

  The ttclear instruction clears the touch-tone buffer. This instruction is useful for applications in which you want to throw away all typed-ahead input. The ttclear instruction removes any touch tones in the touch-tone buffer when the instruction is executed. The number of touch tones cleared is stored in r.0.

• ttdelim(erase-char, erase-all, delim1, delim2)

  The ttdelim instruction sets four control functions and the touch-tone keys used by the caller to perform those functions. The functions for the erase-char and erase-all arguments are defined by the system. The functions for the delim1 and delim2 arguments are defined by the application developer. The application developer defines the touch-tone keys used in performing all four functions.

  The system-defined functions erase-char and erase-all do not terminate the collection of touch tones initiated by the getinput instruction and those characters are removed from the buffer. The developer-defined functions delim1 and delim2 terminate the collection of touch tones and those characters remain in the buffer.

  The ttdelim instruction works with the getinput and tttime instructions. For example, after requesting five digits with a getinput instruction, normally r.0 is set to 5 and the actual digits received are stored at the destination. Any time the ttdelim instruction is used, the script also has to check the received digits to determine if delim1 or delim2 is used.

  The touch-tone buffer is scanned for the delineators that are in effect when a getinput instruction is executed.

  The values for the ttdelim arguments are shown in the following table. 

The following functions and characters might be specified for the instruction:

ttdelim('#1','#*','*1','*2')

Script routines written by the application developer must check for *1 and *2 in the buffer. If the ttdelim instruction uses only one argument, then a default value must be entered for the other three arguments. An example of a ttdelim instruction using only the erase-all function is ttdelim(-1,'#',-1,-1). Whenever erase-char and erase-all are used in a script, a delim argument is probably used to allow a caller to end touch-tone entry. This argument indicates to the getinput instruction that although it may have received the maximum number of digits, a caller may make a mistake and may want to erase some digits and re-enter them.

To allow for the extra digits requested by a delim1 or delim2 argument, the getinput instruction should specify more digits than it needs. For instance, if a 5-digit entry is required, but it is anticipated that a caller might enter all incorrectly and need to erase them, getinput would require a minimum of 7 digits to accommodate the two-digit delineator for erase-all.

Based on the previous arguments for the sample ttdelim instruction shown earlier, the getinput instruction would have the results given by the examples in the following table. 

The time-outs for the system-defined functions, erase-char and erase-all, are the same. The tttime instruction only uses the firstsec argument once, but it repeatedly uses the interdig argument to wait the maximum amount of time specified for receiving the next digit. The application developer needs to write code to implement the functions. For example, delim2 would need a talk instruction to play a help message.

• dbase(dip,type.mcont_field, type.dst,mbyte,type.src,nbyte)

  The dbase instruction passes information between the script and a host, a local database, or any other DIP.

  The dip argument specifies the DIP that is to receive the message. A DIP number or name may be used for dip. If dip is a name, it must be in the form name. The type.mcont_field argument is a value sent to the DIP that the DIP uses to identify the message type and determine its next action. The ctype.dst argument specifies the destination script address for the data. The mbyte argument specifies its length. The type.src argument specifies the script address where data sent to the DIP is stored. The nbyte argument specifies its length. If type.src is a register, nbyte is ignored and four bytes are sent.

  If the dbase call is successful and returns data to the script, r.0 is set to the mcont value of the DIP message. If the DIP is not running, r.0 is set to -1. After a response timeout (default value is 45 seconds), r.0 is set to -2. To change the default value for the timeout, use the nwitime instruction. If nbyte is zero (0), no information is transferred to the DIP. If nbyte is negative, no message is sent to the DIP, but the dbase call may wait (if mbyte is not negative) for a message from the DIP. If mbyte is negative, no return data is expected from the DIP. r.0 is set to zero (0) and script execution continues immediately after dbase is executed.

  In the following example, the dbase instruction tells the script to send ch.INFO_TO_HOST (nine bytes) to the host. The Bankdip DIP processes the information to the host based on the action defined by ACCOUNT_BAL and stores the result in ch.INFO_FROM_HOST (up to 55 bytes).

  dbase("Bankdip",ACCOUNT_BAL,ch.INFO_FROM_HOST,
55,ch.INFO_TO_HOST,9)

• dipterm(dip [,flag ])

  The dipterm instruction specifies to TSM that a DIP receives a termination message when the script terminates. A DIP number or name may be used for dip. The dipterm instruction may be called repeatedly with different DIP numbers or names. The termination message goes to all DIPs specified.

  The optional flag may be used to turn off a dipterm setting. Valid values for flag are 1 and 0. If flag is 1 (the default), dipterm is set for the dip. If flag is 0, dipterm is reset for dip.

  The following dipterm instruction example tells TSM that DIP0 will receive a termination message when the script completes:

  dipterm(0)

  For additional information about the dipterm instruction, see dipterm.

� 2003 Avaya Inc. All Rights Reserved.