ColdFusion MX Professional Projects

The Administrator settings provide debugging information for every page requested by the browser. You can change these debug settings by using the Debug menu page of ColdFusion Administrator, shown in Figure 14.3.

Figure 14.3: The Debug menu page of ColdFusion Administrator.

The options on this page are

• Enable Debugging. Checking this option enables the display of debugging output. When this box isn't checked, no debugging information is displayed. This option overrides all the other debugging options. Disable this option on the production server to increase security.

• Select Debugging Output Format. This option allows you to select the display format of the debug output. There are two types of display formats, as specified by the templates: classic.cfm and dockable.cfm. classic.cfm displays information in plain HTML text format at the bottom of the page. dockable.cfm uses the DHTML format, which displays information in expanding tree form in a separate window. The window style can be pane, docked, or floating.

• Report Execution Times. This option highlights the templates in red that have execution times longer than the time specified here. The default time is 250 ms. The display type is either a summary or a more detailed tree structure.

• Database Activity. Checking this option displays debugging information related to database activity for SQL query events and stored procedures.

• Exception information. Checking this option allows the application to place all the ColdFusion exceptions raised for the request in the debugging output.

• Tracing Information. Checking this option shows the trace event information in the debugging output. It allows you to track program flow and efficiency by using the <cftrace> tag.

• Variables. Checking this option enables variable reporting. Check the corresponding options to specify other variable types whose reporting is required.

• Enable Robust Exception Information. Checking this option displays information such as Java stack trace, line number, short snippet of the code where the error occurred, data source and any SQL statement, URL, and the path of the template.

• Enable Performance Monitoring. Checking this option allows the NT Performance Monitor to display information about the running ColdFusion application server. CFSTAT displays this information for platforms that don't support NT.

• Enable CFSTAT. Checking this option enables CFSTAT, which is a command-line utility that provides real-time performance metrics of ColdFusion.

Debugging the IP Address Page

You can use the Debugging IP Addresses menu of ColdFusion Administrator to ensure that debugging output is available to all local end users. You can add to or restrict the addresses that can view this information. To enforce strict security, you can limit this information to ColdFusion Administrator or original developers. Figure 14.4 displays the Debugging IP Address menu of the ColdFusion Administrator page.

Figure 14.4: The Debugging IP Address menu of the ColdFusion Administrator page.

Type the IP address in the text box, and click Add to include the end user to whom you wish to display the information. Select the IP address from the list, and click Remove Selected to delete the address from the list.

You can use CFML tags and functions to set or override the debug options set in ColdFusion Administrator. For example, set the debug attribute in <cfquery> to no to override a checked database activity checkbox in ColdFusion Administrator.

The syntax for <cfquery> is

<CFQUERY NAME="queryname" DATASOURCE="datasource name" DEBUG="no"> Select * from tablename </CFQUERY>

You can also use the <cfsetting> tag to turn off debugging output for a specific page. The default value for this tag is yes. It works only if the ColdFusion Administrator Debugging settings page enables debugging output. The syntax for <cfsetting> is

<CFSETTING SHOWDEBUGOUTPUT="NO">

You can use the IsDebugMode function to check whether debugging is enabled or not. This provides more flexibility to the <cftrace> tag.

Using the <cftrace> Tag

You can use this tag to log and display debugging information at runtime. The <cftrace> tag executes only if the Enable Debugging option is checked in ColdFusion Administrator. The output of this tag is logged in logs/cftrace.log under the ColdFusion installation directory. You can use this tag to trap the values of internal variables, data structures, and intermediate results at runtime. This helps you to identify the root cause of an error. You can display the output of <cftrace> as a section in debugging output or inline in your application.

These are the attributes of <cftrace>:

• Abort. Stops the processing of code lines once you reach the <cftrace> tag. This helps you to debug the program easily and pinpoint the error code lines. It takes a Boolean value, and the default value is FALSE.

• Category. Specifies an end user-defined trace type category. This is useful to process multiple lines of code. You can sort entries in the log according to the category.

• Inline. Decides whether to display the trace output as inline. Takes a Boolean value, and the default is FALSE.

• Text. Describes the trace point. You can add variables in the message. Arrays, structures, or objects cannot be added.

• Type. Specifies the severity type as information, warning, error, or fatal.

• Var. Specifies a simple variable such as a string, or a complex variable such as a structure name. Don't surround this variable name with the pound sign (#).

The syntax for <cftrace> is

<CFTRACE ABORT="FALSE" CATEGORY="structures " INLINE="TRUE" TEXT="error description "VAR="myvar">