(Page 11 of 13 in this chapter)

2.10 Monitoring Fax Session Status

The application can track the progress of a fax session by monitoring the NaturalFax events on a specified CTA context.
Upon receipt of an error, the application can decide whether to continue with remaining documents in the queue or to abort the operation with nfxStopSession. Refer to Appendix C for a complete listing of NaturalFax events.
Use nfxGetSessionStatus to obtain information about the status of the current fax session. This function stores the information it retrieves in an NFX_FAX_STATUS structure.
For information about a specific document, call nfxGetDocStatus. This function stores the information it retrieves in an NFX_DOC_STATUS structure.
Refer to Appendix D for details about NaturalFax data structures.

2.10.1 Tracing NaturalFax Applications

Tracing for NaturalFax is available using CT Access tracing functions. Tracing must be enabled in the call to ctaInitialize. Then you call ctaSetTraceLevel with the CTA context, NFX service name, and a flag indicating what to trace.
The following NaturalFax trace masks are available (See the CT Access Function Reference Manual for CT Access trace masks.):
NFX_TRACE_T30 Turns on tracing for T30 protocol NFX_TRACE_ALL Turns all fax tracing on
Based on the flags set, the NFX service will log internal trace information to the CT Access daemon (ctdaemon). The following is an example of setting the trace level: ctaSetTraceLevel( ctahd, "NFX", NFX_TRACE_T30 | CTA_TRACEMASK_ALL_EVENTS );

If tracing is enabled, the CT Access daemon (ctdaemon) must be running. See Chapter 13 in the CT Access Developer's Manual for more information on the ctdaemon.

2.10.2 Error Handling During a Fax Session

During an active fax session (while sending or receiving a fax), it is important to monitor all events and respond accordingly. The following table provides some guidelines on some error conditions that may occur and suggested solutions: Event Problem and Solution ADIEVN_BOARD_ERROR An unexpected error has occurred on your AG board. Call nfxStopSession to cancel the fax session. Contact NMS with the specific error information. This should be considered a fatal error on this channel. Error Code with DONE Event Problem and Solution NFXERR_NEGOTIATION_FAILED Failed T.30 fax negotiation at the beginning of a session or between documents. When transmitting, this error indicates that training failed (usually due to bad phone line quality) or that the transmitter and receiver capabilities do not match. When receiving, this error indicates that the remote transmitter sent a DCN message or did not send a capabilities frame (DCS). NFXERR_BUFFER_UNDERRUN On fax transmit, buffers of image data have not been provided in time. Check your host computer loading to be sure events and disk I/O are being processed in a timely fashion. NFXERR_BUFFER_OVERRUN On fax receive, buffers to receive the incoming image data have not been provided in time. Check your host computer loading to be sure events and disk I/O are being processed in a timely fashion. NFXERR_CONNECT_FAILED The called fax machine was not detected. Check that the number you are dialing is a fax machine. NFXERR_OPEN_QUEUE_FAILED Could not open the specified document queue. Check that you have a valid transmit queue. NFXERR_SESSION_FAILED The fax session failed due to an unexpected event. May indicate a T.30 timeout or failure to receive a post page message. Check your host processor CPU and I/O loading. CTA_REASON_RELEASED The call has been disconnected by the remote fax machine. Check that events are being handled in a timely fashion. Check your host processor CPU loading. CTAERR_OUT_OF_RESOURCES A NaturalFax DSP function could not be started. Check to see that you are using the proper AG configuration for your application. Check to see that you have not exceeded the maximum number of fax operations for your hardware configuration. CTAERR_FUNCTION_ACTIVE A function is already running on the CTA context. Be sure your application waits for a DONE event from other fax or voice operations before initiating a new fax operation. CTAERR_FUNCTION_NOT_AVAIL A NaturalFax DSP overlay has not been downloaded to the board. Check your AG configuration file and review agerror.log and ag.rpt for start-up problems.

Event	Problem and Solution
ADIEVN_BOARD_ERROR	An unexpected error has occurred on your AG board. Call `nfxStopSession` to cancel the fax session. Contact NMS with the specific error information. This should be considered a fatal error on this channel.

Error Code with DONE Event	Problem and Solution
NFXERR_NEGOTIATION_FAILED	Failed T.30 fax negotiation at the beginning of a session or between documents. When transmitting, this error indicates that training failed (usually due to bad phone line quality) or that the transmitter and receiver capabilities do not match. When receiving, this error indicates that the remote transmitter sent a DCN message or did not send a capabilities frame (DCS).
NFXERR_BUFFER_UNDERRUN	On fax transmit, buffers of image data have not been provided in time. Check your host computer loading to be sure events and disk I/O are being processed in a timely fashion.
NFXERR_BUFFER_OVERRUN	On fax receive, buffers to receive the incoming image data have not been provided in time. Check your host computer loading to be sure events and disk I/O are being processed in a timely fashion.
NFXERR_CONNECT_FAILED	The called fax machine was not detected. Check that the number you are dialing is a fax machine.
NFXERR_OPEN_QUEUE_FAILED	Could not open the specified document queue. Check that you have a valid transmit queue.
NFXERR_SESSION_FAILED	The fax session failed due to an unexpected event. May indicate a T.30 timeout or failure to receive a post page message. Check your host processor CPU and I/O loading.
CTA_REASON_RELEASED	The call has been disconnected by the remote fax machine. Check that events are being handled in a timely fashion. Check your host processor CPU loading.
CTAERR_OUT_OF_RESOURCES	A NaturalFax DSP function could not be started. Check to see that you are using the proper AG configuration for your application. Check to see that you have not exceeded the maximum number of fax operations for your hardware configuration.
CTAERR_FUNCTION_ACTIVE	A function is already running on the CTA context. Be sure your application waits for a DONE event from other fax or voice operations before initiating a new fax operation.
CTAERR_FUNCTION_NOT_AVAIL	A NaturalFax DSP overlay has not been downloaded to the board. Check your AG configuration file and review `agerror.log` and `ag.rpt` for start-up problems.

(Page 11 of 13 in this chapter)

tech_support@nmss.com