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

							Programming Manual Pages
Issue  3  May 1998
9-9
Notes
The library returns information only on the number of nodes you specify. If you 
specify fewer than the actual number of nodes, information is returned on the 
nodes set in the first calls to asai_set_env. It is recommended that you specify 
num_node as 30 or to any configurable parameter. For example:
# define MAXNUMSERV 30
server_type_t    server = {maxnumserv, services};
service_spec_t   services[MAXNUMSERV];
See Also
asai_open() asai_rcv() asai_send() asai_set_env() 
						

							Programming Manual Pages
9-10Issue  3  May 1998 
asai_open (3ASAI)
Name
asai_open — Open a communication path
Synopsis
# include 
#include  
#include  
#include  
long  asai_open(pathname, ndelay_flag)
char  *pathname;
long  ndelay_flag;
Description
This function opens a communication path identified by pathname, a 
null-terminated character string; the default path is /dev/asai/asai. If the 
ndelay_flag is set to O_NDELAY, the operation is asynchronous and the send 
or receive request does not block. If the ndelay_flag is set to !_NDELAY, the 
operation is synchronous and the send or receive request blocks. In the 
synchronous mode, control is not returned to the user until the send or receive 
request has been completed or an error occurs.
Return Value
Upon successful completion, the function returns the integer value of fd. If an 
error occurs, the function returns -1. The file descriptor can be used by 
subsequent calls to ASAI library functions.
Errors
The type of error is indicated by the error value set in asai_errno:
C_BADFD — Invalid file descriptor supplied
C_BADFLAG — An invalid value was given for the asai_open() flag
C_NOENT — No such file or directory
C_OSER — A system call failed, check errno 
						

							Programming Manual Pages
Issue  3  May 1998
9-11
C_INVALID_CLIENT — This error is returned only by MAPD, when a client 
cannot be validated, that is, its IP address is not administered on the MAPD.
C_LINKDOWN — This error is returned by MAPD to notify the application that the 
ASAI has been taken out of service by the administrator.
See Also
asai_close() asai_rcv() asai_send() 
						

							Programming Manual Pages
9-12Issue  3  May 1998 
asai_rcv (3ASAI)
Name
asai_rcv — Receive message via the communication path
Synopsis
#include  
#include  
#include  
typedef union{
        asai_common_t      asai_common;
        abort_info_t       abort_info;
        vq_buf_t           vq_buf;
        vqr_buf_t          vqr_buf;
        vqc_buf_t          vqc_buf;
        en_buf_t           en_buf;
        en_rsp_t           en_rsp;
        evr_buf_t          evr_buf;
        enc_rsp_t          enc_rsp;
        ene_info_t         ene_info;
        a3pmc_info_t       a3pmc_info;
        a3pmc_ack_t        a3pmc_ack;
        a3pmc_nak_t        a3pmc_nak;
        a3pmc_rsp_t        a3pmc_rsp;
        a3ptc_info_t       a3ptc_info;
        a3ptc_ack_t        a3ptc_ack;
        a3ptc_nak_t        a3ptc_nak;
        a3psh_info_t       a3psh_info;
        a3psh_rsp_t        a3psh_rsp;
        a3psd_info_t       a3psd_info;
        a3psd_rsp_t        a3psd_rsp;
        a3psl_disc_t       a3psl_disc;
        a3psl_disc_ack_t   a3psl_disc_ack;
        a3psl_rconn_t      a3psl_reconn;
        a3psl_reconn_ack_t a3psl_reconn_ack;
        a3pr_info_t        a3pr_info;
        a3pr_rsp_t         a3pr_rsp;
        a3prc_rsp_t        a3prc_rsp;
        a3pm_info_t        a3pm_info;
        a3pm_ack_t         a3pm_ack;
        a3pm_nak_t         a3pm_nak;
        a3pcc_rsp_t        a3pcc_rsp;
        a3pce_info_t       a3pce_info;
        a3pad_info_t       a3pad_info;
        a3pad_ack_t        a3pad_ack;
        a3pad_nak_t        a3pad_nak; 
						

							Programming Manual Pages
Issue  3  May 1998
9-13
        a3pans_info_t      a3pans_info;
        a3pans_nak_t       a3pans_nak;
        a3pdc_info_t       a3pdc_info;
        a3pdc_ack_t        a3pdc_ack;
        a3pdc_nak_t        a3pdc_nak;
        a3pdce_info_t      a3pdce_info;
        a3pssc_info_t      a3pssc_info;
        a3pssc_ack_t       a3pssc_ack;
        a3pssc_nak_t       a3pssc_nak;
        en_scn_t           en_scn;
        en_scn_nak_t       en_scn_nak;
        sv_buf_t           sv_buf;
        sv_rsp_t           sv_rsp;
        rf_buf_t           rf_buf;
        rf_rsp_t           rf_rsp;
        rt_info_t          rt_info;
        rts_info_t         rts_info;
        rte_info_t         rte_info;
        rt_nak_t           rt_nak;
        hb_nak_t           hb_nak;
        hb_rsp_t           hb_rsp;
        en_scn_rsp_t       en_scn_rsp;
        a3psds_info_t      a3psds_info;
        a3psds_rsp_t       a3psds_rsp;
        a3predir_info_t    a3predir_info;
        a3predir_nak_t     a3predir_nak;
        a3predir_ack_t     a3predir_ack;
}asai_info_t;
   long  asai_rcv(fd, buf, length)
   int   fd;
   char  *buf;
   long  length;
