Technotes

Pages using CFTHREAD sometimes leave stack frames visible in Eclipse, even after the page has completed.

When stepping through code against a ColdFusion 8 engine, you might see the stack frames continue to be displayed even though the page has resumed normally.

This occurs only on pages using CFTHREAD, and even then, only occasionally.

The problem is understood and is due to how the CF8 server completes the page, on these occasions. Unfortunately no fix is available at this time. We may re-evaluate this issue for a future release.

FusionDebug has a complete IDE installer packages for Windows, MacOS, Linux and Solaris which include and configure Eclipse,CFEclipse and FusionDebug. These installers are the fastest way to get started with FusionDebug. Use these packages if you do not have an existing installation of Eclipse, CFEclipse, Flex Builder or FusionDebug.

FusionDebug also has Plugin installers that allow you to install FusionDebug and optionally CFEclipse into an existing Eclipse or Flex Builder installation. You should use the plugin installers when adding FusionDebug to your existing Eclipse / Flex Builder installation.

There is also an Eclipse update site available.

These files and associated instructions can be found on the Downloads page.

Error

“Windows could not start the CF MX7 Server on Local Computer…refer to service-specific error code 2.”

The problem is likely to be that the jvm.config file still contains some advanced garbage collection options such as : -XX:+UseParallelGC

See related technotes for further details, as there could also be other garbage collection options in the file that may need removing.

The issue may also be that one of following has occured;

• ColdFusion (Jrun) is still running. You can check this by looking at the processes in task manager.If you see a process called jrun.exe or jrunsvc.exe you need to end the processes, and then restart CF. Don’t forget to check on “Show all processes”
• Port 8000 is already in use:
  • Open a DOS window
  • CD to C:/CFusionMX7/bin
  • Type: cfstart
  • ColdFusion should start and you should get an error message if it doesn’t
• The dt_socket transport is not available. Please confirm this by following the same steps under point 2.

Also check to see that the dt_socket .dll is in the folder C:/CFusionMX7/runtime/jre/bin. If it is then the C:/CFusionMX7/runtime/jre/bin folder is not being picked up by your windows path. This can be solved in one of two ways;

1. Add C:/CFusionMX7/runtime/jre/bin to your windows PATH variable
2. Copy dt_socket.dll to a folder in your windows PATH (e.g. C:\CFusionMX7\runtime\jre\bin)

NOTE: The dt_socket.dll is given only when requested. To make a request contact

Problem:

• Breakpoints don’t fire at all
• Breakpoints don’t fire in CFM/CFC pages in subfolders

Two of the most important options in FusionDebug are Webserver Folder, and Eclipse folder structure mirrors webserver. This article discusses how to configure these options in detail.

FusionDebug uses the information in the Configuration Dialog (accessible from the Run -> Debug menu) to accurately set breakpoints. If the information in this dialog is not configured correctly, FusionDebug may report that a breakpoint has been set, but it never fires: the associated page always runs to completion.

Solution:

In most cases, this problem can be solved by correctly configuring the Webserver Folder and Eclipse folder structure options in FusionDebug. Once these options are correctly configured, the configuration usually doesn’t need to be subsequently changed.

FusionDebug needs to know exactly where on your ColdFusion server the files are located, and how folders are structured. It uses these options, together with your Eclipse folder structure, to accurately set breakpoints and select the correct files when breakpoints fire.

Webserver Folder

This is the folder where you store your CFML files on your ColdFusion server, and from where they are run by ColdFusion.

The following image shows the web server root for the TestProject application:

Unable to render embedded object: File (support-bpdf-rootfolder_1.5.gif) not found.

c:\inetpub\wwwroot\TestProject is entered into the FusionDebug configuration in the Webserver Folder field:

Here are two images showing the Project Explorer in Eclipse, with the Test Project open, and the Properties for that project. You can see the project has been set up to point directly within the webserver folder.

TestProject in the Project Explorer

Location of TestProject in Eclipse

Eclipse folder structure mirrors webserver

This setting tells FusionDebug whether the folder layout inside your Eclipse project mirrors the files which are actually served by ColdFusion.

This setting is important for FusionDebug to be able to accurately tell when a breakpoint has fired. The following graphics illustrate how this option can be set.

Either…

Eclipse project has same structure as webserver… check this option

Or…

Eclipse project has structure but webserver is flat… uncheck this option

Problem: When a breakpoint fires or I’m using the stepping commands, FusionDebug sometimes finds the wrong source code file.

