5.2. Setting Parameters for Receive Fax

• 5.2.1. Specifying Encoding Scheme to Store Incoming Fax Data
• 5.2.2. Storing Incoming Fax Data
• Storing in a Single TIFF/F File
• Storing in Multiple TIFF/F Files
• Storing in a Raw File
• 5.2.3. Setting Acceptable Percentage of Bad Scan Lines
• 5.2.4. Selecting Preferred Maximum Receive Baud Rate
• 5.2.5. Replacing Bad Scan Lines
• 5.2.6. Routing Fax Data to Multiple Subaddresses

The fax parameters described in this section are specified using fx_setparm( ).

• 5.2.1. Specifying Encoding Scheme to Store Incoming Fax Data

The incoming fax data may be stored in one of the following encoding schemes based on the capability of the receiving station: MH or MMR.

On most Dialogic products, the encoding scheme for storing incoming fax data is determined by the FC_RXCODING parameter in the fx_setparm( ) function. For details on product support, see Section 2.4. Key Product Features on page 8.

• When incoming fax data is stored in TIFF/F files, the encoding scheme specified in the FC_RXCODING parameter is included in the TIFF/F tags embedded in the stored file. For TIFF/F tag details, see Appendix A.
• When incoming fax data is stored in raw image files, the application must keep track of the encoding scheme by referring to the value specified in the FC_RXCODING parameter.

The Dialogic fax software automatically converts the incoming fax data to the encoding scheme specified in the FC_RXCODING parameter regardless of the encoding scheme negotiated during Phase B of the fax transfer.

To determine the negotiated line encoding scheme, call ATFX_CODING( ) after the negotiation of Phase B has completed.

5.2.2. Storing Incoming Fax Data

Incoming fax data is delimited by Phase D command values sent from the transmitter to the receiver. The transmitter application sets these values using the FC_ENDDOC parameter in fx_setparm( ).

Storing in a Single TIFF/F File

For most applications, a multi-page fax document is stored in a single TIFF/F file.

The DFS_EOP value indicates to the receiver that all incoming pages will be stored in a single, multi-page TIFF/F file. This is the default setting.

For information on specifying the file storage format (TIFF/F or raw), see Section 5.3.1. File Format for Incoming Fax Data on page 81.

Storing in Multiple TIFF/F Files

An application can store each page (or group of pages) of a multi-page fax in a separate TIFF/F file.

The DFS_MPS and/or DFS_EOM value tells the receiver to store individual pages of a multi-page fax in separate TIFF/F files. When you execute fx_rcvfax( ) or fx_rcvfax2( ) in a loop delimited by a DFS_MPS or DFS_EOM (and the default, DFS_EOP), the application will specify a different file each time the receive fax function is issued.

Incoming fax data stored as TIFF/F files can be delimited by the following Phase D command values, sent from the transmitter to the receiver:

DFS_EOP (End of Procedure) - default. Indicates to the receiver that the fax procedure has completed. This setting stores all incoming pages into a single multi-page TIFF/F file. The fax phone line is still active after a DFS_EOP. To terminate the call, set the voice channel on-hook.

DFS_MPS (Multi-Page Signal). Indicates to the receiver that there is more fax data to follow, and the next page is in the same format as the page just received. The application proceeds to T.30 Phase C.

DFS_EOM (End of Message). Indicates to the receiver that there is more fax data to follow. The application returns to T.30 Phase B and negotiates parameters for the next page.

By default, incoming fax data is delimited by the reception of DFS_EOP from the transmitter. For example, if the FC_ENDDOC parameter is set to DFS_EOM, the incoming fax is delimited on DFS_EOM as well as the default value of DFS_EOP.

When the receiver station receives DFS_EOM or DFS_EOP from the transmitter, fx_rcvfax( ) completes, returns a 0 (in synchronous mode) or a TFX_FAXRECV event is generated (in asynchronous mode), and control is returned to the application.

The application must then check the Phase D command using ATFX_PHDCMD( ) to determine if more fax pages will follow or if the last page of the fax has been stored (DFS_EOP). If there are more fax pages to follow, the application must issue another fx_rcvfax( ) function specifying a different file for storage. When the last page of the fax has been stored, a DFS_EOP value is present indicating the end of fax reception.

Storing in a Raw File

Incoming fax data stored in a raw file contains unstructured fax data that does not conform to TIFF/F or other formats.

Incoming fax data stored in a raw file in MH or MMR encoding is written with a fill order of LSB (Least Significant Bit) first.

For MH: EOL (end of line) sequences are not byte aligned.

For MMR: No EOL (end of line) sequences, byte alignment or zero fill.

Storage in raw files is automatically delimited by all of the following Phase D status command values sent from transmitter to receiver. This means that the receive function returns control to the application on all FC_ENDDOC values. The transmitter application sets these values using the FC_ENDDOC parameter in fx_setparm( ).

• DFS_EOM (End of Message)
• DFS_EOP (End of Procedure)
• DFS_MPS (Multi-Page Signal)

