The Ultimate Var Scope Resource list? Understanding/resolving problems with the var scope in CFML
Note: This blog post is from 2010. Some content may be outdated--though not necessarily. Same with links and subsequent comments from myself or others. Corrections are welcome, in the comments. And I may revise the content as necessary.Do you know what the "var scope problem" is, and how pernicious it can be in causing very subtle bugs that can cause errors that are VERY hard to understand? I list here several resources to help you understand the issue. Some help plainly explain what the issue is, including even a live demo.
I also discuss below the key varscoper tool which you will want to use to help assess and indeed correct your own code.
(Update in 2022, 2019: while the many resources are indeed all quite old now, they all still apply, and most still exist. Where needed, I recovered them from the good ol' archive.org, an awesome resource for finding old content, as I've written about before.)
Why a list was needed
If you or anyone you know ever wants to get up to speed on the "var scope problem" in CF, you may be challenged by the fact that there are many discussions of the topic, spread across many blogs.
I created this list 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, and especially when instances of such a CFC may be saved in a shared scope. Like many, these folks still hadn't heard about the problem (introduced in CF6!). Others may have seen mention of it but didn't really understand it.
As always, the CF community has rallied the troops on the matter over the years, and several folks have blogged in various detail or on various related aspects. I think it's helpful to have all the resources in one place. Indeed, I've since moved this also to my "resource lists" page where I keep similar "compendia".
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 (sadly, his "live examples" mechanism no longer operates)
- 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 (recovered via archive.org)
- Object Oriented Coldfusion : 4 : The var scope, by Adrian Moreno
And some that address various issues related to using the VAR scope (in descending order of recency):
- cfparam with unscoped variables, by Mike Henke (recovered via archive.org)
- So what happens when you don't var scope? and Always var scope! Always!! Except..., by Ray Camden
- Var Scoping Queries, by Gary Gilbert (recovered via archive.org)
- VAR scoping using structures, by Dave Shuck (recovered via archive.org)
- The VAR keyword is idiotic, by Steve Nelson (recovered via archive.org)
- The REAL reason you need to var-scope your local CFC function variables, by Tyson Vanek (recovered via archive.org)
On the new "local" scope added in CF9
Some may know that CF9 added a new "local" scope, to help ease the challenge of working with "unscoped" vars within functions. For more on that, read on:
- The New ColdFusion LOCAL Scope, by Ben Forta
- 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 that new "local" scope alternative:
- Be careful with the 'local' scope when migrating from CF8 to CF9, by Dan Skaggs (recovered via archive.org)
- 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 (recovered via archive.org)
- ColdFusion 9 and the local scope continued, by Paul Kukiel (recovered via archive.org)
- Major Flaw in CF9 - May Break Code! and part 2/part 3, by Sami Hoda
The VarScoper tool
Finally, of course, as most of these resources point out, be sure to use Mike Schierberl's wonderful which can help you easily find whether you have instances of this problem. It tells you literally what to change, where, so don't let concern of this problem overwhelm you.The tool: varscoper tool (previously at riaforge.org until mid-2019, then that site was abandoned by Adobe)
It can help with tags or script (though he was seeking help in 2012 with an aspect of working with entirely-script-based CFCs, which never seemed resolved, if that may be an issue for your own needs).
And here are some resources about using that varscoper tool (they will link typically to where it WAS, at riaforge):
Twitter feed on the tool and its use- 'varscoper' For CFML Revisited (in 2016, by wouter)
- Several blog posts on the var scope tool, from creator Mike Schierberl (from 2006-2012)
- Ray Camden introducing his readers to it in 2008
- Ray shared some tips on the tool (See also comments from others)
- Brian Ghidinelli's commendation of it (and that it should be used frequently)
Finally, even as old as is, it has continued to be included in or integrated with various tools:
- Note that the tool is embedded in the Ortus CodeChecker, on ForgeBox
- VarScoper integration for Sublime Text 2 (from 2012)
- Mike Henke's varScoper Ant Target Example, if that may aid you in using Ant (recovered via archive.org)
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.
For more content like this from Charlie Arehart:Need more help with problems?
- Signup to get his blog posts by email:
- Follow his blog RSS feed
- View the rest of his blog posts
- View his blog posts on the Adobe CF portal
- If you may prefer direct help, rather than digging around here/elsewhere or via comments, he can help via his online consulting services
- See that page for more on how he can help a) over the web, safely and securely, b) usually very quickly, c) teaching you along the way, and d) with satisfaction guaranteed
I know this is an older discussion but my company recently moved from CF 8 to CF 10 and we are having issues with the local scope. I know that on CF 8 some people didn't like using <cfset var Local = StructNew() /> but I used it. I've read on a couple of pages that CF 9 will ignore it. Is this documented anywhere in Adobe documentation? If so, is this true in CF 10? I ask because I can't find it anywhere. Also, one of my pages included <cfset var Local = StructNew() /> and another structure <cfset var documentFields = StructNew() /> and CF 10 threw me an error "Variable DOCUMENTFIELDS is undefined." until I changed "<cfset var Local = StructNew() />" to "<cfset var myLocal = StructNew() />" and all of my variables that were prefixed as "Local." to "myLocal." This all leads me to believe that CF 10 is not ignoring <cfset var Local = StructNew() />.
So as for the local scope, it's not that CF 8 used it and 9/10 do not. Rather, it's that CF9 added a new built-in scope called "the local scope", so when you say you were using it before, what you were doing was creating a variable CALLED local. And now you are experiencing a clash with the new behavior.
As for you saying you "can't find it anywhere" in the CF docs, I would suspect you're looking in the CFML Reference, right? It's such a shame that folks gravitate to that only as "the docs". If you were not aware, there is an equally great (I might even say "better") manual, "Developing Applications with CF" that is in fact nearly as large (1300 pages, versus 1500 for the Ref manual).
You can find the manual online, and in fact here's the link to a discussion of the Local scope:
http://help.adobe.co...
And here's a link to the section that describes it as a new feature in CF9:
http://help.adobe.co...
Hope that helps.
Sorry to repeat myself but I must say that I find it odd that one of my functions in a CFC that included
<cfset var Local = StructNew() />
<cfset var documentFields = StructNew() />
...
<cfset Local.me = "Scott" />
<cfset StructClear(documentFields) />
<cfset StructInsert(documentFields,"job_id",form.job_id) />
...
threw this error "Variable DOCUMENTFIELDS is undefined."
And worked after I changed it to
<cfset var myLocal = StructNew() />
<cfset var documentFields = StructNew() />
...
<cfset myLocal.me = "Scott" />
<cfset StructClear(documentFields) />
<cfset StructInsert(documentFields,"job_id",form.job_id) />
...
Thanks again
It's that local is now a scope all its own, and therefore you run risk of oddities if you try to create a variable that uses that scope as its name (just as one can run afoul in using a variable called URL, when there is a scope of that name, and so on.)
Now, I have not studied the matter carefully, to understand when it may or may not "work', when it may or may not fail with a suitable and obvious message, and when it may or may not result in unexpected behavior (as it seems you're experiencing).
And I won't deny that it could be that the docs could do a better job at discussing those sort of issues. The docs don't always get it right. Sometimes there's more info in release notes (about what's "changing") that may not make it to the docs.
More than that, often it's only after a new release has been out for a while (sometimes weeks, months, or even years) before many people experience a given problem and start talking it up. You may find that others have indeed discussed this more, and may have identified useful workarounds for the challenges, or they may well have opened bug reports to which you could add a vote.
Finally, you may also want to bring this up on the Adobe CF forums (http://forums.adobe....) to see if others have experienced it or would share thoughts.
Hope that's helpful.