FusionDebug uses the source tab in the Configuration dialog to find any source code it needs. By default, this tab contains all projects in the workspace, and is configured to stop looking for source code when it finds a matching file.

If you have the same filename in two or more projects, FusionDebug will pick the first one it finds – which may not be correct.

This behaviour is easy to change.

Changing Source Lookup Behaviour

• Open the Configuration dialog and select the configuration you’d like to edit.
  Open Run -> Debug, open the FusionDebug element and select your FusionDebug configuration.
• Either
  1. Select Search for duplicate source files on the path.
     This will make FusionDebug find all the matching files, and ask you to pick the right one every time it finds duplicates.
  2. Edit the source lookup path manually.
     Instead of looking in all Eclipse projects, you can fine tune the search areas to include only your current project, or a small collection of projects. See the next section for more information on using this functionality.
• In either case, don’t forget to click ‘Apply’, and re-start your debugging session to make the change visible.

Editing the Source Lookup Path

By default, the source lookup path contains all workspace projects. You can change how the lookup path works by adding or removing projects from the path, or changing the order in which the path is searched.

The following screenshot shows a default source lookup path.

The projects CF_VideoStoreApplication and FDB_TestFiles both contain a testfile.cfm, but only the FDB_TestFiles one has been distributed to the web server, since that’s the application we’re debugging. Since the source lookup path is unchanged from the default, FusionDebug will pick the first one in the list – that from the CF_VideoStoreApplication – which is incorrect.

We can solve this by checking the box marked Search for duplicate source files on the path. Now, when FusionDebug tries to find the file, it asks us which one is correct, by popping up the following dialog:

This is a good solution, but being asked every time can be a bit time-consuming. Instead, we can edit the source lookup path to include just the project we need. The source path is specific to each configuration, so if we were debugging another project, we could simply add a new configuration, and set up the source path for that project too. More information on creating configurations can be found in the User Manual.

We can’t edit the Default element of the source path, since Eclipse maintains that automatically. We can remove it though. We click on the Default element, and select Remove. This removes the default element completely, leaving an empty source path.

Now we select Add. The Add Source (Selection Needed) dialog appears, listing all resources available in the workspace.

We select Project and put a check-mark against the FDB_TestFiles project, then click OK. This adds the FDB_TestFiles project to the source path. We click Apply and, since FusionDebug is not connected, Debug.

Now whenever the breakpoint fires in testfile.cfm, FusionDebug opens the correct one without asking – that from the FDB_TestFiles project.

Conclusions and Further Exercises For The Reader

We’ve created a custom source lookup path for our configuration. This ensures that FusionDebug is able to find the correct source file whenever a breakpoint fires. It’s particularly important to do this since many projects share common files, not the least of which is application.cfm.

Some development organisations may also have common libraries of CFCs or pages which they re-use. It would be a simple matter to create an Eclipse project for these common libraries, and then to include it in the source lookup path too.

Careful ordering of path elements (using the up and down buttons) can help FusionDebug quickly locate the right file without having to turn on Search for duplicate source files on the path.

Problem: My breakpoints don’t fire.

In order to set breakpoints accurately, FusionDebug needs to know about the layout of files on your web server.

There are three settings which must be set accurately for breakpoints to fire, and they’re located in the Connect tab of the Debug Configuration dialog.

• Webserver Folder
  This setting tells FusionDebug where the files are located on your web server. This should be the path to the web root as seen by the web server. This setting doesn’t take into account mapped drives or network connections, and should use local (to the server) drive letters, if necessary.
• Eclipse folder structure mirrors webserver
  This setting tells FusionDebug where to find the pages on the server. You can find more information on setting this option correctly below.
• “CF Server is on Windows”
  This option should be checked if the CF server is running a Microsoft Windows operating system (Windows 2000/XP etc.) For Unix and Unix-like operating systems (Linux, BSD, MacOS X etc.), uncheck this option.

More on Folder Structure

If you are debugging locally, and have configured your Eclipse project to use the same files that are served by the web server, this option should be checked.

Otherwise, use the two rules below to set this option.

• Eclipse source in folder structure and web server has same structure OR Eclipse source in single folder and web server in single folder:
  • Check this option
    Eclipse source in folder structure and web server in single folder
  • Uncheck this option

Troubleshooting Breakpoints

You might find the following steps helpful if you are having problems making breakpoints fire in your environment.

