Using the cftry tag: an example

The following example shows the cftry and cfcatch tags. It uses the cfdocexamples data source, which many of the examples listed here use, and a sample included file, includeme.cfm.

If an exception occurs when you run the cfquery statement, the application page flow switches to the cfcatchtype="Database" exception handler. It then resumes with the next statement after the cftry block, once the cfcatchtype="Database" handler completes. Similarly, the cfcatchtype="MissingInclude" block handles exceptions raised by the cfinclude tag.

<!--- Wrap code you want to check in a cftry block ---> 
<cfset EmpID=3> 
<cfparam name="errorCaught" default=""> 
<cftry> 
    <cfquery name="test" datasource="cfdocexamples"> 
        SELECT Dept_ID, FirstName, LastName 
        FROM Employee 
        WHERE Emp_ID=#EmpID# 
    </cfquery> 
 
    <html> 
    <head> 
    <title>Test cftry/cfcatch</title> 
    </head> 
    <body> 
    <cfinclude template="includeme.cfm"> 
    <cfoutput query="test"> 
        <p>Department: #Dept_ID#<br> 
        Last Name: #LastName#<br> 
        First Name: #FirstName#</p> 
    </cfoutput> 
 
<!--- Use cfcatch to test for missing included files. ---> 
<!---     Print Message and Detail error messages. ---> 
<!--- Block executes only if a MissingInclude exception is thrown. ---> 
    <cfcatch type="MissingInclude"> 
        <h1>Missing Include File</h1> 
        <cfoutput> 
        <ul> 
            <li><b>Message:</b> #cfcatch.Message# 
            <li><b>Detail:</b> #cfcatch.Detail# 
            <li><b>Filename:</b> #cfcatch.MissingFileName# 
        </ul> 
        </cfoutput> 
        <cfset errorCaught = "MissingInclude"> 
    </cfcatch> 
 
<!--- Use cfcatch to test for database errors.---> 
<!--- Print error messages. ---> 
<!--- Block executes only if a Database exception is thrown. ---> 
    <cfcatch type="Database"> 
        <h1>Database Error</h1> 
        <cfoutput> 
        <ul> 
            <li><b>Message:</b> #cfcatch.Message# 
            <li><b>Native error code:</b> #cfcatch.NativeErrorCode# 
            <li><b>SQLState:</b> #cfcatch.SQLState# 
            <li><b>Detail:</b> #cfcatch.Detail# 
            </ul> 
        </cfoutput> 
        <cfset errorCaught = "Database"> 
    </cfcatch> 
 
<!--- Use cfcatch with type="Any" ---> 
<!--- to find unexpected exceptions. ---> 
    <cfcatch type="Any"> 
        <cfoutput> 
            <hr> 
            <h1>Other Error: #cfcatch.Type#</h1> 
            <ul> 
                <li><b>Message:</b> #cfcatch.Message# 
                <li><b>Detail:</b> #cfcatch.Detail# 
            </ul> 
        </cfoutput> 
        <cfset errorCaught = "General Exception"> 
    </cfcatch> 
</body> 
</html> 
</cftry>

Use the following procedure to test the code.

Test the code

  1. Make sure that there is no includeme.cfm file and display the page. The cfcatch type="MissingInclude" block displays the error.

  2. Create a nonempty includeme.cfm file and display the page. If your database is configured properly, you see an employee entry and do not get any error.

  3. In the cfquery tag, change the line:

    FROM Employee

    to:

    FROM Employer

    Display the page. This time the cfcatch type="Database" block displays an error message.

  4. Change Employer to Employee.

    Change the cfoutput line:

    <p>Department: #Dept_ID#<br>

    to:

    <p>Department: #DepartmentID#<br>

    Display the page. This time the cfcatch type="Any" block displays an error message indicating an expression error.

  5. Change DepartmentID back to Dept_ID and redisplay the page. The page displays properly.

    Open \CFusion\Log\MyAppPage.log in your text editor. You should see a header line, an initialization line, and four detail lines, like the following:

    "Severity","ThreadID","Date","Time","Application","Message" 
