CFML Reference
ColdFusion Expressions: Operands, Operators and Other Constructs

Variables

Variables are the most frequently used operands. Variable values can be set and reset, and passed as attributes to CFML tags and JRun servlets. They can be passed as parameters to functions, and can replace most constants.

For a list of the variables associated with ColdFusion, see the CFML Quick Reference.

Variable naming conventions

When naming ColdFusion variables and form fields, keep these guidelines in mind:

• Variable names must begin with a letter, which can be followed by any number of letters or numbers or the underscore character.
• Variable names must be one word.
• Do not use spaces in variable names.
• Use descriptive names not abbreviations.
• Queries and variables cannot have the same name in a ColdFusion application page.
• Although ColdFusion variables are not case-sensitive, keep capitalization consistent in order to keep your code consistent.
• When writing queries and forms, match your form field names with the corresponding database field name.
• In some cases, you must put a pounds signs around a variable name to allow ColdFusion to distinguish it from string or HTML text, and to insert its value as opposed to its name. For more information, see "Pound Signs".

ColdFusion variable types

The following table describes the types of variables you can use in a ColdFusion application page.

Variable Type	Description
Query Result	Results of a database query can be used as dynamic parameters. For example, if you create a query named LookupUser that finds the ID for a given user name, you can use this ID in another query or in a call to cfoutput.
Local Variable	The default scope for variables of any type created with the cfset and cfparam tags. For example, <cfset A = 5> sets the variable A to 5. This variable is available only on the application page where it is created and any included pages.
URL Parameter	Parameters appended to a URL after the application page name in the format variablename = value. URL parameters are stored in structures. For more information, see "Variables stored in structures".
Form Field	The most common way of passing parameters to a page. When a user enters data in a form field, a parameter with the name of the form field is passed to the action page. Form fields are stored in structures. For more information, see "Variables stored in structures".
Client	Variables associated with a particular client. Lets you maintain state as a user moves from page to page in an application. Stored in the system registry by default, but you can also store them in a cookie or in a database. Client variables are part of the ColdFusion Web Application Framework. For more information, see Developing ColdFusion Applications.
Server	Variables associated with the current Web server. Available to all ColdFusion applications until the ColdFusion server is shut down. This server scope lets you define variables that all your ColdFusion application pages can reference. Server variables are stored in structures. For more information, see "Variables stored in structures". For information on locking server variables, see the description of cflock.
Session	Variables tied to an individual client that persist for as long as that Client ID maintains a session. Session variables, like current client variables, require a client name and are available only to that one Client ID. Unlike client variables, session variables are stored in the server's memory and can be set to time-out after a precise period of inactivity. Session variables are stored in structures. For more information, see "Variables stored in structures". Session variables should be locked when accessed. For information, see the description of cflock. Session variables are part of the ColdFusion Web Application Framework. This means that they are used in the context of an Application.cfm page. For more information, see Developing ColdFusion Applications and the description of cfapplication.
Application	Variables tied to an application as defined in the CFAPPLICATION NAME attribute, typically used in the Application.cfm file. Application variables work only if an application name is defined. Application variables are stored in structures. For more information, see "Variables stored in structures". Application variables should be locked when accessed. For information, see the description of cflock. Application variables are part of the ColdFusion Web Application Framework. This means that they are used in the context of an Application.cfm page. For more information, see Developing ColdFusion Applications and the description of cfapplication.
Request	Variables storing data that pertains to the processing of a request to a single page. Request variables are convenient for storing data in a structure, carried through nested tags, such as Custom Tags, and processed at once. Request variables are stored in structures. For more information, see "Variables stored in structures".
Caller	Variable that lets you call and use variables from the calling template in a ColdFusion custom tag.
HTTP Cookies	Variables stored in the browser. Available every time the browser makes a page request. You can create cookie variables with the cfcookie tag.
File	Read-only variables. Created when a cffile action = "upload" operation is executed.
CGI Environment	Every page request has several environment variables sent to it that relate to the context in which it was requested. The variables available depend on the browser and server software. For a list of the commonly used CGI variables, see "CGI Environment Variables". Note: CGI environment variables are created even when you are using a Web server that supports a server API.

Qualifying, or scoping, variable references

ColdFusion distinguishes between identically named parameters from different sources by using a different prefix for each source. Specifying a variable's source is known as "scoping" the variable. For example, to specify a variable called State that is passed in a form submission, you would reference it as Form.State. To specify a variable named State passed in a URL, you would reference it as URL.State.

Although you are not required to use the scope prefix unless two variables in different scopes have the same name, it is recommended for readability and processing speed that you use prefixes. For example, the variable Form.lastname is clearer than a variable called simply lastname.

Many CFML tags, such as cferror and cfftp, have variables associated with them. Typically, these variables use the tag name as the prefix. For a list of the variables, see the Quick Reference to CFML.

