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.

Syntax

<cfcatch type = "exceptiontype">
   Exception processing code here
</cfcatch>

History

ColdFusion MX:

Changed SQLSTATE value behavior: the SQLSTATE return value in a cfcatch tag depends on the database driver type:
- Type 1 (JDBC-ODBC bridge): the value is the same as in ColdFusion 5
- Type 4 (100% Java, no native methods): the value might be different
Changed the behavior of this tag when type="any": it is not necessary, when you include a cfcatch tag with type="any", to do so in the last cfcatch tag in the block, to ensure that all other tests are executed before it. ColdFusion finds the best-match cfcatch block.
Changed the behavior of the cfscript tag: it includes try and catch statements that are equivalent to the cftry and cfcatch tags.
Changed object modification: you cannot modify the object returned by cfcatch.
Changed thrown exceptions: the cfcollection, cfindex, and cfsearch tags can throw the SEARCHENGINE exception. In earlier releases, an error in processing these tags threw only an UNKNOWN exception.

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:

"custom_type"
"Application"
"Any"

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