1. Use the Debug View to make sure you have connected to the same machine you’re running pages on in your browser. The Debug View shows this information as the second item in the tree (e.g. “FusionDebug (localhost:8000)”).
2. Make sure the page you’re running, and the parameters passed to it actually would cause the breakpoint to fire. Consider the flow of control through if-else tags. Has the page already completed or aborted before the breakpoint?
3. Make sure the breakpoint is enabled (shown by the presence of a check mark in the box by the side of the breakpoint in the Breakpoints view)
4. Make sure the Skip all breakpoints option is not active. This can be checked by looking at the status of the Skip button in the Breakpoints view (the blue circle ). If Skip is active, all breakpoints – both in the Breakpoints view and in individual editors – will have a line through them.
5. Carefully examine the options in the Debug Configuration
   • Is the Webserver Folder set correctly? Are the drive letters from the point of view of the server?
   • Is the option CF Server is on Windows correctly set? If you are running on any Unix or Unix-like platforms, this check mark must be cleared.
   • Is the Eclipse folder structure option correctly set? You might try toggling this option to see if it helps.

The likelihood of this problem is caused by the Source Tab on the launch configuration being incorrectly configured. The source tab must be mapped to the project that contains the source files, or to the default (which is all the projects). If the project that contains the source code is closed, FusionDebug can’t tell Eclipse to highlight the code. Take a look at the following support articles and check to see that the source tab is correctly configured for your project:

FusionDebug 1.0 Finds the Wrong Source File
Setting up a Debug Configuration in FusionDebug

These platforms can be debugged by ensuring the location of the components on the server is entered as a mapping in the Source Code Lookups tab of FusionDebug’s Launch Configuration.

Ensure the Source Code Lookup page contains an accurate mapping which mirrors the layout of your code on the server. This can be verified after setting the Lookup by setting a sample breakpoint, and ensuring the Server File text in the Breakpoints View reflects the exact location of the file on the server.

For more information on configuring FusionDebug, please see the support article Setting up a Debug Configuration.

You may have problems with how you’ve configured your FusionDebug setup. See this support article for how to correctly configue FusionDebug.
One of the features mentioned there is an option called “Compile CF page in debug-friendly mode.” This is the default but if you have a problem it would solve, you have to recompile the affected templates while you’re debug-enabled. That means you need to open and change the file (even if that means just entering a space and removing it) and then save it so that the next request for the page will recompile it.

Another issue is that if you’re configuring debugging against a server that’s not your local machine, be careful when configuring the “web server folder” in the “connect” tab since the value for the location of the Web server files should be relative to that Web server (not relative to your local machine, such as if you use a mapped drive locally).

Another possible problem is if you set a breakpoint on a line that doesn’t contain CFML tags or expressions. Eclipse won’t prevent that, but execution won’t break on that line. Relative to that, the breakpoint line numbers are fixed and static. If you change the file to add or remove lines, the breakpoint line number(s) may now be incorrect, which could cause the problem above (or the breakpoint may now be on a CFML line that doesn’t execute). As of FusionDebug version 2.0.1, these breakpoints may fire. Consider upgrading to FD 2.0.1.

Open projects

Make sure all projects which you are working with are open within Eclipse. FusionDebug cannot trigger breakpoints on files contained within closed projects.

There are several other reasons that your breakpoints mighty not be firing:

Breakpoint is optimised away

When ColdFusion MX compiles pages prior to running them it may optimize away some lines which it considers unimportant (along with any breakpoints on those lines).

These include empty lines, comments or line which are only outputting HTML.

To ensure your breakpoint fires, place it on a line containing a CF statement. Please note that there are a couple of CF tags such as cfscript or cfreturn which can also be optimised away, resulting in breakpoints on these lines not firing.

FusionDebug 2.0.1 can reliably set breakpoints on many of these lines; consider upgrading to FD 2.0.1.

FusionDebug can’t find the source code

To be able to find and open a file being debugged or stepped, FusionDebug must be able to predict where the file is located on the server. This is done using the Source Code Lookup rules defined in the launch configuration dialog.

We have two support articles relating to configuring this information:

• Breakpoints Don’t Fire: Setting Webserver Folder and Eclipse Project Structure and
• My Breakpoints Don’t Fire: Setting up a Debug Configuration.

The following points should be borne in mind when setting up Source Code Lookup rules:

