This is the man page for vda. I received it off the news group comp.sys.att, so I assume there are no legal problems with making it available here.
vda(1) VOICE POWER vda(1) NAME vda - voice data access utility SYNOPSIS vda [-c chan] [-L max_tt_length] [-t timeout] [-r max_record_len] [-f flash_dur] [-V vocab_file] [-v] [-l linecontrol] [-p pass_file] [-m] [-i] [-D] [-F tmpl_file] menu_file DESCRIPTION Vda conducts a dialog with callers to the Voice Power Voice Card according to instructions contained in a database. The database consists of three types of files: voice files, branch files, and password files. Voice files and branch files are arranged in a tree structure; each node of the tree corresponds to one of these files. The leaves of the tree are always voice files. The root node of the tree is menu_file. -c chan Use voice channel chan. Default: -1, the first channel found searching from channel 0. A channel number of -2 means the first non-busy channel found searching from 0. -L max_tt_length If a multi-key touch tone input max_tt_length characters long is received, assume it is complete without waiting for a terminating '#' character. Default and maximum value is 21. -t timeout If no touch tone input is received when one is expected, timeout after timeout seconds. A value of 0 means wait forever. Default value is 15; maximum value is 59. When a timeout occurs, the action indicated by a timeout line (if any) in the current menu is performed. If no timeout line is present, the current call is disconnected and vda waits for a new call. -r max_record_len When recording a file, stop recording when max_record bytes have been written. Default value is 120,000; range 12000 to 840000 inclusive. Note that recording is at 2020 bytes per second (16k bits). -f flash_dur Set the duration of switch hook flashes to flash_dur milliseconds. Default 500; range 100 to 10000. -V vocab_file Page 1 vda(1) VOICE POWER vda(1) Use vocabulary file vocab_file:e:v and vocabulary header file vocab_file_h when playword and playnum are called. -v Provide diagnostics on stderr when dial is called. -l linecontrol The line control in vda's initial state is set to linecontrol. Valid values are 0 for on-hook (the default), 2 for line and set, and 3 for set only. Usually used with the -i option described below. -p pass_file Use the file pass_file as an ASCII list of valid passwords, one per line (numeric characters only). -m Process the root branch file for multi-key input. In this case user inputs are '#' key terminated. -i Immediate. Vda runs its script immediately, rather than waiting for the phone to ring. When vda is done talking with the caller, it then exits rather than waiting for the phone to ring. A -l option is usually needed with this option. -D Delay. If vda was run in immediate mode, delay will leave the voice card port switches (line control) in their current state for 10 seconds after vda exits. -F tmpl_file Use the call classification template file tmpl_file when dialing. The template file permits the addition of new tones or the redefinition of existing tones. It's format is defined in v_cc_tfile(3). FILE TYPES Voice files are 16k or 24k sub-band data files, or 64k mu law data files. A full path is needed if they are not in the same directory where vda is run. These files are played to a caller over the phone line. For 64k data, a function called play64 is used (see below). The 16k files may be created or edited with the voice editor ve(1), or the record function (see below). Ve(1) can also edit or create 24k and 64k voice files. Password files hold a list of valid passwords that are accepted whenever a password function is executed. A -p command line argument to vda specifies the name of the password file. The prompt used to ask the user to enter their password is determined by the ARGUMENT field in the appropriate line of the branch file. Password is usually used as a greeting function to restrict access to a subtree. Page 2 vda(1) VOICE POWER vda(1) After three bad entries vda hangs up. Branch files describe a voice or a shell menu. A voice menu usually includes a voice prompt telling the caller what touch tone choices are available. An optional greeting message may be spoken when the menu is first accessed. In addition, responses to various touch tone entries are defined in the branch file. A shell menu is similar to a voice menu, except that instead of responding to the user's touch tone input, response is based on the exit value of a shell script. A shell menu has a run line, designated by R as the first field. BRANCH FILES Each line of a branch file is of the form: TT FUNCTION ARGUMENT FLOW TT The valid values for the TT field are shown below. Note that at least one of the first three (G P R) must be present; other lines are optional. The other three fields on each line define a function with an argument that is executed in response to the TT input. After this function is done, the FLOW field determines what happens next. G Indicates the greeting line, which is executed once when the menu is first entered. P Indicates the prompt line, which is executed after the greeting line, and repeatedly each time a "loop" is encountered. After the prompt is executed vda waits for a Touch Tone input from the caller. R Indicates the run line, which is executed after the greeting line (if any). The FUNCTION must be shell. This runs a shell script and causes branching to be based on the exit value of the shell script. Note: this exit value is an unsigned 8 bit number. No prompt line or greeting is permitted in a script with a run line. T Indicates the time out line. If the user does not enter a TT within the time out period the time out line (if present) is executed. The units are seconds. O Indicates the option line. Some vda command line Page 3 vda(1) VOICE POWER vda(1) options may follow this character, each separated by white space, to adjust some operating parameters just within that menu. Options supported are: -l, -r, and -t (see above). - Indicates the default line, which is executed if the user's input does not match any TT value in the file. + Indicates the confirmation line, which is executed if the user's input matches any TT value in the file. The confirmation line is executed before the line that was matched is executed. The FLOW field is not considered for confirmation lines. This line may be used only in scripts including explicit touch tone specifications, that is, a TT value of 0-9, *# abcd, or shell exit code values. . A place holder with no corresponding input. Used in sequences (see below). 0-9 * # In a voice menu corresponds to a user Touch Tone input. For a shell menu see the next line. The line with this TT value is executed when the user enters this value. string In a voice menu strings of numeric values or '*' correspond the a user's multiple Touch Tone input terminated by a '#' key. The line with this numeric string in the TT field is executed when the user enters this string terminated by a '#' key. In a shell menu strings of numeric values ('*' not valid) correspond to a shell scripts return value. The line is executed when the shell script returns the corresponding exit value. FUNCTION The valid FUNCTION values are shown below. Each acts on the value or file name specified in the ARGUMENT field. play Plays a 16k or 24k voice file. play64 Plays a 64k voice file. playnum Plays a numeric value. The ARGUMENT is either a Page 4 vda(1) VOICE POWER vda(1) number or one of: r1, r2, ..., r6. r1 refers to the first number written to standard output by a shell script (see shbranch and shell below). playword Like playnum with two exceptions. First, numbers are played one digit at a time. Second, the letters A - Z are accepted in the ARGUMENT. If a custom vocabulary is present, these letters address the words or phrases (maximum 26) in that vocabulary. Words indicated in ARGUMENT but missing in the vocabulary file are silently ignored. Play Play64 Playnum Playword Same as above but can not be interrupted with a Touch Tone. branch Jumps to a new node described by a branch file, in which single key TT inputs are interpreted. If a run line is encountered in the branch file, 8 bit exit values are interpreted instead. mkbranch Jumps to a new node described by a branch file, in which multiple key TT inputs terminated by the '#' key are interpreted. shbranch Obsolete, same as branch. dial Dials the number specified by ARGUMENT which may include: touch tone digits 0-9 *# abcd, to wait for normal dialtone, 't' to wait for transfer dialtone, 'k' to wait for PBX confirmation dialtone. Initial dialtone detection is only performed when the indicated string starts with '+'. The touch tone string may also include 'u' to dial the last touch tone input from the user, or 'r' to dial a number obtained from the first number written to standard output by a called shell script, record Records a 16k voice file. Recording stops when a TT is entered, a silence threshold is exceeded, or the maximum number of bytes to record is reached. passwd Plays a 16k voice file that prompts the user for a '#' terminated entry, and then checks to see if Page 5 vda(1) VOICE POWER vda(1) the entry is in the pass_file. The user has three trys to enter the correct password. The -p pass_file option must be given if this line is included. If the -L max_tt_length option is also included, max_tt_length must be large enough to contain the password including the terminating '#'. shell Runs a shell script named by ARGUMENT with the $1 argument set to the user's last touch tone input. The shell script's standard output is read to collect up to six newline separated numeric strings, which can be referenced by the dial and the playnum functions. register Operate on the ten general-purpose registers, 0 through 9. Data accessible to this function includes: u for last user input (converted to an integer), and r0 - r5 for the first six numeric values written to standard output by the last shell script executed. Operators include: i for increment, d for decrement, +, and -. The register function and the next two log and monitor are discussed in greater detail in the VDA Tutorial in the appendix. log Print a formatted string on standard output. Numeric data (%d) accessible to this function includes: n0 - n9 for the ten general purpose registers, x for the last shell script exit value, and c for the Voice Card number. String data (%s) accessible includes: r0 - r5 for the first six numeric values written to standard output by the last shell script executed, u for the last touch tone entry by the user, and t for the date and time. monitor Store a formatted string in a structure ipc shared memory. Identical to the log function, except that data goes to shared memory instead of standard output. The user can write a program to examine ipc shared memory and display it in an application specific way. FLOW The valid values for the FLOW field are shown below. loop After the line is executed the prompt line is executed. Page 6 vda(1) VOICE POWER vda(1) return After the line is executed the control returns to the parent node. exit After the line is executed vda hangs up, and is ready for another call. On the last line of a sequence, this applies to all the elements of the sequence. nextline After the line is executed the next line in the file is executed. A sequence of responses to a specific input can be implemented with the nextline FLOW value. An upper limit of 50 lines is permitted in a sequence. DIAGNOSTICS Diagnostic information is written to stderr when a problem occurs. All underflow or overflow errors are reported to stderr. EXIT CODE An exit code of 0 is returned on normal termination; 1 for non-recoverable command line, internal, library, or driver errors; 2 for V2R_FATAL errors; and 3 for V2R_OFATAL errors. FILES Status shared memory key: from ftok( "/usr/bin/vda", 'V' ) BUGS The identifiers used for the values returned from stdout of shell scripts is inconsistent. Identifiers r1-r6 are used for the playnum function. Identifiers r0-r5 are used for register, log, and monitor functions. In the interest of backwards compatibility with existing scripts that account for this inconsistency, this cannot be repaired. SEE ALSO VDA - Voice Data Access Utility tutorial, v_cc_tfile(3), vcb.h Page 7 vda(1) VOICE POWER vda(1) Page 8