ADDRESS VOX Commands › Voice Commands › CALL Command

CALL Command

The CALL command initiates a telephone call by placing the voice channel in an off-hook state and dialing the tone string (telephone number).

This command has the following format:

ADDRESS VOX "CALL CHANNEL(channelhandle) TONESTRING(tonestring)
   [SYSTEM(sysname)]
   [NAME(CPAparameterset)]
   [RINGS(maxrings)]
   [RETRY(numretries)]
   [WAIT(secs)]
   [PREFIX(varname)]
   [CMDRESP(destination)]"

CHANNEL

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

Default: There is no default.

TONESTRING

Specifies the telephone number or other special digits to dial.

Valid characters are: 0 1 2 3 4 5 6 7 8 9 * # a b c d & - , T P M L   I X

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

NAME

(Optional) Specifies the name of the call progress analysis (CPA) parameter set to use for dialing.

CPA set names can be created and configured using the Configuration Manager.

Default: EngineDefault

RINGS

(Optional) Specifies the approximate number of rings to allow before timing out the request and returning a “noanswer” call completion state. The number of rings specified is not an exact count of the actual rings on the telephone, but an estimation of how long the call should wait to get the given rings count.

Default: 4

RETRY

(Optional) Specifies the maximum number of call retries (after the initial call attempt) to establish a connection.

Default: 0

WAIT

(Optional) Specifies the amount of time to wait, in 1/10-second units, before redialing if you specify the RETRY operand.

Default: 600 (One minute)

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.CALL

CMDRESP

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

Default: REXX

Return Information:

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

• If the command executes successfully, the RC variable contains a value of zero. The VOX.CALL variable contains the following:
  • CADNCBRK-Connection due to cadence break.
  • LCDDROP-Connection due to loop current.
  • PVD-Connection due to Positive Voice Detection.
  • PAMD-Connection due to Positive Answerplay Machine Detection.

  For more details about specific return information, see the ATDX_CONNTYPE() function definition in the Intel Dialogic documentation.

  The connection reason is useful when you need to adjust the call progress analysis (CPA) parameters of your voice card using the Configuration Manager to fine-tune your voice application. The Dialogic voice software determines the connection reason, but the algorithm is not always correct.

• If the command does not execute successfully, the RC variable contains one of the following values: 5112, 5117, 5155, 5199, 5204, 5301, 5302, 5303, 5304, 5305, 5306. (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.

Usage Notes:

• The return information that the CALL command provides (see PREFIX) contains the reason that the command was able to establish a connection.
• See Valid Dialing Characters for information on valid DTMF dialing characters.

Example:

Suppose that you have written a REXX program to call a remote party and play a voice message. If the reason that the CALL command establishes a connection is Positive Voice Detection, a person probably answered the telephone. If the reason for the connection is Positive Answering Machine Detection, an answering machine or voice-mail system probably answered the call. In both cases, the default values for the CPA parameters are acceptable; your REXX code can simply provide for playing the prerecorded voice message at the appropriate time.

On the other hand, suppose that the office of the remote party is equipped with a PBX system and that the connection reason is Loop Drop. The voice message might already be in progress by the time the remote party hears it. In such a scenario, the PBX has sent a loop-drop signal before the remote party answered the call, causing the CALL command to complete and the subsequent lines in your REXX code to execute. To fix the problem, you may need to adjust some CPA parameters.

The following REXX code illustrates how to use the CALL command to call a remote party and report a problem:

phonenumber = '2000'

/* A T-1 trunk has dropped.                      */
/* Notify the telcom group immediately using the */
/* notification server located in the Los Angeles office. */

/* Acquire exclusive access to a voice channel.  */

address vox 'getchannel channelnum(1) prefix(handle) system(laengine)'

/* Call the main number of the telcom group */
/* to make sure that we did not get their   */
/* voice mail.                              */

address vox 'call channel('handle') tonestring('phonenumber') system(laengine)'
if vox.call != PAMD then
do
   /* Because some answering machines are so clear*/
   /* that they cannot be detected easily,        */
   /* make sure that we are connected to a person */
   /* by asking them to press 1.                  */

   address vox 'playgetdigits channel('handle') file(greeting.vox press1.vox) prefix(response) system(laengine)'

   if response == 1 then
   do
      /* Inform the remote party of     */
      /* the problem and offer options  */
      /* for responding to the problem. */

      address vox 'play channel('handle') file(t1down.vox options.vox) prefix(response) system(laengine)'
      ...
      /* Correcting problem according to */
      /* remote party's response         */
      ...
   end

end

/* Release the voice channel */

address vox 'releasechannel channel('handle')'