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

							ASAI Capability Primitives
Issue  3  May 1998
8-15
NOTE:
Whenever the server returns cause_value with an unrecognized value, 
the value is mapped to C_PROTERR. If the server does not return a value, 
then cause_value is mapped to C_NUSE_LONG.
Future releases of the ASAI library may include new cause_values. The 
application can be programmed for upward compatibility by providing for 
unexpected cause_values in the code.
Pool
The pool parameter, used with a number of capabilities, identifies a buffer area for 
storing user information. The various call_identifier values returned by these 
capabilities (call_id, party_id) are pointers to the pool buffer.
1 The pool 
buffer (pool [C_DATSZ]) contains various call-identifier numbers in the form of 
null-terminated strings.
1. The programmer must do more than simply copy these identifiers to guarantee that the space to 
which they point, will exist in the future. 
						

							ASAI Capability Primitives
8-16Issue  3  May 1998  
						

							Issue  3  May 19989-1
9
Programming Manual Pages
ASAI Library Manual Pages
Access to ASAI services is provided through a collection of functions known as 
the ASAI library. A single library can:
nAccess multiple ports (IPCI boards) or LAN Gateway links
nCommunicate with one or more switches
nManage communications for multiple ASAI links and ports 
These capabilities are provided by specifying a different node_id argument to 
the asai_set_env function for each newly opened file descriptor on which the 
programmers would like to start new associations. Up to 8 node_ids are 
supported; signal01 through signal08 correspond to links 1 through 8, 
respectively.
A program can request client services (that is, create a new association) from only 
one c_node_id per file descriptor. To obtain services from four switches, the 
program must obtain four file descriptors by opening the library four times. 
Different c_node_ids must then be specified to the set_env function for each 
file descriptor.
ASAI functions are not reentrant but they are threadsafe. Because of this, 
interrupt handlers that are invoked when an application is interrupted during a 
function call should not themselves invoke another library function. Application 
programmers must set interrupt levels with this restriction in mind.
The library is identified by its version number. Various releases of the library are 
distinguished using 
major, minor and delta version numbers. 
						

							Programming Manual Pages
9-2Issue  3  May 1998 
A major release is defined by a technological level or major change in operation 
from a previous release. A minor release is an enhancement or refinement to an 
existing major release. A delta release is a small enhancement or bug fix, 
differently tuned, or specific to a hardware platform.
Applications Development 
Environment for CV/LAN
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.
The required UNIX header files will be placed under 
\include\unix.
Windows NT Platform
In Windows NT, a MS Visual C 5.0 environment must be set as follows: 
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. 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” 
						

							Programming Manual Pages
Issue  3  May 1998
9-3
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
ASAI Library Functions
ASAI library functions do the following:
nManage communications paths
—asai_open
—asai_close
—asai_set_env
—asai_get_env
nManage associations over an established communications path
—asai_rcv
—asai_send
nAssist in debugging 
—asai_errval
On the following pages, each library function is described by some or all of the 
following sections:
Name
This section names and succinctly describes the function. 
						

							Programming Manual Pages
9-4Issue  3  May 1998 
Synopsis
This section illustrates the declaration of the function, including necessary header 
files.
Description
This section describes the function, including its parameters.
Return Value
This section gives the return values of the function on success and failure.
Errors
This section lists error values and describes the errors that are set in 
asai_errno. asai_errno is defined as follows:
long asai_errno;
Notes
This section is used to describe any exceptions, caveats, or usage suggestions 
pertaining to the function.
See Also
This section lists related functions and ASAI capabilities, where appropriate. 
						

							Programming Manual Pages
Issue  3  May 1998
9-5
asai_close (3ASAI)
Name
asai_close — Close the communication path
Synopsis
#include  
#include  
#include  
long  asai_close(fd)
int  fd;
Description
This function closes the communication path identified by fd. All activity 
associated with the specified fd is terminated.
Return Value
Upon successful completion, the function returns 0. If an error occurs, the function 
returns -1.
Errors
The type of error is indicated by the error value set in asai_errno:
C_BADFD — Invalid file descriptor supplied.
C_SYSER — ASAI service error, cannot close the Streams device. Check errno.
See Also
asai_open() 
						

							Programming Manual Pages
9-6Issue  3  May 1998 
asai_errval (3ASAI)
Name
asai_errval — Write specified error message to stderr
Synopsis
#include  
#include  
#include  
long  asai_errval(mes_buf)
char  mes_buf[C_MESIZE];
Description
This function allows the client to incorporate a specified error message with a 
message provided by the ASAI library. The programmer specifies the message in 
the null-terminated string mes_buf of maximum size C_MESIZE. The 
ASAI-supplied message maps to the value asai_errno. The entire message is 
written to the standard error device, the program-supplied message first, then a 
colon (:) and then the ASAI message.
Return Value
Upon successful completion, the function returns 0. If an error occurs, the function 
returns -1.
Errors
The type of error is indicated by the error value set in asai_errno:
C_SYSER — ASAI service error. It indicates that stderr cannot be written; check 
errno.
NOTE:
This function is not available on Windows/NT. 
						

							Programming Manual Pages
Issue  3  May 1998
9-7
asai_get_env (3ASAI)
Name
asai_get_env — Request information about a specified characteristic of a 
communication path
Synopsis
#include  
#include  
#include  
typedef union{
        version_t      version;
        ulong          num_node;
        server_type_t  server;
        char           node_id[C_NODSIZ];
}get_type;
long  asai_get_env(fd, characteristic, arg)
int  fd;
long  characteristic;
get_type  *arg;
Description
This function is used to obtain a specified characteristic of the communication 
path associated with fd. The parameter characteristic can assume any of 
the following values:
C_LIB_VER
The C_LIB_VER parameter requests the version of the ASAI library. Data of the 
structure type version_t (shown above) is returned, pointed to by the third 
argument.
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. 
						

							Programming Manual Pages
9-8Issue  3  May 1998 
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, defined below, is returned. If no service requests have been 
set, then num_server is returned as 0.
typedef struct{
        long            num_node;
        service_spec_t  *buf;
}server_type_t;
Within this structure, num_node indicates the number of structures of the type 
service_spec_t, defined below, that can be contained in the buffer pointed to 
by buf.
typedef struct{
        long  server_type;
        char  node_id[C_NODSIZ];
}service_spec_t;
Upon return, the ASAI library indicates the number of structures actually supplied 
in buf, but no more than the number requested by the user. Within the
service_spec_t structure, server_type indicates the service requests that 
will be accepted and node_id indicates the node from which the service requests 
are accepted. Valid server types that can be put together with the option of 
selecting either one are:
C_RT_SER — Routing
C_MAINT_SER — Maintenance
Return Value
Upon successful completion, the function returns 0. If an error occurs, the function 
returns -1.
Errors
The type of error is indicated by the error value set in asai_errno:
C_BADFD — Invalid file descriptor supplied
C_BADCHAR — Unknown or improper context for a characteristic