dt_tstcom( )

Description | Cautions | Example | Errors | See Also

Name:	int dt_tstcom(devh,tmo)
Inputs:	int devh	Digital Network Interface logical board device handle
	int tmo	timeout value
Returns:	Digital Network Interface return code -1 on failure
Includes:	srllib.h dtilib.h
Category:	Diagnostic
Mode:	synchronous/asynchronous

Description

The dt_tstcom( ) function tests the ability of a Digital Network Interface device to communicate with the host PC. This function can operate in either synchronous (blocking) or asynchronous (non-blocking) mode.

Please note the following guidelines when using this function:

• This function can be issued at any time, but it is recommended that all time slots be idle and closed
• This function has no effect on calls in progress
• This function has no effect on the state of the board

Parameter	Description
devh:	Specifies the valid Digital Network Interface logical board device handle returned by a call to dt_open( )
tmo:	Specifies the maximum amount of time in seconds that the function will block while waiting for a response from the Digital Network Interface. If a response is not returned within tmo seconds, an error is returned

Synchronous Mode

To run this function in synchronous (blocking) mode, set tmo to the length of time, in seconds, to await a return. If a response is not returned within tmo seconds, an error is returned. A suggested tmo setting for this function is 5.

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_COMRSP will be returned by the sr_getevttype( ) function included in the SRL when the test is successfully completed. See Appendix A - Standard Runtime Library for information on event handling.

Cautions

1. This function returns a failure under the following conditions:
   • The specified device fails to respond within tmo seconds, if operating in synchronous mode
   • A time slot or invalid Digital Network Interface logical device handle is specified
   • There is a hardware problem on the Digital Network Interface
   • There is a configuration problem (for example, IRQ conflict)

   NOTE:

   Device configuration information is found in the appropriate hardware installation card (see Appendix D).

1. To use this function in asynchronous mode, you must use the SRL sr_enbhdlr( ) function to enable trapping of events and create an event handler to process the completion event returned by the device.

 
The event can be detected by using the new event management functions included in the new release of the Standard Runtime Library. See Appendix A - Standard Runtime Library for more information on Digital Network Interface event management.

Example

#include <windows.h>        /* For Windows applications only */  
#include <srllib.h>  
#include <dtilib.h>  
#include <errno.h>  
   
main()  
{  
   int devh;                /* Board device handle */  
   /*  
    * Open board 1 device  
    */  
   if ( ( devh = dt_open( "dtiB1", 0 ) ) == -1 ) {  
      printf( "Cannot open board dtiB1.  errno = %d", errno );  
      exit( 1 );  
   }  
   
   /*  
    * Test the board's ability to communicate with the system.  Give it 5  
    * seconds to complete.  
    */  
   if ( dt_tstcom( devh, 5 ) == -1 ) {  
      printf( "Error message = %s.",ATDV_ERRMSGP( devh ) );  
      exit( 1 );  
   }  
              .  
              .  
              .  
}

Errors

If the function returns -1, use the SRL Standard Attribute function ATDV_LASTERR( ) to obtain the error code or use ATDV_ERRMSGP( ) to obtain a descriptive error message. 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_INVBD - invalid Digital Network Interface logical board device handle
• 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

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

See Also

• dt_tstdat( )
• dt_rundiag( )

Click here to contact Dialogic Customer Engineering