HOWTO: Troubleshoot Rendering issues

ZTN1301

Monday, October 31, 2005

ID: ZTN1301

This Zetafax technical note applies to:

Zetafax 8 and later

Summary

When using the e-mail gateway to send faxes it is possible to send document attachments which are converted into faxes using either the 'Mail Rendering Subsystem (MRS)' printer on the Zetafax server system or the 'Document Conversion add-on (DOCTIFF)'. Some times the process used to convert attachments fails. This document describes the process and details procedures to troubleshoot problems that you may be experiencing with either of the above.

The problem description and symptom will determine which area below to begin your troubleshooting.

DOCTIFF issues rendering

Symptoms can include:

All PDF attachments failing via Email gateway, API or Web client
All faxes with attachments failing
Graphic Quality not up to standard
Layout or font issues
Fax converted to pages of code
Landscape PDFs rendering in Portrait
Some embedded fonts don't render well
Text output looks patchy
Certain PDFs render as thousands of pages
Rendering add on fails on Terminal services machines
Rendering add on fails where the display cannot handle high resolution

All PDF attachments failing via Email gateway or ZSUBMIT

When submitting a PDF document to Zetafax, either in a ZSUBMIT file or through the Email Gateway, Epstiff attempts to render the document, rather than pass it to DOCTIFF. This is characterised in the Zetafax server by the fact the DOCTIFF is not launched, and that the resulting document is a textual representation of the PDF encoding characters, rather than the PDF document itself. Fix is a later build of Epstiff referenced in ZTN1409 FIX: PDF documents do not render correctly

All faxes with attachments failing

This is rare and can mean one of two things. DOCTIFF not starting could mean it is not licensed. To check this open the Zetafax configuration and Modify Licence details to check that a rendering add on licence is installed and registered. Secondly it could mean that DOCTIFF is licensed but Adobe or other installed applications haven't been removed from the rendering options in the gateway configuration. If you remove these and restart the server, DOCTIFF should start up.

Graphic quality not up to standard

Change the Maximize Graphics setting in setup.ini DOCTIFF paragraph from NO to YES as per ZTN1298-HOWTO Change the maximum size of graphic files on sent using the document conversion Add on DOCTIFF.EXE
DOCTIFF settings for file conversion can also be optimised as per ZTN1419-HOWTO Optimise Rendering add-on settings for file conversion

Note: Try changing the IGFunc to each option one by one to see if quality improves. Diffusion is very process intensive and if quality doesn't improve any more than with the other options, leave it set to Bayer which is the default from Zetafax 9 SP1 onwards.

Further to this there is one other thing to try alongside these two technotes. The graphic threshold can be increased to above the default of 2800. To determine how much, create a DOCTIFF enabled server log file as per ZTN1065-INFO: Enabling detailed logging within Zetafax.

Increasing the graphic threshold: It is possible to increase this to higher than the 'twips' size of the document presented. (A twip is 1/1440th of an inch and the unit of measurement that DOCTIFF works in). The only way to tell what it is for sure is to render the document with logging enabled, capture the server log file and see what the size is in twips. If for example your document presents as 'Page dimensions: 4954 x 6997 twips' then increase the Graphic Threshold to 7000 to cope with the higher of the two sizes. There is no set rule about this but it is possible to go as far as approximately 40000 which will render larger size documents.

If all of the above doesn't work, the graphics within the document may need to be reworked in fewer colours, or at a lower resolution.

Layout or font issues

There is a known DOCTIFF issue with Microsoft Word documents which have tables within tables which don't render well. There is currently no known release date for a fix.
Larger resolution attachments can cause layout issues. If the fax renders fine, but comes out at half or even a quarter of the size of the original document, increase the graphic threshold as above to fix this. For example a standard 200x200 DPI tiff will render fine with the graphic threshold set to the default, however a 600x600 DPI tiff would render at a quarter of the original size. 3. Another known issue is text placed close to margins, can cause some blurring between the text and the lines. There is no known fix for this; therefore the document would have to be reworked to prevent it.

Once again if the above doesn't work, the graphics within the document may need to be reworked in fewer colours, or at a lower resolution.

PDFs converted to pages of code

This is another symptom of Epstiff failing to pass the file to DOCTIFF. The updated Epstiff in ZTN1409 FIX: PDF documents do not render correctly will fix this.

Landscape PDFs rendering in Portrait

DOCTIFF will read the properties of the PDF it is presented with and if the PDF you send is appears to be portrait but really is in landscape (although not obviously so) then it will be rendered in landscape. To check if this is the case go to the advanced properties of the document. If for example Adobe reports the page size as 11 X 8.5 which refers to width and length, then this implies that it is the PDF presenting as landscape rather than DOCTIFF reading it incorrectly.

Some embedded fonts don't render well

Barcode fonts are mainly created from text and sometimes they render well and sometimes they don't. ZTN1352-FIX Rendering (DOCTIFF.exe) add-on uses incorrect fonts might help, as long as you know what font the document uses (as stated in its properties). The reason for this is that one of the easiest ways to create barcodes is using a text string and the current limitation of the Stellent technology Outside In is that it does not render embedded PDF fonts.

