2.5. How to Use Call Analysis

• 2.5.1. Set Up the Call Analysis Parameter Structure (DX_CAP)
• 2.5.2. To Initiate Call Analysis Use the dx_dial( ) Function
• 2.5.3. Determine the Outcome of the Call
• 2.5.4. Obtain Additional Call Outcome Information

The following procedure describes how to initiate an outbound call with Call Analysis:

1. Set up the Call Analysis Parameter structure (DX_CAP), which contains parameters that control the operation of Call Analysis.
2. Execute the dx_dial( ) function to initiate Call Analysis.
   • If running dx_dial( ) asynchronously, use the Event Management functions to determine when dialing with Call Analysis is complete (TDX_CALLP termination event).
   • If running dx_dial( ) synchronously, wait for dx_dial( ) to return a value greater than 0 to indicate successful completion.

 
See the dx_dial( ) function description in the Voice Software Reference: Programmer's Guide for information about asynchronous and synchronous operation.

3. Use ATDX_CPTERM( ) to determine the outcome of the call.

an intercept	CR_CEPT
no ringback	CR_NORB
busy signal	CR_BUSY
no answer	CR_NOANS
fax machine	CR_FAXTONE
no dial tone	CR_NODIALTONE
connect	CR_CNCT
Call Analysis stopped	CR_STOPD
Call Analysis error	CR_ERROR

NOTE:

When running dx_dial( ) synchronously, these results are also returned by dx_dial( ).

4. Obtain additional termination, frequency, or cadence information (such as the length of the salutation) as desired using Extended Attribute functions.

Each of these steps is described in detail in the following pages.

NOTE:

For information about dx_dial( ), ATDX_CPTERM( ), and the DX_CAP data structure, see the Voice Software Reference: Programmer's Guide:

2.5.1. Set Up the Call Analysis Parameter Structure (DX_CAP)

The dx_dial( ) function enables Call Analysis after dialing.

If you want to customize the parameters for your environment, you must set up the Call Analysis Parameter structure before calling dx_dial( ). By adjusting the DX_CAP parameters, you can:

• Eliminate Call Analysis functions that do not pertain to your environment.
• Optimize performance of the required functions.
• Support non-standard system configurations.
• Perform additional functions, such as determining whether the called party is a business, residence, or answering machine.

To set up the DX_CAP structure for Call Analysis: Execute the dx_clrcap( ) function to clear the DX_CAP and initialize the parameters to 0. The value 0 indicates that the default value will be used for that particular parameter. dx_dial( ) can also be set to run with default Call Analysis parameter values, by specifying a NULL pointer to the DX_CAP structure.

For more detailed information on the DX_CAP block parameters, refer to Section 2.6. How the DX_CAP Controls Call Analysis.

2.5.2. To Initiate Call Analysis Use the dx_dial( ) Function

Enable Call Analysis by calling dx_dial( ) with the mode function argument set to DX_CALLP. Termination of dialing with Call Analysis is indicated differently depending on whether the function is running asynchronously or synchronously. More information on dx_dial( ) can be found in the Voice Software Reference: Programmer's Guide.

2.5.3. Determine the Outcome of the Call

Once dx_dial( ) with Call Analysis has terminated, use the Extended Attribute function ATDX_CPTERM( ) to determine the outcome of the call. ATDX_CPTERM( ) will return one of the following Call Analysis Termination results:

CR_BUSY	Called line was busy.
CR_CNCT	Called line was connected.
CR_FAXTONE	Called line was answered by a fax machine or a modem (PerfectCall Call Analysis only).
CR_NOANS	Called line did not answer.
CR_NODIALTONE	Called line failed to produce a dial tone (PerfectCall Call Analysis only).
CR_NORB	Called line did not ring.
CR_CEPT	Called line received operator intercept (SIT). The Extended Attribute functions provide information on the detected frequencies and durations.
CR_STOPD	Call Analysis stopped due to dx_stopch( ).
CR_ERROR	Call Analysis error occurred. ATDX_CPERROR( ) returns the type of the Call Analysis error.

Figure 3 illustrates the possible outcomes of Call Analysis.

Figure 4 illustrates the possible outcomes of PerfectCall Call Analysis.

Figure 3. Call Analysis Outcomes for Basic Call Analysis

Figure 4. Call Analysis Outcomes for PerfectCall Call Analysis

2.5.4. Obtain Additional Call Outcome Information

Additional Call Analysis information can be retrieved using the following Extended Attribute functions:

ATDX_ANSRSIZ( )	Returns duration of answer
ATDX_CPERROR( )	Returns call analysis error
ATDX_CPTERM( )	Returns last call analysis termination
ATDX_CONNTYPE( )	Returns connection type
ATDX_CRTNID( )	Returns the identifier of the tone that caused the most recent Call Analysis termination
ATDX_DTNFAIL( )	Returns the dial tone character that indicates which dial tone Call Analysis failed to detect
ATDX_FRQDUR( )	Returns duration of first frequency detected
ATDX_FRQDUR2( )	Returns duration of second frequency detected
ATDX_FRQDUR3( )	Returns duration of third frequency detected
ATDX_FRQHZ( )	Returns frequency detected in Hz of first detected tone
ATDX_FRQHZ2( )	Returns frequency of second detected tone
ATDX_FRQHZ3( )	Returns frequency of third detected tone
ATDX_FRQOUT( )	Returns percent of frequency out of bounds
ATDX_LONGLOW( )	Returns duration of longer silence
ATDX_SHORTLO( )	Returns duration of shorter silence
ATDX_SIZEHI( )	Returns duration of non-silence

For a discussion of how frequency and cadence information returned by these Extended Attribute functions relate to the DX_CAP parameters, refer to Section 2.6. How the DX_CAP Controls Call Analysis.

Click here to contact Dialogic Customer Engineering