Detecting an Error
First of all, the LAS software need to know when a Ferret error occurs. In order to detect errors LAS searches the text that is written by Ferret to STDERR for certain strings. Because Ferret writes many messages to STDERR which are warnings and informational notes, LAS must be configured with an complete list of all text strings that should be considered a fatal error. If the is not complete, then errors will go undetected and the user will get unexpected results in the output window.
The list of error strings that Ferret users can be found in the FerretBackendConfig.xml file. This file is constructed in the configure process from the JavaSource/resources/ferret/FerretBackendConfig.xml.base.in. If a new string needs to be added to the list, it should be added to the FerretBackendConfig.xml.base.in file.
Adding an Error Message
Say for example, a new error message "PPL+ error: You're attempting to use more colors than are available." should be added to the list of error strings. We need to create a new <message> element in the collection of <messages>.
<message type="startsWith" level="error"> <key>PPL+ error</key> <text> An error occurred in the service that was creating your product. </text> </message>
The <key> element is what LAS uses to detect that an error occurred. Since we can reasonably guess that there will be other error messages from Ferret of this form, we tell LAS that any string that "startsWith" the text "PPL+ error" is an "error". The <text> block is the message the user actually sees when this error occurs. If you want them to see the contents of STDERR instead, just leave out the <text> element.
Controlling the Message
To make a product for the user, the Ferret Backend Service runs the legacy analysis and visualization program called Ferret. Well, duh you say. Well duh, indeed, because sometimes Ferret will write out a detailed error message that makes sense to an experienced Ferret user, but would be baffling to an LAS user that just dropped by to make a plot of the latest Sea Surface Temperature field.
To keep these ugly messages from the user (unless they really want to see them) we've created some XML in the FerretBackendConfig.xml file to map Ferret message to friendly message. This file contains all of the error messages that Ferret produces when it fails to make a product and assigns a substitute message that the user will see. Here's the relevant section:
<messages> <message type="startsWith" level="error"> <key>**Error</key> <text> An error occurred in the service that was creating your product. </text> </message> <message type="startsWith" level="error"> <key>**TMAP ERR</key> <text> An error occurred in the service that was creating your product. </text> </message> <message type="startsWith" level="error"> <key>STOP -script mode</key> <text> An error occurred in the service that was creating your product. </text> </message> <message type="startsWith" level="error"> <key>Segmentation</key> <text> An error occurred in the service that was creating your product. </text> </message> <message type="startsWith" level="error"> <key>No such</key> <text> An error occurred in the service that was creating your product. </text> </message> <message type="startsWith" level="error"> <key>**Internet data error</key> <text> A remote server was unable to deliver the data LAS needs to make your product. </text> </message> <message type="startsWith" level="error"> <key>**netCDF error</key> <text> A remote server was unable to deliver the data LAS needs to make your product. </text> </message> <message type="startsWith" level="error"> <key>**Internet Data error</key> <text> A remote server was unable to deliver the data LAS needs to make your product. </text> </message> </messages>
So, when an error occurs (particularly when a remote OPeNDAP server is unable to deliver the data, the page sent to the user will have only the simple message:
A remote server was unable to deliver the data LAS needs to make your product.
The URL of this product. (In the actual output you can use this link to copy the URL of the product into a browser and submit the request again with debugging turned on by adding &debug=debug at the end of the URL.)
More details about this error.
And by following the "More details about this error" link the user can see the full Ferret error message if they want. If for some reason you would prefer that you user see the Ferret error text, which in the case of the example would be:
**Internet Data error OPeNDAP Error: Error while reading the URL: http://www.cdc.noaa.gov/cgi-bin/nph-nc/Datasets/ncep.pac.ocean/otemp.mnmean.nc.dds?. The OPeNDAP server returned the following message: Not Found: The data source or server could not be found. Often this means that the OPeNDAP server is missing or needs attention; Please contact the server administrator. (OPeNDAP/netCDF Error code 1001) Data set: http://www.cdc.noaa.gov/cgi-bin/nph-nc/Datasets/ncep.pac.ocean/otemp.mnmean.nc SET DATA "http://www.cdc.noaa.gov/cgi-bin/nph-nc/Datasets/ncep.pac.ocean/otemp.mnmean.nc" Command file, command group, or REPEAT execution aborted STOP -script mode, ERROR RUNNING SCRIPT statement executed
just remove the <text> MESSAGE </text> element from the <message> element for the type of message you don't want to hide from your user. Don't remove the <message> element or the <key> since that's what allows the Ferret Backend Service know that a problem occurred when making the product.