This also applies to all other fonts which you attempt to render, but don't exist on the Zetafax server. The above technotes should help in this circumstance also.

Text output looks patchy

If text output looks patchy then font smoothing may need to be turned off. If the server has Windows font smoothing switched on, the rendered output may look rather patchy. Note: This affects text only and not images. The reason is that font smoothing works at a low level, and the output that the Stellent engine generates for each page uses the font smoothing algorithm. This introduces grey to smooth the edge of the font. However, we dither the image to black and white for faxing, which means the grey edges are lost and quality suffers.

The fix in this case is to switch OFF font smoothing on the server as follows:

Go to Control Panel/Display
Click on the Appearance tab
Click on the Effects button
Ensure font smoothing is switched off.

Certain PDFs render as thousands of pages

PDFs created in more obscure applications (such as PDF factory for example) may not get rendered very well. If you come across this issue please upgrade to Zetafax 9.1. Scala (which is a Crystal Reports PDF creator) is another application that creates non standard PDF files. In almost all circumstances Acrobat Distiller creates PDFs of a standard that DOCTIFF can render very well.

Rendering add on fails on Terminal services machines

When the rendering add-on (DOCTIFF) renders a document attachment, the following error (or similar) can occur in the Zetafax server log:

DOCTIFF - (E) - DIB bitmap creation failed, LastError = 8

QUEUEMAN - (E) - Error converting message (0xF206)

This error can occur on a machine which has Terminal Services installed, even if not activated. ZTN1314-PRB Rendering add-on fails on Terminal Services describes how to fix this issue which is basically to uninstall Terminal Services from the server on which Zetafax is installed, or install the Zetafax Server on a non -Terminal Services machine.

Rendering add on fails where the display cannot handle high resolutions

On systems with low-spec video cards, upgrading the video card to at least 8MB of video memory may fix the problem created by the card only handling 16-bit colour for example. See ZTN1314-PRB Rendering add-on fails on Terminal Services for further details.

MRS Issues Rendering

The DOCTIFF add on is not the cure all for all MRS rendering issues. When using the e-mail gateway to send faxes it is possible to send document attachments which are converted into faxes using the 'Mail Rendering Subsystem' printer on the Zetafax server system and an application capable of reading and converting these documents. Quality is often better when using the native application however sometimes the process used to convert attachments fails. This section describes the process, and details procedures to troubleshoot problems that you may experience with the mail rendering subsystem.

The Process:-

The process of converting an attached file is as follows:

When you send an email containing an attachment, it passes from the email server into the Zetafax server application.
The Email is separated from the attachment which is then opened on the Zetafax server system. This places the file temporarily into the Zfax\Mail\ST
Using an application that is able to view that particular file type, the attachment is printed to the Mail Rendering Subsystem printer e.g. Microsoft Word is normally used to print .DOC and .RTF attachments.
The Mail Rendering Subsystem printer creates a .TIFF image of the attachment file in the Zfax\MAIL\ST folder.
Zetafax picks up the .TIFF image file and sends it as part of the final fax

Symptoms of the MRS not working can include the following:

Sending a plain text message with no attachment works correctly but messages in Rich text or HTML format or with an attachment fail
All attachments fail
Some attachments fail i.e. Microsoft Word or PDF
Faxes rendered as lines of code
Multiple attachments fail but single ones work - PDF only
Single attachment but to multiple recipients fails - PDF only

Sending a plain text message with no attachment works correctly but messages in Rich text or HTML format or with an attachment fail

Error messages can include "Unable to process message", "Internal error, invalid parameters". There are a few things to try here. Firstly ASCII is needed by default in the rendering options of the Email gateway. To rendering RTF install Microsoft Word as a rendering application and associate RTF with it.

If this doesn't work, change the plain text/rich text/html settings in Tools | Options | Mail settings in Outlook. You can also change the default Plain text/rich text/optimised settings in the Tools | Options | Zetafax Options dialog in Outlook - this will change it for all future faxes sent. You can make this change within the Zetafax Options of an individual fax also and if you want to find the best option for rendering, then you can test this on a fax by fax basis.

Note: These settings can also be changed on the connector properties if you are using it, which then makes it the default for every fax sent via the gateway. (In Exchange 5.5 this is under the Site Properties and then Zetafax Options and in Exchange 2000/3 this is the Properties of the Connector under routing groups).

All attachments fail

If a particular document fails to render, check rendering with a different document from the same application. Note: Macros, small margins and non-conventional paper sizes in the document you are trying to send may stop the application from rendering correctly.

Are any attachments sent successfully? Before you troubleshoot rendering, you should ensure that the e-mail gateway is actually sending faxes correctly. Send a plain text e-mail as a fax (not " Rich Text" or " HTML" as mentioned above), and verify that it is sent successfully. If the plain text fax is not sent, then you probably have an e-mail gateway, Zetafax server, or connector problem, which is not covered in this document. If the plain text fax is sent successfully, continue with this document.

Things to try before contacting Technical Support are:-

