d42_setparm( )

Description | NEC PBX | Cautions | Example | Errors

Name:	int d42_setparm(devh, parmnum, parmvalp)
Inputs:	int devh	board or channel descriptor
	int parmnum	parameter name
	void *parmvalp	pointer to an application buffer containing the parameter value
Returns:	ED42_NOERROR -1	if success
Includes:	D42LIB.H
Mode:	synchronous
Supports:	D/42-SL, D/42-SX, D/42-NS, D/42-NE2

Description

The d42_setparm( ) function sets a D/42-xx board or channel parameter. Depending on the parameter to be set, the value can be either a character string or an integer. A list of the board and channel parameters that can be set for parmnum can be found in Table 4 and Table 5.

Parameter	Description
devh:	specifies the valid board device or channel device descriptor obtained by a call to dx_open( )
parmnum:	specifies the define for the parameter that is to be updated with the value in the variable pointed to by parmvalp (see Table 4 and Table 5)
parmvalp:	pointer to the application buffer containing the parameter value

NOTE:

Setting board parameters affects all the channels on the board, but setting channel parameters affects only the specified channel.

To set board parameters the following requirements must be met:

• the board must be open
• all channels on the board must be closed

To set channel parameters the following requirements must be met:

• the channel must be open
• the channel must be idle

This function will return a failure if:

• the board or channel descriptor is invalid
• any channels are open when setting board parameters
• when setting channel parameters, the channel is not open and idle
• a read-only parm is specified
• the value of parmnum is invalid
• parmnum is not supported on the specified board
• an MF parm is specified while MF detection is enabled

NEC PBX (D/42-NE2)

The D4BD_MSGACCESSON and D4BD_MSGACCESSOFF parameter values must be character strings. The string cannot exceed 7 characters plus a null. Characters must be 0-9, #, and *.

The D4BD_RESETRINGCNT parameter is used to enable or disable the ring counter. On the D/42-NE2 the ring counter is used to count the number of ring signals received from the PBX. Your application will answer a call after the ring counter reaches a certain value (that you set). The ring counter automatically resets to zero when the D/42-NE2 detects that the call is abandoned or there is sufficient delay between ring events (set to 8 seconds by default).

The NEAX 2400 IMS does not send call abandoned messages, therefore the ring counter will only be reset after when the ring event delay is exceeded. Be aware that if a call is abandoned and a new call comes in before the 8-second delay, the ring counter will not be reset before the second call and will indicate the number of rings from both calls, possibly resulting in inaccurate data being reported to the application. For example, an application using a NEAX 2400 is set to answer a call after two rings. An incoming call is abandoned after the first ring and a new call comes in immediately following the abandoned call (less than 8 seconds apart). The application will answer the new call after the first ring because the ring counter was not reset after the first call was abandoned (it was incremented from one to two). This may result in inaccurate data being returned to the application, such as calling/called number ID or display data.

When using a D/42-NE2 with a NEAX 2400 IMS, the D4BD_RESETRINGCNT parameter must be set to 0 (which is the default). If enabled, the D/42-NE2 may intermittently reset the ring counter and your application will not answer calls reliably.

When using a D/42-NE2 with the NEAX 2000 IVS, you should set the D4BD_RESETRINGCNT parameter 1. This will enable the D/42-NE2 to reset the ring counter when it detects that a call is abandoned, allowing your application to retrieve accurate called/calling number ID and display data.

Cautions

When setting a parameter, the user passes a pointer to a variable containing the new parameter value. This variable should be treated as an unsigned integer for all parameters except D4BD_MSGACCESSON and D4BD_MSGACCESSOFF. Both D4BD_MSGACCESSON and D4BD_MSGACCESSOFF should be treated as ASCIIZ strings (char *). The application should cast the parmvalp parameter to a (void *) to avoid compiler warnings.

Table 4. D/42 Board Parameters for d42_getparm( ) & d42_setparm( )

