gc_LoadDxParm( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_LoadDxParm(linedev, pathp, errmsgp, err_length)
Inputs:	LINEDEV linedev	line device
	char *pathp	pointer to parameter file
	char *errmsgp	pointer to error message
	int err_length	maximum error message length
Returns:	0 if successful <0 if failure
Includes:	gclib.h gcerr.h
Category:	voice and media
Mode:	synchronous
Platform and Technology:	Springware: T-1/E-1 (PDKRT only), Analog

Description

The gc_LoadDxParm( ) function sets voice parameters associated with a line device that operates as a dedicated or shared resource. The line device resource operates in conjunction with an analog loop start network interface resource to handle call processing activities. The parameters set by this function affect basic and enhanced call progress and interact with the gc_MakeCall( ) function.

Global Call assigns an LDID number to represent the physical devices that will handle a call, such as a voice resource and an analog loop start (or a digital) network interface resource, when the gc_OpenEx( ) function is called. This identification number assignment remains valid until the gc_Close( ) function is called to close the line devices.

Parameter	Description
linedev	Global Call line device handle
pathp	points to the voice parameter file to load
errmsgp	points to the storage address of any error message
err_length	maximum length in bytes of the error message stored at address defined by the errmsgp parameter

When the gc_LoadDxParm( ) function is called, the function looks for a voice parameter file listing only the voice parameters to be changed from their default value in the location defined by the pathp parameter, typically in the current directory or in the standard Dialogic cfg directory. The voice parameter file is read and the voice device is configured based on the parameters and parameter values defined in this file. Any parameter not defined will use the default parameter value.

The following is an example of a voice channel parameter (.vcp) file called dxchan.vcp (file names are defined by the user):

#
#     D/xxx parameter file for downloading channel level
#     parameters supported by dx_setparm() and DX_CAP structure.
#
#     Values are in decimal unless a leading 0x is included in which
#     case the value is hexadecimal.
#
#     Refer to the Voice Software Reference for the DX_CAP
#     structure ca_* parameters. The upper case parameters can also
#     be found in the Voice Software Reference - Features Guide under the
#     dx_setparm() function.
#
#     To set a parameter, uncomment (delete the '#' or ';') and set a
#     value to the right of the parameter name.
# 
# ca_stdely   
# ca_cnosig        
# ca_lcdly        
# ca_lcdly1        
# ca_hedge         
# ca_cnosil       
# ca_logltch 
#
# Values of bitmask flags for setting ca_intflg
# add desired flags to set ca_intflg
# 
# DX_OPTEN         =   1
# DX_OPTDIS        =   2
# DX_OPTNOCON      =   3
# DX_PVDENABLE     =   4
# DX_PVDOPTEN      =   5
# DX_PVDOPTNOCON   =   6
# DX_PAMDENABLE    =   7
# DX_PAMDOPTEN     =   8 
ca_intflg  5 
#
#
# 
# ca_lowerfrq      
# ca_upperfrq      
# ca_timefrq       
# ca_maxansr       
# ca_ansrdgl       
# ca_mxtimefrq     
# ca_lower2frq     
# ca_upper2frq     
# ca_time2frq      
# ca_mxtime2frq    
# ca_lower3frq     
# ca_upper3frq     
# ca_time3frq      
# ca_mxtime3frq    
# ca_dtn_pres      
# ca_dtn_npres     
# ca_dtn_deboff    
# ca_pamd_failtime 
# ca_pamd_minring  
# ca_pamd_spdval   
# ca_pamd_qtemp    
# ca_noanswer      
# ca_maxintering 

A voice parameter file contains parameter definition lines and may contain comment lines. Each parameter definition line comprises a case-sensitive voice parameter as the first field of the line, a space, and a second field defining the parameter value.

A comment line begins with either of the following characters:

• # character
• ; character

The gc_LoadDxParm( ) function will return upon the first detected error. The reason for the error will be stored in the msgbufferp location. Typical error reasons are:

• a parsing error (in the .vcp file)
• a low-level function call error
• an open file failure error

Note: Not all errors can be detected by the gc_LoadDxParm( ) function. Errors in the value of the voice call analysis parameters in the DX_CAP structure cannot be detected until a call is set up by the gc_MakeCall( ) function.

All channel-level parameters set by the voice function, dx_setparm( ), can be set using the gc_LoadDxParm( ) function. Global Call uses the dx_setparm( ) parameter names to identify all voice channel-level parameters:

• DXCH_DFLAGS
• DXCH_DTINITSET
• DXCH_DTMFDEB
• DXCH_DTMFTLK
• DXCH_MAXRWINK
• DXCH_MFMODE
• DXCH_MINRWINK
• DXCH_PLAYDRATE
• DXCH_RECRDRATE
• DXCH_RINGCNT (Not used. The default number of rings parameter in the .cdp file sets this parameter value.)
• DXCH_WINKDLY
• DXCH_WINKLEN

Also see the Voice API Library Reference for your operating system for a description of these parameters.

The gc_LoadDxParm( ) function supports all basic and enhanced call progress fields defined in the DX_CAP data structure. The parameter value may be entered as a decimal value or as a hexadecimal value when prefixed with a "0x". The call analysis parameters defined in the DX_CAP data structure affect the gc_MakeCall( ) function. Global Call uses the DX_CAP data structure names to identify all call progress parameters:

• ca_alowmax
• ca_ansrdgl
• ca_blowmax
• ca_cnosig
• ca_cnosil
• ca_dtn_deboff
• ca_dtn_npres
• ca_dtn_pres
• ca_hedge
• ca_hi1bmax
• ca_hi1ceil
• ca_hi1tola
• ca_hi1tolb
• ca_higltch
• ca_hisiz
• ca_intflg
• ca_lcdly
• ca_lcdly1
• ca_lo1bmax
• ca_lo1ceil
• ca_lo1rmax
• ca_lo2bmax
• ca_lo2rmin
• ca_lo1tola
• ca_lo1tolb
• ca_lo2tola
• ca_lo2tolb
• ca_logltch
• ca_lower2frq
• ca_lower3frq
• ca_lowerfrq
• ca_maxansr
• ca_maxintering
• ca_mxtime2frq
• ca_mxtime3frq
• ca_mxtimefrq
• ca_nbrbeg
• ca_nbrdna
• ca_noanswer
• ca_nsbusy
• ca_pamd_failtime
• ca_pamd_minring
• ca_pamd_qtemp
• ca_pamd_spdval
• ca_stdely
• ca_time2frq
• ca_time3frq
• ca_timefrq
• ca_upper2frq
• ca_upper3frq
• ca_upperfrq

Also see the Voice API Library Reference for your operating system for more information about the fields in the DX_CAP data structure.

For analog applications, the gc_LoadDxParm( ) function is used to set call analysis parameters (board and channel-level) that are otherwise set by the voice function, dx_setparm( ). While the gc_LoadDxParm( ) function is used for analog applications, the gc_SetParm( ) and gc_GetParm( ) functions continue to be used to set and display parameter values for other technologies such as E-1, T-1, ISDN, etc.

For technologies other than analog, a voice resource must be attached before calling this function.

Termination Events

None

Cautions

• Before calling the gc_LoadDxParm( ) function, the gc_OpenEx( ) function must be used to open the voice line device.
• The maximum length of the error message string, msglength, must be passed to the gc_LoadDxParm( ) function to avoid overwriting memory locations outside the message string array.
• The maximum length of the error message string, msglength, should be passed to the function to avoid overwriting memory locations outside the array pointed to by the msgbufferp parameter.
• The call analysis parameters (see above) are used only for analog loop start protocols. If this function is invoked for an unsupported technology, the function fails. The error value EGC_UNSUPPORTED will be the Global Call value returned when the gc_ErrorInfo( ) function is used to retrieve the error code. See also the Errors section of this function description.
• When using the North America Analog Bidirectional Protocol for ANAPI, the application must call the gc_LoadDxParm( ) function after calling gc_OpenEx( ). Failure to do so may lead to incorrect call progress information.

Errors

If this function returns <0 to indicate failure, use the gc_ErrorInfo( ) function to retrieve the reason for the error. See the "Error Handling" section in the Global Call API Programming Guide. All Global Call error codes are defined in the gcerr.h file. If the error returned is technology specific, see the technology-specific error header file(s) for the error definition (for example, ccerr.h or isdnerr.h file for the ISDN call control library).

If the error is not EGC_UNSUPPORTED, then a more detailed description of the error is copied to the address specified by the msgbufferp parameter. When a parsing error is detected, an "Invalid line" followed by the line number and the line containing the error are stored in the msgbuffer buffer.

Example

#include <stdio.h>
#include <srllib.h>
#include <dxxxlib.h>
#include <gclib.h>
#include <gcerr.h> 
#define MSGLENGTH 80 
main()
{
    LINEDEV ldev; 
    GC_INFO gc_error_info;  /* GlobalCall error information data */
    .
    .
    .
    /*
     *   Assume the following has been done:
     *   Open line device (ldev) specifying voice and network resource using
     *   gc_OpenEx()
     *   
     */      
    /* call gc_LoadDxParm() to download the channel parameters */
    if ((gc_LoadDxParm(ldev, "dxchan.vcp", errmsg, MSGLENGTH)) != 0) {
        gc_ErrorInfo( &gc_error_info );
        printf ("Error: gc_LoadDxParm() on linedev: 0x%lx, GC ErrorValue: 0x%hx - %s, 
                 CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
                 ldev, gc_error_info.gcValue, gc_error_info.gcMsg, 
                 gc_error_info.ccLibId, gc_error_info.ccLibName,
                 gc_error_info.ccValue, gc_error_info.ccMsg);
        return (gc_error_info.gcValue);
    }
    .
    .
    .
} 

See Also

• gc_MakeCall( )
• gc_OpenEx( )

Click here to contact Telecom Support Resources