Local (function-local, UDFs and CFCs only)
Last updated on
Dec 20, 2023
Variables differ in how they are set (by your code or by ColdFusion), the places in your code where they are meaningful, and how long their values persist. These considerations are generally referred to as a variable's scope. Commonly used scopes include the Variables scope, the default scope for variables that you create, and the Request scope, which is available for the duration of an HTTP request.
Note:
User-defined functions also belong to scopes. For more information, see Specifying the scope of a function in the Using UDFs effectively.
Scope types
The following table describes ColdFusion scopes:
| Scope | Description |
|---|---|
| Application | Contains variables that are associated with one, named application on a server. The cfapplication tag name attribute or the Application.cfc This.name variable setting specifies the application name. For more information, see Using Persistent Data and Locking. |
| Arguments | Variables passed in a call to a user-defined function or ColdFusion component method. For more information, see About the Arguments scope in the Working with arguments and variables in functions. |
| Attributes | Used only in custom tag pages and threads. Contains the values passed by the calling page or cfthread tag in the tag's attributes. For more information, see Creating and Using Custom CFML Tags and Using ColdFusion Threads. |
| Caller | Used only in custom tag pages. The custom tag's Caller scope is a reference to the calling page's Variables scope. Any variables that you create or change in the custom tag page using the Caller scope are visible in the calling page's Variables scope. For more information, see Creating and Using Custom CFML Tags. |
| CGI | Contains environment variables identifying the context in which a page was requested. The variables available depend on the browser and server software. For a list of the commonly used CGI variables, see Reserved Words and Variables in the CFML Reference. |
| Client | Contains variables that are associated with one client. Client variables let you maintain state as a user moves from page to page in an application, and are available across browser sessions. By default, Client variables are stored in the system registry, but you can store them in a cookie or a database. Client variables cannot be complex data types and can include periods in their names. For more information, see Using Persistent Data and Locking. |
| Cookie | Contains variables maintained in a user's browser as cookies. Cookies are typically stored in a file on the browser, so they are available across browser sessions and applications. You can create memory-only Cookie variables, which are not available after the user closes the browser. Cookie scope variable names can include periods. |
| Flash | Variables sent by a SWF movie to ColdFusion and returned by ColdFusion to the movie. For more information, see Using the Flash Remoting Service. |
| Form | Contains variables passed from a Form page to its action page as the result of submitting the form. (If you use the HTML form tag, you must use method="post".) For more information, see Introduction to Retrieving and Formatting Data. |
| Local (function local) | Contains variables that are declared inside a user-defined function or ColdFusion component method and exist only while a function executes. For more information, seeWriting and Calling User-Defined Functions. |
| Request | Used to hold data that must be available for the duration of one HTTP request. The Request scope is available to all pages, including custom tags and nested custom tags, that are processed in response to the request. This scope is useful for nested (child/parent) tags. This scope can often be used in place of the Application scope, to avoid the need for locking variables. Several chapters discuss using the Request scope. |
| Server | Contains variables that are associated with the current ColdFusion server. This scope lets you define variables that are available to all your ColdFusion pages, across multiple applications. For more information, see Using Persistent Data and Locking. |
| Session | Contains variables that are associated with one client and persist only as long as the client maintains a session. They are stored in the server's memory and can be set to time out after a period of inactivity. For more information, see Using Persistent Data and Locking. |
| This | Exists only in ColdFusion components or cffunction tags that are part of a containing object such as a ColdFusion Struct. Exists for the duration of the component instance or containing object. Data in the This scope is accessible from outside the component or container by using the instance or object name as a prefix. |
| ThisTag | Used only in custom tag pages. The ThisTag scope is active for the current invocation of the tag. If a custom tag contains a nested tag, any ThisTag scope values you set before calling the nested tag are preserved when the nested tag returns to the calling tag. The ThisTag scope includes three built-in variables that identify the tag's execution mode, contain the tag's generated contents, and indicate whether the tag has an end tag.A nested custom tag can use the cfassociate tag to return values to the calling tag's ThisTag scope. For more information, see Accessing tag instance data in the Executing custom tags. |
| Thread |
Variables that are created and changed inside a ColdFusion thread, but can be read by all code on the page that creates the thread. Each thread has a Thread scope that is a subscope of a cfthread scope. For more information, see Using ColdFusion Threads. |
| thread local | Variables that are available only within a ColdFusion thread. For more information, seeUsing ColdFusion Threads. |
| URL | Contains parameters passed to the current page in the URL that is used to call it. The parameters are appended to the URL in the format ?variablename = value&variablename=value...; for example www.MyCompany.com/inputpage.cfm?productCode=A12CD1510&quantity=3. |
If a URL includes multiple parameters with the same name, the resulting variable in the ColdFusion URL scope consists of all parameter values separated by commas. For example, a URL of the form http://localhost/urlparamtest.cfm?param=1¶m=2¶m=3 results in a URL.param variable value of 1,2,3 on the ColdFusion page.|
Variables |
The default scope for variables of any type that are created with the cfset and cfparam tags. A Variables scope variable is available only on the page on which it is created and any included pages (see also the Caller scope).Variables scope variables created in a CFC are available only to the component and its functions, and not to the page that instantiates the component or calls its functions. |
Note:
To prevent data corruption, you lock code that uses Session, Application, or Server scope variables. For more information, see Using Persistent Data and Locking.
Creating and using variables in scopes
The following table shows how you create and reference variables in different scopes in your code. For more information on the mechanisms for creating variables in most scopes, see Creating variables.
| Scope prefix(type) | Prefix required to reference | Where available | Created by |
|---|---|---|---|
| Application | Yes | For multiple clients in one application over multiple browser sessions. Surround code that uses application variables in cflock blocks. | Specifying the prefix Application when you create the variable. |
| Arguments | No | Within the body of a user-defined function or ColdFusion component method. | The calling page passing an argument in the function call. |
| Attributes | Yes | On a custom tag page, or inside a thread | For custom tags, the calling page passing the values to a custom tag page in the custom tag's attributes. For threads, the cfthread tag specifying attribute values. |
| Caller | On the custom tag page, Yes.On the calling page, No (Variables prefix is optional). | On the custom tag page, by using the Caller scope prefix.On the page that calls the custom tag, as local variables (Variables scope). | On the custom tag page, by specifying the prefix Caller when you create the variable.On the calling page, by specifying the prefix Variables, or using no prefix, when you create the variable. |
| Cffile | Yes | Following an invocation of cffile . | A cffile tag. |
| CGI | No | On any page. Values are specific to the latest browser request. | The web server. Contains the server environment variables that result from the browser request. |
| Client | No | For one client in one application, over multiple browser sessions. | Specifying the prefix Client when you create the variable. |
| Cookie | No | For one client in one or more applications and pages, over multiple browser sessions. | A cfcookie tag. You can also set memory-only cookies by specifying the prefix Cookie when you create the variable. |
| Flash | Yes | A ColdFusion page or ColdFusion component called by a Flash client. | The ColdFusion Client access. You assign a value to Flash.You can assign values to the Flash.result and Flash.pagesize variables. |
| Form | No | On the action page of a form and in custom tags called by the action page; cannot be used on a form page that is not also the action page. | A form or cfform tag. Contains the values of form field tags (such as input) in the form body when the form is submitted. The variable name is the name of the form field. |
| Local | No | Within the body of a user-defined function or ColdFusion component method, only while the function executes. | Either of the following:
|
| Request | Yes | On the creating page and in any pages run during the current HTTP request after the variable is created, including in custom tags and nested custom tags. | Specifying the prefix Request when you create the variable. |
| Server | Yes | To any page on the ColdFusion server. Surround all code that uses server variables in cflock blocks. | Specifying the prefix Server when you create the variable. |
| Session | Yes | For one client in one application and one browser session. Surround code that uses Session scope variables in cflock blocks. | Specifying the prefix Session when you create the variable. |
| This | Yes | Within a ColdFusion component or the body of a user-defined function that was created using the cffunction tag and place in an object, structure, or scope. In the containing page, through the component instance or containing object. | Within the component or function by specifying the prefix This when you create the variable.In the containing page, by specifying the component instance or object that contains the function as a prefix when you create the variable. |
| ThisTag | Yes | On the custom tag page. | Specifying the prefix ThisTag when you create the variable in the tag or using the cfassociate tag in a nested custom tag. |
| Thread | The thread name.Inside the thread that creates the variable, you can also use the keyword thread. | Any code in the request. | Using the keyword thread or the thread name as a prefix when you create the variable.You can create Thread variables only inside the thread. |
| thread-local (no prefix) | none | Within a thread created by the cfthread tag | Using no prefix when you create the variable. You can also use the keyword var before the variable name. |
| URL | No | On the target page of the URL. | The system. Contains the parameters passed in the URL query string used to access the page. |
| Variables(Local) | No |
On the current page. Cannot be accessed by a form's action page (unless the form page is also the action page). Variables in this scope used on a page that calls a custom tag can be accessed in the custom tag by using its Caller scope; however, they are not available to any nested custom tags. | Specifying the prefix Variables, or using no prefix, when you create the variable. (To create a Variables scope variable inside a ColdFusion thread, you must use the Variables prefix.) |
Using scopes
The following sections provide details on how you can create and use variables in different scopes.
Evaluating unscoped variables
If you use a variable name without a scope prefix, ColdFusion checks the scopes in the following order to find the variable:
-
-
Arguments
-
Thread local (inside threads only)
-
Query (not a true scope; variables in query loops)
-
Thread
-
Variables
-
CGI
-
Cffile
-
URL
-
Form
-
Cookie
-
Client
Because ColdFusion must search for variables when you do not specify the scope, you can improve performance by specifying the scope for all variables.
To access variables in all other scopes, you must prefix the variable name with the scope identifier.
Scopes and CFX tags
ColdFusion scopes do not apply to ColdFusion Extension (CFX) tags, custom tags that you write in a programming language such as C++ or Java. The ColdFusion page that calls a CFX tag must use tag attributes to pass data to the CFX tag. The CFX tag must use the Java Request and Response interfaces or the C++ Request class to get and return data.
The Java setVariable Response interface method and C++ CCFX::SetVariable method return data to the Variables scope of the calling page. Therefore, they are equivalent to setting a Caller scope variable in a custom ColdFusion tag.
Using scopes as structures
ColdFusion makes all named scopes available as structures. You cannot access the function-local scope for user-defined functions (UDFs) that you define using CFScript as a structure.
You can reference the variables in named scopes as elements of a structure. To do so, specify the scope name as the structure name and the variable name as the key. For example, if you have a MyVar variable in the Request scope, you can reference it in either of the following ways:
Request["MyVar"] |
Similarly, you can use CFML structure functions to manipulate the contents of the scope. For more information on using structures, see Using Arrays and Structures.
Note:
Do not call StructClear(Session) to clear session variables. This deletes the SessionID, CFID, and CFtoken built-in variables, effectively ending the session. If you want to use StructClear to delete your application variables, place those variables in a structure in the Session scope, and then clear that structure. For example, place all your application variables in Session.MyVars and then call StructClear(Session.MyVars)_ to clear the variables._