ADDRESS VOX Commands › Voice Commands › PLAY Command

PLAY Command

The PLAY command 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 a nonindexed voice file, specify the file on the FILE operand. If you specify multiple file names, CA Automation Point plays each file in the order listed with no pauses or clicks inserted between the 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 in a REXX variable (or REXX stem variables), and then code the REXX variable's name on the VAR operand.

This command has the following formats:

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

ADDRESS VOX "PLAY CHANNEL(channelhandle)
  FILE(filename_1 [...filename_n])
  FILETYPE(NONINDEX)
  [SYSTEM(sysname)]
  [INTERRUPT(YES|NO)]"

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

ADDRESS VOX "PLAY CHANNEL(channelhandle)
  FILE(filename)
  FILETYPE(WORDLIB)
  VAR(varname)
  [SYSTEM(sysname)]
  [INTERRUPT(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-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

Return Information:

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

• If the command executes successfully, the RC variable contains a value of zero.
• If the command does not execute successfully, the RC variable contains one of the following values: 5106, 5109, 5112, 5116, 5117, 5155, 5199, 5204, 5252, 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.

Usage Notes:

You can use the PLAY command to play voice messages through a voice channel connected to an amplified speaker attached directly to the voice card's analog expansion bus (with pins GND and AUD1-AUD4).

Examples:

• The following REXX code illustrates how to use the PLAY command to play three individual voice messages. Each message is stored in a nonindexed (flat) voice file.

  /* Get exclusive access to a specific voice channel. */
  
  address vox 'getchannel channelnum(1) prefix(handle)'
  ...
  
  /* Play messages from nonindexed voice files. */
  
  address vox 'play channel('handle') file(greeting.vox mainmnu1.vox mainmnu2.vox)'
  ...
  
  /* Release the voice channel. */
  
  address vox 'releasechannel channel('handle')'
  

• The following REXX code illustrates how to use the PLAY command to play voice messages stored in an indexed voice file:

  /* Get exclusive access to a specific voice channel. */
  
  address vox 'getchannel channelnum(1) prefix(handle)'
  ...
  
  /* Play messages from an indexed file. */
  
  greeting = 1
  mainmenu1 = 2
  mainmenu2 = 2
  ...
  messages.0 = 3
  messages.1 = greeting
  messages.2 = mainmenu1
  messages.2 = mainmenu2
  
  address vox 'play channel('handle') file(helpdesk.vap) filetype(index) var(messages.)'
  ...
  
  /* Release the voice channel. */
  
  address vox 'releasechannel channel('handle')'
  

• The following REXX code illustrates how to use the PLAY command to play voice messages using the voice word library:

  /* Get exclusive access to a specific voice channel. */
  
  address vox 'getchannel channelnum(1) prefix(handle) '
  ...
  
  /*Play messages via the VOX Word Library. */
  
  messages.0 = 4
  messages.1 = "System"
  messages.2 = "IMS"
  messages.3 = "Is"
  messages.4 = "Down"
  
  address vox 'play channel('handle') file(voxm_a) filetype(wordlib) var(messages.)'
  ...
  
  /* Release the voice channel. */
  
  address vox 'releasechannel channel('handle')'