"Information","web-0","11/20/01", "16:27:08",, "cf_root\runtime\servers\default\logs\ MyAppPage.log initialized" 
"Information","web-0","11/20/01","16:27:08",, 
    "Page: web_root/MYStuff/MyDocs/ cftryexample.cfm Error: MissingInclude" 
"Information","web-1","11/20/01","16:27:32",," 
    Page: web_root/MYStuff/MyDocs/ cftryexample.cfm Error: " 
"Information","web-0","11/20/01","16:27:49",, 
    "Page: web_root/MYStuff/MyDocs/ cftryexample.cfm Error: Database" 
"Information","web-1","11/20/01","16:28:21",, 
    "Page: web_root/MYStuff/MyDocs/ cftryexample.cfm Error: General Exception" 
"Information","web-0","11/20/01","16:28:49",,     
    "Page: web_root/MYStuff/MyDocs/ cftryexample.cfm Error: "

Reviewing the code

The following table describes the code:

Code

Description

 
<cfset EmpID=3> 
<cfparam name="errorCaught" default="">

Initializes the employee ID to a valid value. An application would get the value from a form or other source.

Sets the default errorCaught variable value to the empty string (to indicate no error was caught).

There is no need to put these lines in a cftry block.

 
<cftry> 
    <cfquery name="test" datasource="cfdocexamples"> 
    SELECT Dept_ID, FirstName, LastName 
    FROM Employee 
    WHERE Emp_ID=#EmpID# 
    </cfquery>

Starts the cftry block. Exceptions from here to the end of the block can be caught by cfcatch tags.

Queries the cfdocexamples database to get the data for the employee identified by the EmpID variable.

 
<html> 
    <head> 
    <title>Test cftry/cfcatch</title> 
    </head> 
    <body> 
    <cfinclude template="includeme.cfm"> 
    <cfoutput query="test"> 
        <p>Department: #Dept_ID#<br> 
        Last Name: #LastName#<br> 
        First Name: #FirstName#</p> 
    </cfoutput>

Begins the HTML page. This section contains all the code that displays information if no errors occur.

Includes the includeme.cfm page.

Displays the user information record from the test query.

 
<cfcatch type="MissingInclude"> 
    <h1>Missing Include File</h1> 
    <cfoutput> 
    <ul> 
        <li><b>Message:</b> #cfcatch.Message# 
        <li><b>Detail:</b> #cfcatch.Detail# 
        <li><b>Filename:</b> #cfcatch.MissingFileName# 
    </ul> 
    </cfoutput> 
    <cfset errorCaught = "MissingInclude"> 
</cfcatch>

Handles exceptions thrown when a page specified by the cfinclude tag cannot be found.

Displays cfcatch variables, including the ColdFusion basic error message, detail message, and the name of the file that could not be found.

Sets the errorCaught variable to indicate the error type.

 
<cfcatch type="Database"> 
    <h1>Database Error</h1> 
    <cfoutput> 
    <ul> 
        <li><b>Message:</b> #cfcatch.Message# 
        <li><b>Native error code:</b> #cfcatch.NativeErrorCode# 
        <li><b>SQLState:</b> #cfcatch.SQLState# 
        <li><b>Detail:</b> #cfcatch.Detail# 
    </ul> 
    </cfoutput> 
    <cfset errorCaught = "Database"> 
</cfcatch>

Handles exceptions thrown when accessing a database.

Displays cfcatch variables, including the ColdFusion basic error message, the error code and SQL state reported by the databases system, and the detailed error message.

Sets the errorCaught variable to indicate the error type.

 

 
<cfcatch type="Any"> 
    <cfoutput> 
    <hr> 
    <h1>Other Error: #cfcatch.Type#</h1> 
    <ul> 
        <li><b>Message:</b> #cfcatch.Message# 
        <li><b>Detail:</b> #cfcatch.Detail# 
    </ul> 
    </cfoutput> 
    <cfset errorCaught = "General Exception"> 
</cfcatch>

Handles any other exceptions generated in the cftry block.

Since the error can occur after information has displayed (in this case, the contents of the include file), draws a line before writing the message text.

Displays the ColdFusion basic and detailed error message.

Sets the errorCaught variable to indicate the error type.

 
</body> 
</html> 
</cftry>

Ends the HTML page, then the cftry block.