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

							CV/LAN Programming
Issue  3  May 1998
6-9
 For further information see‘‘asai_send( )’’ on page 4-10 in Chapter 4 and 
‘‘asai_send (3ASAI)’’ on page 9-15 in Chapter 9, ‘‘Programming Manual Pages.’’
asai_rcv() 
 Description 
asai_rcv() allows the user to receive indication primitives. Indications may take 
either the form of requests, or positive, or negative acknowledgments.
Prototype
long asai_rcv (int socketfd, asai_info_t * buf, long length)  
Arguments
The first argument is the descriptor that identifies the communication path. The 
second argument is the information buffer to receive the ASAI message. The 
third argument is the maximum size of the information buffer that may receive the 
ASAI message.
Return Value
asai_rcv() returns the size of the information buffer that must be a value 
greater than 0 on success and -1 on failure. asai_errno is set to indicate the 
reason for failure. 
Example
 if (asai_rcv(socketfd,(char *)&rt_info,sizeof
      (rt_info_t)) < 0)
 { 
asai_errval(“2-minute timer indicates a   
Heartbeat was not issued” ); 
 exit(-asai_errno);
 }
 . 
 . 
 .
For further information see ‘‘asai_rcv( )’’ on page 4-12 in Chapter 4 and 
‘‘asai_rcv (3ASAI)’’ on page 9-12 in Chapter 9, ‘‘Programming Manual Pages.’’ 
						

							CV/LAN Programming
6-10Issue  3  May 1998 
asai_close() 
Description
Close a socket to the CV/LAN Server.
Prototype
long asai_close(int socketfd)
Argument
File descriptor of the socket connection to the CV/LAN server.
Return Value
If the socket was closed successfully, the return value is 0 but if there is an error it 
is -1.
Example
close_routine()
{
  extern int fd; 
if (asai_close(fd) < 0)
{ 
asai_errval(“error closing communication   
path”);
}
return; 
}
.
.
.
For further information see ‘‘asai_close( )’’ on page 4-13 and 
‘‘asai_close (3ASAI)’’ on page 9-5 in Chapter 9, ‘‘Programming Manual Pages.’’
NOTE:
An error may occur if an asai_rcv is blocked in another thread. 
						

							Issue  3  May 19987-1
7
Error Messages
Library Error Messages
Library error messages are listed alphabetically below with a brief explanation of 
the probable cause of each error. The header file in which these library error 
messages are found is asai_err.h. 
 C_NOENTNo such file or directory. This value is set when the file 
passed to asai_open() does not exist. This will also 
be returned by CV/LAN, when the machine name 
cannot be found.
 C_BADCHARUnknown or improper context for a characteristic. This 
value is set when an invalid characteristic is passed to 
either asai_set_env() or asai_get_env().
 C_BADCHARVALCharacteristic’s value is invalid. This value is set when 
asai_set_env() is passed an invalid number of 
servers, or a bad type of server.
 C_BADCLUSTIDThe Cluster_ID (also known as sao_id) is invalid for 
the given stream. This value is set when asai_send() 
is passed an initiating request with an ID that matches 
an existing SAO, or when it passes a noninitiating 
request with an ID that matches no existing SAO.
 C_BADFDFile descriptor was not returned by asai_open(). This 
value is set when the file descriptor passed to 
asai_close(), asai_get_env(), asai_rcv(), 
asai_send(), or asai_set_env() is invalid possibly 
because it had been closed previously. 
						

							Error Messages
7-2Issue  3  May 1998 
 C_BADFLOWCommunications are flow controlled. This value is set in 
asai_rcv() if there was no message pending when it 
was called and the stream was opened in no-delay 
mode. Also, asai_send() will set this value when it 
cannot send a message.
 C_BADFLAGAn invalid value was given for the asai_open() flags.
 C_SYSERASAI service error. This error is set in asai_close(), 
asai_rcv(), and in asai_errval() whenever an 
error is detected in the operation of the ASAI 
Application Entity.
 C_SERVEXService is being provided by another application. This 
error is set in asai_set_env() whenever it has been 
passed a service that another Application Process is 
already providing.
 C_BADNODENode is not available. This error is set in asai_set_
env() whenever it has been passed a Node ID that 
has no communication path.
 C_INTRA system call was interrupted by a signal. This error is 
set in all ASAI functions whenever an external event 
causes a function to return before the operation 
requested could be performed.
 C_OSERA system call failed. This error is set in all ASAI 
functions whenever a failure in the operating system 
causes a function to return before the operation 
requested could be performed.
 C_BADMSGA corrupt message was received on the given stream. 
This error is set in asai_send() and asai_rcv() 
whenever a malformed message was read from a 
stream. It is recommended that the stream be closed as 
soon as possible.
 C_BADLNGThe send or receive buffer is too small for the capability. 
This error is set in asai_send() and asai_rcv() 
whenever the buffer size passed is too small.
 C_UNCAPCannot send an unknown capability. This error is set in 
asai_send() whenever an invalid capability is found 
in the user buffer. 
						

							Error Messages
Issue  3  May 1998
7-3
 C_BADPMATCHThe request has a missing or invalid matching 
parameter. This error is set in asai_send() and 
asai_rcv() whenever a mandatory parameter is 
missing or when two parameters are used 
inconsistently. For example, the values in the capability 
and primitive type parameters must match; an initiating 
capability with an acknowledgment type is an error. 
When returned by asai_rcv(), this error indicates 
that a message has been lost.
 C_BADVALUEThe request has an invalid parameter value. This error 
is set in asai_send() whenever a parameter has an 
invalid value. Typically, this will result from using a 
definition not meant for the parameter being set.
 C_TOOBIGA variable length field pointed to by a parameter was 
