What's changed about IIS 7 support in 9.01?

Some folks will know that ColdFusion 9 Updater 1 (9.0.1) has finally added full support for IIS 7, without need to rely upon enabling IIS 6 Compatibility (which IS still required for CF 9.0, 8.0, and 8.0.1). This is indeed great news, whether you're running on Vista, Windows 7, or Windows Server 2008, which all have IIS 7 by default, and for which you can enable IIS 6 Compatibility mode, but it's not on by default and not always straightforward to enable.

So bottom line, if you're on 9.0.1, you no longer need to go through the hoops described in the CF9 Admin/Install docs (nor in helpful blog entries like here and here, though those are still great for those running on CF 9.0 and 8, and may even offer tips of value to anyone setting up CF to run on IIS, which has other challenges on Server 2008.)

Gotcha 1: The IIS 7 Compatibility change is NOT documented where expected

Sadly, though, if you go looking for help on this in the CF docs, such as Chapter 6 of the manual, Installing ColdFusion 9, you will find that it has NOT been updated with the info that is new in the updater.

It opens, "If you are configuring IIS 7 ... ensure that you have the options IIS Metabase and IIS 6 configuration compatibility ... and ISAPI Extensions ... selected".

What a shame.

Solution 1: Where the change IS documented

So with respect to change in 9.0.1, where you no longer need to enable IIS 6 compatibility, the details are covered instead in the installation guide that was created just for installing CF9 updater 1 itself, called "Installing the Coldfusion 9 Update", available online at:

http://www.adobe.com/support/documentation/en/coldfusion/901/cf901install.pdf

It's certainly reasonable to expect that the primary install manual would have been updated with the info above.

But that's why I'm pointing this out. I have also added a comment explaining it on the page pointed to in the first link above. Hope that may help someone.

(The same info is also offered as a chapter in the manual, "ColdFusion 9 Updater 1: New Feature Notes", available at http://www.adobe.com/support/documentation/en/coldfusion/901/cf901features.pdf, which is of course very interesting if you may have missed it.)

I'll explain the second gotcha in a follow-up blog entry.

Here's the next, related, myth:

True or False: "If/when I apply Cumulative Hotfixes, I need apply only the latest CHF, right?"

For instance, let's say you're currently running CF 9 update 1 or CF 8.0.1 and discover (perhaps due to my last blog entry) that you had never applied any of their associated CHFs. It would seem you should just be able to apply the latest CHF and not bother with anything related to the previous ones, right?

Answer: Well, yes and no.

There may be manual steps in skipped CHFs

Technically, yes, you need only apply the latest CHF in terms of getting whatever hotfixes are included in the chf jar.

The problem is, there are sometimes multiple steps involved in applying a given CHF (especially in CF 7 and 8), or there may be specific hotfixes that are indicated at the end of the CHF technote as requiring a manual step. I'll explain the differences in more detail in a moment.

If you have NOT done those manual steps, you WILL still need to do them, even if you "skip" that CHF in question.

This is definitely the case for CF 8.0.1, which had 4 CHFs, and also for CF 7.0.2, which had 3, and for each release some of the CHFs had manual steps. It's not the case for CF 9 Updater 1 (9.0.1) CHF2 and 1 (this sentence added as an update since this entry was originally posted.)

The table below details which CHFs, specifically, have manual steps. (For CF 8.0, none of the 3 CHFs had any manual steps. I'll explain later here why I can't tell you for CF 7.0.1 or 7.0, and why this isn't an issue for CF 6.1 and 6.0 users because they didn't have CHFs at all to potentially "skip".)

This isn't a mere technicality: it could be critical

Some may think I'm being pedantic in raising this concern, but take my word as a CF troubleshooting consultant: some of these manual steps are very important ones, so it's really unfortunate that some people may be "skipping" them inadvertently. I help people with this very problem at least once a month.

For instance, in 8.0.1 CHF 4, there are both a bootstrap.jr needed, some manual hotfixes, and some related to security fixes. In 8.0.1 CH 3 there are important fixes related to image processing problems (which have plagued many, who are missing this fix).

And perhaps most important, for those running CF 7.0.2, there was a surprisingly critical (yet innocuous looking) manual step in its CHF 2, and this one hotfix may be the explanation for many people suffering inexplicable memory leaks in that release. I'll discuss each of these more in a moment.

What do I mean by "manual steps" in a CHF? How would you tell if they are there?

What I'm talking about here is either of different kinds of manual steps in a given CHF. I'll first explain them, then reflect it more succinctly in a table to follow.

1: A simple, single-step CHF

First, by comparison, note that for most CHFs, applying the update merely involves downloading a zip, extracting a single jar, and using that to apply the update (whether by uploading it in the CF Admin "system information" screen, or by dropping it into the appropriate lib/updates directory, each of which are discussed in the technotes. I'll note that many don't realize they can apply HFs and CHFs merely by dropping their respective jar into the appropriate lib/updates directory: the technotes sometimes only mention this fact in the "uninstalling" section, where they point out that the files to be deleted have been placed there by using the Admin interface.)

2: A multi-step CHF

As a second example, in contrast to the simple one-step CHF above, sometimes the technote for a CHF will have more steps which indicate that you need to manipulate multiple files in one or more extra steps.

As I mentioned above, the CHF4 for 8.0.1 is an example of that. This is the kind that is most disconcerting to me.

3: A CHF with multiple zips

A third example is really a variation of the last one: some CHFs don't have so much "multiple steps" but instead have multiple zip files that need to be extracted.

The CHF1 for CF 9.0.1 is such an example. Note that its steps 6-9 involve updating files in WEB-INF/cftags and CFIDE directories.

In such a case, we just need to hope that any next CHF will offer those same files (and as an update since this entry was first written, CHF2 DOES include the same--though perhaps updated--files in its zips).

Unfortunately, the technote for CHF2 doesn't make this entirely clear, but I compared the extracted zips to confirm it.

4: A CHF with separately applied individual hotfixes

Finally, in some CHFs, there may still be only one chf jar file, but after the simple list of steps for applying that, the technote may then also list additional individual hotfixes which still need to be applied, separately from the hotfix.

These may be listed either at the top or bottom of the CHF technote (though usually, they are listed at the bottom). There are several CHFs of this sort, and again I will detail them for you later here. But first, let me stress an important example of this.

A Critical example from CF 7.0.2

A critical (and sadly, oft-missed) example of this is the 7.0.2 CHF 2. At the bottom of that page are listed several such "manual" hotfixes, and among those is one extremely important one. Unfortunately, the wording on the page doesn't make it sound very worrisome (and frankly, seems incorrect from my experience). In testing I did at the time, this was a hotfix which when implemented would stop a bug where CF would hold memory from a file upload until CF was restarted--a true memory leak. Adobe did fix the problem in CF 8, and said so, which is how some of us became aware of it.

But even if you DID read the CHF technote, you may not sense the severity. The link to the hotfix labels it as "Update for cffile memory leak", and the text preceding that says, "This hot fix is for a potential memory leak caused by cancelling cfuploads in progress with ColdFusion MX 7." In my testing, though, it really had nothing to do with "cancelling cfuploads". It was any file upload (where you had an input type="file" in a form that was used to post a file) to a CF page, whether you cancelled it or not!

Further, if you go on to read the page about the hotfix itself, its own title might lead some to think it applies even less to them, "Hot fix to make ColdFusion release memory properly with file uploads and CFC's stored in application, session or server scope". Is this meant to be read that the file upload has to happen in a CFC stored in a shared scope? If you thought so, again, you may shrug it off as a seemingly rare situation, but again in my testing back then, it did not matter. Any file upload to a CF page held memory for the size of the file uploaded, until CF was restarted. To make matters worse, the text in the body of the technote says (in my mind, incorrectly), "ColdFusion does not release the memory properly with file uploads when a reference to a CFC is stored in the application, session or server scope in the same page".

Take my advice: ignore all that mumbo-jumbo. If you're still on CF 7.0.2 and you missed that manual hotfix listed in CHF 2, go apply it! It may be the reason you've had CF crashing for running out of heap. (And if you're still on CF 7, then of course you should move up to the free 7.0.2 updater. Again, I discuss and link to updaters in the previous blog entry.)

Again, though, this is just one example (7.0.2). There are similar examples of such similarly-required separate individual hotfixes in some other CHFs for other releases.

When will adobe stop the madness with an automated installer?

Well, the good news is that as Adobe has been talking about the upcoming new release (currently codenamed "Zeus"), one of the most significant new features is an automated hotfix mechanism. This isn't the place to elaborate on that (since few details have been shared), but I may do another blog entry in the future, if someone else doesn't first. (If you're reading this and know somehow who has, share it in a comment.)

What CHFs in what releases have manual steps?

So, given all the above, which CHFs do you need to worry about, if you are intending to "skip" them? To help make things easier to track, following is a table that identifies each CHF for the most recent releases, and it indicates for each CHF whether it has any manual steps. If it does, then if you are skipping it to move to a later one, you need to be sure to apply those manual steps:

So you can see that this problem is most significant (for now) for those on CF 7.0.2 and 8.0.1.

I'm not going to list 7.0 or 7.0.1, because for one thing, the links to the technotes for their CHFs are currently failing for me (as offered from the CF 7 hotfixes page), so I can't look at them to confirm if they have manual steps. It's reasonable to assume they do. Another reason not to list 7.0 and 7.0.1 is that, again, if you're on those releases, you really ought to update to 7.02 (for free), if not to 8 or 9.

You may notice that I don't list CF 6.1 or 6, either. Well, in fact, the whole concept of cumulative hotfixes was added only as of CF 7, so this concern (about trying to "skip" CHFs) just doesn't apply to those running CF 6 or 6.1.

And don't forget to check for any subsequent hotfixes after whatever "latest" CHF you apply

Finally, this entry has focused on what manual steps you may need to do related to previous CHFs you may be trying to "skip". But separate from those, keep in mind as well that there may be one or more individual hotfixes that have come out since any given CHF was released (or you may have applied it).

Part of the challenge is that, since the technote for a given CHF is written when that CHF is released, it obviously does not at that point in time reflect any new hotfixes posted after that. I suppose we could argue that Adobe should warn you (at the bottom of each CHF) to also go check if there are any subsequently released hotfixes.

For now, it's incumbent upon you to keep an eye on the hotfix page for the version you are using. I listed them in the last blog entry, but here they are again:

• "ColdFusion 9 : List of Hot fixes" (for 9.0 and 9.0.1)
• "Hot Fixes | Cold Fusion 8 and 8.0.1"
• "ColdFusion hot fixes (MX 7 through MX 7.02)"
• "ColdFusion Hot Fixes (MX through MX 6.1)"

For example, as of this writing, there are 2 hotfixes listed after (chronologically) the latest CHF for CF 9, CHF 1. There are also 2 hotfixes currently listed after the latest CHF for CF 8.0.1 (CHF 4), there are 4 hotfixes after the latest CHF for CF 8.0 (CHF 3), and there are 2 after the latest CHF for CF 7.0.2 (CHF 3). So again, if you think you're "at the latest CHF", make sure there may not be still more hotfixes that apply to you. For more information, see the corresponding page in the links immediately above, for whatever version of CF you're running.

Finally, with respect to watching out for individual hotfixes within a given release, note that you generally cannot watch only the main "CF Updates" page. That generally lists only installers, updaters, and CHFs. (That said, there is at least one "input sanitization" hotfix shown at the top of the list of CF 8.0.1 CHFs. )

Hope all that's helpful. Let me know what you think.

First myth up for consideration:

True or false: "If/when I download CF to install it from scratch, the installer has all the latest fixes (updaters, at least)"

Answer: False (generally). For instance, if you download CF9 today (Dec 2010), you still get CF 9.0, released originally in Oct 2009. You don't get the latest updater (9.0.1 as of this writing, released July 2010), though its existence is at least mentioned on the page, nor of course does it then include any hotfixes or cumulative hotfixes.

Why not, you may wonder? I'll explain more in a moment, along with more about hotfixes and updaters as concepts (and where to find them specifically, for each CF release).

About this CFMyths Series

First, I want to introduce this new series, CFMyths. Today's entry, though prompted by a question on a mailing list, is in fact a frequent source of confusion for folks. Indeed, it's one that I've covered (along with many like it) in a CFMythbusters talk that I've given at various events. Of course, relatively few see such talks, and even though I offer the details in the slides, available on my site, many never dig into those, either I think, so I've long meant to create some blog entries from them.

Today's question prompted me to go ahead and start that series. (And I know I still owe readers the continuation of a CF911 series on memory problems that I started last month. Part 2 is now written. I just needs to refine it. This topic got my attention, and once I started writing, well, here you go. :-)

"So why is the currently available installer not necessarily 'the very latest version'"?

It's about logistics, really. CF runs on many platforms (OS's, web servers, databases, and different releases of each), so it's expensive for Adobe to create new installers. This is why the base version may be left there for quite a while, with you being expected to apply any subsequent updaters or hotfixes. That will surely surprise many, but it's the way it's been for some time (except 8.0.1, when a completely new installer was offered, in addition to one to update those already on CF 8.)

So it's incumbent upon you, when you download a given release, to pay close attention to what version it is. It will be reflected first in the installer filename, such as coldfusion_9_WWE_win64.exe. It will also be listed with the specific version number as reported in the CF Admin and logs once it's installed (such as 9,0,0,251028 for the base version of 9.0, or 9,0,1,274733 for the base version of 9.0.1). You'll then need to check to see if there may be any updates, hotfixes, or cumulative hotfixes. The same is true for 8.0.1, too (whose base build number is 8,0,1,195765). I'll point you to the updaters and hotfixes in a moment.

"What are all these terms? Hotfixes, updaters, CHFs?"

Before proceeding, it may help some readers if I explain the terminology of the various updates for CF that may exist:

• Hotfixes are individual fixes to specific problems (typically offered as a single jar file, such as hf801-76563.jar, and for which there is usually an individual technote, such as this one for that hotfix, which is a recent fix--Oct 2010--for CF 8.0.1)
• Cumulative hot fixes (CHFs): when there have been many hotfixes, they will typically be rolled into a cumulative hotfix which includes several(such as the CHF 1 for 9.0.1, which can only be applied to CF 9.0.1, not CF9). There's no fixed number of hotfixes which will trigger Adobe to create a CHF. They are usually deployed also as a single jar, and you are expected to remove any individual hotfixes that are included. Again, the technote for each hotfix will explain these things. As the name implies, they are also cumulative, such that CHF 2 includes all the hotfixes that CHF1 included (with a caveat, discussed below). CHFs do not included new features
• Updaters: When there have been some number of CHFs, they will often be rolled into an update/updater (like 9.0.1, 8.0.1, 7.0.2, 7.0.1, 6.1). Updaters are always executable installers, and they often do add some minor new functionality to CF.

Adobe has a page that explains more about these terms generically.

Note that when looking at hotfix/CHF filenames(such as hf801-76563.jar), you can tell by its prefix whether it's a hotfix (hf) or CHF and what version it's for (8.0.1, in that example.)

Indeed, that brings up another potential gotcha: be careful about inadvertently applying a hotfix/CHF to the wrong release, or leaving an old HF in that's been obviated by a CHF that includes it. I discuss the potential gotcha of applying the wrong hotfix/CHF for the wrong version in a blog entry, You may have mistakenly applied an 8.0 CHF on a 8.0.1 CF server, and not realize it!

Finally, the Adobe technote page about each hotfix, CHF, or updater will each explain how to apply that particular update. Again, I'll offer links to the key pages for different release updates in a moment. First, there are a couple of other common misconceptions I want to address.

Phew: I bet some readers thought all this should be pretty straightforward, and may be surprised to learn all these details. It's the kind of thing I often find myself helping my customers correct, and again it also often comes up in questions on lists/forums. You might think we've covered all there is, but sadly, there are still some more gotchas.

"At least when I apply an updater, that includes all hotfixes that preceded it, right?"

Well, not necessarily. For instance, when the CF 7 updater 2 (7.0.2) came out, Macromedia decided not to bundle an updated set of JDBC drivers in the updater. It was up to you to download and install those as a manual hotfix. I blogged about that back at the time, in 2006.

Again, the logic was understandable: there were considerable changes introduced by the drivers (licensed from a third party), and forcing it on existing users could have been troublesome. If you wanted the updated drivers, you needed to download (for free, from Adobe) and install them yourself. The installer notes clarified this, so as always, it pays to read the updater documentation carefully. There are often multiple documents for any new updater, including a FAQ, release notes, and more.

"Well, at least with Cumulative Hotfixes, I need apply only the latest, right?"

Again sadly, no, not necessarily. Let's say you're on CF 8.0.1 and never applied any of its 4 CHFs. You may think you can just apply CHF 4 and not bother with anything related to the previous three. Unfortunately, there are often manual steps within any one previous CHFs which you WOULD still need to apply.

In fact, this question (and answer) is important enough that I'll create another entry on that so it's not lost here (where this entry's title will lead some to think it applies only to installing CF from scratch).

"OK, so where do I find these updaters I need to check?"

Fortunately, there's one primary page you can keep an eye on, but technically there are various pages you may want to check, depending on your CF version, to get more or less detail.

First, the main "CF updates" page can be found here. It not only includes updaters and CHFs, it even has them for CF 9, 8, 7, 6, and even 5, as well as CF Builder (and CF Studio!)

For those on CF 9.0.1, it includes the latest CHF1 for CF 9.0.1.

Note that it also lists CHFs for CF 8.0.1, 8.0, and 7.0.2.

As for updaters, it includes those for 9.0.1, 8.0.1, 7.0.2, 7.0.1, 6.1, and so on. (Sadly, there's no HTML anchor within the page for sections like the 9.0.1 updater, so I can't offer a link to that part of the page. But if you're still running CF 9.0, go get it! It includes useful new features.)

As for getting a list of all the individual hotfixes (and CHFs) for any specific releases, there are individual pages for those:

• "ColdFusion 9 : List of Hot fixes"
• "Hot Fixes | Cold Fusion 8 and 8.0.1"
• "ColdFusion hot fixes (MX 7 through MX 7.02)"
• "ColdFusion Hot Fixes (MX through MX 6.1)"

While these list both hotfixes and CHFs, the info on the CHFs should be the same as the main "CF updates" page offered previously. But note that these version-specific update pages may well list new hotfixes that came out after a CHF. Do keep an eye on them.

(You may wish there was a better way to keep up with updates and hotfixes, whether a feed you could follow, or even an automated update mechanism. Sadly, there have been feeds but I'm not aware that is reliably updated by Adobe. And there is no automated update mechanism for CF from Adobe. But there is a free tool and service that solves both those problems, providing an automated update mechanism and constantly updated feed of hotfix notifications. For more information, see Merlin Manager.)

Finally, again, look for another entry to come on the sticky problem of how you can't "just apply the latest CHF" and assume you're good to go on any previous updates for that release. Sadly, it's just not often the case.

It's a simple JVM tweak to cause it to use a fixed port:

-DDEBUGGER_SERVER_PORT=portNumber

You can add this either in the "Java & JVM" page of the CF Admin (if in Standard or Enterprise Server), or on the java.args line in the jvm.config file (for any form of CF).

You do need to restart CF for this to take effect.

A few warnings are in order

First, as always, be very careful when changing the jvm configuration. If you make any mistake, then it's possible CF won't be able to restart. (This is one strong reason to favor making changes in the jvm.config file, rather than the "Java & JVM" admin page. If CF can't start, you won't be able to get to the Admin to undo your changes. By knowing how and where to edit the file, you can undo any bad changes.)

Second, beware that you don't pick a port that's already in use, or again CF won't start. And beware that while it may be open now (if you test it), it may not be open later if something's running then that is not now. Along those lines, ....

If you're using multiple instances...

Third, beware especially if you're using the Multiserver form of CF deployment (multiple instances) where by default you have the multiple instances sharing one jvm.config. In that case, they all would inherit this setting, and whichever instance starts first would claim that designated port, and then the others will not be able to start (reporting an error like "FATAL ERROR in native method: JDWP No transports initialized" or "bind failed: Address already in use").

There are various resources that discuss dealing with how to cause each instance to have its own jvm.config (which is a little more challenging when you run CF as a Windows service). See any of these blog entries:

• Nate Williams
• Mark Kruger
• Jeff Houser
• Scott Stroz

Where is this port tweak documented?

I'm sure some may wonder, "where would I have learned of this DEBUGGER_SERVER_PORT tweak for the debugger port?" It's easy to have missed but it's discussed in several places:

• The CFBuilder docs page on using the debugger, also in the whole user guide in PDF form
• Mentioned also in the cf8 release notes (PDF) (the debugger was in fact enabled then, for use with the Adobe CF Eclipse extensions, and is something I've written about before: see older entries in my debugging category here). Sadly, while the CF8 docs do have a page on using the debugger, the page makes no mention of this port setting argument. Worse, I see now that we can no longer add comments to the help pages in that release, to point to the CF9 docs for more.

Want still more documentation on this and more about the debugger?

I also document it in my 25-page chapter on the CF Debugger in the ColdFusion 9 Web Application Construction Kit, Vol 2. Fortunately, that chapter is one of a few that are available online. If I may say so, it's about the only substantial documentation on the CF debugger, as I cover not only understanding and configuring it, but also troubleshooting like that above. (And the concepts apply just as well to CF8.)

Hope all that helps someone.

I'll post a review in coming weeks after I've had a chance to take a look.

Free Preview Chapter on ORM

It's chapter 4, ORM Database Interaction, and as you'll see John leads you gently through this important new feature of CF9. Assuming you have no prior experience with ORM, he works in 20 pages from introducing the concepts, to quickly configuring and coding, to working with relationships, and more. You'll see he uses lots of screenshots and example code.

One editorial/review comment: I did notice that the preview chapter lists a last section to be on "custom configuration", which isn't ever found in the chapter. I brought this to John's attention and he apologized that it slipped through.

Having contributed to several books myself^*, I know that can happen and I don't regard it as a big deal. It doesn't take away at all from the rest of the book.

Looking forward to the rest of the book

As for that rest of the book, and why you may want to consider it, the introduction indicates it "will teach you the basics of ColdFusion programming, basic application architecture, object reuse, and ORM concepts before showing you a range of topics including AJAX library integration, RESTful Web Services, Unit Testing, building custom tags, and his hybrid example of tags and objects COOP" ... "with real-world examples of the hows and whys, to get more done faster with ColdFusion 9" ...[and] "also covers the new features of ColdFusion Builder and additional version 9 updates".

I'm sure it will benefit many, and I'll look into all that when I get the review copy, and I'll be back to pass along my observations.

^*I'm sure the publishers of my own books would think it appropriate at this point to mention those other books, which are also out recently and updated for CF9. They are the ColdFusion 9 Web Application Construction Kit, Volume 1 (Getting Started), Volume 2, Application Development, and Volume 3, Advanced Application Development.

I think it's helpful to have all the resources in one place. Indeed, ultimately I'll move this to my "resource lists" page where I keep similar "compendia".

I created the list of VAR scope resources today after helping a client with a problem which seemed related to this classic problem: the need to remember to var scope your variables in CFCs. It's often the cause of subtle bugs. Like many, they still hadn't heard about the problem (or had seen mention of it but didn't really understand it).

So if you're in that place, or know someone who may be, here are resources to help get started on understanding the topic and related issues. As always, the CF community has rallied the troops on the matter, and several folks have blogged in various detail or on various related aspects.

About the resources

The first few elaborate on the problem, and the first one even includes a live running example to demonstrate the point. Then a couple explain some related issues.

I also then list resources on the related new "local" scope in CF 9, and some more that discuss compatibility issues with that.

Note that these may have been written any time in the past couple/few years, so keep that in mind and be sure to check the comments as well.

The resources

First, some general resources introducing the var scoping issue/feature:

• Thread safety and the var scope - live example, by Mike Schierberl
• Memory Leaks: Part III - sessions and cfcs, Mike's previous blog entry discussing a memory leak he'd found related to CFCs (and perhaps the var scope) back in 2006
• Why precisely is it important to var-scope your variables?, by Nathan Strutz
• Thread safety example: Var scope your loop index in ColdFusion CFCs!, by Dave Shuck
• Object Oriented Coldfusion : 4 : The var scope, by Adrian Moreno

And some that address various issues related to using the VAR scope:

• Always var scope! Always!! Except..., by Ray Camden
• Var Scoping Queries, by Gary Gilbert
• VAR scoping using structures, by Dave Shuck
• The VAR keyword is idiotic, by Steve Nelson
• The REAL reason you need to var-scope your local CFC function variables, by Tyson Vanek

And some on the change in CF9, for the local scope:

• The New ColdFusion LOCAL Scope, by Ben Forta
• Deciphering the new Local Scope, by Adam Tuttle
• Repeat - ColdFusion 9 does NOT remove the need to var scope!, by Ray Camden

And some tangential discussions of that, including some compatibility issues with the new scope:

• Be careful with the 'local' scope when migrating from CF8 to CF9, by Dan Skaggs
• CHF Warning - Impacts MXUnit, by Ray Camden (important impact of CF 9 CHF 1, even if not using MXUnit)
• LOCAL Variables Scope Conflicts With ColdFusion Query of Queries, by Ben Nadel
• Is this an issue with the local scope in ColdFusion 9?, by Paul Kukiel
• ColdFusion 9 and the local scope continued, by Paul Kukiel
• ColdFusion 9 and the LOCAL Scope, by Joseph Lamoree
• Major Flaw in CF9 - May Break Code! and part 2/part 3, by Sami Hoda

The VarScope tool

Conclusion

Hope those are helpful. Again, it's just a starting list. I welcome additions, and I look forward to your comments. In time, I'll move this (and any suggested additions) to my "resource lists" page. Check that out for similar lists of resources on various subjects.

Well, there are several ways you can watch them, as this entry will discuss, and some may be better suited to the job than others. It can be very interesting to discover what's going on, especially if you're having any suspected performance problems which you think may be related to ORM processing (or just if you wonder what all it does for you).

As for spying on the SQL, of course ORM support is just a different way that the CFML engine (through the ORM framework) sends SQL to a database via a regular DSN, just like any other request, so there's nothing really "tricky" about this. It's just about realizing that while you don't write the SQL yourself, it's still generated by the CFML engine/ORM framework, and you may not realize/consider the available tools which can spy on it, just like any other DB processing from within CF. Indeed, some people may not even realize how many options exist to spy on JDBC interactions from their CFML engine to the database engine.

The good news is that there are several approaches, some included in CF (some depending on the edition), and some available separately which would work in any edition of CF or the other CFML engines (Open BlueDragon, Railo, etc.), and with any of the ORM frameworks. And again, some may be better than others for certain challenges.

(FWIW, besides the aforementioned Transfer and Reactor, there are still other ORM solutions for CFML, which I mention in my CF411 list as CFML ORM Frameworks. Indeed, note that you can run Hibernate on CF prior to CF9, if you want to.)

Built-in ORM Logging Option

First, note that there is indeed a built-in option in the CF ORM setup where one can enable logging, settable in the application.cfc: see the this.ormsettings option and its available key/value pair, logSQL="true".

There are several resources where you can learn more on that (and a related log4j property file approach to logging this). Besides the CF9 docs page on the ORM settings, there is also a blog entry by Adobe engineer Rupesh Kumar.

The default is to log this information to the console, but you can manipulate those log4j settings to tell it to use a file (see the links above). Even so, this will result in quite a lot of data being logged, which you will then need to connect back to your specific requests. The following approaches may be preferable.

Using FusionReactor or SeeFusion

Users of any CF edition (6+) or CFML engine can use tools like SeeFusion and FusionReactor, which have always had the ability to monitor database interactions by "wrapping" the datasource to be monitored. FusionReactor engineer John Hawksley has posted a recent article specifically on monitoring CF9's ORM interaction, in the FR Devnet site, Using FusionReactor's JDBC Driver Wrapper With ColdFusion 9 ORM. Its concepts would apply to any ORM, of course.

Similarly, I've written generically about FusionReactor's database monitoring feature in What is the FusionReactor datasource monitoring feature? Why would I use it? Powerful stuff. As I point out in that article, the concepts discussed apply as well to SeeFusion's ability to monitor queries by wrapping datasources.

That said, it's worth noting that FusionReactor does have a couple of advantages, in that it provides for the display of all queries for a given request (while viewing the details of that request), whereas SeeFusion only lets you see the slowest query in a given request. FusionReactor also provides a separately available display of all the slowest queries (across all requests). It also logs every query (connecting it to a given request as well), while SeeFusion (Enterprise, at least) can also log the slowest queries to a database.

And note that both of these track any requests coming out of CF, not just those associated with a given request. So if there is ORM SQL that is associated with the startup of CF, that's tracked too. (And for those aware of issues with CF's Client Variables, such DB activity is also tracked, even that done by the hourly purge, which takes place on a background, non-jrpp thread.)

CF Enterprise Server Monitor

Those running CF 8 or 9 (Enterprise only) will find that its available Server Monitor does offer built-in monitoring of the SQL executed against CF datasources, at least, as long as you enable "Start Profiling" (which also enables other features, and overhead, as well). In this way, the Enterprise Server Monitor can monitor database interactivity, including ORM interactions.

Unlike FusionReactor (and like SeeFusion), it focuses only on showing queries that exceed certain limits, and at that it shows them only in a "Slowest Queries" interface, tracking the slowest queries among all requests. The CF Enterprise Server Monitor also has no logging ability at all.

Being able to see every single DB interaction for a given request (or across all requests) may be all the more interesting for discovering/observing what's happening with ORM interactivity.

Another alternative CF feature

Still another little-known feature for spying on JDBC interactions in CF is by way of the JDBC "spy" feature, which does in fact allow logging of all JDBC interactions mde from within CF. This feature was first enabled by way of the DataDirect 3.5 driver update which was made available (as an optional upgrade for 6 and 7) in the CF 7.02 timeframe. I wrote about the Spy feature back back in Aug 2006.

Since then, CF 8 (and now 9) offer it instead as a new "log activity" option in the "advanced settings" for a datasource definition in the CF Admin (which is disabled by default). I pointed this out in another entry from 2007 as one of many easily missed changes for the CF 8 Admin.

This "log activity" output is not as easy to interpret as FusionReactor's logs, and can indeed be voluminous (moreso than FR's), so be careful. Anyway, it's one of the several ways you can monitor JDBC interactions between CFML and your DB engine. Again, any of these may be useful for monitoring any of your CFML/database interactions.

Generic DB Monitoring tools

Indeed, it's worth noting finally that while the focus here has been watching the DB interaction from CF (and the ORM framework) to the database (by watching the JDBC traffic going out of CF and returning), you could just as well watch the DB interactivity from the DB's perspective instead (watching it coming and and being returned).

There are many tools that can monitor database processing, available for each of the major databases (free and commercial). I list several such tools in one of my CF411 section, Database/SQL Monitoring Tools.

Hope all that's helpful, whether you use ORM or not.

About the hidden gems series

With CF9 out and final, I'm excited to start identifying the interesting little bits and bobs which you may not have heard much about. Some will know I've done this going back to one of my first articles in the CFDJ from Feb 2000, on "Hidden Gems in 4.01".

Over the course of the next few weeks, I'll share various things that you may have missed, whether in the CF Admin, the language, the docs, or otherwise.

Hidden Gem 1: Controlling Application.cfm/cfc Lookup Order in Admin

If you've not noticed it, there is now a setting in the CF9 Admin for controlling how far above the current directory CF will look for Application.cfm/cfc if not found in the current directory. This is a server-wide setting (found on the Settings page).

How application file searching works by default

As you should know, if CF doesn't find an Application.cfm (or Application.cfc, since CF 7) in the current folder where a request starts, CF searches up to the parent, then the grandparent, trying to find one (and since CF 7 if it finds an Application.cfc it chooses that over an Application.cfm).

What many don't know is that by default ColdFusion has always searched all the way to the system root (the drive root). It doesn't stop at the webroot, which could lead to both security and possibly performance issues. This can now be changed using this setting.

To change this, find the Settings page which is the first link in the options on the left (see the arrow pointing to it in the image above). This new setting is about 2/3 the way down this page of settings (which is getting quite long!)

The options available in CF9

As the screenshot above shows, you can now change things to choose either of these alternative search behaviors:

• Default order
• Until webroot
• In webroot

As I said at the outset, things are not quite as obvious as they may seem. OK, the first is: it maintains the default behavior of searching to the system root, such as c:\.

The second does what some have wished: makes CF stop searching when it reaches the webroot. (The third option may make you think that this second option means search until the webroot but do not search in the webroot. That's NOT what it means.)

Before explaining that, let me point out as well that changing this setting is immediate. No restart of CF 9 is required.

The surprising "in webroot" option

So what then is the deal with the third option, "in webroot"? It may surprise you (as it did me, at first). What it does is tell CF to search either in the current directory (as they all do) or if not found, search ONLY in the webroot. It DOES NOT search the directories between the current directory and the webroot. Interesting. (To be clear, it does not mean "don't look in the current directory but only in the webroot". It still takes affect only if there is no Application.cfc/cfm in the current directory where a request starts.)

Why might one use this third option? Well, if they know that their server code directories are setup in such a way that the Application.cfc/cfm file is either in the directory of templates it should apply to, or if not there it's only in the webroot, then this option would suit them.

I can see it potentially causing confusion if folks don't know about the change in behavior and wonder, "why isn't my Application.cfc/cfm file (in an intermediary directory) running?"

Also, the fact that this is a system-wide feature means that all your apps on your entire server must accept the behavior specified here.

No documentation on this feature

Another source of confusion is the fact that there's no documentation explaining this feature. It's mentioned only in passing in the online help of the Administrator, without explanation of the meaning of the options. It's not mentioned at all in the docs, either the "Configuring and Administrating CF" manual or the "Developing Applications" manual. That's a real shame and I hope it will change in the next release.

In the meantime, I hope that this entry will help. Sorry that it was a long one, but again it's just not a trivial feature. It is indeed a hidden gem, and look for more to come from me soon.

(I've provided a zip here that can help you demonstrate things. Unzip it into a web root and run the nested /testdir/testsubdir/test.cfm, and observe that whichever Application.cfm runs reports where it was found. You can rename the various Application.cfm files to xApplication.cfm to observe the impact of CF's search order, and as you change the Admin settings. You'll also want to copy one of the Application.cfm files to a direcory above your webroot to test that, too. The content is identical in all of them.

Of course, beware when unzipping the file that you don't overwrite any Application.cfm that you already have in your webroot. Also, beware that if you have an Application.cfc file in that webroot, it would take precedence over the Application.cfm file.

Finally, to find the zip file, see the link appearing just below this blog entry.)