dt_rundiag( )

Description | Cautions | Example | Errors | See Also

Name:	int dt_rundiag(devh,tmo,diagbufp)
Inputs:	int devh	Digital Network Interface logical board device handle
	int tmo	Timeout value
	char *diagbufp	Pointer to 1 byte buffer for diagnostic code
Returns:	0 on success -1 on failure
Includes:	srllib.h dtilib.h
Category:	Diagnostic
Mode:	synchronous/asynchronous

Description

The dt_rundiag( ) function runs diagnostics on the Network firmware. The function can operate in 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 is destructive to calls in progress.
• The board will be restored to its previous state; that is, the state the board was in before the function was called.
• The function should take about 5 seconds to complete.

Parameter	Description
devh:	Specifies the valid Digital Network Interface board device handle returned by a call to dt_open( )
tmo:	When operating the function in synchronous mode, specifies the length of time in seconds the function will block while waiting for a response from the device
diagbufp:	Pointer to a one-byte data buffer to which the diagnostic code will be returned when the function is operating in synchronous mode

Synchronous Mode

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

Asynchronous Mode

To operate the function in asynchronous (non-blocking) mode, set tmo to 0. This allows the application to continue processing while awaiting a completion event from the device.

If event handling is set up properly for your application, DTEV_RETDIAG is returned by the SRL sr_getevttype( ) function when the diagnostics are successfully completed.

To use this function in asynchronous mode, you must use the SRL sr_enbhdlr( ) function to enable trapping of the event and create an event handler to process the completion event returned by the device. See Appendix A - Standard Runtime Library for more information on Digital Network Interface event management.

NOTE:

To run this function in asynchronous operation, you must pass a NULL pointer to diagbufp.

Diagnostic Return Codes

The diagnostic codes listed below provide results of the diagnostics run on the Digital Network Interface firmware. In synchronous mode, the diagnostic codes are returned to the one-byte buffer pointed to by diagbufp. In asynchronous mode, the codes are returned by the SRL sr_getevtdatap( ) function.

• D2DE_BRDCFG - Invalid board configuration data
• D2DE_INVEE - Invalid EEPROM data (not valid for D/240SC-T1)
• D2DE_LIUFAIL - Read/write to LIU failed
• D2DE_MEMTST - Memory test failed
• D2DE_NOERR - No errors
• D2DE_ROMCHK - Bad ROM checksum (not valid for D/240SC-T1)
• D2DE_XCVRFAIL - Read XCVR register failed

Cautions

1. This function will fail under the following conditions:
   • An invalid Digital Network Interface logical board device handle is specified
   • There is a firmware/hardware problem on the device
2. Make sure all time slots are closed and idle. This function is destructive to calls in progress.

Example

#include <windows.h>          /* For Windows applications only */  
#include <srllib.h>  
#include <dtilib.h>  
#include <errno.h>  
   
main()  
{  
   int devh;                  /* Board device handle */  
   int retval;                /* Return value from function call */  
   char diagbufp;             /* Diagnostic buffer */  
   /*  
    * Open board 1 device  
    */  
   
   if ( ( devh = dt_open( "dtiB1", 0 ) ) == -1 ) {  
      printf( "Cannot open board dtiB1.  errno = %d", errno );  
      exit( 1 );  
   }  
   /*  
    * Run diagnostics on the board with a 5 second timeout.  
    */  
   if ( ( retval = dt_rundiag( devh, 5, &diagbufp ) ) == -1 ) {  
      printf("Error activating diag tests: error message = %s\n",  
                 ATDV_ERRMSGP( devh ) );  
   }  
   if ( diagbufp ! = DTDE_NOERR )  
      printf( "Diagnostic buffer value = %d\n", diagbufp );  
      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_SIZEERR - message too big or too small
• EDT_SKIPRPLYERR - a required reply was skipped
• EDT_SYSTEM - indicates system error - look at global variable errno for actual error
• EDT_TMOERR - timed out waiting for reply from firmware

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

See Also

• dt_tstcom( )
• dt_tstdat( )

Click here to contact Dialogic Customer Engineering