ADDRESS VOX Commands › Voice Commands › PLAYGETDIGITS Command

PLAYGETDIGITS Command

The PLAYGETDIGITS command performs the following operations:

• Plays voice data (prerecorded speech) through a specified voice channel. The voice data can exist in one of these formats:
  • A nonindexed file

    To play nonindexed files, specify the file on the FILE operand. If you specify multiple file names, CA Automation Point plays each file in the order listed. CA Automation Point does not insert pauses between multiple files.

  • A voice word library

    To play words from a voice word library, specify the name of the library on the FILE operand and the text of the word to play on the VAR operand.

• Retrieves tone digits from a voice channel's digit buffer. The digits can be menu selections or access codes that the remote party enters from the telephone keypad in response to a prompt from the voice file.

This command has the following format:

Use the following format to play a message from a non-indexed voice file:

ADDRESS VOX "PLAYGETDIGITS CHANNEL(channelhandle)
  FILE(filename_1 [...filename_n])
  FILETYPE(NONINDEX)
  [SYSTEM(sysname)]
  [INTERRUPT(YES|NO)]
  [COUNT(numtones)]
  [IDDELAY(maxdelay)]
  [TERMKEY(keytone)]
  [PREFIX(varname)]
  [CMDRESP(destination)]
  [SINGLESTRING(YES|NO)"

Use the following format to play a message from a voice word library file:

ADDRESS VOX "PLAYGETDIGITS CHANNEL(channelhandle)
  STRING(tonestring) 
  FILE(filename)
  FILETYPE(WORDLIB)
  VAR(varname)
  [SYSTEM(sysname)]
  [INTERRUPT(YES|NO)]
  [COUNT(numtones)]
  [IDDELAY(maxdelay)]
  [TERMKEY(keytone)]
  [PREFIX(varname)]
  [CMDRESP(destination)]
  [SINGLESTRING(YES|NO)"

CHANNEL

Specifies the channel handle (channelhandle)-identifying some physical channel-that the GETCHANNEL command returns.

FILE

Specifies the name of a voice file or voice word library.

FILETYPE

Specifies the type of voice file to play. Valid values are:

NONINDEX - A nonindexed voice file

WORDLIB - A voice word library

Note: When specifying FILETYPE (WORDLIB), do not include a file extension on the FILE operand.

Default: NONINDEX

VAR

This operand is required only when specifying a voice word library on the FILETYPE operand.

For a voice word library, code either a REXX regular variable or stem variable. When coding regular variables with the VAR keyword, only that variable is searched.

With a stem variable, all numeric indexes for this stem will be searched. When coding a stem variable, varname. should follow this format:

varname.0

Specifies the number of words in your message.

varname.1 through varname.n

Each variable contains one word from the voice word library.

SYSTEM

(Optional) Specifies the name of the system that is running the notification server to which you want to direct the command. The sysname value can contain up to eight alphanumeric characters.

Default: The local system name

INTERRUPT

(Optional) Specifies whether CA Automation Point interrupts a currently playing voice message if it receives a tone digit (that is, if the remote party presses a key on the telephone keypad). Valid values are:

YES

Allows the interruption

NO

Prevents the interruption

Default: YES

COUNT

(Optional) Specifies the maximum number of tones to retrieve.

Default: 1

IDDELAY

(Optional) Specifies the maximum time delay allowed between each digit's retrieval (in 1/10-second units).

Default: 30

TERMKEY

(Optional) A termination tone digit that the remote party enters on the telephone keypad.

If CA Automation Point detects a tone that you specify, it terminates the PLAYGETDIGITS operation. You can specify one or more termination tones.

Valid values are: 0 1 2 3 4 5 6 7 8 9 * # a b c d

Note: The pound key (#) is a common tone-string terminator.

Default: #

PREFIX

(Optional) Specifies the name of the REXX stem variable (other than the default name) that contains the returned digit string.

For information about changing the default variable name, see ADDRESS VOX Return Information in this chapter.

Default: VOX.PLAYGETDIGITS

CMDRESP

(Optional) Directs return information to a specific destination. For a list of valid destination values, see ADDRESS VOX Return Information in this chapter.

Default: REXX

SINGLESTRING

(Optional) Specifies whether the PLAYGETDIGITS command's return string appears as a single string of digits in one variable (rather than as individual digits in separate variables).

Default: YES

Return Information:

After the PLAYGETDIGITS command executes, it sets the special REXX return code variable RC.

• If the command executes successfully, the RC variable contains a value of zero. Additionally, if you accept the default SINGLESTRING(YES) operand, the entire string of tone digits appears in the VOX.PLAYGETDIGITS (or VOX.PLAYGETDIGITS.1) variable.
• If the command does not execute successfully, the RC variable contains one of the following values: 5106, 5107, 5109, 5112, 5116, 5117, 5155, 5199, 5204, 5300. (For more information, see the Message Reference Guide.) Additionally, the VOX.ERROR variable contains the complete VOX error message, which includes the four-digit return code and complete error message text.

If you specify the optional SINGLESTRING(NO) operand, the PLAYGETDIGITS command returns this information in each of the VOX.PLAYGETDIGITS variables (VOX.PLAYGETDIGITS.1 through VOX.PLAYGETDIGITS.n):

Example:

The following REXX code illustrates how to use the PLAYGETDIGITS command to play a voice message from a nonindexed (flat) voice file, and then collect the tone digits that the remote party enters from the telephone keypad in response:

/* Get exclusive access to a specific voice channel. */

address vox 'getchannel channelnum(1) prefix(handle)'
...

/* Play the Reset menu message and give the user five seconds */
/* to respond. */

address vox 'playgetdigits channel('handle') file(resetmnu.vox) iddelay(5) prefix(response)'
...

/* Release the voice channel. */
address vox 'releasechannel channel('handle')'