8.3. Error Handling

• 8.3.1. Synchronous Mode
• 8.3.2. Asynchronous Mode

This section describes error handling in general and for specific modes of operation, namely synchronous and asynchronous. For a list of Dialogic fax error codes, see Appendix D.

All Dialogic fax library functions return a value to indicate success or failure of the function.

• To indicate success, the library returns a value of zero or a non-negative number.
• To indicate failure, the library returns a value of -1.

Extended attribute functions that do not return a pointer indicate failure by returning AT_FAILURE. Extended attribute functions that return a pointer indicate failure with AT_FAILUREP.

If a fax library function fails, call the standard attribute function ATDV_LASTERR( ) to return the error code and ATDV_ERRMSGP( ) to return a string describing the error. These functions are described in the Voice Software Reference - Standard Runtime Library.

If ATDV_LASTERR( ) returns the error EDX_SYSTEM, a system error has occurred; use dx_fileerrno( ) to obtain the system error value. Refer to the dx_fileerrno( ) function in the Voice Software Reference - Voice Programmer's Guide for a list of possible system error values.

NOTE:

fx_open( ) and fx_close( ) are exceptions to the above error handling rules. If these functions fail, the return code is -1 and an error from the operating system has occurred; use dx_fileerrno( ) to obtain the system error value.

If a fax send or receive function successfully completes, you can learn the final Phase D status of the fax transfer using fax extended attributes. If the function fails, Phase E status (using the fax extended attribute ATFX_ESTAT( )) provides additional error information for the T.30 fax protocol. Values for Phase D and Phase E status are described in Appendix B and Appendix C, respectively.

8.3.1. Synchronous Mode

Fax library functions that operate in synchronous mode return a value to indicate successful completion or failure of the function.

• To indicate successful completion, the function returns a value of zero.
• To indicate failure, the function returns a value of -1.

If a fax library function operating in synchronous mode fails, an error code is generated. To learn more about this failure, call the standard attribute function ATDV_LASTERR( ) to return the error code and ATDV_ERRMSGP( ) to return a string describing the error.

8.3.2. Asynchronous Mode

The fx_rcvfax( ), fx_rcvfax2( ), fx_sendfax( ) and fx_loadfont( ) functions can be specified to operate in synchronous or asynchronous mode. All other fax library functions operate in synchronous mode.

Fax library functions that operate in asynchronous mode return a value to indicate invocation success or failure, immediately after the function has been initiated:

• Invocation success is indicated by a return value of zero.
• Invocation failure is indicated by a return value of -1.

If the function is successfully invoked in asynchronous mode, it completes processing or terminates due to a processing error and an event is generated by the Standard Runtime Library.

The Standard Runtime Library may return the following events on completion of fx_rcvfax( ), fx_rcvfax2( ) or fx_sendfax( ) operating in asynchronous mode:

Event	Description
TFX_FAXERROR	Error in processing
TFX_FAXRECV	Successful completion of fx_rcvfax( ) or fx_rcvfax2( )
TFX_FAXSEND	Successful completion of fx_sendfax( )

If a function fails, a TFX_FAXERROR event is generated. Call the standard attribute function ATDV_LASTERR( ) to return the error code and ATDV_ERRMSGP( ) to return a string describing the error.

Click here to contact Dialogic Customer Engineering