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

							ASAI Capabilities
Issue  3  May 1998
5-51
Abort Capabilities
The ASAI library includes an Abort capability that is part of every capability group. 
The Abort capability provides two types of Aborts:
nU_ABORT — A client-initiated abort 
nP_ABORT — A library-initiated abort
Description
The Abort capability allows the client to inform the peer entity (client or server) that 
processing for the ASE is terminating. The 
Cause parameter indicates the reason 
for terminating.
The client invokes the Abort capability by issuing a C_ABORT with the type of abort 
specified as C_USER_ABORT. The library invokes the Abort capability by issuing a 
C_ABORT with the type of abort returned to the client as C_PROV_ABORT.
Request/Indication Parameters
nAssociation Identifier
Notes
There are no restrictions on this capability. 
						

							ASAI Capabilities
5-52Issue  3  May 1998  
						

							Issue  3  May 19986-1
6
CV/LAN Programming
Introduction to CV/LAN  
CV/LAN allows application software running on UnixWare, Solaris x86, SPARC 
Solaris, or Window NT 4.0 to access the DEFINITY ECS CallVisor ASAI features 
across a TCP/IP LAN in a client-server arrangement. The server runs on the 
CallVisor PC or the Multi-Application Platform for DEFINITY (MAPD). CallVisor 
PC and CV/LAN client applications use the same library and differ slightly in only 
one API call. For further information see ‘‘asai_open( )’’ on page 4-3, in Chapter 4 
and ‘‘asai_open (3ASAI)’’ on page 9-10, in Chapter 9, ‘‘Programming Manual 
Pages.’’
The CV/LAN server supports multithreading and has an independent send and 
receive path. Most of the message processing and checking is local.
Applications Development 
Environment
The CV/LAN provides an executable for the server, asaiserv. asaiserv 
automatically runs after installation or system reboot. 
UNIX Platforms
Basically, the client applications are multithreaded and require sockets. In 
UnixWare, -Kthread, -lsocket, -lnsl, and -DMTHREAD must be specified. In 
Solaris, -Ithread, -Isocket, -Insl, and -DMTHREAD must be specified. 
						

							CV/LAN Programming
6-2Issue  3  May 1998 
Windows NT Platform
In Windows NT, the multithread or debug multithread run time libraries must be 
specified in the “code generation” category of the “C/C++” tab. The sockets library, 
wsock32.lib should be included in the list of libraries in the “Link” tab. In addition, 
the WIN_NTS, CVPC, and ASAIDLL (Dynamic-Link Library) must be included in 
the settings.
For Windows NT, a Dynamic-Link Library (DLL) called asaidll.dll along with 
its import library asaidll.lib, is provided. Required ASAI header files are 
installed in \asai\include\asai. Here 
 is the path you specify during the installation of the CV/LAN SDK.
After installation, asaidll.dll and asaidll.lib will be placed under 
\system32.
In addition, under Windows NT, some Unix header files are required and provided 
along with the CV/LAN SDK. The required UNIX header files will be placed under 
\include\unix. Some of those header files include 
their NT namesake as well. For instance, the Unix fcntl.h includes the NT 
fcntl.h in the following manner:
#include “m:\include\fcntl.h”
Here m: is the drive and path leading to include\fcntl.h. For example, 
m: can refer to:
c:\Program Files\DevStudio\Vc
You MUST properly set m: with the subst command at the DOS prompt to 
avoid getting errors during compilation. For example:
subst m: c:\Program Files\DevStudio\Vc
The following paths to the ASAI and Unix header files under Windows NT must be 
included in your development environment:
\include\unix
\asai\include
By default  is set as:
C:\Program Files\Lucent Technologies\Cvlan 
						

							CV/LAN Programming
Issue  3  May 1998
6-3
Future Upgrade Considerations 
Motivation for New CV/LAN Server
In this release, the interface to CV/LAN was changed to increase the likelihood 
that your application will continue to run with new releases of the ECS to work in a 
multi-threaded environment, and to improve the throughput by a factor of 2 to 10.
Previously, the applications did not work. From this release forward, the following 
rules will apply:
1. If you have new client, new ECS with an old server then all the new fields in 
the existing messages will be sent to the client. But if the client attempts to 
use the new messages then an error is returned as the old server is not 
programmed to receive these new information fields.
2. If you have an older client with new ECS and a new server, then the new 
fields in the existing messages will not be received by the client since the 
client is not programmed to receive these new information fields.
The CV/LAN speeds up the ASAI applications development cycle by eliminating 
the need to develop client-server connectivity software. The CV/LAN provides a 
simple client Application Program Interface (API) that facilitates the CV/LAN 
application development.
The CV/LAN server will be installed on a UNIX CallVisor PC and will use the ASAI 
library to interface with the CallVisor stack. Once the system reboots, the CV/LAN 
server will be started.The server will wait in listen mode for the next client 
connection. For each client connection it will generate a child server process. 
The CV/LAN client API is described below.
 Client API  
The CV/LAN library functions provide the application program an easy method of 
sending and receiving information (in the form of ASAI capabilities) to and from 
the ECS. Before you can send and receive information, however, you must 
establish a communication path to the CV/LAN server asaiserv. This is done by 
calling asai_open with an IP address or machine name instead of 
“/dev/asai/asai” or a similar address. 
The CV/LAN client API provides the following library functions:
          asai_open()
          asai_close()
          asai_set_env()
          asai_get_env()
          asai_send() 
						

							CV/LAN Programming