Scopes and variables

The following table lists the types of variable scopes, and shows how you refer to them in your code. In addition to these scopes, there are a number of ColdFusion data structures that provide information about the results of a tag or operation. For information on special variables, see the CFML Quick Reference and the documentation of the individual CFML tags that return these variables.

Prefix	Required	Availability	Comment
Variables (Local)	No	Cannot be accessed by a custom tag called by the page or by an action page that differs from a form page that creates the variables	Created by the cfset or cfparam tag by using a Variables prefix or no prefix
Form	No	Can be used on the action page of a form; cannot be used on a form page that is not also the action page	Created by the form or cfform tag name attribute. Contains the values of data tags (such as input) in the form body when the form is submitted.
URL	No	The target page of a URL	Contains the parameters passed in the URL query string that accesses a page
Attributes	Yes	On the custom tag page only	Contains the values passed in the custom tag's attributes by the calling page to a custom tag page
Caller	No in calling page. Yes in custom tag page.	As normal local variables on the page calling the custom tag. Available on the custom tag page by using the Caller scope prefix.	Created in a custom tag page cfset or cfparam tag by using a Caller prefix. Created as local variables on the calling tag page.
Request	Yes	On the creating page and in any tags, including nested tags, called after the variable is created	Created by the cfset or cfparam tag by using a Request prefix
CGI	No	On any page; values are specific to the latest browser request	Created by the Web server. Contains the server environment variables that result from the browser request.
Cookie	No	For one client, in one or many applications and pages, over multiple browser sessions	Created by the cfcookie tag
Client	No	For one client in one application over multiple browser sessions	Created by the cfset or cfparam tag by using a Client prefix
Session	Yes	For one client in one application and one browser session	Created by the cfset or cfparam tag by using a Session prefix
Application	Yes	For multiple clients in one application over multiple browser sessions	Created by the cfset or cfparam tag by using an Application prefix
Server	Yes	On any page on the ColdFusion server	Created by the cfset or cfparam tag by using a Server prefix

Performance and scoping

You can improve performance by qualifying variables with the proper scope. Adding variable scopes improves processing speed, but the trade-off is that it may reduce the ease of code reuse.

In the following example, both forms of the fullname variable are permitted. However, the example that includes a scoping prefix will be evaluated more quickly than the unscoped example:

<cfoutput>

  #Client.fullname#

  #fullname#

</cfoutput>

When a variable does not have a scope prefix, ColdFusion searches for it in the following sequence:

1. Local variables created using cfset and cfquery
2. CGI
3. File
4. URL
5. Form
6. Cookie
7. Client

The following scopes are exposed as ColdFusion structures:

• Form
• URL
• Attributes
• Request
• CGI
• Cookie
• Session
• Application

Variables across application pages

Most ColdFusion variables apply only to a single application page. However, several types of variables can be used across multiple application pages:

• Client variables store identifying information about an individual client.

  Client variables hold long-term information about an individual client. You can store them in the system registry, a database, or a cookie named for the application.

• Server variables are valid for all ColdFusion applications on a server.

  Server variables store information (typically read-only) that does not change often and can be shared across users and ColdFusion applications.

• Session variables are valid for as long as an individual Client ID maintains a session.

  Session variables are useful for storing short-term information needed for a single site visit or set of requests. They are specific to individual users.

• Application variables are valid for an application.

  Application variables are available to individual, specified applications and to all users of that application who access the ColdFusion server. They are stored in the server's memory and can be set to time out.

• Caller variables are valid for ColdFusion custom tags.

  Caller variables are available for passing information among application pages of a ColdFusion custom tag.

For information on setting up client state management using the clientManagement attribute in the cfapplication tag, see the description of cfapplication. For information about using Application, Client, and Session variables, see Developing ColdFusion Applications.

Variables stored in structures

As of ColdFusion 5, Form, Application, Session, Server, Request, and URL variables are stored in structures. Thus, you can reference all of the fields taken from a form as a structure, all parameters passed in a URL as a structure, and so forth.

You can access structures using any of the ColdFusion structure functions in the form structname.key, where each key represents a field name of a form or a variable name of a specific type. Because ColdFusion creates these structures whenever these variables are used, conversion to WDDX is straightforward.

For example:

<cfif isDefined("form.submit")>

  <cfwddx action = "CFML2WDDX" input = "#form#" output = "formscope">

  <cfoutput>#formScope#</cfoutput>

</cfif>



<cfoutput>

<form method = "post" action = "myForm.cfm">

  <input type = "Text" name = "Title"><br>

  <input type = "Text" name = "URL"><br>

  <textarea name = "teaser" rows = "3" cols = "40"></textarea>

  <br>

  <input type = "Submit" name = "submit" value = "Submit">

</form>

</cfoutput>

Copyright © 2001, Macromedia Inc. All rights reserved.

---