cfthrow

Description

The cfthrow tag raises a developer-specified exception that can be caught with cfcatch tag having any of the following type specifications:

cfcatch type = "custom_type"
cfcatch type = "Application"
cfcatch type = "Any"

Syntax

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

Attributes

Attribute

Description

type
Optional. A custom type or the predefined type Application. Do not enter any other predefined types because they are not generated by ColdFusion applications. If you specify the exception type Application, you need not specify a type for cfcatch, because the Application type is the default cfcatch type.

message
Optional. A message that describes the exceptional event.

detail
Optional. A detailed description of the event. The ColdFusion server appends the position of the error to this description; the 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.

Attribute	Description
type	Optional. A custom type or the predefined type Application. Do not enter any other predefined types because they are not generated by ColdFusion applications. If you specify the exception type Application, you need not specify a type for `cfcatch`, because the Application type is the default `cfcatch` type.
message	Optional. A message that describes the exceptional event.
detail	Optional. A detailed description of the event. The ColdFusion server appends the position of the error to this description; the 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.

Usage

Use cfthrow within a cftry block to raise an error condition. The cfcatch block can access any accompanying information as follows:

Message with cfcatch.message
Detail with cfcatch.detail
Error code with cfcatch.errorcode.
To get additional information, use cfcatch.tagContext. tagContext captures the context of the exception; that is, the name and position of each tag in the tag stack, and the full pathnames of the files that contain the tags in the tag stack.

Note

To see the information displayed by tagContext, use the ColdFusion Administrator to enable the CFML stack trace, which can be found on the debugging page in the ColdFusion Administrator. Select the checkbox next to Enable CFML stack trace.

Example

<!--- This example shows the use of cfthrow. --->

<html>
<head>
<title>
cfthrow Example
</title>
</head>

<BASEFONT face = "Arial, Helvetica" size = 2>

<body bgcolor = "#FFFFD5">

<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>

</body>

</html>