On rare occasions, a picture or document pasted or imported into Helix Client is stored improperly, resulting in a collection that reports Fatal Damage when Helix Utility is used to do a Data Damage Check or Data Damage Repair. This technote explains how to determine if damage reported by Helix Utility is of this nature and how to potentially resolve it.

Fatal Damage, as reported by Helix Utility, can take many shapes. Typically damage occurs when the data that Helix is working with in memory is not successfully transferred to the collection file stored on disk. This can happen as a result of network noise, hardware issues, bugs in OS X, bugs in Helix, or even external influences.

This technote is strictly about two types of errors; errors that are reported when a picture pasted into a Helix Picture field, or a document imported into a Helix Document field, is corrupted during storage. The corrupt picture (or document) often appears to display correctly, but even minute errors are detected and reported by Helix Utility’s Data Damage Check/Repair tests. Essentially, these errors indicate that the checksum Helix calculated for the picture/document does not match the actual data stored. Whether the error is in the actual data or the checksum, the ‘damage’ is contained within the picture/document object stored in Helix. Therefore, removing the picture/document removes the damage. This effectively makes it possible for the end user to repair the collection, avoiding the need to send the collection to QSA ToolWorks.

These specific errors are referred to as 1601 and 1801 errors. They are so named because the output of the Helix Utility Diagnostic Mode Error Queue contains one or more lines beginning with those numbers when a corrupt picture or document (technically, a byte stream) has been detected. So, in order to determine whether or not your damage is caused by a 1601 or 1801 error, you must first know how to get Helix Utility to produce an Error Queue.

During the normal operation, the contents of a Helix collection are in flux, as internal objects are created and destroyed in the process of supporting the operations. During normal operation, these transient objects are disposed of when a collection is closed. However, some situations (crash, power fluctuation, Helix bug) can occasionally cause a transient object to be left in the collection. These are sometimes reported as fatal damage.

Helix RADE, Engine, and Server also contain routines that verify the internal objects when a collection is opened, disposing of transient objects that were left by accident. So it is occasionally possible to ‘repair’ a collection simply by reopening it with Helix RADE, Engine, or Server. Then close the collection normally and recheck with Helix Utility and Update Collection before you conclude that your collection is truly damaged.

To get the Error Queue file, you must run Helix Utility in Diagnostic Mode. You do this by holding the Control key down while Helix Utility launches. Helix Utility beeps once during launch to let you know that you have successfully entered Diagnostic Mode.

Note that if you hold the Control key down before clicking on Helix Utility, the OS X Contextual Menu pops up. (When this happens, select Open from the menu and continue to hold the Control key down while Helix Utility launches.) The easiest way to enable Diagnostic Mode is to use this drag and drop technique: click (and keep holding the mouse button down) on the collection, then press and hold the control key, then drag the collection onto Helix Utility. Release the mouse button when Helix Utility highlights, but do not release the Control key until you hear the beep. If you do not hear the beep, check the volume on your computer, then quit Helix Utility and try again.

Now that Helix Utility is in Diagnostic Mode, open the collection as always and choose Data Damage Check from the Tools menu; the check proceeds as usual. If damage is found, a dialog box appears asking you to save the Error Queue. Save this file.

Open the error queue file (it is plain text, so any text editor should work) and look at the lines in the file. The first line is simply an identifier (ignore it) but the rest of the lines contain data we use to identify the types of errors and their locations within the collection. If you see lines that start with 1601 or 1801 it might be possible to repair the collection by deleting the damaged pictures or documents that are triggering these errors.

If the error queue does not contain any lines beginning with 1601 or 1801, the following information will not help repair the collection. If it contains some lines beginning with 1601 or 1801 along with other types of errors, it might help. Either way you are encouraged to send the Error Queue file to technical support. We may be able to suggest a method of removing that particular type of damage. At the very least, we should be able to give you an estimate on how long a repair would take.

The Error Queue file contains hexadecimal codes that are used by Helix Technical Support to identify the damaged sections of the collection and to remove the damage. Unfortunately, there is nothing in the Error Queue that can help you identify exactly which records the damage is in. The queue is generated with the expectation that it will be read by people trained in doing collection repair.

However, our technical support department has created two scripts that can help. These scripts can use the information in the error queue file to provide information that should enable you to identify the affected record. With the affected record identified, open the collection, go to the affected record and remove the damaged picture/document. Then Save the collection, Quit Helix, and (after making a backup) run Helix Utility again; the collection should now pass.

In the event that it still does not pass, quit the Utility, open the collection again in Helix RADE, Server or Engine, entering your username and password if necessary, and quit and save. Then try the Utility again.

At this point, if you like, you can paste or import the offending picture or document back into the field without fear — Helix will recalculate the checksum based on the current contents of the picture and the error should not return.

The Picture field datatype is one of the original options in Helix. It stores picture data in PICT format, which has been replaced by various cross-platform formats in OS X. Although we will continue to support the Picture field for as long as possible, a future version of OS X may render it obsolete. In fact, under OS X 10.6, the Preview application can not display PICT files unless Preview is run in 32-bit mode. (But QuickLook can display the PICT file contents.)

Consequently, our recommendation is to use the Document field datatype instead. Documents containing images of various formats can be displayed in Helix by creating an abacus containing a picture tile (with the document field in its hole) and placing that abacus on any template where the picture should be displayed.

Our file server has some sample scripts that show techniques used to extract PICTs from Helix so they can be saved as files.