Does printing to the Mail Rendering Subsystem printer work? Open a document in the application that is failing, and print it to the Mail Rendering Subsystem printer. This should create a TIFF file in the Zfax\MAIL\ST folder.

If the Mail Rendering Subsystem printer is not available, or a TIFF image is not created when you print to it, then there is a problem with the Mail Rendering Subsystem printer. Please refer to ZTN1025 HOWTO Reinstalling the Mail Rendering Subsystem driver for instructions on how to reinstall this printer.

Does right-clicking on a file and selecting FaxConvert work?

If the Mail Rendering Subsystem is working correctly, then there may be a problem with the command used to print the document from the e-mail gateway.

In some cases, this may be incorrect or became corrupt. Reinstalling the MRS printer as per ZTN1025 HOWTO Reinstalling the Mail Rendering Subsystem driver will reinstall the FaxConvert.

Does rendering fail when the Zetafax server runs as a service but works when Zetafax runs as an application? In some cases, rendering may only fail if the Zetafax Server is running as a service.

Note: When Zetafax is running as an application, the rendering applications will open up on screen, which may disrupt any work the user is doing on the server desktop.

If rendering works correctly with the Zetafax Server running as an application, check whether the account the service is using is causing problems. It is also worth noting that if your e-mail server is on a different machine than the Zetafax Server, the service will need to run with an account which has access to other machines i.e. your mail server (so LocalSystem is not suitable). ZTN1227-PRB Word documents may not be rendered when Zetafax is run as a service on some systems describes how Microsoft Word documents can fail when Zetafax runs as a service.

Note: On some systems rendering will not work for any attachments where the email gateway files are installed on any drive other than the C drive of the Zetafax server. If troubleshooting doesn't work, there is evidence that moving the Zetafax Server \ Mail folder to the C drive, and change the path reference in two files. The first is the Zetafax Server \ Zetafax.ini file (this file resides in the system Windows directory pre Version 9). The second is the stm.ini file, which lives in the system Windows folder (regardless of the version of Zetafax).

Some attachments fail i.e. Microsoft Word or PDF documents

If you usually only send one type of attachment (for example, Microsoft Word documents), check whether other types of attachments fail as well. If only one type of attachment fails, there may be something wrong with that application's installation on the Zetafax Server.

There are a few known issues in this area:-

The Office Assistant or an error message appears when you open the application on the Zetafax Server. Disable the Office Assistant or troubleshoot the error message to solve the problem.
The command used to call Microsoft PowerPoint in Zetafax 7.0 was incorrect for Windows 2000 machines. Refer to technical note ZTN1147-PRB: PowerPoint files fail to render on Windows 2000 Zetafax servers for more information on this one.
Adobe Acrobat 4.05 has been installed on the server at some point. There was a flaw in this version of Acrobat which stopped rendering from working. Upgrading to Acrobat 5.0 does not fix this problem, because parts of 4.05 will remain intact. The solution is to install Acrobat 3.0. This problem does not affect clean installations of Acrobat 4.0, 5.0, 6.0 or 7.0. See ZTN1150-PRB Acrobat Reader 4.05 does not render PDF documents through the mail gateway for more on this.
Sometimes Adobe Reader cannot convert more complex PDFs, and the symptoms include failure and/or lack of quality. Installing Adobe Acrobat Professional on the Zetafax server may work in this circumstance. (At this point it may be worth noting that DOCTIFF while also chargeable is worth testing also).
Large Adobe Acrobat PDFs can cause problems. The error you would see is Error 'Invalid control character 0x06 in EPSON file'. This behaviour is described in technical note ZTN1224-PRB Error 'Invalid control character 0x06 in EPSON file' when rendering Adobe PDF files. Zetafax 9.1 contains an Epstiff that should fixes these errors.

Faxes rendered as lines of code

This is in fact RTF. To fix this associate RTF with a valid application in the rendering options of the gateway, Microsoft Word for example. It is sometimes possible to render simple RTF documents by associating RTF with WordPad rather than Microsoft Word. It isn't enough to save a file with the RTF extension; it has to be a genuine RTF file to be rendered by Microsoft Word.

For example, saving a file from another unknown Word processing application as an .RTF or indeed .DOC file won't automatically mean it will be converted successfully.

Multiple attachments fail but single ones work

Rendering a Tiff and a PDF together, you have to attach the tiff to the email first and then the PDF or the fax will fail. It can also happen that multiple attachments cause the process running the rendering application on the server to open and close more times than the application can handle and once it freezes all subsequent faxes fail.

Single attachment but to multiple recipients fails - PDF only

This only happens with Adobe Acrobat which launches the document on the server in order to render it. Once the attachment is rendered the kill process in Gateway closes the document, however the reader is left open, meaning that it cannot be launched again. Given that in order to render, the application has to be launched every time this causes a problem when multiple PDF's are rendered together. A new feature of Adobe Acrobat 7.0 should fix this and can be used to do the rendering. See ZTN1452-HOWTO: Render PDF documents sent via the email gateway when using Adobe Acrobat 7 ®.