Lucent Technologies DEFINITY Enterprise Communications Server Release 6 CallVisor PC ASAI Instructions Manual

							Issue  3  May 1998xxi 
About This Document
This reference guide is for Lucent Technologies’ DEFINITY® Enterprise 
Communications Server (ECS) CallVisor® PC Adjunct-Switch Application 
Interface (ASAI) platform for UNIX® and Windows® NT™. 
NOTE:
This document can be used with the earlier versions of DEFINITY 
Communications System products.
The information in this document relates to a specific implementation of an API for 
the ASAI protocol between an adjunct and the DEFINITY ECS. Emphasis is on 
the API rather than on the protocol, adjunct, or the DEFINITY ECS. Specific 
information concerning these other products is readily available in other 
documents. See the section ‘‘Related Documents’’ at the end of this preface, or 
the documentation provided with your operating system, or computer.
The DEFINITY ECS utilizes the following products made by other software 
vendors:
nSolaris™ of Sun Microsystems, Inc.
nUNIX is licensed exclusively through X/Open Company Limited
nUnixWare® of the Santa Cruz Operation, Inc.
nWindows® of Microsoft Corporation
nWindows NT of Microsoft Corporation
Reason for Reissue
This document covers all the new features up to Release 6.3. 
						

							About This Document
xxiiIssue  3  May 1998
New features 
This section summarizes the new features up to Release 6.3. 
Single-Step Conference
The Single-Step Conference allows applications to add a device into an existing 
call for the purpose of playing announcements or facilitating application-initiated 
transfers and conferences. This is accomplished with a single ASAI request, 
without the need for placing anyone on hold or initiating a new call.
Universal Call ID
Universal Call ID (UCID) is a unique tag assigned to each DEFINITY call. It is 
used by an application to track a call for its life, from origination to disconnect, 
regardless of where the call may end up and how it gets there (transfer, 
conference, routing, through a variety of network and the DEFINITY Enterprise 
Communications Servers, and voice responses, etc.). 
The UCID is reported to all ASAI links on the DEFINITY ECS, if so administered. 
The event reports that contain the UCID are: Call Initiated, Call Offered, Alerting, 
Connected, Call Transferred, and Call Conferenced. Acknowledgments to Third 
Party Make Call, Third Party Auto-dial, Third Party Merge, and Third Party Take 
Control also contain UCID. The UCID is also passed in a Route Request 
Capability and UCID Query is also available in this release.
Release 5 Major Enhancements
nAdvice of Charge
This feature provides an ASAI application with the capability to receive 
information regarding the cost of an active outgoing call. It applies only in 
those countries where the network is able to send the cost of the current 
call to the DEFINITY ECS using the ISDN Advice of Charge feature.
nReason Codes 
ASAI will allow adjuncts to enter a reason code when an agent’s work 
mode changes to AUX work or when an agent logs out. In addition, the 
adjunct can also query for an agent’s reason code status. This feature must 
be optioned and it is mandatory that the AUX Work Reason Codes and the 
Agent Logout Reason Codes be set to “forced” or “requested.”
nASAI Selective Listening
This feature allows an ASAI adjunct application to disconnect or reconnect 
selected listening paths. An application can use this feature to prevent one 
or more parties on a call from hearing communications among other parties 
on that call.  
						

							New features
Issue  3  May 1998
xxiii
nII-Digits
II-Digits provide information about the originating line. For example, these 
digits will indicate if the call is originating from a prison, a cellular system, a 
coin machine, or special operator, etc. II-Digits are passed to the 
DEFINITY ECS by the network on Integrated System Digital Network 
Primary Rate Interface (ISDN-PRI) trunks and are then passed to the 
adjunct over an ASAI link. An ASAI application can use the information 
provided by II-Digits to properly route or provide special treatment for the 
incoming call. This feature can also be used to prevent fraud. 
II-Digits will be populated in the Call Offered, Alerting, Connected Event 
Reports and in Route Request.
n27-Character Display
The ASAI-Accessed Integrated Directory query has been modified to return 
up to 27 characters for names when extensions are retrieved from the 
Integrated Directory of ECS. Link version 3 (G3V5), must be negotiated 
between the ECS and the adjunct for this enhancement to work (otherwise, 
only 15 characters will be passed). International Standards Organization 
(ISO) certified optrex characters are also included in the ASAI-Accessed 
Integrated Directory.
nOPTREX Characters 
Some newer phones support escape sequences to display certain 
international characters. CallVisor PC now provides this data in new fields 
in “wide character” format so that it can be processed by the standard 
functions that accompany the UNIX operating system. 
						

							About This Document
