cftry

Description

Used with one or more cfcatch tags. 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

<cftry>
  code here
<cfcatch type = "exceptiontype">
  Exception processing code here
</cfcatch>
  Optional: More cfcatch blocks here
</cftry> 

See also

cfcatch, cferror, cfrethrow, cfthrow

History

New in ColdFusion MX: The SQLSTATE return value in a cfcatch tag depends on the database driver type:

If your application depends on SQLSTATE values for flow control, the application might produce unexpected behavior with ColdFusion MX.

New in ColdFusion MX: 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.

New in ColdFusion MX: the cftry and cfcatch tags can be used as cfscript constructs, and for handling component method invocation errors.

New in ColdFusion MX: you cannot modify the structure returned by cfcatch.

New in ColdFusion MX: 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 developer-defined exceptions, defined in the cfthrow tag
  • searchengine: catches Verity search engine exceptions
  • any: catches all exception types

Usage

Within a cftry block, you must code at least one cfcatch tag. Put cfcatch tags at the end of a cftry block. ColdFusion tests cfcatch tags in the order in which they appear.

If type="any", ColdFusion Server 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"), the cfcatch tag can catch the custom type by its character pattern. The tag searches for 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">

The cfcatch tag first searches the cfthrow tag for the entire type string:

  <cfcatch type = "MyApp.BusinessRuleException.InvalidAccount"> 

If it does not find a match, it searches for the next most specific:

<cfcatch type = "MyApp.BusinessRuleException"> 

Finally, it searches for the least specific:

  <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 following example shows how to throw an exception from a component method:

<cfcomponent>
  <cffunction name="getEmp">
  <cfargument name="lastName" required="yes">   
     <cfquery name="empQuery" datasource="ExampleApps" >
       SELECT LASTNAME, FIRSTNAME, EMAIL
       FROM tblEmployees
      WHERE LASTNAME LIKE '#arguments.lastName#'
     </cfquery>
     <cfif empQuery.recordcount LT 1>
       <cfthrow type="noQueryResult" 
        message="No results were found. Please try again.">
      <cfelse>
          <cfreturn empQuery>
      </cfif>
  </cffunction>
</cfcomponent>

For an explanation of the example and more information, see the "Building and Using ColdFusion Components" chapter in Developing ColdFusion Applications.

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 CFML interpreter. The message contains HTML formatting. It can help determine which tag threw the exception.
cfcatch.tagcontext
Tag stack name, position of each tag in the stack, and absolute pathnames of the files that contain the tags in the stack.
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.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

This tag requires an end tag.

Example

<!--- cftry 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 = "cfsnippets">
    SELECT *
    FROM EMPLOYEEAS
  </cfquery>

  <!--- <p>... 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>
      <!--- and the diagnostic message from the ColdFusion server --->
      <p>#cfcatch.message#</p>
      <p>Caught an exception, type = #CFCATCH.TYPE# </p>
      <p>The contents of the tag stack are:</p>
      <cfloop index = i from = 1 
          to = #ArrayLen(CFCATCH.TAGCONTEXT)#>
        <cfset sCurrent = #CFCATCH.TAGCONTEXT[i]#>
        <br>#i# #sCurrent["ID"]# 
          (#sCurrent["LINE"]#,#sCurrent["COLUMN"]#) 
          #sCurrent["TEMPLATE"]#
      </cfloop>
    </cfoutput>
  </cfcatch>
</cftry>

Comments