Description
This function is used to read a message (that is, a packet containing primitives, 
capabilities and/or program-specific information) from the communication path 
identified by file descriptor fd. The program passes a pointer to the buffer, buf, of 
size length, to the ASAI library. The ASAI library then returns the message into 
the program-specified buffer.
The maximum useful size of the user buffer is sizeof (asai_info_t).
In the event that a received message will not fit in the buffer supplied by the 
programmer, the ASAI library returns a -1 (error) and sets asai_errno to -14 
(C_BADLNG). The message is saved for the next call. 
						

							Programming Manual Pages
9-14Issue  3  May 1998 
NOTE:
If a program ignores this error and simply calls the library again, an infinite 
loop is created. Because of this, all application programs must check for the 
presence of a C_BADLNG error and provide a larger buffer if it occurs.
If the function is used in a synchronous mode of operation, asai_rcv() blocks 
until an entire message has been received, until an error occurs, or until fd is 
closed by an interrupt function. If the function is used in an asynchronous mode of 
operation, asai_rcv() does not block.
The library can assume the role of the server (that is, a program that responds to 
the ECS initiated associations) only for the route and maintenance (heartbeat) 
services. For all other services it must assume a client role. asai_rcv() will 
never return an inappropriate message for the current role(s).
Return Value
Upon successful completion, the function returns the size of the message. If an 
error occurs, the function returns -1. A return code of 0 does not indicate an error; 
the received message was intended for the library and no program data is 
available at this time.
Errors
The type of error is indicated by the error value set in asai_errno:
C_BADFD — Invalid file descriptor supplied
C_BADFLOW — Cannot issue the request because of flow control
C_SYSER — ASAI service error received a message on an unknown 
association. This message will be returned only if sao_id (formerly known as 
cluster_id) in a route request is already in use.
C_BADLNG — The send or receive buffer is too small for the capability
C_BADMSG — A corrupt message was received on the given stream
C_INTR — A system call was interrupted by a signal
C_OSER — A system call failed, check errno
See Also
asai_open()  asai_send()  asai_set_env()
NOTE:
The buf argument may be filled with zeroes even if the function call fails. 
						

							Programming Manual Pages