6-4Issue  3  May 1998 
          asai_rcv()
          asai_errval()
These are the same routines that are available to all the ASAI applications on the 
server.
The above table describes each function and shows how it works. The functions 
are presented in a logical, rather than in an alphabetical, order. Thus,
asai_open() comes first and asai_close() comes last as indicated in the 
above table.
It is possible to process messages from more than one node as long as all the 
nodes are on the same server.
Table 6-1. Client API Library Functions
FunctionPurpose
asai_openOpen communication path
asai_errvalWrite error message if function call fails
asai_set_envEstablish communication path by setting node 
ID; set server
asai_get_envCheck library version (optional) or server 
settings
asai_sendSend a capability
asai_rcvReceive a capability
asai_closeClose the communication path (optional) 
						

							CV/LAN Programming
Issue  3  May 1998
6-5
asai_open
Description
The asai_open() is the first library function that your application calls. This 
function opens a communication path (socket) to the CV/LAN server.
Prototype
int asai_open ( const char *path, int flags )
Arguments
Path represents a pointer to the hostname or IP address of the machine running 
the CV/LAN server. flags may be set to 0 or O_NDELAY.
Return Value
On successful completion, the message Socket file descriptor is 
displayed. If an error occurs, the function returns -1.
Example:
open_routine()
{
int fd;
if (( fd = asai_open(“135.20.70.72“, O_NDELAY)) 
 0 )
          {
exit(-asai_errno); 
}
.
.
.
}
For further information see ‘‘asai_open( )’’ on page 4-3, in Chapter 4 and 
‘‘asai_open (3ASAI)’’ on page 9-10, in Chapter 9, ‘‘Programming Manual Pages.’’ 
						

							CV/LAN Programming
6-6Issue  3  May 1998 
asai_errval
The asai_errval is the standard ASAI library function. See ‘‘asai_errval ( )’’ on 
page 4-4 in Chapter 4, and ‘‘asai_errval (3ASAI)’’ on page 9-6 in Chapter 9, 
‘‘Programming Manual Pages.’’  For error messages, see Chapter 7, ‘‘Error 
Messages.’’
asai_set_env()
The asai_set_env function is also a standard ASAI library function. See
‘‘asai_set_env( )’’ on page 4-6, in Chapter 4 and ‘‘asai_set_env (3ASAI)’’ on page 
9-18 in Chapter 9, ‘‘Programming Manual Pages.’’ However, the node id(s) refer 
to the node id(s) on the server.
NOTE:
asai_set_env should not be used after asai_rcv has been called. 
						

							CV/LAN Programming
Issue  3  May 1998
6-7
asai_get_env()
Description 
The asai_get_env() function allows you to check the version of the ASAI 
library.
C_LIB_VER
The version number of the ASAI library includes three values: major, minor, and 
delta. A change to a major value indicates significant functional changes to the 
ASAI library, for example, addition of new capabilities. A change to a minor value 
indicates changes made to existing capabilities. A delta change indicates a 
correction with no change in parameters or functionality. The parameters
major_ver, minor_ver, and delta_ver represent these values respectively.
C_NUM_NODE
The C_NUM_NODE parameter requests the number of servers that have been 
assigned by the most recent call to the asai_set_env() function.
arg -> num_node is returned.
C_NODE_ID
The C_NODE_ID parameter requests the node identifier(s) for a server.
C_SERVER
The C_SERVER parameter requests information on the number and type of 
servers previously set by calls to asai_set_env(). Data of structure type 
server_type_t, is returned. If no service requests have been set, then 
num_server is returned as 0.
Prototype
long asai_get_env (int socketfd, long attr, get_type * value)
Argument
The first argument is the socket file descriptor returned by an asai_open() call. 
The second argument attr gets the environment attribute. The third argument 
points to the new value of the attribute.
Return Value
The function returns 0 on successful completion and it returns -1 on failure. 
						

							CV/LAN Programming
6-8Issue  3  May 1998 
Example
if ( asai_get_env( socketfd, attr, &envbuf) < 0 )                
 {                         
asai_errval(asai_get_env failed);                         
exit(-asai_errno);                
 }                
 . 
 . 
                    .
For further information see ‘‘asai_get_env( )’’ on page 4-9 in Chapter 4 and 
‘‘asai_get_env (3ASAI)’’ on page 9-7 in Chapter 9, ‘‘Programming Manual 
Pages.’’
asai_send()
Description
asai_send() and asai_rcv() together are the central functions in the library. 
These two functions send all ASAI capabilities and data across an association.
Prototype
long asai_send (int socketfd, asai_info_t * buf, long length)
Arguments
The first argument is the file descriptor of the socket connection to the CV/LAN 
server. The second argument is the capability buffer to be sent. The third 
argument is the size of the buffer being sent.
Return Value
Upon successful completion, the function returns a nonnegative value. If an error 
occurs, the function returns -1.
Example
if (asai_send (socketfd, (char *)(&a3predir), 
sizeof(&a3predir_info_t) < 0)               
{                       
     asai_errval(3rd party redirect alerting call   
request); 
     exit(-asai_errno);   
}         
.            
.