• These rules must be accurate for breakpoints to fire
• You can test the rule by entering it, setting a breakpoint in a file and connecting FusionDebug to the ColdFusion Server
  • The Server File text of the breakpoint in the Breakpoints View will reflect where FusionDebug expects to find the file on the server.
  • If it’s not correct, simply open the Source Code Lookup tab in the launch configuration and examine the rules for correctness.
• When entering these rules, the CF Server Folder is the location of the file as seen by the server, not the client. Do not use the name of a share, for example. If you are on a Unix-like system, you must use absolute paths instead of symbolic links.

• The checkbox “CF Server is on Windows” on the Conenct tab of the launch configuration must be set accurately. It need only be checked on Windows. All other platforms should leave it unchecked.

Your folder structure in Eclipse (from the project on down) must mirror that of the webserver from the folder that you have entered in the launch configuration. An exception to this is that FusionDebug will pick the most specific rule when it has a choice of rules.

Name conflict with CF tag

There are several CF tags which are implemented as internal cfm files. In order to stop you from stepping into these encrypted cfm files we filter them out by name. If your file happens to be named the same as one of these files then it will not appear in FusionDebug.

The excluded filenames are as follows:

You are using a Multiserver installation of ColdFusion:

Since version 7, the ColdFusion Setup allows you to install ColdFusion as a SingleServer or MultiServer edition.

The latter allows you to run multiple cfusion servers. Per default all these servers share the same JVM configuration (jvm.config) which will let you run into problems when you have added the debugging configuration parameters required by FusionDebug.

We have a support article relating to configuring FusionDebug on MultiServer installations: FusionDebug on MultiServer Configurations

FusionDebug can be used with a MultiServer configuration.

Since version 7 the ColdFusion Setup allows you to install ColdFusion as a SingleServer or MultiServer edition. The latter allows you to run multiple cfusion servers. Per default all these servers share the same JVM configuration (jvm.config) which will let you run into problems when you have added the debugging configuration parameters required by FusionDebug. As a result you will be able to run only one server at once. When you try to start another server it fails and you will see a message like the following in the logs:

09/22 14:27:32 error Exception thrown in operation start
[1]java.net.BindException: Port in use by another service or process: 8000
   at jrun.servlet.network.NetworkService.bindToSocket(NetworkService.java:337)
   at jrun.servlet.network.NetworkService.start(NetworkService.java:198)
   at jrun.servlet.http.WebService.start(WebService.java:73)
   ...

If you only temporarily add the FusionDebug configuration to jvm.config this might be not a problem for you. Just remove it once you finished debugging.

A better approach would be to use multiple jvm.config files – each one dedicated to one server. Adobe has published a technote that explains in detail how to do this.

On Windows platforms, if you add a new CFusion instance using the Enterprise Manager->Instance Manager page in the ColdFusion Administrator, the default settings will NOT create a dedicated windows service and therefor the newly created instance will use the same jvm.config file as the cfusion instance. When you try to debug this new instance with FusionDebug it will connect to the port already used by the cfusion instance – but the files you want to debug are served by the newly created instance, e.g. debugging will not work.

I had previously installed the trial version and now get the message saying “This version of FusionDebug has expired. Please install a valid license.”

To install a license file:

• Open the Eclipse Menu Windows->Preference
• Open on the FusionDebug Node
• Click on the License Node to show the License Information Panel
• Enter the location of the license.lic file in the License File Dialog
• Click on the Install License button
• To activate the license click on the Activate License button

You can also watch the video on installing licenses available from the following link: http://www.fusion-reactor.com/fd/captivates/?swf=automaticactivation

Debugging a remote server is exactly the same as debugging a local server. Just remember that the path to the files on the server must be local to that machine, not shares. To get more information about setting up FusionDebug take a look at the new Training videos which are available from the website.

FusionDebug is implemented as an Eclipse plugin but you don’t have to use FusionDebug or Eclipse to edit pages, or change your development platform at all.

You can still develop with DW8 and jump into FusionDebug whenever you need to debug. FusionDebug is able to use your files from whatever software you used to create them; many of our users .

Eclipse is free, very easy to install and can be used in parallel to DW8. It is very simple to use and you require a minimum amount of knowledge to work the debugger which would be necessary no matter which platform you use.

As a side note, FusionDebug also integrates seamlessly with Adobe’s FlexBuilder product which is also based upon Eclipse and allows you to debug complete ColdFusion driven Flex Projects without having to leave FlexBuilder.

Further Information:

About FusionDebug
Eclipse
CFEclipse

Error

FusionDebug could not connect to the target system (Localhost:8000). Please ensure the debug agent is listening on the system, check you configuration file.

