User manual MACROMEDIA COLDFUSION 5-DEVELOPING APPLICATIONS

[. . . ] Developing ColdFusion Applications MacroMedia ColdFusion® 5 Macromedia® Incorporated Copyright Notice © 1999­2001 Macromedia Incorporated. This book, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. The content of this manual is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Macromedia, Incorporated. Macromedia, Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in this book. [. . . ] When you enable this option, cfcatch blocks make available an array of structures called cfcatch. tagContext. Each structure represents one level of the ColdFusion runtime's active tag context at the time when the ColdFusion interpreter detected the exception. Handling Exceptions in ColdFusion 207 The structure at position 1 of the array represents the outermost tag in the stack of tags that were executing when the interpreter detected the exception. The structure at position ArrayLen(cfcatch. tagContext) represents the currently executing tag at the time the interpreter detected the exception. The tagContext structures have the following attributes: · Template The pathname of the application page that contains the tag. · Line and Column The tag's line number and column number within the application page. Note Clear the Enable CFML stack trace option to avoid having production servers expend resources creating a traceback stack by default. When you turn off this setting, cfcatch. tagContext is a zero-length array. Database exceptions The following additional variables are available whenever the exception type is database: Property variable cfcatch. nativeErrorCode Description The native error code associated with this exception. Database drivers typically provide error codes to assist in the diagnosis of failing database operations. Database drivers typically provide error codes to assist in the diagnosis of failing database operations. If no SQLState value was provided, the value of SQLState is -1. cfcatch. SQLState Expression exceptions The following variable is only available for expression exceptions: Property variable cfcatch. errnumber Description An internal expression error number, valid only when type="Expression". 208 Chapter 11 Preventing and Handling Errors Locking exceptions The following additional information is available for exceptions related to cflock sections: Property variable cfcatch. lockName cfcatch. lockOperation Description The name of the affected lock. This is set to "unknown" if the failed operation is unknown. Missing include exceptions The following additional variable is available if the error is caused by a missing file specified by a cfinclude tag: Property variable cfcatch. missingFileName Description The name of the missing file. Exception handling strategies Use cftry with cfcatch to handle exceptions based on their point of origin within an application page, or based on diagnostic information. Use the cftry tag with one or more cfcatch blocks to define a ColdFusion block for exception handling. When an application page raises an error condition, the ColdFusion Server checks the stack of currently active blocks for a corresponding cfcatch handler. In particularly problematic cases, you might enclose an exception-prone tag in a specialized combination of cftry and cfcatch to immediately isolate the tag's exceptions, or to use cftry with cfcatch type="Any" at a main processing level to gracefully terminate a subsystem's processing in case of an unexpected error. Exception handling example The following example shows cftry and cfcatch, using the CompanyInfo data source used in many of the examples in this book and a sample included file, includeme. cfm. If an exception occurs during the cfquery statement's execution, the application page flow switches to the cfcatch type="Database" exception handler. It then resumes with the next statement after the cftry block, once the cfcatch type="Database" handler completes. Similarly, the cfcatch type="MissingInclude" block handles exceptions raised by the cfinclude tag. Any unknown, but possibly recoverable, exceptions are handled by the cfcatch type="Any" block. Handling Exceptions in ColdFusion 209 <!--- Wrap code you want to check in a cftry block ---> <cfset EmpID=3> <cftry> <cfquery name="test" datasource="CompanyInfo"> SELECT Dept_ID, FirstName, LastName FROM Employee WHERE Emp_ID=#EmpID# </cfquery> <html> <head> <title>Test cftry/cfcatch</title> </head> <body> <hr> <cfinclude template="includeme. cfm"> <cfoutput query="test"> <p>Department: #Dept_ID#<br> Last Name: #LastName#<br> First Name: #FirstName#</p> </cfoutput> <hr> <!--- Use cfcatch to test for missing included files. ---> <!--- 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>File name:</b> #cfcatch. MissingFilename# </ul> </cfoutput> </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> 210 Chapter 11 Preventing and Handling Errors </cfcatch> <!--- Use cfcatch with TYPE="Any" ---> <!--- to find unexpected exceptions. ---> <cfcatch type="Any"> <cfoutput> <h1>Other Error: #cfcatch. Type#</h1> <ul> <li><b>Message:</b> #cfcatch. message# <li><b>Detail:</b> #cfcatch. Detail# </ul> </cfoutput> </cfcatch> </cftry> </body> </html> To test the code: 1 2 3 Make sure there is no includeme. cfm file and display the page. [. . . ] You can then run the cfserver executable under the dbx debugger and set breakpoints in your CFX code. You might need to set a breakpoint in main so the debugger loads the symbols for your CFX before you can set breakpoints in your code. 404 Chapter 21 Building Custom CFXAPI Tags Registering CFXs To use a CFX tag in your ColdFusion applications, first register it in the Extensions, CFX Tags page in the ColdFusion Administrator. To register a Java CFX: 1 2 3 4 5 6 On the ColdFusion Administrator Server tab, select Extensions > CFX Tags to opent the CFX Tags page. Click Submit Changes. You can now call the tag from a ColdFusion page. To register a C++ CFX: 1 2 3 4 5 6 On the ColdFusion Administrator Server tab, select Extensions > CFX Tags to opent the CFX Tags page. When the tag is ready for production use, you can select this option to keep the DLL in memory for improved performance. [. . . ]