CFML Reference

cfthrow

Description

Throws a developer-specified exception, which can be caught with a cfcatch tag that has any of the following type attribute options:

• type = "custom_type"
• type = "Application"
• type = "Any"

Category

Exception handling tags, Flow-control tags

Syntax  1

<cfthrow 
  type = "exception_type "
  message = "message"
  detail = "detail_description "
  errorCode = "error_code "
  extendedInfo = "additional_information" 

  object = "java_except_object"> 

Syntax  2

<cfthrow 
  object = #object_name#> 

See also

cferror, cfrethrow, cftry

History

New in ColdFusion MX: this tag can throw ColdFusion component method exceptions.

Attributes

Attribute	Req/Opt	Default	Description
type	Optional	Application	A custom type Application Do not enter another predefined type; types are not generated by ColdFusion applications. If you specify Application, you need not specify a type for cfcatch.
message	Optional		Message that describes exception event.
detail	Optional		Description of the event. ColdFusion appends error position to description; server uses this parameter if an error is not caught by your code.
errorCode	Optional		A custom error code that you supply.
extendedInfo	Optional		A custom error code that you supply.
object	Optional		Requires the value of the cfobject tag name attribute. Throws a Java exception from a CFML tag. This attribute is mutually exclusive with all other attributes of this tag.

Usage

Use this tag within a cftry block, to throw an error. The cfcatch block can access accompanying information, as follows:

• Message, with cfcatch.message
• Detail, with cfcatch.detail
• Error code, with cfcatch.errorcode

To get more information, use cfcatch.tagContext. This shows where control switches from one page to another in the tag stack (for example, cfinclude, cfmodule).

To display the information displayed by tagContext: in the ColdFusion Administrator, Debugging page, select Enable CFML Stack Trace.

To use this tag with the object parameter, you must define an exception using the cfobject tag, with code such as the following:

<cfobject 
type="java" 
action="create" 
class="coldfusion.tagext.InvalidTagAttributeException" 
name="obj">
<cfset obj.init("Attribute", "value")>

With this code, the cfthrow statement would be as follows:

<cfthrow object=#obj#>

The cfthrow tag passes exception parameters to the obj variable.

Example

<h3>cfthrow Example</h3>
<!--- open a cftry block --->
<cftry>
<!--- define a condition upon which to throw the error --->
<cfif NOT IsDefined("URL.myID")>
  <!--- throw the error --->
  <cfthrow message = "ID is not defined">
</cfif>

<!--- perform the error catch --->
<cfcatch type = "application">
<!--- display your message --->
  <h3>You've Thrown an <b>Error</b></h3>
<cfoutput>
  <!--- and the diagnostic feedback from the application server --->
  <p>#cfcatch.message#</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>

Copyright © 2002, Macromedia Inc. All rights reserved.

Comments