Using Notification Services › Example VOX Environment Applications › Inbound Application with Input from Caller › VOX Commands Used

VOX Commands Used

When coding such a VOX environment application, use the following ADDRESS VOX commands:

ANSWERPLAY

Begins the application in an ANSWER state. When a call comes in, the application can play a voice file or words from a word library. The advantage of using ANSWERPLAY instead of ANSWER, then PLAY, is that the VOX environment automatically loads the voice message segment to play prior to answering the phone call, thereby improving performance during the initial connection.

GETCHANNEL

Obtains an available channel using a hardcoded channel number or retrieving a channel from a group (see the note after the table).

GETDIGITS

Obtains a user's user ID (in DTMF tones), assuming the voice message segment played with ANSWERPLAY has prompted the user appropriately.

PLAYGETDIGITS

Plays voice messages with a prompt to retrieve the user's response to the prompt. PLAYGETDIGITS is recommended instead of PLAY then GETDIGITS because it facilitates an improved reading and maintenance of your application.

RELEASECHANNEL

Releases the channel used by the phone call, placing the channel in an available state for the next caller.

VERIFYUSER

Verifies the caller as a valid user of the application.

Note: When coding an inbound application, you can eliminate the GETCHANNEL command by using the ANSWERPLAY command with the GROUP keyword (waiting for a phone call from a group of channels); when a call comes in, the ANSWERPLAY command returns the appropriate channel handle to be used on subsequent ADDRESS VOX commands.

REXX Code Listing

The following sample REXX code illustrates a sample inbound status application:

/* REXX */ 
ChannelInUse = 'N'        /* Channel not obtained yet */ 
Terminate = 'N' 
/* Setup Error Handler in event program encounters Ctrl-Break */ 
SIGNAL ON HALT NAME DOEXIT 

0   ...
Call GetFreeChannel 
  
Do While (Terminate <> 'Y') 
  Call WaitForACall 
  If (result <> 0) Then 
     Terminate = 'Y' 
  Else 
  Do 
    Call UserApplication
    If (result <> 0) Then 
       Terminate = 'Y' 
  End 
End 
Call ReleaseTheChannel

exit 
          
GetFreeChannel:
/*----------------------------------------------*/ 
/* Obtain an available voice channel            */
/* Channel can be obtained by channel number    */
/* or by Group, in this example, a Group of ALL */
/* is used......                                */
/*----------------------------------------------*/ 
Address VOX "GETCHANNEL Group(All) Prefix(Handle)" 
If (rc <> 0) Then Do 
   say 'Unable to obtain an available channel. RC='rc 
   exit 16
End 
ChannelInUse = 'Y'   /* remember we now have a channel */ 
return 

WaitForACall:
/*-----------------------------------------------------------*/ 
/* Waiting for a call on a specific channel before returning */ 
/* For improved performance, use VOX ANSWERPLAY              */
/* since VOX message to be played is loaded into             */
/* memory prior to making answering phone call.              */
/*-----------------------------------------------------------*/ 
GreetingToPlay = 'greeting.vox getuserid.vox' 
         
Address VOX "ANSWERPLAY Channel("Handle") ", 
          "File("GreetingToPlay") FILETYPE(NONINDEX)" 
If (rc <> 0) Then Do 
   say 'Problem answering call  RC='rc 
   return 16
End 

0/* Before returning to main line code, you may want to */
/* verify connecting caller, you can use VOX GETDIGITS,*/
/* PLAYGETDIGITS and VERIFYUSER commands...            */
   
IdLen = 6               /* Assume Userid is length 6   */
PinLen = 6             /* Assume Pin # is length 6     */ 
Address VOX "GETDIGITS Channel("Handle") ", 
                               "Count("IdLen") Prefix(CallerId)" 

If (rc <> 0) Then Do 
   say 'Problem obtaining caller userid RC='rc 
   return 16
End 

/* Get caller's pin number. */ 
       
Address VOX "PLAYGETDIGITS Channel("Handle") ",
              "FILE(GetPin.Vox) FILETYPE(NONINDEX)", 
              "Count("PinLen") Prefix(CallerPin)"
If (rc <> 0) Then Do 
   say 'Problem obtaining caller pin number RC='rc 
   return 16
End 

/* Verify the connected phone call */ 

Address VOX "VERIFYUSER Userid("CallerId") Pin("CallerPin")" 
If (rc <> 0) Then Do 
   say 'Unable to Verify Caller RC='rc 
   return 16
End 

/* Caller is OK, now we can return to main line */ 
return 0 

UserApplication: 
/*--------------------------------------------*/ 
/* User specific application can go here      */
/*--------------------------------------------*/ 
  /* Can use VOX PLAY command to play  */ 
  /* stock quotes, system status etc., */ 
              ...
              ... 
/* Make sure phone is back on hook before returning to mainline */ 
Address VOX "SETHOOK Channel("Handle") HOOKSTATE(ONHOOK)" 
If (rc <> 0) Then Do 
   say 'Unable to put phone back onhook  RC = 'rc 
   return 16
End 

return 0 

ReleaseTheChannel: 
/*-----------------------------------------------*/ 
/* Release the channel obtained, this is done    */
/* by calling VOX RELEASECHANNEL command         */
/*-----------------------------------------------*/ 
If (ChannelInUse = 'Y') Then Do 
   Address VOX "RELEASECHANNEL Channel("Handle") 
   If (rc <> 0) Then Do 
      say 'Unable to release channel RC='rc 
   End 
   Else 
          ChannelInUse = 'N' 
End 
return 

DoExit: 
/*-----------------------------------------------------*/ 
/* Perform any necessary cleanup such as releasing the */
/* channel by calling VOX RELEASECHANNEL command       */
/*-----------------------------------------------------*/ 
Call ReleaseTheChannel 
/*  perform other application specific cleanup */ 
     ....
     ...
/* terminate application */ 
exit 
return

How it Works

Typically, an inbound notification application remains in an ANSWER state until a call is received. Once the VOX environment receives an inbound phone call, the application can provide status updates, acknowledge the receipt of a message, or provide various MIS services.