Board Parameters	Description
D/42D-SX
D4BD_SPMODE	Set speaker phone mode. Values: 0 - enable (default) 1 - disable
D/42D-SL
D4BD_RINGON	Set ring on duration. Values: 0 - 1000 x 10 ms. (default: 400)
D4BD_RINGOFF	Set ring off duration. Values: 0 - 1000 x 10 ms. (default: 200)
D/42-NS
(no parameters)
D/42-NE2 (PBX only)
D4BD_MSGACCESSON	Set message access code on. Values: string (default: **9)
D4BD_MSGACCESSOFF	Set message access code off Values: string (default: ##9)
D4BD_RESETRINGCNT	Controls the automatic reset of the ring counter on the D/42-xx board. Values: 0 - disable (default) 1 - enable

Table 5. D/42 Channel Parameters for d42_getparm( ) & d42_setparm( )

Channel Parameters	Description
D/42D-SX
(no parameters)
D/42D-SL
D4CH_PDNKEY	Define PDN key feature Values: 0 - 9 decimal (default: 0)
D4CH_XFERKEY	Define transfer feature key Values: 0 - 9 decimal (default: 1)
D4CH_SENDKEY	Define send message feature key Values: 0 - 9 decimal (default: 2)
D4CH_CANCELKEY	Define cancel message feature key Values: 0 - 9 decimal (default: 3)
D4CH_DNKEY	Define DN feature key Values: 0 - 9 decimal (default: 4)
D4CH_RELEASEKEY	Define release feature key Values: 0 - 9 decimal (default: 9)
D/42-NS
D4CH_ASYNCCALLID	Control Caller ID reporting through the asynchronous TD42_ASYNCCALLID event. Values: 0 - disable Caller ID reporting (default) 1 - enable Caller ID reporting
D4CH_ASYNCCHSTATUS	Control channel synchronization status reporting through the asynchronous TD42_ASYNCCHSTATUS event. Values: 0 - disable channel status reporting (default) 1 - enable channel status reporting Data values returned with the TD42_ASYNCCHSTATUS event are   D42_CH_STATUS_OFF - communication off   D42_CH_STATUS_ON - communication on
D4CH_ASYNCCLOSEFEATSESSION	Control feature session reporting through the TD42_ASYNCCLOSEFEATURESESSION event. Note that this parameter is not normally manipulated through the d42_setparm( ) function because it is built into the d42_openfeaturesession( ) and d42_closefeaturesession( ) functions, which can automatically enable and disable this parameter, respectively. This parameter requires an open feature session. Values: 1 - enable feature session reporting 0 - disable feature session reporting (default)
D4CH_SOFTKEYINPUT	Control softkey input reporting through the TD42_SOFTKEYINPUT event. Note that this parameter is not normally manipulated through the d42_setparm( ) function because it is built into the d42_openfeaturesession( ) and d42_closefeaturesession( ) functions, which can automatically enable and disable this parameter, respectively. Values: 0 - disable softkey input reporting (default) 1 - enable softkey input reporting
D/42-NE2
(no parameters)

Example

void main(void)  
	{  
	int			devh;  
	int			rc = 0;  
	unsigned int	parmvalp = 1;  
	/* Open Board Device */  
	if ( (devh = dx_open("dxxxB1",NULL))==-1)  
		{  
		printf("Error dx_open( )\n");  
		exit(-1);  
		} /* End dx_open */  
	if ( (ATD4_BDTYPE ( devh )) == TYP_SX)  
		{  
		/* Set the Board Parameter To Enable Calling/Caller Id */  
		if ( (rc = d42_setparm(devh, D4BD_SPMODE, (void *)&parmvalp)) == -1)  
			{  
			printf("Error d42_setparm(D4BD_SPMODE)\n");  
			dx_close(devh);  
			exit(-1);  
			} /* End d42_setparm */  
		} /* end ATD4_BDTYPE */  
		dx_close(devh);  
	}	/* End main */

Errors

If this function returns -1 to indicate a failure, use ATDV_LASTERR( ) and ATDV_ERRMSGP( ) to retrieve one of the following (most common) errors. For a complete list of error codes and definitions, refer to Appendix C.

ED42_FWREQFAILURE	Firmware error
ED42_BADPARM	Invalid value for parameter
ED42_UNKNOWNBOARD	Unknown D/42 board type
ED42_INVALARG	Invalid argument passed to function

Click here to contact Dialogic Customer Engineering