ADDRESS VOX Commands › Voice Commands › GETCHANNEL Command

GETCHANNEL Command

The GETCHANNEL command retrieves an available voice channel and marks it as in-use and performs these additional channel management tasks:

• Prepares the channel for subsequent I/O operations by resetting the channel's call progress analysis (CPA) parameters
• Clears the channel's digit buffer
• Clears the channel's loop-drop, silence-on, and silence-off history
• Resets the channel's volume level (the level at which CA Automation Point plays voice files)
• Sets the channel's hook state to on-hook

Use the GETCHANNEL command with the RELEASECHANNEL command to serialize a voice channel's I/O activity.

This command has the following format:

ADDRESS VOX "GETCHANNEL {GROUP(groupname|ALL) | CHANNELNUM(channelnum)}
  [SYSTEM(sysname)]
  [TIMEOUT(waittime|0|-1)]
  [PREFIX(varname)]
  [CMDRESP(destination)]"

GROUP

Specifies the name of the group from which to retrieve an available voice channel and assign a channel handle. (This is the most common method for retrieving a channel.)

Specifying ALL enables the GETCHANNEL command to search all groups for an available channel.

CHANNELNUM

Specifies the number of a specific, physical channel number to use.

Valid values range from 1 through the number of lines installed.

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

TIMEOUT

(Optional) Specifies the maximum amount of time to wait for a channel to become available (in 1/10-second units). Or, you can specify 0 (zero) to return immediately if a channel is not available or -1 to wait indefinitely.

If you specify a TIMEOUT value, CA Automation Point queues and services requests for an unavailable channel in the order you requested.

Default: 0

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

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

Return Information:

After the GETCHANNEL 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, the VOX.GETCHANNEL variable contains the returned channel handle.
• If the command does not execute successfully, the RC variable contains one of the following values: 5105, 5117, 5135, 5155, 5201, 5202, 5206. (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:

• You do not need to issue the GETCHANNEL command before issuing the ANSWER or ANSWERPLAY commands (if GROUP is specified).
• The calling REXX program has exclusive access to the channel. Exclusive access remains in effect until one of the following occurs:
  • The RELEASECHANNEL command executes.
  • You reset the channel through the Configuration Manager.
  • You close or exit from the command shell that executed the REXX program.

Examples:

• The following REXX code illustrates how to use the GETCHANNEL command to access a specific voice channel:

  /* Get exclusive access a specific voice channel. */
  
  address vox 'getchannel channelnum(1) prefix(handle)'
  ...
  
  /* Perform voice processing using the voice channel. */
  ...
  
  /* Release the voice channel when processing is completed. */
  
  address vox 'releasechannel channel('handle')'
  

• The following REXX code illustrates how to use the GETCHANNEL command to access the first available voice channel:

  /* Get exclusive access to the first available voice channel. */
  
  address vox 'getchannel group(all) prefix(handle)'
  ...
  
  /* Perform voice processing using the voice channel. */
  ...
  
  /* Release the voice channel when processing is completed. */
  
  address vox 'releasechannel channel('handle')'