Please follow the procedure given in the FDS – 92 linked below.

Consider the following points when installing:

• Make sure the Eclipse.ini file within the copied Eclipse.app bundle is correct (i.e. has the given line removed)?
• Make sure you’re running the copied bundle, not the original one
• Make sure you have modified your JRun jvm.config file to include the debug agent settings, as outlined in the FusionDebug user manual:
  • http://www.fusion-reactor.com/fd/helpdocs/fusiondebug_user_guide.pdf

FusionDebug can create breakpoints in any ColdFusion page, tag, component, module, webservice etc, in any folder on your server.

You must create a FusionDebug Launch Configuration that maps the files in your Eclipse or FusionDebug project(s) to where you actually place the code on the server. Each mapping describes where code is distributed to on the ColdFusion server machine and allows FusionDebug to work out the file actual place a breakpoint needs to be set on the server that runs the code.

For further information please read the article on Source Code Lookup

FusionDebug is an interactive ColdFusion debugger and does indeed let you step through each line of code and step into CF components, functions, tags and includes. You can see exactly where you are in the code and can examine every variable, scope etc.

Take a look at the Captivates on this page to see what is possible:

http://www.fusion-reactor.com/fd/gettingstarted.cfm

The steps for remote debugging are as follows:

• Install FusionDebug plugin into Eclipse
• Update the jvm.config file on the remote computer to add debugging options
  (or use the Server Configuration Wizard on the remote computer)
• Create a debugging profile for FusionDebug
  (A captivate training video explaining this is available from
  http://www.fusion-reactor.com/fd/gettingstarted.cfm)
• Add a breakpoint to your file.
• Launch the debugger and step through your code.

Note: The webserver folder must be an absolute file path from the root of your remote server and the port should be that entered in your jvm.config file.

For more detailed information on this, please refer to the following User Guide;
http://www.fusion-reactor.com/fd/helpdocs/fusiondebug_user_guide.pdf

FusionDebug is supported to debug against the following ColdFusion versions:

• ColdFusion 6.1
• ColdFusion 7 (All versions)
• ColdFusion 8

Standalone, J2EE and multiserver installs are all supported.

FusionDebug as a client is supported by installers on the following platforms:

• Microsoft Windows 2000/XP/Vista
• Mac OS X 10.4.9
• Linux

Additionally, it may be possible to install on other platforms using the FusionDebug Eclipse Update Site, available from here.

If you are using an already-installed Eclipse installation, we also provide plugin installers (see link above). Eclipse is supported from revision 3.2.2 onwards.

If your Eclipse installation does not have access to the internet, you can perform a manual activation. Go to the license activation page and follow the instructions listed there.

See also the FusionDebug User Guide for further details.

Go to the license activation page and follow the instructions listed there.

This problem was reported against Fusebox 5.1

The issue is that there is insufficient Source Code Lookup data for FusionDebug to accurately place the breakpoint.

Often, the addition of a Source Code Lookup in the debug launch configuration tab is sufficient to get breakpoints firing reliably.

More help on getting breakpoints firing can be found in technotes below.

The Expressions View can handle most expressions which are valid in ColdFusion MX. A good rule of thumb is: if you can write it as an IF condition, on the right side of a CFSET assignment, or within “#” characters, it’s a valid expression.

Expressions are evaluated and re-evaluated only in the context of a suspended request. If no request is suspended, expressions are not evaluated. If a thread is suspended, try clicking on it. This will implicitly tell the Expressions View to re-evaluate its expressions for that request.

Highlight the name of the variable that you what to set/change the value of within an editor and then select the right-mouse click menu option “Set Variable”. In the dialog that opens enter a ColdFusion expression exactly as you would when performing a <CFSET> CFML tag. Note that a variable can only be set in a request that is currently stopped and you may have to use the scope of the variable to set the correct variable.

You can enter almost any ColdFusion expression as the value of a Set Variable (CFSET).

FusionDebug evaluates the expression like ColdFusion, which means that strings must be wrapped in double (“”) or single quotes(”) otherwise they will be interpreted as variable names.

<cfset myvar = "my string">
<cfset myvar = mystring>

Some examples of what you can enter in the dialog:

You can also create variables by using a scratch pad file where you enter the names of variables you want to create.

No. The port specified in the jvm.config (which defaults to 8000) should reflect an available port on your system, which then the FusionDebug configuration will point to, it is not releated to the web server or JRun.