| CFML Reference |
|
|
ColdFusion Tags |
|
| CFML Reference |
|
|
ColdFusion Tags |
|
Used with one or more cfcatch tags, the cftry tag lets you catch and process exceptions in ColdFusion pages. Exceptions include events that disrupt the normal flow of instructions in a ColdFusion page, such as failed database operations, missing include files, and developer-specified events.
<cftry> ... Add code here <cfcatch type = "exceptiontype"> ... Add exception processing code here </cfcatch> ... Additional cfcatch blocks go here </cftry>
| Attribute |
Description |
|---|---|
| type |
Optional. Specifies the type of exception to be handled by the cfcatch block. The following lists basic exception types you can use:
|
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 as Any, do so in the last cfcatch tag in the block so that all 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, if the custom type is defined as a series of strings concatenated by periods, as in "MyApp.BusinessRuleException.InvalidAccount". The cfcatch tag 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 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 as "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 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 with the cfrethrow tag.
You can use the cfcatch variable to access exception the following information:
cfcatch.
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. 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. type = "expression" only. Internal expression error number.type = "missingInclude" only. Name of the file that could not be included.type = "lock" only. The name of the affected lock (if the lock was unnamed, set to anonymous).type = "lock" only. The operation that failed (set to Timeout, Create Mutex, or Unknown).type = "custom" only. A string error code.type = "application" and custom only. A custom error message.
The following table lists advanced exception types you can specify in the type attribute.
|
Note To see the tag stack displayed by TagContext, use the ColdFusion Administrator to enable the CFML stack trace. Under Debugging in the ColdFusion Administrator, select the checkbox next to "Enable CFML stack trace. " |
<!--- 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>
| Copyright © 2001, Macromedia Inc. All rights reserved. |
|