GETDIGITS Command

ADDRESS VOX Commands › Voice Commands › GETDIGITS Command

GETDIGITS Command

The GETDIGITS command retrieves tone digits from a voice channel's digit buffer. The digits can represent one of the following data types:

A menu selection or access code, such as a personal identification number (PIN), that a remote party enters from the telephone keypad in response to a voice prompt.
ANI (caller identification) digits that the telephone company sends in response to a WINK command.

This command has the following format:

ADDRESS VOX “GETDIGITS CHANNEL(channelhandle)
  [SYSTEM(sysname)]
  [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.

SYSTEM

(Optional) Specifies the name of the system 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

COUNT

(Optional) Specifies the maximum number of tones to retrieve. Valid values are 0 (zero) through 31.

Note: If you specify COUNT(0), the GETDIGITS command returns only the number of digits in the digit buffer (but no digits).

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 GETDIGITS 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

Notes:

The pound key (#) is a common tone-string terminator.
A special keypad is necessary to send a, b, c, or d from a phone.

Default: The pound key (#)

PREFIX

(Optional) Specifies the name of the REXX stem variable (other than the default name) that contains the return information for the command.

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

Default: VOX.GETDIGITS

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 GETDIGITS command's return string appears as a single string of digits in one variable (rather than as individual digits in separate variables).

Default: SINGLESTRING(YES)

Return Information:

After the GETDIGITS 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.GETDIGITS (or VOX.GETDIGITS.1) variable.
If the command does not execute successfully, the RC variable contains one of the following values: 5106, 5107, 5112, 5117, 5155, 5199, 5204, 5300. (See the Message Reference Guide for further information.) 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 GETDIGITS command returns this information in each of the VOX.GETDIGITS variables (VOX.GETDIGITS.1 through VOX.GETDIGITS.n):

Field

Description of Returned Information

A single digit entered by the remote party or sent by the telephone company.

The tone type of the digit that was retrieved:

DTMF-Dual Tone Multi-Frequency
AP-Audio Pulse
LP-Loop Pulse

MF-Multi-Frequency

The value stored in the VOX.GETDIGITS.0 variable represents the number of tone digits that were retrieved.

Example:

The following REXX code illustrates how to use the GETDIGITS command to collect a remote user's personal identification number (PIN) entered from the telephone keypad:

/* Get exclusive access to a specific voice channel. */
/* If the channel is in use, wait up to two minutes  */
/* for it to become available.                       */

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

/* Prompt the remote party to enter a PIN. */

address vox 'play channel('handle') file(entrpin.vox)'

/* Collect the PIN digits entered. */

address vox 'getdigits channel('handle') count(8) singlestring(yes) prefix(response)'
...

/* Release the voice channel. */

address vox 'releasechannel channel('handle')