xxivIssue  3  May 1998
Intended Audience
This document is intended for system administrators, programmers and testers. It 
provides step-by-step procedures for installation and administration of CallVisor 
PC. This document also describes the interaction between the UNIX ASAI adjunct 
and the DEFINITY ECS. It is intended to assist applications programmers in 
developing applications for the adjunct. It includes complete information on all the 
ASAI library functions, capabilities and capability primitives. Integration Test Tool 
(ITT) is designed to help in testing the library functions. A number of issues and 
problems that may be encountered during various phases, from installation to 
regular administration, are also addressed.
It is assumed that the readers are familiar with the UNIX operating system 
(including advanced topics such as device polling through signals and unwaited 
I/O) and have at least a basic knowledge of the Integrated Services Digital 
Network (ISDN). In addition, readers should be thoroughly familiar with the 
DEFINITY ECS ASAI features and their restrictions. 
						

							Organization of This Document
Issue  3  May 1998
xxv
Organization of This Document
 This document is organized as follows:
Chapter 1 provides detailed installation steps.
Chapter 2 provides the manual pages for commands, daemons, and files used in 
administration.
Chapter 3 is an overview of the Adjunct-Switch Application Interface. It presents 
the terms and concepts specific to ASAI and includes an overview of the ASAI 
library: the functions, the application service elements (ASEs) and the capability 
primitives.
Chapter 4 describes the ASAI library functions and their use and contains a 
number of coding examples.
Chapter 5 has all the ASAI application service elements, providing details about 
the capabilities that comprise each ASE.
nEvent Notification and Event Reports 
nThird Party Call Control Capabilities
nSet Value
nValue Query 
nRequest Feature
nAdjunct Routing 
nMaintenance 
nAbort Capabilities 
Chapter 6 introduces a new feature — CV/LAN.
Chapter 7 has a detailed list of error returns from the library functions
Chapter 8 is an introduction to ASAI capability primitives. 
Chapter 9 contains manual pages for ASAI library functions, ASAI capabilities 
and primitive types in detail. 
Chapter 10 is an overview of Integration Test Tool (ITT) and its functions.
Chapter 11 provides solutions to a number of issues and problems encountered 
during various phases of installation, administration, application programming and 
testing. 
Appendix A contains ISO certified OPTREX characters. 
						

							About This Document
xxviIssue  3  May 1998
A Glossary and Index are also provided for easy access to terms and definitions.
Related Documents
For specific information concerning the DEFINITY ECS Release 6 ASAI, the 
following documents are available from Lucent Technologies Publications Center 
(1 800 457-1235) :
nDEFINITY Enterprise Communications Server Release 6 CallVisor ASAI 
Technical Reference
, 555 230-220
nDEFINITY Enterprise Communications Server Release 6 CallVisor ASAI 
Protocol Reference
, 555 230-221
nDEFINITY Enterprise Communications Server Release 6 Administration 
and Feature Description
, 555-230-522
nDEFINITY Enterprise Communications Server Release 6 System 
Description Pocket Reference
, 555-230-211
nDEFINITY ECS CallVisor ASAI DEFINITY LAN Gateway over MAPD 
Installation, Administration, and Maintenance, 555-230-114
nDEFINITY ECS CallVisor ASAI PC LAN over MAPD 
Installation, Administration, and Maintenance, 555-230-113
nCallVisor ASAI CD Document Set, 585-246-801
This CD ROM contains six CallVisor ASAI release 6 documents. It includes 
CallVisor ASAI Technical reference, CallVisor ASAI Protocol Reference, CallVisor 
ASAI Overview, CallVisor ASAI PC
, CallVisor ASAI DEFINITY LAN Gateway over 
MAPD Installation, Administration, and Maintenance
, and CallVisor ASAI PC LAN 
over MAPD Installation, Administration, and Maintenance
Technical Service Center
The CallVisor PC helpline supports CallVisor PC customers who need technical 
assistance. Technical support is provided for installation, administration and 
functionality failures (“bugs”). The number of hours of technical support varies 
with the type of license purchased. The CallVisor PC helpline number is 1 732 
957-5725.
The Technical Service Center (TSC) offers a consulting service to help application 
developers map desired functionality to ASAI capabilities. The TSC can be 
reached at 1 800 344-9670. 
						

							Issue  3  May 19981-1
