This topic describes how to use the ADAP command-line
language. It tells you:
- How to log into or out of
the voice mail system from your PC
- How to use ADAP commands
to retrieve data directly from the ADAP-supported voice mail screens
- How to use ADAP commands
to modify subscriber records in the voice mail database and activity
log parameters in the database
You can use these commands from the MS-DOS prompt,
from an MS-DOS batch file or from within an application program.
This topic focuses on the basic knowledge you need
to use these commands, including input and output requirements and basic
strategies. Individual commands for retrieving and modifying data in
the database are summarized in this chapter and then described individually
in other topics.
These ADAP commands provide you a UNIX-like PC
interface for:
- Retrieving data to the
PC for further processing
- Modifying subscriber data
directly in the voice mail database
Commands can be uppercase or lowercase; options
are case sensitive.
MS-DOS limits program names to eight characters,
plus an optional suffix of up to three characters. All commands described
here have a suffix of .exe, which indicates the files are executable
from the DOS prompt.
Logging in to the Voice Mail
System
To use ADAP commands, you must first
log in to the voice mail system from your PC. You can log in from the
MS-DOS prompt C>, from an MS-DOS batch file, or from within an application
program. Once you are logged in to the voice mail system, you can execute
a series of instructions with intermixed ADAP and MS-DOS commands.
You can log in to the voice mail system from the
PC by using one of the following options:
- An automatic login procedure
(alogin), which combines all of the login identification information
in one step
- A manual login procedure
(login), which requires that you enter individual responses for
the login prompts
These two procedures are described
in this topic.
Automatic Login Procedure
Use the alogin
command to log in to the voice mail system automatically without further
interaction. The format for this command is shown below. Optional arguments
are enclosed by square brackets ([ ... ]).
alogin -d
device [-b
baud rate] [-p
communications port]
[-I modem initialization
string] [-i] [-R]
[-t] [-r release]
[-v] [-w] [-V]
[-P System
Password] loginID
password
[phone number]
Table: alogin command
| Command Arguments |
Description |
|
alogin
|
Automatic login.
|
|
-d
|
Device type flag; must be followed by device.
|
|
device
|
Valid device types are: pdm (MPDM data modules), hayes (Hayes-compatible
modems), att4000 (AT&T's 1200-baud modem), and direct (direct
cable connection).
|
|
-b
|
Baud rate flag; must be followed by baud rate.
If no baud rate is specified, defaults to 4800.
|
|
baud rate
|
Valid transfer baud rates are 1200, 2400,
4800, or 9600.
|
|
-p
|
Communications port flag; must be followed
by communications port. If no port is specified, defaults to 1.
|
|
communications port
|
Valid communications ports are 1 or 2.
|
|
-I
|
Modem initialization string flag; must be
followed by modem initialization string.
|
|
modem initialization string
|
Specifies an initialization string to be sent
to the modem before connection to the voice mail system is attempted.
The default is a null string.
|
|
-i
|
Causes the system to bypass the search for
the data set ready (DSR) signal. Use this option only with a Hayes-compatible
modem.
|
|
-R
|
If errors occur during the login (such as
an invalid login attempt), causes the connection to be dropped
and automatically retried from the beginning, up to three times.
|
|
-t
|
Causes the system to inhibit the terminal
code prompt. Include this option only when using the 513 BCT emulator
software on the PC. This option causes software control to be
returned to the operating system at the point that the AUDIX system
sends the terminal code or Terminal Type prompt to the ADAP machine.
|
|
-r
|
Release flag; must be followed by release.
|
|
release
|
Retrieves data for the specified release of the voice mail
system software.
INTUITY AUDIX: I-r2.0 for 2.0, I-r3.2 for 3.2, I-r3.3 for 3.3,
I-r4.0 for 4.0, 4.1, 4.2, 4.3, or 4.4,
I-r5.0 for INTUITY AUDIX 5.0, 5.1, INTUITY AUDIX LX R1.0, IA
770 INTUITY AUDIX.
|
|
-w
|
Writes a one-line summary of the exit status
of this command into the file alogin.rc.
|
|
-v
|
Writes detailed transfer statistics of the
alogin command status and the voice mail system connect responses
to the screen. This option is primarily a debugging aid.
|
|
-V
|
Writes the ADAP version number for this command
and exits without logging in.
|
|
-P
|
System password flag; must be followed by
System Password. This flag is valid only when connecting to an
AUDIX system under the cust login.
|
|
System Password
|
Identifies your system password. If you have
a null system password, use a space followed by "" .
|
|
loginID
|
Identifies your voice mail system login ID.
|
|
password
|
Identifies your voice mail system login password.
|
|
phone number
|
Identifies the voice mail system phone number.
This number is not required for direct cable configurations. If
you have a Hayes-compatible or AT&T 4000 modem and you have
not set the modem for touchtone dialing, enter t in front
of the phone number for touchtone dialing.
|
While executing this command, the software makes
three attempts to connect with the voice mail system. If the -R
(retry) option flag is set and errors occur during the login (such as
an invalid login attempt), the connection is dropped and automatically
retried from the beginning, up to three times.
The -I feature is intended
to send initialization strings to Hayes and
Hayes-compatible modems. However, you can use the -I
option to send a startup string to any local connection-establishing
device, such as a PDM or modem, that returns the string "OK" to the
computer upon processing and acting on a valid string.
The alogin
command does no checking of the validity of the initialization string
but relies on the connection device to return an "OK" to the COM1 or
COM2 port when the device is successful in using the string. Spaces
are legal in Hayes initialization strings. If strings that contain spaces
are used with this -I option, you must enclose
the string in double quotes when you are following the -I
on the command-line.
If you attempt to log in without using the -i
option when your modem does not generate a DSR signal, the following
message (with the appropriate port number) appears:
alogin: connect: eopen of port 1 failed,
rc = Ox85
processing stopped
If this happens, re-enter the alogin
command and include the -i option.
Manual Login Procedure
Use the login
command to log in to the voice mail system manually. The format for
this command is shown below. Optional arguments are enclosed by square
brackets ([ ... ]).
login [-b
baud rate]
[-p communications
port] [-i]
[-V] [-r release]
Table: login command
You can now execute the ADAP commands to retrieve
screens data or modify subscriber records.
Logging out of the Voice Mail
System
To log out of the voice mail system,
enter the logout command. This command sends
a Ctrl-d disconnect character to the system and causes the DTR (data
terminal ready) signal to be dropped for a half second, disconnecting
the modem.
The logout command
also sends the Hayes modem string "+++ATH" in case your modem is Hayes-compatible.
This command takes approximately 5 seconds to complete.
Interrupting a Command
To interrupt a command in progress,
press Ctrl-c. The MS-DOS prompt reappears.
You can receive faster response to your termination
requests if you set the DOS command BREAK to ON. See information in
your MS-DOS user's guide about the BREAK command usage.
Command-line Commands
The following topic describes how
to use the command-line commands to retrieve and modify data in the
voice mail database. It describes the command format, the use of the
record description tables, the input records, the output records, and
the return codes.
Command Format
Database retrieval and modification
commands are associated with specific voice mail system administrative
and maintenance screens that are supported by ADAP. Each command option
begins with a dash, followed immediately by a one-letter option identifier.
If the option requires an argument, the argument immediately follows
the option letter. You can insert spaces between the option and the
argument for readability — the spaces will be ignored.
Optional arguments are enclosed by square brackets
([ ... ]).
For example, you might enter the gettraf
command as follows:
gettraf -f month -d 1294 -i
In the previous gettraf line command:
Input Records
This topic describes record formats
and parameters for the input file.
Input File Format
You can process multiple voice mail
subscribers by creating an input file containing information about the
subscribers you wish to add, delete, update, or monitor. This file is
then used as input by the data retrieval or modification command.
Certain commands require that you use valid extensions
from the voice mail system as input. For example, the AUDIX Display
Subscribers screen consists of a different record of data for each subscriber.
To retrieve a record for each of several subscribers, you would enter
the extension number for each subscriber on a separate line in the input
file.
Some commands require that you supply only the
subscriber extension for the data that you want to retrieve or modify.
The following example shows a list of extensions, each on a separate
line and containing from three to 10 digits. (On any one voice mail
system, all the extensions must be the same length).
"1234567890"
"2345678901"
"9999999999"
"0011100111"
Because the ADAP software treats extensions as
characters instead of numbers, the leading zeros in 0011100111 are not
lost.
Other commands require that you supply additional
information to identify completely the data that you want to retrieve
or modify. The following example requires extension and name for each
subscriber, defined by delimiters ("") each on a separate
line and containing from three to 10 digits.
"1234567890","Doe,Mary"
"2345678901","Martinez,Bob"
"9999999999","Green,Sarah"
"0011100111","Jones,David"
Notice that this is the data retrieved by the getdir
command. For example, you could retrieve the subscriber extension and
name by first using getdir and then using this data as input
for another command.
Note: When constructing input records for
ADAP commands, all fields, regardless of type, must be enclosed in double
quotation marks and separated by commas. The records must be terminated
with a NEWLINE. These rules hold true whether the input is redirected
from a file or entered interactively from the keyboard though the use
of the -i option.
Optional Input Fields
A field name enclosed in square brackets,
that is [....], indicates an optional input field. You do not have to
provide a value for this input field when using that particular ADAP
command. If you wish not to provide a value for this input field but
want to give a value for a field later in the input field sequence,
you must insert a placeholder set of double quotes ("")
which denotes a null string and a field separator (a comma) into the
input record in the place of this input field.
The null string and comma serve as placeholders
so you can tell ADAP you want to skip the field and go to a field later
in the input sequence. The ADAP command can then determine the purpose
of the value later in the input record. If you wish to provide a value
for the nth input field, you must have provided values or placeholders
for all previous (n-1) fields in the input record. If you wish to omit
all optional fields, you need to provide only the required fields; placeholders
are not necessary.
When you omit optional fields, ADAP does not place
a value in the corresponding field on the voice mail form. It allows
the voice mail machine to provide a default value in the case of adding
local or remote subscribers. When changing existing subscribers, omitting
optional fields causes the corresponding information on the voice mail
machine to be skipped, leaving intact any value that could already be
there.
Input of Name or Extension
Some input records format tables indicate
that a name and an extension should be provided. There is some flexibility
when an ADAP is communicating with a system. When an ADAP command for
a INTUITY AUDIX system accepts both a name and extension in an input
record, an empty set of double quotes may be placed for either the name
or the extension. Both data items need not be provided.
If only the name is provided, the command uses
the name; if only the extension is provided in the input record, the
command uses the extension. If both the name and extension are specified
in an input record, the name is ignored and the extension is employed
in the transaction. For operations which change the name or extension,
these easements apply only to the old name and old extension.
Redirecting Input from Files
Once you have constructed an input
file, you can use it to retrieve data. For example, if you wanted to
retrieve records for all subscribers on the voice mail system, using
an input file called dir.dat, you could enter the following command.
getsub < dir.dat >
sub.dat
Subscriber extension input is supplied to the getsub
command from the dir.dat file. This file contains the extensions of
all subscribers on the voice mail system and has been formatted correctly
by the getdir command. The getsub command (and all other
commands requiring a subscriber extension number) retrieves data for
a subscriber when the subscriber's extension number is entered. ADAP
writes each returned subscriber record to the sub.dat file.
Entering Data from the Keyboard
You may enter data directly from the
keyboard by including the -i option on the command-line. To indicate
that you have finished entering data while in interactive mode, press
Ctrl-z , followed by RETURN. Ctrl-z is the MS-DOS end-of-file (EOF)
character.
For example:
delsub -i <RETURN>
"Doe, John","0123456789" <Ctrl-z
RETURN>
Output Records Format
All data items in output records are
separated by an output field separator (OFS). The default OFS is a comma.
All character (C), digit sequence (K), and logical (L) fields are enclosed
in delimiting characters when appearing in output records.
| Note: Fields
that do not exist for a given release of the voice mail system can
be included in output for compatibility with other releases. Those
fields contain either a 0 or "". |
Delimiters
You can change the output character
string delimiter from double quotes (") to a delimiter of your choice.
To change the delimiter, set an environment variable named DLIM to the
character you want to use as the delimiter. For example, enter the following
command at the DOS prompt or in the autoexec.bat file:
set DLIM=&
If DLIM is not initialized in this way, the PC
system software uses double quotes (") as the default. For instructions
on how to initialize DLIM, see the description of the autoexec.bat file
in your MS-DOS manual.
Output Field Separator
You can use the environment variable
OFS, for Output Field Separator, when communicating with the system
to specify a single character for separating the output from the ADAP
command-line utilities. For example, enter the following command at
the DOS prompt or in the autoexec.bat file.
set OFS=*
Subsequently, an execution of getmlist
with an R1V7 can produce output formatted as follows:
"PERFS1"*"0"*"audix"
"PERFS2"*"29"*"audix"
"PERFT1"*"26"*"audix"
"STL01"*"31"*"audix"
"STS01"*"32"*"audix"
"STT01"*"14"*"audix"
"STT02"*"15"*"audix"
"pluto"*"30"*"audix"
If the OFS is not set, commas are used as output
field separators by default. If the environment variable OFS is set
to a character string of length greater than one, ADAP ignores OFS and
the ADAP commands use commas as separators.
For instructions on how to initialize OFS, see
the description of the autoexec.bat file in your MS-DOS manual. Only
commas can be used as the OFS when communicating with a INTUITY AUDIX
system.
Backward Compatibility
In adding features to each release
of the voice mail system software, fields have been added and deleted
from the screens with which ADAP interacts. As the voice mail releases
evolves, new fields have been added to the end of the ADAP record formats.
If fields have been deleted from any screens in the development of a
new release from a previous one, the ADAP command puts into the output
a placeholding value.
The placeholding value is a zero for numeric fields
that have been deleted. For deleted character, digit sequence, or logical
fields, the placeholding value is an empty string enclosed in a set
of delimiters (which by default is "").
Redirecting Output to Files
If you don't specify an output file
to receive the data, ADAP displays all retrieved screens data on the
PC screen. Most applications can use the MS-DOS redirect capability
to write the data to a file. To do this, specify an output filename
preceded by a redirect symbol such as > ofile.
For example, if you are retrieving data for the
INTUITY List Extensions screen and you want the data written to a file
named dir.dat, enter the following:
getdir > dir.dat
ADAP retrieves the data from the List Extensions
screen for all subscribers on the INTUITY system and writes this data
to a file named dir.dat instead of displaying it on your PC screen.
Return Codes
On successful completion, all of the
screen retrieval commands exit with a return code of 0. If processing
is not complete when a command terminates, the commands exits with a
non-zero return code. The value of return codes may be tested from the
MS-DOS prompt or by using batch programs with the DOS ERRORLEVEL command.
RS-232 driver errors are shown in Converting
RS-232 Driver Errors for ADAP.
Data Retrieval Commands
Database retrieval commands obtain
a copy of data from the voice mail system internal database. The following
table lists the voice mail system screens that are supported and the
corresponding retrieval command. All commands are described in Using
the ADAP Database Retrieval Commands, in alphabetical order.
Table: Database Retrieval Commands
- Screens Correlations
|
|
Messaging Screen Name
|
ADAP Command
|
|
display activity-log
|
getlog
|
|
display administrator's-log
|
getsys
|
|
display alarms
|
getaalar
|
|
display alarms
|
getralar
|
|
display cos
|
getcos
|
|
display events
|
getmaint
|
|
display fragment
|
getfrag
|
|
display remote-subscriber
|
getrsub
|
|
display subscriber
|
getsub
|
|
display subscriber
|
getsysat
|
|
display system-parameters activity-log
|
getalogp
|
|
display system-parameters features
|
getsysfe
|
|
display system-parameters limits
|
getlimit
|
|
list attendants
|
getatt
|
|
list extensions
|
getdir
|
|
list machines
|
getmlist
|
|
list measurements community day
|
getcomm
|
|
list measurements community hour
|
getcomm
|
|
list measurements feature day
|
getfeat
|
|
list measurements feature hour
|
getfeat
|
|
list measurements load day
|
getload
|
|
list measurements load hour
|
getload
|
|
list measurements remote-messages day
|
getrem
|
|
list measurements remote-messages month
|
getrem
|
|
list measurements special-features day
|
getspfea
|
|
list measurements special-features hour
|
getspfea
|
|
list measurements subscriber day
|
gettraf
|
|
list measurements subscriber month
|
gettraf
|
|
list remote-extensions
|
getrlist
|
|
list subscribers
|
getlist
|
|
list measurements network load day
|
getnet
|
|
list measurements network load hour
|
getnet
|
|
list trusted-servers
|
getserve
|
|
list remote-text-addresses
|
gettlist
|
Database Modification Commands
You use database modification commands
to modify certain data directly in the voice mail database. The following
table provides you with the name of each modification command, its purpose,
and the voice mail system software versions for which the commands can
be used. All commands are described in Using the
ADAP Database Modification Commands, in alphabetical order.
|
|
Purpose
|
Command
|
|
Add remote subscriber
|
addrsub
|
|
Add subscriber
|
addsub
|
|
Change covering extension
|
changcex
|
|
Change community id
|
changcom
|
|
Change class of service
|
changcos
|
|
Change subscriber extension
|
changext
|
|
Change miscellaneous field
|
changmis
|
|
Change priority message
|
changmsg
|
|
Change subscriber attributes
|
changsub
|
|
Change subscriber name
|
changnam
|
|
Change password
|
changpwd
|
|
Change switch number
|
changsw
|
|
Change text-service machine user ID
|
changtex
|
|
Change remote subscriber community id
|
chgrcom
|
|
Change remote subscriber extension
|
chgrext
|
|
Change remote subscriber machines
|
chgrmach
|
|
Change remote subscriber names
|
chgrnam
|
|
Delete remote subscribers
|
delrsub
|
|
Set system translation machine adjunct
|
setadj
|
|
Set activity log values
|
setalogp
|
|
Set system cdr screen data
|
setscdr
|
|
