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

							Introduction to ASAI
Issue  3  May 1998
3-13
The programmer is not restricted to a specific number of capabilities that can be 
supported on a given communication path; however, he or she is restricted to a 
single node for all capabilities on a given path.
C_RT_ENDx
C_RT_REQx
C_RT_SELx
C_SV_CONFx
C_SV_REQx
C_VQ_CONFx
C_VQ_REQx
C_VQ_RESPx
Table 3-6. Classification of ASAI Capabilities  — Continued
Acknowledged Unacknowledged
Init. Cont. Term. Init. Cont. Term. 
						

							Introduction to ASAI
3-14Issue  3  May 1998  
						

							Issue  3  May 19984-1
4
ASAI Library Functions
The ASAI library functions provide the application program with an easy method 
of sending and receiving information (in the form of ASAI capabilities) to and from 
the ECS. Before you can send or receive information, however, you must 
establish a communication path. This is a two-step procedure, requiring you to 
first open a path, using asai_open(), and then to identify the ECS link over 
which your program will communicate. The ECS is identified by a node identifier, 
set with asai_set_env().
asai_set_env() identifies applications as being clients and/ or servers. A client 
application initiates a request for service and a server application responds to a 
request for service.
The ASAI library does not allow an application to assume an inappropriate role.  
For those capabilities for which it is registered as a client, an application can only 
send messages defined for clients. It cannot send server-type messages.  
Conversely, when an application is registered as a server, it can only send 
messages defined for servers. It cannot send client-type messages.
This chapter describes each function briefly and shows how it works. The final 
section of this chapter is a sample program. The functions are presented in 
logical, rather than alphabetical order; thus, asai_open() comes first and 
asai_close() comes last, as indicated in Table 4-1. 
						

							ASAI Library Functions
4-2Issue  3  May 1998 
It is possible to process more than one ASE on a communication path; however, 
each communication path can be used to service only a single node. Thus, if an 
application wishes to use a communication path to send service requests, all the 
requests must be made to the same destination node as that of the initiating 
capability. If an application wishes to use a communication path to receive 
capabilities, requests must come via the port used to receive the initiating 
capability.
In general, the ASAI library functions are not reentrant; therefore, you should 
avoid using them in signal handlers, or use sig_hold() for the pertinent signals 
before calling any ASAI function.
All seven of the library functions are declared as long. To prevent unnecessary 
messages from lint, you may want to use 0L to test for successful completion 
rather than just 0. In some cases, you may also need to use a cast to convert 
expressions to type long. There are examples of casting in some of the code 
fragments later in this chapter.
Detailed information on each function can be found in the manual pages in 
Chapter 9, ‘‘Programming Manual Pages.’’
Table 4-1. ASAI Library Functions: A Typical Application
Function Purpose
asai_openOpen communication path
asai_errvalWrite error message if function call fails
asai_set_envBind communication path to a node ID or set server for 
more links
asai_get_envCheck library version (optional)
asai_sendSend a capability
asai_rcvReceive a capability
asai_closeClose the communication path (optional) 
						

							ASAI Library Functions
Issue  3  May 1998
4-3
asai_open( )
The asai_open() function is the first of the library functions that your program 
calls. This function opens a communication path (stream) and returns file 
descriptor fd if the call is successful; the function returns -1 if the call fails.
asai_open() requires two arguments; pathname and ndelay_flag. The 
pathname is /dev/asai/asai or a machine name for CV/LAN.
The ndelay_flag determines whether you will be operating in synchronous 
mode with blocking and no delay, or asynchronous mode with delay and no 
blocking. For synchronous mode, set ndelay_flag to 0. For asynchronous 
mode, set ndelay_flag to O_NDELAY.
Code Example 4-1 below is a typical open routine.
 
