# CFTRY CFCATCH

Used with one or more CFCATCH tags, the CFTRY tag allows developers to catch and process exceptions in ColdFusion pages. Exceptions include any event that disrupts the normal flow of instructions in a ColdFusion page such as failed database operations, missing include files, and developer-specified events.

### Syntax

    <CFTRY>
    ... Add code here
    <CFCATCH TYPE="exceptiontype">
    ... Add exception processing code here
    </CFCATCH>
    ... Additional CFCATCH blocks go here
    </CFTRY>

#### TYPE

Optional. Specifies the type of exception to be handled by the CFCATCH block:

- APPLICATION (default)
- Database
- Template
- Security
- Object
- MissingInclude
- Expression
- Lock
- Custom_type
- Any (default)

### Usage

You must code at least one CFCATCH tag within a CFTRY block. Code CFCATCH tags at the end of the CFTRY block. ColdFusion tests CFCATCH tags in the order in which they appear on the page.

If you specify the type to be ANY, do so in the last CFCATCH tag in the block so that all of the other tests are executed first.

Note | Specifying the type as ANY causes the ColdFusion Application Server to catch exceptions from any CFML tag, data source, or external object, which your application may not be prepared to handle.

Applications can optionally use the CFTHROW tag to raise custom exceptions. Such exceptions are caught with any of the following type specifications:

- TYPE="custom_type"
- TYPE="APPLICATION"
- TYPE="ANY".

The custom_type type designates the name of a user-defined type specified with a CFTHROW tag. CFCATCH has a catch handler that can catch a custom type by pattern, providing the custom type is defined as a series of strings concatenated together by periods, as in "MyApp.BusinessRuleException.InvalidAccount". CFCATCH searches for a custom type match starting with the most specific and ending with the least specific. For example, you could define a type as follows:

        <CFTHROW TYPE="MyApp.BusinessRuleException.InvalidAccount">

CFCATCH first searches for the entire type string defined in the CFTHROW tag, as follows:

        <CFCATCH TYPE="MyApp.BusinessRuleException.InvalidAccount">

Then it searches for the next most specific:

        <CFCATCH TYPE="MyApp.BusinessRuleException">

Finally, it searches for the least specific:

        <CFCATCH TYPE="MyApp">

The order in which you code CFCATCH tags designed to catch a custom exception type within an application does not matter. A CFCATCH tag searches for the custom exception types from most specific to least specific.

If you specify the type to be "APPLICATION, " the CFCATCH tag catches only those custom exceptions that have been specified as having the APPLICATION type in the CFTHROW tag that defines them.

The tags that throw an exception of TYPE="TEMPLATE" are CFINCLUDE, CFMODULE, and CFERROR.

An exception raised 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 by using the CFRETHROW tag.

You can use the CFCATCH variable to access exception information:

- 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.
- LockName -- TYPE=Lock only. The name of the affected lock (set to anonymous if the lock was unnamed).
- LockOperation -- TYPE=Lock only. The operation that failed (set to Timeout, Create Mutex, or Unknown).
- ErrorCode -- TYPE=Custom type only. A string error code.
- ExtendedInfo -- TYPE=APPLICATION and custom only. A custom error message.

Note | In order to see the tag stack displayed by TagContext, use the ColdFusion Administrator to enable the CFML stack trace.Under Debugging in the ColdFusion Administrator, choose the checkbox next to "Enable CFML stack trace. "

### Example

    <!--- CFTRY example, using TagContext to display the tag stack. --->
    <HTML>

    <HEAD>
    <TITLE>
    CFTRY Example
    </TITLE>
    </HEAD>

    <BASEFONT FACE="Arial, Helvetica" SIZE=2>

    <BODY  bgcolor="#FFFFD5">

    <H3>CFTRY Example</H3>

    <!--- open a CFTRY block --->
    <CFTRY>

    <!--- note that we have misspelled the 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 are fishing --->
    <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>

    </BODY>
    </HTML>