1
Installation
This chapter provides all the information on the DEFINITY ECS administration, 
system configuration, operation, and limits which is required to install CallVisor 
PC. This chapter also covers the procedure to install CV/LAN on Windows NT and 
UNIX, and run the sample application. 
Platform Consideration
ASAI supports the following operating system platforms (CallVisor PC server) :
1. SCO UnixWare 2.1.2 (including ptf32801)
2. Solaris 2.4 x86
3. Solaris 2.5 x86
 Hardware Platforms
As a general guideline, if one of the above listed operating systems will run on the 
hardware platform, CallVisor PC will also run. You should first choose a software 
platform, (UnixWare or Solaris x86), and work from the Hardware Certification list 
provided with the operating system. If planning a CallVisor PC ISDN-BRI 
installation, choose a PC model from the list with a clock speed below 90 MHz. A 
multi-CPU PC is not supported for either a PC-ISDN or LAN Gateway 
configurations.
The PC ISDN card (IPCI card) has been known to have problems in some PCs 
with clock speeds greater than 90 MHz. However, many software vendors have 
indicated that they are using CallVisor PC ISDN in systems with clock speeds up 
to 166 MHz. At these speeds, the link will eventually fail.  
						

							Installation
1-2Issue  3  May 1998 
There are two distinct types of ISDN board failures: 
1. Inability to download the ISDN board firmware (failure to “pump”). This is 
discovered at installation time and can be diagnosed by checking the 
/usr/adm/isdn/isdn_log file for errors during the pumping phase. 
2. This is link traffic related. At link message rates, approximately 1/3 to 1/2 
the bandwidth of the ISDN link (link bandwidth is 30 messages per 
second), the ISDN board will experience a hardware timeout, and the link 
will drop. The only recovery is to re-pump the board (ipci_OFF followed 
by ipci_ON). Again, the hardware timeout error can be checked in the 
isdn_log file.
Some PC manufacturers provide the ability to reduce the clock rate via straps on 
the PCs motherboard. Check your PCs manual, or your hardware vendor to see 
if this is possible.
The CallVisor PC LAN Gateway interface has no known problems related to PC 
clock speeds.
The following sequence of steps is necessary to install CallVisor PC ASAI 
package on a PC. The order of these steps eliminates excessive adjunct 
computer kernel rebuilds, reboots and powerdowns.
1. Disable COM 2 (only if IRQ3 is to be used)
2. Install the CallVisor PC ISDN software (IPCI) device driver
3. Install CallVisor PC LAN Gateway software
4. Install the CallVisor PC ASAI software
5. Install the PC/ISDN board (hardware)
6. Test the CallVisor PC ASAI link
7. Install the CallVisor PC ITT software
8. Install CV/LAN Server software
9. Install CV/LAN Client software
The next section of this chapter provides detailed instructions to install the 
CallVisor PC LAN GATEWAY package on an adjunct. The CallVisor PC ISDN 
package must be installed prior to the LAN GATEWAY package. CallVisor PC 
ISDN and CallVisor PC LAN GATEWAY may be run concurrently on the same 
adjunct PC. Instructions to install CV/LAN server software on an adjunct can be 
found in ‘‘Server Installation on UNIX’’ on page 1-15 of this chapter. CV/LAN 
server can also be run on the MAPD. For further information, 
see DEFINITY ECS 
CallVisor ASAI PC LAN over MAPD Installation, Administration and Maintenance
. 
Instructions to install CV/LAN clients on UNIX and Windows NT platforms are 
described later in this chapter. The adjunct is limited to a total of eight links; any 
combination of up to four ISDN links and up to four LAN GATEWAY links, is 
allowed. The links must be installed contiguously; their order may not be 
intermixed. If ISDN links are to be installed, they must be installed as link numbers 
1 through 4. LAN GATEWAY link numbering must start immediately after the last  
						

							Installation
