About scopes

Variables differ in the source of the data, 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 on user-defined function scopes see "Specifying the scope of a function," in Chapter 9.

Scope types

The following table lists the types of ColdFusion scopes and describes their uses:

Scope

Description

Variables (local)

The default scope for variables of any type that are created with the cfset and cfparam tags. A local variable is available only on the page on which it is created and any included pages (see also the Caller scope).

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 information on using the Form scope, see Chapter 26, "Retrieving and Formatting Data".

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.

Attributes

Used only in custom tag pages. Contains the values passed by the calling page in the custom tag's attributes. For information on using the Attributes scope, see Chapter 10, "Creating and Using Custom CFML Tags".

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 information on using the Caller scope, see Chapter 10, "Creating and Using Custom CFML Tags"

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 on the ThisTag scope, see "Accessing tag instance data," in Chapter 10.

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.

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 CFML Reference.

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.

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 information on using the Client scope, see Chapter 15, "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. You cannot use application variables on server clusters where more than one computer can process requests from a single session. For information on using the Session scope, see Chapter 15, "Using Persistent Data and Locking".

Application

Contains variables that are associated with one, named application on a server. The cfapplication tag name attribute specifies the application name. For information on using the Application scope, see Chapter 15, "Using Persistent Data and Locking".

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 information on using the Server scope, see Chapter 15, "Using Persistent Data and Locking".

Flash

Variables sent by a Macromedia Flash movie to ColdFusion and returned by ColdFusion to the movie. For more information on the Flash scope, see Chapter 29, "Using the Flash Remoting Service".

Arguments

Variables passed in a call to a user-defined function or ColdFusion component method. For more information see "About the Arguments scope," in Chapter 9.

This

Variables that are declared inside a ColdFusion component or in a cffunction tag that is not part of a ColdFusion component. These variables exist only while a function executes.

function local

Contains variables that are declared inside a user-defined function that you create using CFScript and exist only while a function executes. For information on using function local variables, see Chapter 9, "Writing and Calling User-Defined Functions".

Scope	Description
Variables (local)	The default scope for variables of any type that are created with the `cfset` and `cfparam` tags. A local variable is available only on the page on which it is created and any included pages (see also the Caller scope).
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 information on using the Form scope, see Chapter 26, "Retrieving and Formatting Data".
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.
Attributes	Used only in custom tag pages. Contains the values passed by the calling page in the custom tag's attributes. For information on using the Attributes scope, see Chapter 10, "Creating and Using Custom CFML Tags".
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 information on using the Caller scope, see Chapter 10, "Creating and Using Custom CFML Tags"
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 on the ThisTag scope, see "Accessing tag instance data," in Chapter 10.
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.
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 CFML Reference.
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.
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 information on using the Client scope, see Chapter 15, "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. You cannot use application variables on server clusters where more than one computer can process requests from a single session. For information on using the Session scope, see Chapter 15, "Using Persistent Data and Locking".
Application	Contains variables that are associated with one, named application on a server. The `cfapplication` tag `name` attribute specifies the application name. For information on using the Application scope, see Chapter 15, "Using Persistent Data and Locking".
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 information on using the Server scope, see Chapter 15, "Using Persistent Data and Locking".
Flash	Variables sent by a Macromedia Flash movie to ColdFusion and returned by ColdFusion to the movie. For more information on the Flash scope, see Chapter 29, "Using the Flash Remoting Service".
Arguments	Variables passed in a call to a user-defined function or ColdFusion component method. For more information see "About the Arguments scope," in Chapter 9.
This	Variables that are declared inside a ColdFusion component or in a `cffunction` tag that is not part of a ColdFusion component. These variables exist only while a function executes.
function local	Contains variables that are declared inside a user-defined function that you create using CFScript and exist only while a function executes. For information on using function local variables, see Chapter 9, "Writing and Calling User-Defined Functions".

Caution: To prevent data corruption, you lock code that uses Session, Application, or Server scope variables. For more information on using these scopes and locking access to code, see Chapter 15, "Using Persistent Data and Locking".

Creating and using variables in scopes

The following table shows how you create and refer to 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

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.

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.

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.

Attributes

Yes

On the custom tag page.

The calling page passing the values to a custom tag page in the custom tag's attributes.

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.

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.

Request

Yes

On the creating page and in any pages invoked 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.

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.

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.

Client

No

For one client in one application, over multiple browser sessions.

Specifying the prefix Client when you create the variable.

Session

Yes

For one client in one application and one browser session. Surround all code that uses application variables in cflock blocks.

Specifying the prefix Session when you create the variable.

Application

Yes

For multiple clients in one application over multiple browser sessions. Surround all code that uses application variables in cflock blocks.

Specifying the prefix Application 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.

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.

Arguments

No

Within the body of a user-defined function or ColdFusion component method.

The calling page passing an argument in the function call.

This

Yes

Within the body of a user-defined function or ColdFusion component method that was created using the cffunction tag, only while the function executes.

Specifying the prefix This when you create the variable.

(function local, no prefix)

Prohibited

Within the body of a user-defined function that was created using CFScript, only while the function executes.

A var statement in the function body.

Scope prefix (type)	Prefix required to reference	Where available	Created by
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.
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.
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.
Attributes	Yes	On the custom tag page.	The calling page passing the values to a custom tag page in the custom tag's attributes.
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.
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.
Request	Yes	On the creating page and in any pages invoked 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.
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.
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.
Client	No	For one client in one application, over multiple browser sessions.	Specifying the prefix Client when you create the variable.
Session	Yes	For one client in one application and one browser session. Surround all code that uses application variables in `cflock` blocks.	Specifying the prefix Session when you create the variable.
Application	Yes	For multiple clients in one application over multiple browser sessions. Surround all code that uses application variables in `cflock` blocks.	Specifying the prefix Application 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.
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.
Arguments	No	Within the body of a user-defined function or ColdFusion component method.	The calling page passing an argument in the function call.
This	Yes	Within the body of a user-defined function or ColdFusion component method that was created using the `cffunction` tag, only while the function executes.	Specifying the prefix This when you create the variable.
(function local, no prefix)	Prohibited	Within the body of a user-defined function that was created using CFScript, only while the function executes.	A `var` statement in the function body.

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
Variables (local scope)
CGI
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 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 to 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 UDFs that you define using CFScript as a structure. (In ColdFusion 4.5 and 5, the following scopes are not available as structures: Variables, Caller, Client, Server.)

You can reference the variables in these 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 refer to either of the following ways:

Request.MyVar

Request["MyVar"]

Similarly, you can use CFML structure functions to manipulate the contents of the scope. For more information on using structures, see Chapter 5, "Using Arrays and Structures".

Caution: 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, put those variables in a structure in the Session scope, then clear that structure. For example, put all your application variables in Session.MyVars and then call StructClear(Session.Myvars) to clear the variables.

Developing ColdFusion MX Applications with CFML
Using ColdFusion Variables