Issue  3  May 1998
9-15
asai_send (3ASAI)
Name
asai_send — Send message via the communication path
Synopsis
#include  
#include  
#include  
typedef union{
        asai_common_t      asai_common;
        abort_info_t       abort_info;
        vq_buf_t           vq_buf;
        vqr_buf_t          vqr_buf;
        vqc_buf_t          vqc_buf;
        en_buf_t           en_buf;
        en_rsp_t           en_rsp;
        evr_buf_t          evr_buf;
        enc_rsp_t          enc_rsp;
        ene_info_t         ene_info;
        a3pmc_info_t       a3pmc_info;
        a3pmc_ack_t        a3pmc_ack;
        a3pmc_nak_t        a3pmc_nak;
        a3pmc_rsp_t        a3pmc_rsp;
        a3ptc_info_t       a3ptc_info;
        a3ptc_ack_t        a3ptc_ack;
        a3ptc_nak_t        a3ptc_nak;
        a3psh_info_t       a3psh_info;
        a3psh_rsp_t        a3psh_rsp;
        a3psd_info_t       a3psd_info;
        a3psd_rsp_t        a3psd_rsp;
        a3psl_disc_t       a3psl_disc;
        a3psl_disc_ack_t   a3psl_disc_ack;
        a3psl_rconn_t      a3psl_reconn;
        a3psl_reconn_ack_t a3psl_reconn_ack;
        a3pr_info_t        a3pr_info;
        a3pr_rsp_t         a3pr_rsp;
        a3prc_rsp_t        a3prc_rsp;
        a3pm_info_t        a3pm_info;
        a3pm_ack_t         a3pm_ack;
        a3pm_nak_t         a3pm_nak;
        a3pcc_rsp_t        a3pcc_rsp;
        a3pce_info_t       a3pce_info;
        a3pad_info_t       a3pad_info;
        a3pad_ack_t        a3pad_ack;
        a3pad_nak_t        a3pad_nak; 
						

							Programming Manual Pages
9-16Issue  3  May 1998 
        a3pans_info_t      a3pans_info;
        a3pans_nak_t       a3pans_nak;
        a3pdc_info_t       a3pdc_info;
        a3pdc_ack_t        a3pdc_ack;
        a3pdc_nak_t        a3pdc_nak;
        a3pdce_info_t      a3pdce_info;
        a3pssc_info_t      a3pssc_info;
        a3pssc_ack_t       a3pssc_ack;
        a3pssc_nak_t       a3pssc_nak;
        en_scn_t           en_scn;
        en_scn_nak_t       en_scn_nak;
        sv_buf_t           sv_buf;
        sv_rsp_t           sv_rsp;
        rf_buf_t           rf_buf;
        rf_rsp_t           rf_rsp;
        rt_info_t          rt_info;
        rts_info_t         rts_info;
        rte_info_t         rte_info;
        rt_nak_t           rt_nak;
        hb_nak_t           hb_nak;
        hb_rsp_t           hb_rsp;
        en_scn_rsp_t       en_scn_rsp;
        a3psds_info_t      a3psds_info;
        a3psds_rsp_t       a3psds_rsp;
        a3predir_info_t    a3predir_info;
        a3predir_nak_t     a3predir_nak;
        a3predir_ack_t     a3predir_ack;
}asai_info_t;
     
   long  asai_send(fd, buf, length)
   int   fd;
   char  *buf;
   long  length;
Description
This function formats and sends an ASAI message to the ECS through the stream 
file descriptor fd. The information used to construct this message is contained in 
a buffer pointed to by buf of size length.
The maximum useful size of the user buffer is size of(asai_info_t). 
If the function is used in a synchronous mode of operation, asai_send() blocks 
until an entire message has been queued for transmission, or an error occurs. If 
the function is used in an asynchronous mode of operation, asai_send() does 
not block and returns an error.
The library can assume the role of server only for the route and maintenance 
(heartbeat) services. For all other services it must assume a client role. Any  
						

							Programming Manual Pages
Issue  3  May 1998
9-17
attempt to send a message in an inappropriate role will be rejected. 
Notice that an application can be simultaneously both a client and a server. 
See the ‘‘asai_set_env( )’’ on page 4-6 in Chapter 4, ‘‘ASAI Library Functions’’ for 
further information.
Return Value
Upon successful completion, the function returns a nonnegative value. 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_BADFLOW — Cannot issue the request because of flow control
C_CLUSTID — The cluster identifier is invalid for the given stream
C_BADLNG — The send or receive buffer is too small for the capability
C_BADMSG — A corrupt message was received on the given stream
C_INTR — A system call was interrupted by a signal
C_OSER — A system call failed
C_UNCAP — Cannot send an unknown capability
C_TOOBIG — The field is too big
See Also
asai_open()  asai_rcv()  asai_set_env() 
						

							Programming Manual Pages
9-18Issue  3  May 1998 
asai_set_env (3ASAI)
Name
asai_set_env — Set a specified characteristic for a communication path
Synopsis
#include  
#include  
#include  
typedef union{
        server_type_t  server;
        char  node_id[C_NODSIZ];
}set_type;
long  asai_set_env(fd, characteristic, arg)
int  fd;
long  characteristic;
set_type  *arg;
Description
This function is used to set a specified characteristic of the communication path 
associated with fd. The parameter characteristic can assume any of the 
following values:
C_NODE_ID
The C_NODE_ID parameter must be used before any initiating capability is sent.  
Its purpose is to assign the destination node (ECS) for all new associations on the 
communication path. If any association is active on the communication path, the 
function fails.
The arg parameter points to a null-terminated string, specifying the node 
identifier. A node identifier is the name of the IPCI board or LAN Gateway link 
connected to ECS with which you wish to communicate. These are typically 
“signal01,” “signal02,” “signal03,” or “signal04.” The use of arg as a null pointer 
clears a destination. Only one destination can be set for a communication path at 
a time.
C_SERVER
The C_SERVER parameter sets the type of service requests to be accepted for a 
specified capability group from the specified node.
When you use this characteristic, previously registered servers are superseded by 
the new values.