Figure 4-1. Opening a Communication Path
Note that the routine above calls asai_errval() if the value returned is less 
than 0.
See the sample code called asai_open() on line 52 in Figure 4-9 on page 4-15.
open_routine()
{
    int fd;
    if ((fd = asai_open(
pathname,0)) < 0
    {
asai_errval(
error message);
exit(-asai_errno);
    }
    .
    .
    .
} 
						

							ASAI Library Functions
4-4Issue  3  May 1998 
asai_errval ( )
When an error occurs, an error value is made available in the variable 
asai_errno of data type long. Once asai_errno is set, its value is not reset 
by successful function calls. If an error is returned by an ASAI library function, 
there is state transition, either for the communication path or for the instance of 
communication. asai_errval() lets you specify an error message that is 
written to the standard error device along with the system-supplied ASAI error 
message.
The asai_errval() function should be used after every failed function call in 
your program.
Your error message is specified in a null-terminated string, mes_buf, of maximum 
size C_MESIZE (the length set for C_MESIZE in the samp.hdrs file supplied 
with the system is 80 characters).
You can specify a message directly, as in the code example in Figure 4-2, or you 
can specify it indirectly, as in the code example in Figure 4-3 on page 4-5.
.
Figure 4-2. Using asai_errval (), Example 1
NOTE:
The variable, asai_errno, can no longer be defined with extern. It must 
be included using .
.
.
.
if (fd < 0)
{
asai_errval(asai_open(/dev/asai/asai) failed:);
exit(i);
}
.
.
. 
						

							ASAI Library Functions
Issue  3  May 1998
4-5
Figure 4-3. Using asai_errval (), Example 2
Note that the colon (:) included as part of the message in Figure 4-2 on page 4-4 
is not necessary. The message written to standard error consists of your specified 
message, a colon, and then the ASAI message. For a full listing of the ASAI error 
messages, see Chapter 7, ‘‘Error Messages.’’
asai_errval returns 0 on success and -1 on failure. The sample code at the 
end of this chapter uses a conditional call to asai_errval() after every function 
call (lines 54, 59, 69, 77, 105, 149 and 154). If the previous function call fails, 
asai_errval() is called.
 
    .
    .
    char pathname[];
    char buf[C_MESIZE];
    char *p;
    if ( asai_
function(args) < 0 )
    {
ASAI function failed

asai_errval “ASAI function failed”;
    }
    .
    . 
						

							ASAI Library Functions
4-6Issue  3  May 1998 
asai_set_env( )
After opening a communication path, the next step is to establish an environment 
that will support your program. The asai_set_env() function enables you to set 
one characteristic at a time. You 
must set the node identifier using the 
C_NODE_ID characteristic, if you are going to establish new association.
asai_set_env() has two mandatory and one optional arguments. The file 
descriptor and the characteristic to be set are mandatory. Depending on the 
characteristic you are setting, you also may have to specify a value. 
The characteristic C_NODE_ID establishes the name of the node from which your 
application will initiate service request. This must be done first. If an application 
needs services from more than one node, it must open the library once for each 
node it needs services from. This means that multiple file descriptors must be 
managed.
You must use the characteristic C_SERVER to specify the name(s) of the node(s) 
for which your application will provide services; that is, it will respond to the ECS 
initiated requests. If your application does not handle the ECS requests, you do 
not need to do this. Note that each node will allow only one server for each kind of 
service.
If your application does not handle the ECS requests, it can provide service to one 
or more nodes for each file descriptor.
The code example in Figure 4-4 on page 4-6 uses the C_NODE_ID characteristic 
to supply the node identifier. Note that the alternative compares the return value 
from asai_set_env() to a long 0. 
Figure 4-4. Setting the Library Environment:  Node ID
if (asai_set_env(fd,C_NODE_ID,node_id) < 0 )
{
    asai_errval (asai_set_env (C_NODE_ID) failed);
    exit (-asai_errno);
}
    /*  an alternative  */
if (asai_set_env(fd,C_NODE_ID,argv[1]) < 0L) 
						

							ASAI Library Functions
Issue  3  May 1998
4-7
You may also need to specify that the application is to function as a server for an 
ECS routing and maintenance requests. A single application can function as a 
server for more than one node on a single file descriptor. (A node can be equated 
to a link or port on an ASAI connection.) Note that each node will allow only one 
server for each kind of service. To do this, set the num_node field of the 
server_type_t structure to the number of nodes the application is to serve. Set 
the *buf field to point to an array of structures of the same length. Set the name 
of the node for example, signal01, in the node_id field or set all the names 
together of the server types desired in the server_type field.
The code example in Figure 4-5 illustrates the use of asai_set_env() to set the 
server type. Note that each call to asai_set_env overwrites the previous 
setting on a per-characteristic basis.
Figure 4-5. Setting the Environment: Establishing a Server
When you are specifying servers, be sure to include maintenance 
(C_MAINT_SER) in the list or invoke the heartbeat OA&M process prior to running 
your application. If you do not, your program will be unable to respond when the 
ECS sends a heartbeat. If this happens, the ECS tears down the link.
 .
 .
 .
 setarg.numnode = 4;
 setarg.buf = srvrs;
 strcpy (srvrs[0].nodeid, “signal01”);
srvrs[0].server_type = C_RT_SER | C_MAINT_SER;
 .
 .
 .
 if (asai_set_env (fd, C_SERVER, &setarg) < 0)
 {
asai_errval (asai_set_env (C_SERVER) failed:);
return asai_errno;
 }
 .
 .
 . 
						

							ASAI Library Functions
4-8Issue  3  May 1998 
You should also include the routing (C_RT_SER) server in order to receive route 
requests.
The sample code at the end of this chapter calls asai_set_env () on line 57, in 
Figure 4-9.
NOTE:
Be aware that each call to asai_set_env overwrites the previous value(s) 
on a per-characteristic basis.