How and when to use RaiseError

Imagine that you have two programs, both of which output measurement files that you want to read into DIAdem. Both formats are written to files with the extension *.dat. Otherwise the formats are different enough that it makes a lot of sense to write a separate DataPlugin for each of them. How do you make sure that DIAdem and the DataFinder use the correct DataPlugin for the correct files?

The answer is that you need to write code in each of your two DataPlugins to recogize invalid files. Most file formats make this possible in some way or another. For example, some programs write their own names, or software version numbers somewhere close to the top of the file. Some file formats start with a header with fields containing numbers and text. If the fields can't be parsed, (for example, the value of an enumeration doesn't match its known possible values, or you find text where you were expecting a number) then that is a sign that the file doesn't match your plugin.

Once you've recognized an invalid file, the proper way to indicate the error, is to call RaiseError with a text describing the problem. How detailed your description is depends on who will use your DataPlugin. If you expect your DataPlugin to read files which users tweak by hand with a text editor, then you would help your users most with a very detailed message. If your DataPlugin reads one file format which can be written in several versions and you don't support all of them, then you could try to break the possible errors down by file format version. Otherwise it is enough just to call RaiseError with a simple statement that the file contains an unsupported format.

Now you may be thinking, "My file extension is pretty unique, so I don't have to worry about another program using the same file extension". Sometimes developers mis-estimate the likelihood that another program might have the same file extension. With only three letters the chance of someone else randomly hitting your combination is actually pretty high. Here are some other good reasons for programming some format-recognition code:

• The program which writes the file may come out in a new version which supports new features for its formats. If this happens, your DataPlugin may incorrectly read the new version of this format.
• The program which writes the file could contain a bug which causes it to occasionally write corrupted files.

In these kinds of cases you would probably rather see an error message, than wonder why your data look so odd.