| CFCATCH | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Description
Used inside a cftry tag. Together, they catch and process exceptions in ColdFusion pages. Exceptions are events that disrupt the normal flow of instructions in a ColdFusion page, such as failed database operations, missing include files, and developer-specified events. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Category
Exception handling tags | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
Syntax<cfcatch type = "exceptiontype"> Exception processing code here </cfcatch> |
||||||||||||||||||||||||||||||||||||||||||||||||||||||
| See also
cftry, cferror, cfrethrow, cfthrow, onError; Chapter 14, "Handling Errors," in ColdFusion MX Developer's Guide |
||||||||||||||||||||||||||||||||||||||||||||||||||||||
| History
ColdFusion MX:
If your application depends on SQLSTATE values for flow control, the application might produce unexpected behavior with ColdFusion MX. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Usage
You must code at least one cfcatch tag within a cftry block. Put cfcatch tags at the end of a cftry block. ColdFusion MX tests cfcatch tags in the order in which they appear. This tag requires an end tag. If type="any", ColdFusion MX catches exceptions from any CFML tag, data source, or external object. To get the exception type use code such as the following: #cfcatch.type# Applications can use the cfthrow tag to throw developer-defined exceptions. Catch these exceptions with any of these type options:
The custom_type type is a developer-defined type specified in a cfthrow tag. If you define a custom type as a series of strings concatenated by periods (for example, "MyApp.BusinessRuleException.InvalidAccount"), ColdFusion MX can catch the custom type by its character pattern. ColdFusion MX searches for a cfcatch tag in the cftry block with a matching exception type, starting with the most specific (the entire string), and ending with the least specific. For example, you could define a type as follows: <cfthrow type = "MyApp.BusinessRuleException.InvalidAccount"> If you have the following cfcatch tag, it will handle the exception: <cfcatch type = "MyApp.BusinessRuleException.InvalidAccount"> Otherwise, if you have the following cfcatch tag, it will handle the exception: <cfcatch type = "MyApp.BusinessRuleException"> Finally, if you have the following cfcatch tag, it will handle the exception: <cfcatch type = "MyApp"> You can code cfcatch tags in any order to catch a custom exception type. If you specify type = "Application", the cfcatch tag catches only custom exceptions that have the Application type in the cfthrow tag that defines them. The cfinclude, cfmodule, and cferror tags throw an exception of type = "template". An exception that is thrown within a cfcatch block cannot be handled by the cftry block that immediately encloses the cfcatch tag. However, you can rethrow the currently active exception with the cfrethrow tag. The cfcatch variables provide the following exception information:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Advanced Exception types
You can specify the following advanced exception types in the type attribute:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||
Example<!--- cfcatch example, using TagContext to display the tag stack. --->
<h3>cftry Example</h3>
<!--- Open a cftry block. --->
<cftry>
<!--- Note misspelled tablename "employees" as "employeeas". --->
<cfquery name = "TestQuery" dataSource = "cfdocexamples">
SELECT *
FROM EMPLOYEEAS
</cfquery>
<!--- Other processing goes here. --->
<!--- Specify the type of error for which we search. --->
<cfcatch type = "Database">
<!--- the message to display. --->
<h3>You've Thrown a Database <b>Error</b></h3>
<cfoutput>
<!--- The diagnostic message from ColdFusion MX. --->
<p>#cfcatch.message#</p>
<p>Caught an exception, type = #CFCATCH.TYPE# </p>
<p>The contents of the tag stack are:</p>
<cfdump var="#cfcatch.tagcontext#">
</cfoutput>
</cfcatch>
</cftry>
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||