too big. This error is set in asai_send() whenever the 
user request cannot be sent because of protocol 
limitations. This may be the result of using variable 
length strings such as extensions that contain too many 
characters.
 C_ACTIVEThe stream has active associations. This error is set in 
asai_set_env() whenever an attempt to change the 
Node ID cannot be performed because currently SAOs 
exist.
C_INVALID_CLIENTThis error is returned only by MAPD, when a client 
cannot be validated, that is, its IP address is not 
administered on the MAPD.
C_LINKDOWNThis error is returned by MAPD to notify the application 
that the ASAI has been taken out of service by the 
administrator. 
						

							Error Messages
7-4Issue  3  May 1998  
						

							Issue  3  May 19988-1
8
ASAI Capability Primitives
The capabilities available to the ASAI library functions manage the 
communications process. This section provides information on data structures 
common to most or all of the capabilities.
Beginning with G3V2, the server provides additional information for certain 
capabilities and messages. In order to provide this information to the application, 
new fields in certain structures have been provided, and in some cases, new 
structures have been defined. These modifications have been made with the 
following design goals:
nAffect the API as little as possible
nMaintain consistency
nRequire no extraneous information from the application 
nMinimize future changes
!CAUTION:
However, there are instances where it has not been possible to 
maintain the capability. All messages from the ECS that contain 
redirecting, calling, called, or connected number IEs can now 
potentially contain new information. The new information consists of 
the Type of Address and Numbering Plan fields for the affected IEs.  
See Chapter 1 of DEFINITY Enterprise Communications Server 
Release 6 CallVisor ASAI Protocol Reference, 555-230-221, for a 
description of the Type of Address and Numbering Plan fields as they 
exist for the Called Party Number IE.  
						

							ASAI Capability Primitives
8-2Issue  3  May 1998 
Many messages contain two or more of the affected IEs: redirecting, calling, 
called, and connected number. To avoid confusing these IEs, it is desirable that 
the Type of Address and Numbering Plan fields be closely associated to the string 
of ASCII digits which they are intended to describe.
These redirecting, calling, called, and connected number fields are immediately 
followed with a structure (of type plan_type_t) that contains the Type of 
Address and Numbering Plan fields. 
Another number_id_t structure contains a plan_type_t structure and a 
pointer to the ASCII digit string as well. As a result, applications that need to 
access the Type of Address and Numbering Plan information can now do so. It is 
recommended that any information stored by these constructs be moved 
(or cast) to a number_id_t structure.
A new structure ucid_t has been added. ucid_t contains a pointer to the ASCII 
digit string id_ptr and a character string id_length.
In those cases where a redirected, calling, called, or connected number field is 
added to a message (for example, third party make call ack), a 
number_id_t structure has been added to the capability structure. 
						

							ASAI Capability Primitives
Issue  3  May 1998
8-3
asai_common
The structure asai_common defined by typedef asai_common_t is part of the 
data included for each capability. As its name implies, this structure contains 
information common to all capabilities. This common information is defined as 
follows:
typedef struct{
        capability_t        capability;
        primitive_t         primitive_type;
        long                sao_id;
        long                reserved;
}asai_common_t;
Within asai_common, the sao_id (also known as cluster_id) parameter 
identifies the particular association for which the message is intended. The value 
of this parameter is an even integer when the capability is user-initiated and an 
odd integer when the association is initiated by the ASAI library.
The type of service received or transmitted, is identified in capability and is 
defined as follows:
typedef enum {
C_3PAD,
C_3PAD_CONF,
C_3PANS,
C_3PANS_CONF,
C_3PCC,
C_3PCC_CONF,
C_3PCE,
C_3PDC_REQ,
C_3PDC_CONF,
C_3PDCE,
C_3PM,
C_3PM_CONF,
C_3PMC_REQ,
C_3PMC_CONF,
C_3PR,
C_3PR_CONF,
C_3PRC,
C_3PRC_CONF,
C_3PREDIR,
C_3PREDIR_ACK,
C_3PTC_REQ,
C_3PTC_CONF,
C_3PSD,
C_3PSD_CONF,
C_3PSDS,
C_3PSDS_CONF, 
						

							ASAI Capability Primitives
8-4Issue  3  May 1998 
C_3PSH,
C_3PSH_CONF,
C_3PSL_DISC
C_3PSL_DISC_ACk,
C_3PSL_RECONN
C_3PSL_RECONN_ACK,
C_3PSSC_REQ
C_3PSSC_CONF
                          C_3PTC_CONF
           C_3PTC_REQ
C_ABORT,
C_EN_CAN,
C_EN_CAN_CONF,
C_EN_CONF,
C_EN_END,
C_EN_REP,
C_EN_REQ,
C_HB_CONF,
C_HB_REQ,
C_RF_CONF,
C_RF_REQ,
C_RT_END,
C_RT_REQ,
C_RT_SEL,
C_SV_CONF,
C_SV_REQ,
C_VQ_CONF,
C_VQ_REQ,
C_VQ_RESP,
C_EN_SCN,
C_EN_SCN_CONF,
C_RM_REQ,
C_RM_CONF,
C_SM_REQ,
C_SM_CONF,
} capability_t;
The type of request or indication is identified in primitive_type:
typedef enum {
        C_REQUEST,
        C_POS_ACK,
        C_NEG_ACK
} primitive_t;
The values of C_REQUEST, C_POS_ACK, and C_NEG_ACK indicate a request, a 
positive acknowledgement, and a negative acknowledgement, respectively.
The 
reserved parameter, which appears in most of these common structures, 
simply means that the parameter is being reserved for future use.