At the end of every fax page received for storage in a raw file, the fx_rcvfax( ) function completes, returns a 0 (in synchronous mode) or a TFX_FAXRECV event occurs (in asynchronous mode). The application must then check the Phase D command using ATFX_PHDCMD( ) to determine if more fax pages will follow (DFS_EOM or DFS_MPS) or if the last page of the fax has been stored (DFS_EOP). If there is another page of fax data to follow, the application must issue another fx_rcvfax( ) function for that page specifying a different raw file for storage. When the last page of the fax has been stored, a DFS_EOP Phase D value is present indicating the end of fax reception.

5.2.3. Setting Acceptable Percentage of Bad Scan Lines

You can specify the percentage of bad scan lines acceptable during a fax page reception before an RTP (Retrain Positive) and an RTN (Retrain Negative) message are sent to the transmitter at the completion of the fax page. To set this percentage, use the fax channel parameters FC_RTP and FC_RTN in fx_setparm( ).

To determine the number of pages received that required an RTN (Retrain Negative) to be returned to the remote station, call the fax extended attribute ATFX_RTNPAGES( ).

5.2.4. Selecting Preferred Maximum Receive Baud Rate

You can specify the maximum preferred baud rate for fax data reception.

To receive fax transmissions at a lower baud rate than the default, set the FC_RXBAUDRATE parameter in fx_setparm( ) to one of the supported baud rates. The default baud rates are the highest supported rates for a product (see Section 2.4. Key Product Features on page 8).

This parameter is useful when receiving fax transmissions over known noisy lines. By setting a lower baud rate than the default, no time is wasted in negotiating baud rates.

5.2.5. Replacing Bad Scan Lines

Noise on the telephone line can cause scan line errors. During the reception of MH encoded fax data, the integrity of every scan line in the data stream is checked. When a scan line error is detected, Bad Line Replacement (BLR) automatically replaces the bad scan line(s) with the last correctly received scan line.

MMR encoded data uses T.30 Error Correction Mode (ECM) to ensure error-free transfer. The fax library verifies the integrity of the MMR encoded data before storage. The capabilities of the remote station determine if ECM is used.

To return the number of bad scan lines detected and replaced on a received page, call the fax extended attribute ATFX_BADSCANLINES( ).

If the number of bad scan lines received per page is higher than the percentage of bad scan lines you will accept, the fax channel may request retraining before receiving the next page or retransmission of the current page (see the FC_RTN and FC_RTP parameters in fx_setparm( )).

NOTE:

When fax data is stored in a TIFF/F file, the bad scan line count is written to the BadFaxLines TIFF/F tag. To verify that the bad scan lines were replaced before storage, the CleanFaxData TIFF/F tag is set to zero.

5.2.6. Routing Fax Data to Multiple Subaddresses

When the T.30 subaddress message is received from the transmitter during Phase B negotiation, the fax data following the negotiation can be routed to the subaddress specified.

One model for implementing the subaddress feature is to store the subaddresses in a file and the incoming fax data in separate files, one file containing the fax data for each subaddress. After receiving fax data for all subaddresses and the fax session is complete, the application can distribute the fax data as specified in each subaddress.

Set the application to receive fax data containing subaddress information as follows:

1. Set the FC_ENDDOC fax parameter to DFS_REMOTESUBADDR in fx_setparm( ) to keep fax pages destined for different subaddresses in separate files. When this bit is set and a T.30 subaddress message is received from the transmitter, control is returned to the application after fx_rcvfax( ) or fx_rcvfax2( ) receives the fax data specified for the subaddress sent during the last Phase B negotiation.

NOTE:

When the FC_ENDDOC parameter is set with the DFS_REMOTESUBADDR flag and an EOM is received by the remote fax machine, the application may receive both a TFX_PHASED and a TFX_FAXRECV event for the same page. Under normal circumstances the last TFX_PHASED is replaced by the TFX_FAXRECV, but in this case the fx_rcvfax( ) or fx_rcvfax2( ) function will not know that it needs to return to the application until after it has already completed Phase D.

1. Set the DF_PHASEB rcvflag bit in fx_rcvfax( ) or fx_rcvfax2( ). This bit enables the generation of Phase B events.
2. After a Phase B event is generated, call the ATFX_BSTAT( ) function to see if the DFS_REMOTESUBADDR bit flag is set. If this bit is set, the incoming fax data contains valid subaddress information.
3. Store the subaddress information contained in the fx_getparm( ) FC_REMOTESUBADDR fax parameter for later use when directing the fax data to the phone number(s) and/or extension(s) specified in the subaddress message.
4. When fx_rcvfax( ) or fx_rcvfax2( ) completes, check the Phase D command from the sender using ATFX_PHDCMD( ). If the Phase D command is not DFS_EOP (End Of Procedure), call fx_rcvfax( ) or fx_rcvfax2( ) again to receive more fax data from the transmitter.
   
   The application must call fx_rcvfax( ) immediately after subaddress information is received or an EFX_NXTCMDRX error may be generated indicating a time out while waiting for the next fx_rcvfax( ) call.
5. Continue to check for T.30 SUB messages during Phase B negotiation and collect the subaddress information for each subaddress during the fax session for later routing. When a DFS_EOP is returned by ATFX_PHDCMD( ) in Step 5, no additional fax data is sent for the fax session.

Click here to contact Dialogic Customer Engineering