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

							Testing
Issue  3  May 1998
10-23
Return Value
Returns the operation mode of the capability-specific function based on how much 
information was given on the command line. The return values are defined as 
follows:
Table 10-2. Return Value Descriptions
Return Value Meaning
INTERACTIVEthe user should be prompted for capability-specific 
information
RECORD_DIALOGa file name has been specified to record the dialog
SCRIPT_MODEa file name was supplied that contained answers to 
the dialog-specific questions 
						

							Testing
10-24Issue  3  May 1998 
print_common(3) 
Name
print_common
Synopsis
print_common( common_ptr )
asai_common_t        *common_ptr;
Description
printf the values of each of the elements of the ASAI common message header 
to 
stdout.
Return Value
Returns the defined value of SUCCESS. This return value is usually ignored by the 
calling function. 
						

							Testing
Issue  3  May 1998
10-25
t_input(3) 
Name
t_input
Synopsis
t_input( fieldname, cap_info, mode, batch_value )
char                *field_key;
struct cap_info     *cap_info;
int                 mode;
char                *batch_value;
Description
If the mode is INTERACTIVE, this function displays the name of the field, gives 
choices (if they were defined in the choices tables set up by the programmer) and 
accepts input. 
If the RECORD_DIALOG bit is on (in the mode), it will append the results to the 
current dialog file. If the mode is equal to SCRIPT_MODE, it is assumed that the 
value of batch_value is the ASCII representation to be used. The ASCII string 
is converted as necessary and stored in the table’s value field.
Arguments to this function are described as follows:
Return Value
Returns the address of the capability information structure for this field.
Table 10-3. Argument Types and Descriptions
Argument Meaning
field_namename of the field being entered
cap_infostarting address of the cap_info table for this capability
modeoperation mode - returned by call to C_W parse()
batch_valueif the mode is SCRIPT_MODE, then this is a pointer to a 
character string containing the ASCII value of the 
parameter 
						

							Testing
10-26Issue  3  May 1998 
t_output(3) 
Name
t_output
Synopsis
t_output( fieldname, expected_filename, type, value, mode )
char        *fieldname;
char        *expected_filename;
int         type;
char        *value;
int         mode;
Description
t_output is called by read-side capability-handling functions. It serves three 
purposes:
1. prints received value to standard output;
2. records name-value pair in specified file; 
3. compares received value with the one recorded in the expected answers 
file.
The mode field is used to determine which of the above three is appropriate.
Return Value
The return value is normally SUCCESS. 
						

							Testing
Issue  3  May 1998
10-27
CV/LAN Testing
Overview
A modified version of ITT called itt is provided to test the CV/LAN client API, the 
CV/LAN server and the ASAI library. 
After installation of the CV/LAN client software for Solaris X86 and UnixWare, 
itt can be found in the /usr/adm/asai_itt directory. For SPARC Solaris, 
it is in /usr/adm/asai/asai_itt directory. For Windows NT 4.0 system, it is 
under the CV/LAN client program group.
Scripts 
The ITT scripts can be used with itt. These scripts will require only a slight 
modification at the beginning of asai_open statement. The statement beginning 
ITT scripts is as follows: 
asai_open return_filename asai_special_file flags node_id 
server_num server_type
All the arguments to asai_open remain the same except for 
asai_special_file. Since the CV/LAN client needs to establish connection to 
the ECS through the CV/LAN server, the asai_special_file must point to 
the server (its IP address) and the ASAI link to the ECS. The format used by 
CV/LAN client API is: IP address or machine name.
 Example:
WWW.XXX.YYY.ZZZ 
						

							Testing
10-28Issue  3  May 1998  
						

							Issue  3  May 199811 - 1
11
Troubleshooting
This chapter presents a variety of issues or problems that you may encounter 
during installation, administration, maintenance, or application programming 
phases of ASAI application development using the CallVisor ASAI product.
PC/ISDN Platform Installation and Reference is the document accompanying the 
ISDN personal computer interface — the BRI interface board (IPCI board).  
Some of the sections are very DOS oriented. However, the document is helpful for 
specific installation instructions such as:
nHow to install multiple IPCI cards
nIPCI-card ECS settings for addresses in PC memory space that may be 
used for the card
nModifications that are required for the installation of additional RAM on the 
IPCI card 
						

							Troubleshooting
11 - 2Issue  3  May 1998 
ECS Administration
When administering the DEFINITY ECS BRI line to be used for ASAI connectivity 
between the ECS and the adjunct computer, enter the command
add station
 ext_num, where ext_num is the extension number associated with 
