One of the new features being provided in ColdFusion MX to aid developers in the debugging of their applications is the CFTRACE tag.

With the CFTRACE tag, you can trace the execution of your application at a variety of levels. Depending on where you choose to place the CFTRACE tag within your application, you can use it to log the execution of particular pieces of code, provide timings for certain sections of CFML that you expect might be problematic, display the contents of variables at various points in the processing of your pages, examine contents of a variable prior to performing a specific function, and engage in many other useful debugging techniques. It all depends on where in your code you choose to use the tag itself.

CFTRACE enables you to peek at what the ColdFusion engine is doing as it processes your code. To demonstrate this concept, let's have a look at a simple example. Suppose we create a simple form that enables users to enter their names. After a user submits his or her name, we want our output page to say "Hello Name!" In addition, prior to displaying the name that the user entered, we are going to convert the entire string to uppercase, using the UCase( ) function. This is easy enough to accomplish, but it gives us a good chance to take a simple look at how you can use CFTRACE.

First, let's examine the simple code used to create the form:

 <html>  <head>          <title>Form Submission</title>  </head>  <body>          <FORM ACTION="form_action.cfm" METHOD="post">  Please enter your name:<INPUT TYPE="text"  NAME="Name">  <BR>                  <INPUT TYPE="submit"    NAME="Submit"                            VALUE="Submit">          </FORM>  </body>  </html> 

Now, if we save this code as form.cfm and run it, our output should look something like Figure 14.3.

Figure 14.3. Output of form.cfm.


Now let's look at the code for our action page. Notice the locations in which I have placed the CFTRACE tag and the comments I've made at each trace point. They enable me to trace the logic flow as my page executes:

 <!--- display what form variables were passed from the form.cfm page --->  <cftrace var="form" inline="yes" text="initial form tag">  <!--- change the name passed so that the whole name is uppercase --->  <cfset newname = ucase(>  <!--- use cftrace to see if my function worked --->  <cftrace var="newname" inline="yes" text="upper case conversion">  <br>  <cfoutput>  hello #newname#  </cfoutput> 

If we save this file as form_action.cfm and then rerun form.cfm, we can see how the entire process works. I'll use the name "John" in the text box on the form.cfm page. After I enter my name and click Submit, the form_action.cfm page with my CFTRACE tags will run, and we see output like that shown in Figure 14.4.

Figure 14.4. Output of form_action.cfm with the CFTRACE tag in use.


Looking at this output, you can see where we've examined the contents of the form variables after they were submitted. The CFTRACE tag conveniently displays for us all the variables that were sent to the action page as part of the form.

Next, we place another trace point right after the conversion of the string to uppercase. Notice how CFTRACE outputs the results of our new variable. At each point in the process, CFTRACE is providing us with timings indicating how long each piece of the page is taking to execute.

This timing and process flow information is an invaluable tool in debugging problematic applications because you can now surround any suspect pieces of code with CFTRACE points to determine exactly what is going on where and how long it's taking each section of code to complete its respective task.

The CFTRACE tag can take different attributes that help you identify the trace point with which you're working and the code that is actually executing.

Table 14.2 gives you an overview of the attributes that are available for use with the CFTRACE tag.

Table 14.2. CFTRACE Tag Attributes




This is an optional attribute that enables you to specify whether you'd like to have page processing stop after a specific trace point.

By default, this attribute is set to No.


This is an optional attribute that enables you to specify a category name for the trace point. Using the example in this section, you might place the first trace point in a "form variables" category.

This enables you to differentiate among trace points when you're reviewing them. You can use ColdFusion variables as part of the textual names of your categories if you so choose to do so.


This attribute enables you to specify whether you'd like to see trace point information in the CFML page itself. In our example, we're using inline="Yes" and are able to see the trace information on the processing pages.

Should you fail to include this optional attribute, or should you set it to No, trace point information would still be available to you in the debugging output of the page.


This attribute enables you to provide a textual clue as to what this trace point is tracking.

In the example in this section, when we traced the conversion to uppercase, we used text="upper case conversion" so that we could easily identify what the trace point was tracing based on this description.

This text can be anything you like as long as it makes sense to you.


Use this attribute to specify the name of a variable that you'd like to dump at any trace point. The contents of the variable at that point in page processing is displayed.

A good thing to remember as you begin to play around with the power of the CFTRACE tag is that you can use it as much as necessary, even in code that's going to production. The overhead on this tag isn't significant, and assuming that you use the inline="No" attribute, the trace information won't be seen by anyone executing your production code unless you've specifically made that possible by allowing their IP to see debugging information through the ColdFusion Administrator on your production server.

ColdFusion MX logs all tracing output to the new log file: cftrace.log. This file is located in the ColdFusionMX/logs directory.

Inside ColdFusion MX
Inside Coldfusion MX
ISBN: 0735713049
EAN: 2147483647
Year: 2005
Pages: 579 © 2008-2017.
If you may any questions please contact us: