dt_dial( )

Description | Cautions | Example 1 | Example 2 | Errors | See Also

Name:	int dt_dial(devh,digstr,tmo)
Inputs:	int devh	time slot device handle
	char *digstr	pointer to an ASCIIZ string of digits
	unsigned int tmo	timeout value
Returns:	0 on success -1 on failure
Includes:	srllib.h dtilib.h
Category:	Time Slot Signaling
Mode:	synchronous/asynchronous

Description

The dt_dial( ) function allows the application to pulse dial an ASCIIZ string of digits on a specified D/240SC-T1, D/240SC-2T1, D/480SC-2T1, D/300SC-E1 D/300SC-2E1 or D/600SC-2E1 time slot. The function can operate in either the synchronous (blocking) or asynchronous (non-blocking) mode.

Parameter	Description
devh:	Specifies the valid time slot device handle returned by a call to dt_open( ). The specified time slot must be in the offhook, idle state when dt_dial( ) is called.
digstr:	Pointer to the ASCIIZ string of digits to dial. The maximum length of the string is 32 digits.
tmo:	Specifies the maximum number of seconds that the function will block while awaiting a dial status response from the D/xxxSC board.

Asynchronous Mode

To operate this function in asynchronous (non-blocking) mode, specify 0 for tmo. This allows the application to continue processing while awaiting a completion event. If event handling is set up properly for your application, DTEV_PDDONE will be returned by the sr_getevttype( ) function included in the SRL when the dial is successfully completed. See Appendix A - Standard Runtime Library for information on event handling.

Synchronous Mode

To operate the function in synchronous (blocking) mode, specify a length of time in seconds that the function will block for tmo. This causes the application to wait for a return from the function before performing any other processing. A suggested tmo setting for this function is 60.

Cautions

1. This function will fail under the following conditions:
   • A logical board or invalid time slot device handle is specified
   • More than a 32 digit buffer is passed
   • There is insufficient memory
   • Signaling insertion is not enabled
   • The time slot is already pulse dialing
   • The time slot is not in the offhook idle state
2. The time slot must be in signaling insertion mode before this function is called. Signaling insertion mode is enabled using the dt_setsigmod( ) function.
3. To use this function in asynchronous mode, you must use the dt_setevtmsk( ) and SRL sr_enbhdlr( ) functions to enable trapping the completion event and create an event handler to process the event. See Appendix A - Standard Runtime Library for more information on Digital Network Interface event management.
4. Make sure adequate time is given to the function to complete the dial if the synchronous mode is used.

Example 1

#include <windows.h>      /* For Windows applications only */  
#include <srllib.h>  
#include <dtilib.h>  
#include <errno.h>  
/*  
 * Basic error handler  
 */  
do_error( devh, funcname )  
   int devh;  
   char *funcname;  
{  
   int errorval = ATDV_LASTERR( devh );  
   printf( "Error while calling function %s.\n", funcname );  
   printf( "Error value = %d.  Error message = %s.", errorval,  
          ATDV_ERRMSGP( devh ) );  
   if ( errorval == EDT_SYSTEM ) {  
      printf( "errno = %d.\n", errno );  
   } else {  
      printf( "\n" );  
   }  
}  
main()  
{  
   int tsdev;         /* Time Slot device handle */  
   /*  
    * Open time slot 1 on board 1  
    */  
   if ( ( tsdev = dt_open( "dtiB1T1", 0 ) ) == -1 ) {  
      printf( "Failed to open device dtiB1T1.  errno = %d\n", errno );  
      exit( 1 );  
   }  
   /*  
    * Set signaling mode to signaling insertion  
    */  
if ( dt_setsigmod( tsdev, DTM_SIGINS ) == -1 ) {  
      do_error( tsdev, "dt_setsigmod()" );  
      exit( 1 );  
   }  
   /*  
    * Disable silence transmission  
    */  
   if ( dt_setidle( tsdev, DTIS_DISABLE ) == -1 ) {  
      do_error( tsdev, "dt_setidle()" );  
      exit( 1 );  
   }  
   /*  
    * Go offhook  
    */  
   if ( dt_settssig( tsdev, DTB_ABIT | DTB_BBIT, DTA_SETMSK ) == -1 ) {  
      do_error( tsdev, "dt_settssig()" );  
      exit( 1 );  
   }  
/*  
    * Dial number with 60 second timeout.  Note that this is the blocking  
    * mode dial.  
    */  
   if ( dt_dial( tsdev, "7223689", 60 ) == -1 ) {  
      do_error( tsdev, "dt_dial()" );  
      exit( 1 );  
   }  
   /*  
    *   Continue processing  
    *          .  
    *          .  
    */  
   /*  
    * Done processing - close device.  
    */  
   if ( dt_close( tsdev ) == -1 ) {  
      do_error( tsdev, "dt_close()" );  
   }  
}

Example 2 -- Setting Flash Hook Using dt_dial( )

/*  
 * Set flash hook  
 */  
   
setflashhook(tsdev)  
{  
   char dial_str[10];  
   int value;  
   sprintf(dial_str, "%c", DTV_FLASHCHR);  
   tmo = 10;  
   dt_dial(tsdev, string, tmo);  
   
/*  
 * Change flash time  
 */  
value = 100;       /* 1 sec */  
   .  
   .  
   .  
   dt_setparm(tsdev, DTG_PDDLFTIM, (void *)&value);  
}

Errors

If the function returns -1, use the SRL Standard Attribute function ATDV_LASTERR( ) to obtain the error code. See Appendix A - Standard Runtime Library for more information on SRL functions. The error codes returned by ATDV_LASTERR are:

• EDT_BADBRDERR - Digital network interface missing or defective
• EDT_BADCMDERR - invalid or undefined command to driver
• EDT_DATTO - data reception timed out
• EDT_FWERR - firmware returned an error
• EDT_NOMEMERR - cannot map or allocate memory in driver
• EDT_PARAMERR - invalid parameter
• EDT_RANGEERR - bad/overlapping physical memory range
• EDT_SIZERR - message too big or too small
• EDT_SKIPRPLYERR - a required reply was skipped
• EDT_SYSTEM - system error - check the global variable errno for more information about the error
• EDT_TMOERR - timed out waiting for reply from firmware
• EDT_INVTS - invalid time slot device handle
• EDT_SIGINS - signaling insertion not enabled
• EDT_TSBSY - time slot is busy
• EDT_PDOFFHK - not in offhook idle state
• EDT_PDSIG - cannot disable insertion when pulse dialing

Error defines can be found in the file dtilib.h.

See Also

In Voice Software Reference (for Linux or Windows):

• dx_dial( )

Click here to contact Dialogic Customer Engineering