Error Handling With Fusebox Presentation By Eron Cohen

What We’ll Learn How to handle Errors with ColdFusion: CFERROR CFTRY/CFCATCH/CFTHROW A little bit about the Fusebox method of writing ColdFusion applications How does it work? Why is it so good for catching and logging errors?

CFERROR vs. CFTRY There are two basic ways to handle errors with CFML: CFERROR and CFTRY. CFTRY is more flexible than CFERROR. CFERROR is a bit easier because its more “cut and dry.” With CFERROR processing usually stops when you throw an error, with CFTRY, processing can continue. CFTRY allows for a finer level of control than CFERROR. CFTRY allows you to handle the error on the same template that threw the error. For a Fusebox application, you’ll probably want to use CFTRY. CFERROR isn’t as flexible and doesn’t lend itself to FUSEBOX as well.

How To Use CFERROR The CFERROR tag is normally used in the APPLICATION.CFM file so that it will be included at the top of every Cold Fusion template. Syntax: If an error is thrown during the execution of a page that is within the realm of your APPLICATION.CFM, the template that you specified will execute. Depending on what type of CFERROR you specify, there are certain restrictions on how you can handle the error. For instance, if you specify the type “REQUEST”, your error handling template cannot contain any CFML tags…it can only output a predetermined list of variables combined with HTML. On the other hand, if you specify the type “Exception” you’ll have the ability to utilize the full-range of CFML functions.

Example of how to use CFERROR APPLICATION.CFM: REQUESTERR.CFM: There was an error: Date/Time: #Error.DateTime# IP Address: #Error.RemoteAddress# Referring Page: # Error. HTTP_REFERER# Offending Script: #error.script_name#"

How to Use CFTRY/CFCATCH For every pair, there needs to be at least one. The syntax is something like:... Add code here.... Add exception processing code here.... Add exception processing code here

Types of Exceptions Used With CFCATCH These are the types of exceptions you can specify in your CFCATCH statement: Application, Database, Template, Security, Object, MissingInclude, Expression, Lock, Custom_type, Any (default). – You can have multiple CFCATCHES to handle different types of errors. – ColdFusion tests CFCATCH types in the ORDER THEY APPEAR on your page! – Type=“Any” is the catch all. It will execute in the face of any type of error. Put that one at the end of your block of CFCATCHES (or if you only specify one CFCATCH, use this one!). Also keep in mind that they really do mean “ANY!” kind of error. – If an error is thrown for a type of error that has no CFCATCH to handle it, it will throw its default error. – The “Custom” and “Application” types of errors are used with the CFTHROW tag.

Variables Exposed to CFCATCH A CFCATCH block may contain certain informational variables. Here are a few of them: Type -- Exception type, as specified in CFCATCH. Message -- The exception's diagnostic message, if one was provided. If no diagnostic message is available, this is an empty string. Detail -- A detailed message from the CFML interpreter. This message, which contains HTML formatting, can help determine which tag threw the exception. TagContext -- The tag stack: the name and position of each tag in the tag stack, and the full path names of the files that contain the tags in the tag stack. See the note that follows this list for more information. NativeErrorCode -- TYPE=Database only. The native error code associated with this exception. Database drivers typically provide error codes to assist diagnosis of failing database operations. If no error code was provided, the value of NativeErrorCode is -1. SQLSTATE -- TYPE=Database only. The SQLState associated with this exception. Database drivers typically provide error codes to assist diagnosis of failing database operations. If no SQLState value was provided, the value of SQLSTATE is -1. ErrNumber -- TYPE=Expression only. Internal expression error number. MissingFileName -- TYPE=MissingInclude only. Name of the file that could not be included. ErrorCode -- TYPE=Custom type only. A string error code. ExtendedInfo -- TYPE=APPLICATION and custom only. A custom error message.

Leverage Your Error Handling with CFTHROW Now that you’ve designed such great error handlers, why not recycle them using CFTHROW? When a condition occurs in your application, that normally would not throw a ColdFusion error, you can “simulate” one with CFTHROW. CFTHROW allows you to send ColdFusion to one of three kinds of CFCATCH error handlers: CFCATCH TYPE= "custom_type " CFCATCH TYPE= "APPLICATION " CFCATCH TYPE= "ANY " Syntax:

A Brief Explanation of Fusebox The Fusebox method is simply a style of writing code as a “circuit application.” Depending what “fuseaction” is specified, a different CFSWITCH is thrown. Code is modular so it is easy to reuse. Code is self-documenting and easier to read. Code is written to a documented standard so the next time someone works on the code it will be easy to understand.

A Simple Fusebox Example INDEX.CFM:

Fusebox is perfect for trapping errors! One of the great things about the Fusebox methodology is that all actions for the entire application are controlled through one file: your main index.cfm. This means that if you want to trap errors you have a single point of attack to do so. Lets look at my example index.cfm printout…

Gotchas & Mentionables Gotcha: In ColdFusion 4.5 and before, the error handling templates for CFERROR cannot contain any CFML, just a few predetermined variables! Later versions of ColdFusion have added flexibility for some types of CFERRORs. Gotcha: Make sure you don’t have any errors in your CFCATCH. CFCATCH exceptions are not handled by the CFTRYs that enclose it. Mentionable: You can customize your default Cold Fusion and Web server error messages. Sick of seeing ugly white screen 404 errors? You can substitute your own in the webserver software. Cold Fusion Administrator also provides a preference setting for handling problems:

Creative ways to use CFTRY/CFCATCH We log any errors that occur on our website in a database for review at a later time. It means we don’t have to rely on an end user to describe what happened. Problem with CFPOP solved by CFTRY Big Query/little query