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 may be upper or lower case;
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 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 into 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]
|
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 causes software control to be returned
to operating system at the point 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, Avaya
S8300 Media Server.
|
|
-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 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 only valid 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, enter t in
front of the phone number for touch-tone 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 returning 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 containing spaces
are used with this -I option, you must enclose
the string in double quotes when 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 into 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]
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 — they 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
|
|
