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