the ASAI link. Then enter the precise values listed in Chapter 1, ‘‘Installation’’ of 
this document.  
Other Release 6 administration commands that may be useful include:
Message Trace Capability
Use isdn_trace to write the actual messages (in hexadecimal format) that are 
coming from or going to the IPCI device to stdout.
IPCI_ON
If ipci_on fails, an error message is written to stderr. A list of the error codes 
with explanations is in /usr/adm/isdn/log_msgs. list station To find an extension number that has been 
administered as ‘‘type” ASAI. For example, the 
extension number of the ASAI link may be 
needed for a ‘‘route to adjunct” step in a vector.
change vector 
vect_numTo administer vector steps for routing 
applications where 
vect_num is the number of 
the vector being administered.
display cor 
rstrict_numThe Direct Agent Calling field must be set
to y on the class of restriction (COR) form for a 
station’s COR for that station to originate or 
receive direct agent calls through
an adjunct. 
rstrict_num is the COR number. 
						

							Troubleshooting
Issue  3  May 1998
11-3
Application Programming
Cause Values 
CallVisor ASAI product must be installed to access the complete set of correct 
cause values. For a complete description of the DEFINITY ECS and ASAI cause 
values, see the section “Cause” in Chapter 4, “Information Elements” in 
DEFINITY 
Enterprise Communications Server Release 6 CallVisor ASAI Protocol Reference
; 
also see ‘‘cause_value’’ on page 8-12 in Chapter 8, ‘‘ASAI Capability Primitives’’ 
of this document.
Nonblocking I/O 
Some applications must be implemented as ‘‘nonblocking I/O.” For nonblocking 
I/O in the library, an application must call asai_open with 
ndelay_flag set to O_NDELAY. It is also necessary to check error returns on 
every library function call. See open(2) in the 
UNIX User Reference Manual for 
more details.
The oflag that is passed to the library is O_NDELAY for nonblocking reads and 
writes. Since the library is not reentrant, an interrupt service routine (signal 
catcher) cannot call asai_rcv if the main application has already done so.
It is beyond the scope of this document to discuss the requirements and 
techniques of nonblocking I/O. Since the implementation of nonblocking I/O is an 
intricate matter, it is strongly recommended that such an undertaking should not 
be attempted before careful planning is conducted by an experienced developer.
Integration Test Tool
The integration test tool (ITT) is included only as a very basic example of an 
application.
Responding to Heartbeat 
It is the responsibility of the CallVisor PC adjunct to respond to the ASAI heartbeat 
messages that are periodically sent from the ECS. This is the case for every 
CallVisor PC adjunct and for each ASAI link that is active. 
						

							Troubleshooting
11 - 4Issue  3  May 1998 
The ECS sends a register message (with the operation value set to heartbeat) to 
the adjunct every two minutes. In order to respond to this request, the application 
must have previously called the function asai_set_env with server_type set 
to C_MAINT_SER for the application to be considered a maintenance server. As a 
maintenance server, the application must respond to every C_HB_REQ capability it 
receives from the ECS with a C_HB_CONF. If the adjunct fails to respond to three 
consecutive heartbeat requests from the ECS, the ECS takes down Layer 1 for 
five seconds and all active associations are aborted. If the application program 
itself has to perform the maintenance server role, great care must be taken to 
ensure that the application does not block waiting on other events which would 
cause it to miss a heartbeat request. A separate process should be used to 
perform the maintenance server role.
Beginning with Release 2.2 of the CallVisor ASAI product, an OA&M process, 
asai_hb, is available to accomplish this maintenance task.
Link Startup Failure 
The QP module logs link startup failures to both the system console and the crash 
buffer. Use crash (1M) to examine the crash buffer. If the QP module has failed it 
is probably because of ECS and adjunct version incompatibility. If the link failure 
was because of incompatible parameters, correct the parameters as described in 
‘‘Starting Up the System’’ on page 1-23 in Chapter 1, ‘‘Installation.’’
Detecting Failed ASAI Links
Some applications are required to detect and report a failed link within a certain 
time.
If the link failure detection time is more than three or four seconds, a good way to 
detect a failed link is to send a heartbeat request to the ECS at twice the rate of 
the requirement. If the heartbeat acknowledgment has not been received from the 
ECS when it is time to send the next heartbeat request, the link can be assumed 
to have failed. If the link failure detection time is fewer than two seconds, a more 
sophisticated algorithm might be needed. In constructing such an algorithm, the 
programmer should allow at least 100 milliseconds for the ECS to acknowledge 
the heartbeat. The programmer must also consider the delays due to any 
time-sharing activity that may be present.
The rate at which heartbeat requests are sent should take the link capacity and 
overall message load into consideration as well as the detection time requirement.
The link capacity is about 40 messages per second. The exact figure depends on 
the length and content of the messages. A heartbeat request and 
acknowledgment count as one message each. Sending a heartbeat once a 
second will consume somewhat less than 5 percent of the link capacity.