Issue  3  May 1998
1-3
ISDN link. For example, if three ISDN links and two LAN links are installed, the 
ISDN links will be links 1, 2, 3 and the LAN links will be links 4 and 5. If no ISDN 
links are installed, LAN links will be configured starting at link number 1. The 
installation scripts will perform this numbering automatically. It is not possible to 
change the number of links (ISDN or LAN) without completely uninstalling and 
reinstalling the CallVisor PC ISDN, CallVisor PC LAN GATEWAY, and CallVisor 
PC ASAI packages.
Throughout this document the PC/ISDN board is referred to as the ISDN PC 
interface (IPCI) board; the DEFINITY LAN Gateway Board (for the optional LAN 
GATEWAY package) as the MFB, and the Multi Application Platform for the 
DEFINITY ECS as the MAPD. The MAPD currently supports the DEFINITY LAN 
Gateway package and the CV/LAN package. The IPCI device driver is part of the 
CallVisor PC ISDN software that is pumped to the board.
If this is an upgrade installation or the packages are being uninstalled and/or 
reinstalled to change the number of links, the current configuration parameters 
should be written down or printed out for future reference. These parameters can 
be found in the files /usr/adm/isdn/ipci_parms,
/usr/adm/asai/asai_parms, and /usr/adm/isdn/lan_parms. Enter the 
following commands:
cat /usr/adm/isdn/ipci_parms
and 
cat /usr/adm/asai/asai_parms
and 
cat /usr/adm/isdn/lan_parms
to see the parameters.
NOTE:
Before beginning, the installer must make sure that the Network Support 
Utilities package has been installed.
1. If no ISDN links are going to be installed, skip to Step 3.
Decide on the interrupt level (IRQ) number to be used. The IRQ number is 
the same as the Interrupt Vector Number (IVN) referred to when installing 
the CallVisor PC ISDN software. Available IRQs are 2 or 3. The CallVisor 
PC ISDN software package will ask which package is to be used. IRQ 2 is 
preferred because asynchronous communications port COM2 uses IRQ 3. 
If IRQ 2 is unavailable, IRQ 3 has to be used. If IRQ 3 must be used, the 
installer must first find out how to disable COM2 for his or her particular 
computer before going to the next step. 
						

							Installation
1-4Issue  3  May 1998 
2. Decide on the shared memory addresses (SCMA) that the IPCI boards will 
use. The default PC memory space address for one IPCI board is d0000. 
Use this default address as long as it does not conflict with any other 
hardware. See Task 1 in Chapter 3, “Configure The Platform Hardware” of 
PC/ISDN Platform Installation and Reference for details on setting the 
address selection switches to use the desired address; also see Table 3-3,
 
“Switch Settings for PC/ISDN Interface Card Base Addresses.”
3. When no one else is using the computer, log in as root. Bring the computer 
to single-user mode and then run state 1 by entering the command:
shutdown -iS -y -g120
Press ctrl-d to proceed and enter 1 for the selected run state.
4. Copy /unix to  stand/unixold as a safety precaution in case of 
disaster. Enter the command:
cp  /unix  /stand/unixold
5. Enter the command:
pkgadd -d diskette1
  Place the disk in the appropriate drive and follow the online instructions.
The Pkgadd displays that the CallVisor PC ISDN package is available to 
process. Press   to continue the installation.
6. After several minutes the installation procedure asks how many IPCI 
boards are installed on the machine. Enter the number of IPCI boards that 
are already installed or the number which will be installed on the machine. 
The default is 1. If your installation will have only CallVisor PC LAN 
GATEWAY links, enter 0. Entering 0 will cause the installation to skip to the 
link version administration step. Enter the correct number (0, 1, 2, 3) or 
press  for the default.
7. The installation procedure asks to enter the IVN number. This is the 
IRQ/IVN number for the IPCI boards that you decided to use in Step 1. The 
default is 2. Enter the correct number (2, 3) or press  for the default.
8. The installation procedure asks you to enter the 5-digit SCMA address 
value. This is the shared memory address selected in Step 2. Be sure to 
use lowercase letters. The defaults are available for four boards and online 
help displays the available values. Enter the correct numbers or press 
 for the default.
9. The installation procedure asks you to enter the desired version. The ISDN 
protocol stack, specifically the QP module, supports link version selection. 
Version 1 (default) corresponds to G3V3, version 2 corresponds to G3V4, 
and version 3 corresponds to Release 6. 
RETURN
RETURN
RETURN
RETURN