GETGROUP Command

ADDRESS VOX Commands › Voice Commands › GETGROUP Command

GETGROUP Command

The GETGROUP command returns the group name that you specify and a list of all physical voice channel numbers associated with the group. The return information also indicates whether the channels in the specified group can be interrupted by other REXX programs.

This command has the following format:

ADDRESS VOX "GETGROUP 
  [GROUP(groupname)]
  [SYSTEM(sysname)]
  [PREFIX(varname)]
  [CMDRESP(destination)]"

The GETGROUP command requires no operands.

Specifying the GETGROUP command with no operands returns information about the ALL group only. To see all defined groups, use GETGROUP GROUP(*).

GROUP

(Optional) Specifies the name of the group from which to retrieve a list of all associated voice channels.

Default: ALL

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

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

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 GETGROUP 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.GETGROUP variable contains the returned channel listing.
If the command does not execute successfully, the RC variable contains one of the following values: 5117, 5155, 5199, 5203. (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.

The GETGROUP command returns this information in each of the VOX.GETGROUP variables (VOX.GETGROUP.1 through VOX.GETGROUP.n):

Field	Description of Returned Information
1	The group name.
2	Whether the channels in the group are interruptible by other REXX programs (YES or NO) .
3	The number of channels associated with the group.
4	The number of the first channel in the group.
5	The number of the second channel in the group.
n	The number of the nth channel in the group.

The value stored in the VOX.GETGROUP.0 variable represents the number of groups about which the GETGROUP command returned information.

Example:

The following REXX code illustrates how to use the GETGROUP command to retrieve the information for the group ALL, and then use that information to create a new channel group:

/* Get a list of the local notification server's available channels. */

address vox 'getgroup group(all)'

if RC == 0 then
do
   parse var vox.getgroup.1 name interrupt numchannels channelsingroup

   /* Define the new group to contain all available channels. */

   newgroup.0 = 1
   newgroup.1 = "NEWGROUP" || " " || interrupt || " " || "set " || numchannels || " " || channelsingroup

   /* Create the new group on the local notification server workstation.*/

   address vox 'setgroup var(newgroup.)'
   ...

end