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; Handling Errors in ColdFusion MX Developer's Guide

History

ColdFusion MX:

Attributes

Attribute Req/Opt Default Description

type

Optional

Any

  • application: catches application exceptions
  • database: catches database exceptions
  • template: catches ColdFusion page exceptions
  • security: catches security exceptions
  • object: catches object exceptions
  • missingInclude: catches missing include file exceptions
  • expression: catches expression exceptions
  • lock: catches lock exceptions
  • custom_type: catches the specified custom exception type that is defined in a cfthrow tag
  • searchengine: catches Verity search engine exceptions
  • any: catches all exception types

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:

cfcatch variable  Content
cfcatch.type

Type: Exception type, as specified in cfcatch.

cfcatch.message 

Message: Exception's diagnostic message, if provided; otherwise, an empty string; in the cfcatch.message variable.

cfcatch.detail 

Detailed message from the CFML interpreter or specified in a cfthrow tag. When the exception is generated by ColdFusion (and not cfthrow), the message can contain HTML formatting and can help determine which tag threw the exception.

cfcatch.tagcontext 

An array of tag context structures, each representing one level of the active tag context at the time of the exception.

cfcatch.NativeErrorCode

Applies to type = "database". Native error code associated with exception. Database drivers typically provide error codes to diagnose failing database operations. Default: -1.

cfcatch.SQLState

Applies to type = "database". SQLState associated with exception. Database drivers typically provide error codes to help diagnose failing database operations. Default: -1.

cfcatch.Sql

Applies to type = "database". The SQL statement sent to the data source.

cfcatch.queryError

Applies to type ="database". The error message as reported by the database driver.

cfcatch.where

Applies to type = "database". If the query uses the cfqueryparam tag, query parameter name-value pairs.

cfcatch.ErrNumber

Applies to type = "expression". Internal expression error number.

cfcatch.MissingFileName 

Applies to type = "missingInclude". Name of file that could not be included.

cfcatch.LockName

Applies to type = "lock". Name of affected lock (if the lock is unnamed, the value is "anonymous").

cfcatch.LockOperation

Applies to type = "lock". Operation that failed (Timeout, Create Mutex, or Unknown).

cfcatch.ErrorCode

Applies to type = "custom". String error code.

cfcatch.ExtendedInfo

Applies to type = "application" and "custom". Custom error message; information that the default exception handler does not display.

Advanced Exception types

You can specify the following advanced exception types in the type attribute:

ColdFusion advanced exception type

COM.Allaire.ColdFusion.CFEXECUTE.OutputError

COM.Allaire.ColdFusion.CFEXECUTE.Timeout

COM.Allaire.ColdFusion.FileException

COM.Allaire.ColdFusion.HTTPAccepted

COM.Allaire.ColdFusion.HTTPAuthFailure

COM.Allaire.ColdFusion.HTTPBadGateway

COM.Allaire.ColdFusion.HTTPBadRequest

COM.Allaire.ColdFusion.HTTPCFHTTPRequestEntityTooLarge

COM.Allaire.ColdFusion.HTTPCGIValueNotPassed

COM.Allaire.ColdFusion.HTTPConflict

COM.Allaire.ColdFusion.HTTPContentLengthRequired

COM.Allaire.ColdFusion.HTTPContinue

COM.Allaire.ColdFusion.HTTPCookieValueNotPassed

COM.Allaire.ColdFusion.HTTPCreated

COM.Allaire.ColdFusion.HTTPFailure

COM.Allaire.ColdFusion.HTTPFileInvalidPath

COM.Allaire.ColdFusion.HTTPFileNotFound

COM.Allaire.ColdFusion.HTTPFileNotPassed

COM.Allaire.ColdFusion.HTTPFileNotRenderable

COM.Allaire.ColdFusion.HTTPForbidden

COM.Allaire.ColdFusion.HTTPGatewayTimeout

COM.Allaire.ColdFusion.HTTPGone

COM.Allaire.ColdFusion.HTTPMethodNotAllowed

COM.Allaire.ColdFusion.HTTPMovedPermanently

COM.Allaire.ColdFusion.HTTPMovedTemporarily

COM.Allaire.ColdFusion.HTTPMultipleChoices

COM.Allaire.ColdFusion.HTTPNoContent

COM.Allaire.ColdFusion.HTTPNonAuthoritativeInfo

COM.Allaire.ColdFusion.HTTPNotAcceptable

COM.Allaire.ColdFusion.HTTPNotFound

COM.Allaire.ColdFusion.HTTPNotImplemented

COM.Allaire.ColdFusion.HTTPNotModified

COM.Allaire.ColdFusion.HTTPPartialContent

COM.Allaire.ColdFusion.HTTPPaymentRequired

COM.Allaire.ColdFusion.HTTPPreconditionFailed

COM.Allaire.ColdFusion.HTTPProxyAuthenticationRequired

COM.Allaire.ColdFusion.HTTPRequestURITooLarge

COM.Allaire.ColdFusion.HTTPResetContent

COM.Allaire.ColdFusion.HTTPSeeOther

COM.Allaire.ColdFusion.HTTPServerError

COM.Allaire.ColdFusion.HTTPServiceUnavailable

COM.Allaire.ColdFusion.HTTPSwitchingProtocols

COM.Allaire.ColdFusion.HTTPUnsupportedMediaType

COM.Allaire.ColdFusion.HTTPUrlValueNotPassed

COM.Allaire.ColdFusion.HTTPUseProxy

COM.Allaire.ColdFusion.HTTPVersionNotSupported

COM.Allaire.ColdFusion.POPAuthFailure

COM.Allaire.ColdFusion.POPConnectionFailure

COM.Allaire.ColdFusion.POPDeleteError

COM.Allaire.ColdFusion.Request.Timeout

COM.Allaire.ColdFusion.SERVLETJRunError

COMCOM.Allaire.ColdFusion.HTTPConnectionTimeout

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>

View comments in LiveDocs