• Sr. Technical Writer
  • Macromedia, Inc.

Created

8 September 2010

Requirements
User level
All

 

 
Creating Variables

A ColdFusion variable is created by assigning a value to it. Most commonly, you create variables by using the CFSet tag. You can also use the CFParam tag and assignment statements in CFScript. Tags that create data objects also create variables. For example, the cfquery tag creates a query object variable.
 
ColdFusion automatically creates some variables that provide information about the results of certain tags or operations. ColdFusion also automatically generates variables in certain scopes, such as Client and Server. For information on these special variables, see the CFML Quick Reference and the documentation of the CFML tags that create these variables.
 
ColdFusion does not support variables with Null - or no - values. Therefore, ColdFusion generates an error when it tries to use a variable before it is created. This can happen, for example, when processing data from an incompletely filled form. To prevent such errors, test for the variable's existence before you use it. For more information on testing for variable existence, see Developing ColdFusion Applications.
 
For more information on how to create variables, see Creating and Using Scope Variables.
 

 
Variable Naming Rules

When naming ColdFusion variables and form fields, follow these guidelines:
 
  • A variable name must begin with a letter, which can be followed by any number of letters, numbers, and underscore characters.
  • A variable name cannot contain spaces.
  • A query is a type of variable, so it cannot have the same name as another local variable in the current ColdFusion application page.
  • Use consistent capitalization, to keep your code consistent. (ColdFusion variables are not case-sensitive.)
  • When creating a form with fields that are used in a query, match form field names with the corresponding database field names.
  • Prefix each variable's name with its scope. Although some ColdFusion programmers do not use the Variables prefix for local variable names, you should use prefixes for all other scopes. Using scope prefixes makes variable names clearer and increases code efficiency. In some cases, you must prefix the scope. For more information, see Creating and Using Scope Variables.

 
Variable Characteristics

You can classify a variable using these characteristics:
 
  • The data type of the variable value, which indicates the kind of information a variable represents, such as number, string, or date
  • The scope of the variable, which indicates where the information is available and how long the variable persists

 
Data Types

ColdFusion is often referred to as "typeless" because you do not assign types to variables and ColdFusion does not associate a type with the variable name. However, the data that a variable represents does have a type, and the data type affects how ColdFusion evaluates an expression or function argument. ColdFusion can automatically convert many data types into others when it evaluates expressions. In fact, for simple data, such as numbers and strings, the data type is unimportant until the variable is used in an expression or as a function argument.
 

Note: Although ColdFusion variables do not have types, it is often convenient to refer to a variable's type as a shorthand for the type of data that the variable represents.
 

ColdFusion variable data belongs to one of these type categories:
 
  • Simple: Represents one value. ColdFusion simple data types include numbers, strings, Booleans, and date-time variables. You can use simple data types directly in ColdFusion expressions.
  • Complex: A container for data. Complex variables generally represent more than one value. ColdFusion built-in complex data types include arrays, structures, and queries.
    You cannot use a complex variable, such as an array, directly in a ColdFusion expression, but you can use simple data type elements of a complex variable in an expression.
     
    For example, with a one-dimensional array of numbers called myArray, you cannot use the expression myArray * 5. However, you could use an expression myArray[3] * 5 to multiply the third element in the array by 5.
     
  • Binary: "Raw" data, such as the contents of a GIF file or an executable program file.
  • COM, CORBA, and Java (including EJB) objects: Complex objects that you create and access using the cfobject tag. For more information on using these objects, see Developing ColdFusion Applications.

Note: Unlike some programming languages, ColdFusion does not have the concept of NULL values. (ColdFusion does have empty strings.) To prevent errors, you must make sure that variables exist before using them. For more information, see the section "Ensuring that Variables Exist" in Developing ColdFusion Applications.
 

 
Numbers

ColdFusion supports integers and real numbers. You can intermix integers and real numbers in expressions; for example, 1.2 + 3 evaluates to 4.2.
 
Integers
 
ColdFusion supports integers between -2,147,483,648 and 2,147,483,647 (32-bit signed integers). You can assign a value outside this range to a variable, but ColdFusion initially stores the number as a string. If you use it in an arithmetic expression, ColdFusion converts it into a floating point value, preserving its value, but losing precision. The following code shows this:
 
<cfset mybignum=12345678901234567890> <cfset mybignumtimes10=(mybignum * 10)> <cfoutput>mybignum is: #mybignum#</cfoutput><br> <cfoutput>mybignumtimes10 is: #mybignumtimes10# </cfoutput><br>
This code generates the following output:
 
mybignum is: 12345678901234567890
mybignumtimes10 is: 1.23456789012E+020
 
Real numbers
 
Real numbers, numbers with a decimal part, are also known as floating point numbers. ColdFusion real numbers can range from approximately -10300 to approximately 10300. A real number can have up to 12 significant digits. As with integers, you can assign a variable a value with more digits, but the data is stored as a string. It is converted to a real number, and can lose precision when you use it in an arithmetic expression.
 
You can represent real numbers in scientific notation. This format is xEy, where x is a positive or negative real number in the range 1.0 (inclusive) to 10 (exclusive), and y is an integer number. The value of a number in scientific notation is x times 10y. For example, 4.0E2 is 4.0 times 102, which is equal to 400. Similarly, 2.5E-2 is equal to 2.5 times 10-2, which is equal to 0.025. Scientific notation is useful for writing very large and very small numbers.
 

 
Strings

In ColdFusion, text values are stored in strings. Strings are text delimited by either single or double quotes. For example, the two strings below are equivalent:
 
"This is a string"
'This is a string'
 
An empty string can be written in these ways:
 
  • As "" (a pair of double quotes with nothing in between)
  • As " (a pair of single quotes with nothing in between)
Strings can be of any length, limited by the amount of available memory on the ColdFusion Server. There is, however, a 64K limit on the size of text data that can be read from and written to a ColdFusion database or HTML text area. The ColdFusion Administrator lets you increase the limit for database string transfers, but doing so can reduce server performance. To change the limit, select the Enable retrieval of long text option on the CF Settings page for the data source.
 
To include a single-quote character in a string that is single-quoted, use two single quotes (this is known as escaping the single quote). The following example uses escaped single quotes:
 
<cfset myString='This is a single quote: '' This is a double quote: "'> <cfoutput>#mystring#</cfoutput><br>
To include a double-quote character in a double-quoted string, use two double quotes (this is known as escaping the double quote). The following example uses escaped double quotes:
 
<cfset myString="This is a single quote: ' This is a double quote: """> <cfoutput>#mystring#</cfoutput><br>
Because strings can be in either double quotes or single quotes, both of these examples output the same text:
 
This is a single quote: ' This is a double quote: "
 
To insert a pound sign in a string, you must escape the pound sign, as in:
 
"This is a pound sign ##"
Lists
 
ColdFusion has functions that operate on lists, but it does not have a list data type. In ColdFusion, a list is just a string that consists of multiple entries separated by delimiter characters. The default delimiter for lists is the comma. If you use any other character to separate list elements, you must specify the delimiter in the list function.
 
You can specify alternative delimiter characters. For example, you can tell ColdFusion to interpret a comma or a semicolon as a delimiter, as the following example shows:
 
<cfset MyList="1,2;3,4;5"> <cfoutput> List length using ; and , as delimiters: #listlen(Mylist, ";,")#<br> List length using only , as a delimiter: #listlen(Mylist)#<br> </cfoutput>
This example displays the following output:
 
List length using ; and , as delimiters: 5
List length using only , as a delimiter: 3
 
Each delimiter must be a single character. For example, you cannot tell ColdFusion to require two hyphens in a row as a delimiter.
 
If a list has two delimiters in a row, ColdFusion ignores the empty element. For example, if MyList is "1,2,,3,,4,,,5" and the delimiter is the comma, the list has 5 elements and list functions treat it identically to "1,2,3,4,5".
 

 
Booleans

A Boolean value represents whether something is true or false. ColdFusion has two special constants-TRUE and FALSE- to represent these values. For example, the Boolean expression 1 IS 1 evaluates to TRUE. The expression "Monkey" CONTAINS "Money" evaluates to FALSE.
 
Boolean constants can be used directly in expressions, as in this example:
 
<cfset UserHasBeenHere = TRUE>
In Boolean expressions, the values TRUE, non-zero numbers, and the string "Yes" are equivalent. The values FALSE, 0, and the string "No" are equivalent.
 
Boolean evaluation is not case sensitive.
 

 
Date-Time Values

ColdFusion can perform operations on date and time values. Date-time values identify a date and time in the range 100 AD to 9999 AD. Although you can specify just a date or a time, ColdFusion uses one data type representation, called a date-time object, for date, time, and date and time values.
 
ColdFusion provides many functions to create and manipulate date-time values and to return all or part of the value in several different formats.
 
You can enter date and time values directly in a cfset tag with a constant:
 
<cfset myDate = "October 30, 2001">
When you do this, ColdFusion stores the information as a string. If you use a date-time function, ColdFusion stores the value as a date-time object, which is a separate simple data type. When possible, use date-time functions such as CreateDate and CreateTime to specify date and times, because these functions can prevent you from specifying the date or time in an invalid format and they create a date-time object immediately.
 
Date and time formats
 
You can directly enter a date, time, or date and time, using standard US date formats. ColdFusion processes the two-digit-year values 0 to 29 as 21st century dates; it processes the two-digit-year values 30 to 99 as 20th century dates. Time values are accurate to the second.
 
To specify Use these formats
Date October 30, 2001
Oct 30, 2001
Oct. 30, 2001
10/30/1
2001-10-30
10-30-2001
Time 02:34:12
2:34a
2:34am
02:34am
2am
Date and Time Any combination of valid date
and time formats, such as these:

October 30, 2001 02:34:12
Oct 30, 2001 2:34a
Oct. 30, 2001 2:34am
10/30/1 02:34am
2001-10-30 2am
10-30-2001 2am
Locale-specific dates and times
 
ColdFusion provides several functions that let you input and output dates and times (and numbers and currency values) in formats that are specific to the current locale. A locale identifies a language and locality, such as English (US) or French (Swiss). Use these functions to input or output dates and times in formats other than the US standard formats. (Use the SetLocale function to specify the locale.) The following code shows an example:
 
<cfset oldlocale = SetLocale("French (Standard)")> <cfoutput>#LSDateFormat(Now(), "ddd, mmmm dd, yyyy")#</CFOUTPUT>
This code outputs a line like this:
 
ven., juin 15, 2001
 
For more information on International functions, see CFML Reference.
 
How ColdFusion stores dates and times
 
ColdFusion stores and manipulates dates and times as date-time objects. Date-time objects store data on a timeline as real numbers. This is done for efficiency in evaluation and because it directly mimics the method used by many popular database systems. In date-time objects, one day is equal to the difference between two successive integers. The time portion of the date-and-time value is stored in the fractional part of the real number. The value 0 represents 12:00 AM 12/30/1899.
 
Although you can use arithmetic operations to manipulate date-and-time values directly, this method can be troublesome. Use the ColdFusion date-time manipulation functions instead.
 

 
Binary Data Type and Base64 Encoding

Binary data is "raw" data, such as the contents of a GIF file or an executable program file. You do not normally use binary data directly, but you can use the cffile tag to read a binary file into a variable. This is typically done for conversion to Base64 encoding before transmitting the file by e-mail.
 
Base64 format encodes the data in the low six bits of each byte. It ensures that binary data and non-ANSI character data can be transmitted by e-mail without corruption. The MIME specification defines the Base64 encoding method.
 
ColdFusion does not have a Base64 data type; it processes Base64 encoded data as string data. ColdFusion provides these functions that convert among string data, binary data, and Base64 encoded string data:
 
Function Description
ToBase64 Converts string and binary data to Base64 encoded data.
ToBinary Converts Base64 encoded data to binary data.
ToString Converts most simple data types to string data. It can convert numbers, date-time objects, and Boolean values. (It converts date-time objects to ODBC timestamp strings.) It cannot convert binary data that includes bytes that are not printable characters.
The ToString function cannot convert Base64 encoded data directly to an unencoded string. To convert Base64 encoded data that was originally a string back to a readable string, first use the ToBinary function to convert the Base64 data into binary format. Then use the ToString function to convert the binary data to string. For example, the following two lines print the same results:
 
<cfoutput>This is a test</cfoutput> <cfoutput>#tostring(tobinary(tobase64("This is a test")))#</cfoutput>
Do not use binary data or Base64 data directly in ColdFusion expressions.
 

 
Complex Data Types

Arrays, structures, and queries are ColdFusion built-in complex data types. Structures and queries are sometimes referred to as objects, as they are containers for data, not individual data values. For details on complex data types and their use, see Developing ColdFusion Applications.
 
Arrays
 
Arrays are tables of objects or data that can be indexed. To create an array and specify its initial dimensions, use the ColdFusion ArrayNew function. For example, the following line creates an empty two-dimensional array:
 
<cfset myarray=ArrayNew(2)>
Elements stored in an array are referenced as follows:
 
<cfset myarray[1][2]=Now()>
Although the ArrayNew function can only create up to three-dimensional arrays directly, there is no limit on array size or maximum dimension. To create arrays with more than three dimensions, create arrays of arrays.
 
After you create an array, you can use functions or direct references to manipulate its contents. When you assign an existing array to a new variable, ColdFusion creates a new array and copies the old array's contents to the new array. The following example creates a copy of the original array:
 
<cfset newArray=myArray>
Structures
 
You can use structures to create and maintain key-value pairs, to refer to related string values as a unit, or to create associative arrays. To create a structure, use the ColdFusion StructNew function. For example, the following line creates a new, empty structure called depts:
 
<cfset depts=Structnew()>
After you create a structure, you can use functions or direct references to manipulate its contents, including adding key/value pairs.
 
You can use either of the following methods to reference elements stored in a structure:
 
  • StructureName.KeyName
  • StructureName["KeyName"]
The following code shows examples of these methods:
 
depts.John="Sales" depts["John Doe"]="Sales"
When you assign an existing structure to a new variable, ColdFusion does not create a new structure. Instead, the new variable accesses the same data (location) in memory as the original structure variable. One way of expressing this is to say that both variables are references to the same object.
 
For example, the following code creates a new variable myStructure2 that references the same structure as the myStructure variable:
 
<CFSET myStructure2=myStructure>
When you change the contents of myStructure2, you also change the contents of myStructure. To copy the contents of a structure, use the ColdFusion Duplicate function, which copies the contents of structures and other complex data types.
 
Structure key names can be the names of structures or arrays. This enables you to create arbitrarily complex structures.
 
Queries
 
A query object, often referred to as a query, is a complex ColdFusion data type. The following ColdFusion tags can create query objects:
 
  • cfquery
  • cfdirectory
  • chttp
  • cfldap
  • cfpop
  • cfprocresult
In these tags, the name attribute specifies the query object's variable name. The QueryNew function also creates queries.
 
When you assign a query to a new variable, ColdFusion does not copy the query object. Instead, both names point to the same record set data. For example, the following code creates a new variable myQuery2 that references the same record set as the myQuery variable.
 
<CFSET myQuery2 = myQuery>
If you make changes to data in myQuery, myQuery2 also shows those changes.
 
You reference query columns by specifying the query name, a period, and the column name; for example:
 
myQuery.Dept_ID
When you reference columns inside tags such as cfoutput and cfloop, in which you specify the query name in a tag attribute, you do not have to specify the query name.
 
You can access query columns as if they were one-dimensional arrays. For example, the following statement assigns the contents of the second row of the Employee column in the myQuery query to the variable myVar:
 
<CFSET myVar = myQuery.Employee[2]>
You cannot use this notation to add rows to a query; instead, use the QueryAddRow function.
 

Note: The scoping rules that apply to all variables apply to queries. For more information on scoping, see Scopes.
 

Working with structures and queries
 
Because structure variables and query variables are references to objects, the following rules apply to both types of data.
 
When multiple variables refer to a structure or query object, the object continues to exist as long as at least one reference to the object exists. The following code shows how this works:
 
<cfscript> depts = structnew();</cfscript> <cfset newStructure=depts> <cfset depts.John="Sales"> <cfset depts=0> <cfoutput> #newStructure.John# #depts# </cfoutput>
This example displays the following output:
 
Sales
0
 
After the <cfset depts=0> tag executes, the variable depts does not refer to a structure; it is a simple variable with the value 0. However, the variable newStructure still refers to the original structure object.
 
You can give a query or structure a different scope by assigning it to a new variable in the other scope. For example, the following line creates a Server variable Server.SScopeQuery using the local myquery variable:
 
<CFSET Server.SScopeQuery = myquery>
To clear the server scope query variable, reassign the query object, as follows:
 
<CFSET Server.SScopeQuery = 0>
This deletes the reference to the object from the server scope, but does not remove any other references that may exist.
 
You can use the Duplicate function to copy a structure or query object. Changes to the copy do not affect the original.
 

 
Passing Variables to Custom Tags and Functions

The following sections describe rules for how data gets passed to custom tags and functions that are written in CFML, and to CFX custom tags that are written in Java or C++.
 

 
Passing Variables to CFML Custom Tags and Functions

When you pass a variable to a CFML custom tag as an attribute, or to a custom function as an argument, the following rules determine whether the custom tag or function receives its own private copy of the variable or only gets a reference to the calling page's variable:
 
  • Simple variables and arrays are passed as copies of the data. If your argument is an expression that contains multiple simple variables, the result of the expression evaluation is copied to the function or tag.
  • Structures, queries, and cfobject objects are passed as references to the object.
If the tag or function gets a copy of the calling page's data, changes to the variable in the custom tag or function do not change the value on of the variable on the calling page. If the variable is passed by reference, changes to the variable in the custom tag or function also change the value of the variable in the calling page.
 
To pass a variable to a custom tag, you must surround the variable name in pound signs. To pass a variable to a function, do not surround the variable name in pound signs. For example, the following code calls a custom function using three Form variables:
 
<cfoutput> TOTAL INTEREST: #TotalInterest(Form.Principal, Form.AnnualPercent, Form.Months)# </cfoutput>
The following example calls a custom tag using two variables, MyString and MyArray:
 
<cf_testTag stringval=#MyString# arrayval=#MyArray#>

 
Passing Variables to CFX Tags

You cannot pass arrays, structures, or cfobject objects to CFX tags. You can pass a query to a CFX tag by using the query attribute when calling the tag. ColdFusion normally converts simple data types to strings when passing them to CFX tags; however, the Java Request Interface getIntAttributs method allows you to get a passed integer value.
 

 
Data Type Conversion

ColdFusion automatically converts between data types to satisfy the requirements of an expression's operations, including a function's argument requirements. As a result, you generally don't have to be concerned about compatibility between data types and the conversions from one data type to another.
 

 
Operation-Driven Evaluation

Conventional programming languages enforce strict rules about mixing objects of different types in expressions. For example, in a language such as C++ or Basic, the expression ("8" * 10) produces an error because the multiplication operator requires two numerical operands and "8" is a string. When you program in such languages you must convert between data types to ensure error-free program execution. For example, the previous expression might have to be written as (ToNumber("8") * 10).
 
In ColdFusion, however, the expression ("8" * 10) evaluates to the number 80 without generating an error. When ColdFusion processes the multiplication operator, it automatically attempts to convert its operands to numbers. Since "8" can be successfully converted to the number 8, the expression evaluates to 80. ColdFusion processes expressions and functions in this sequence:
 
  1. For each operator in an expression, it determines the required operands. For example, the multiplication operator requires numeric operands and the CONTAINS operator requires string operands.
  2. It evaluates all operands or function arguments.
  3. It converts all operands or arguments whose types differ from the required type. If a conversion fails, it reports an error.

 
Conversion Between Types

Although the expression evaluation mechanism in ColdFusion is very powerful, it cannot automatically convert all data. For example, "eight" * 10 produces an error because ColdFusion cannot convert the string "eight" to the number 8. Therefore, you must understand the rules for conversion between data types.
 
The following table explains how conversions are performed. The first column shows values to convert. The last four columns show the result of conversion to the listed data type.
 
Value As Boolean As number As date-time As string
"Yes" TRUE 1 Error "Yes"
"No" FALSE 0 Error "No"
TRUE TRUE 1 Error "Yes"
FALSE FALSE 0 Error "No"
Number TRUE if Number is not 0, FALSE otherwise. Number See Date-Time Values Number is converted using a default format.
String If "Yes" or "No" or if the string can be converted to a number, it is treated as above. If it represents a number (for example, "1,000" or "12.36E-12"), it is converted to the corresponding number. If it represents a date-time (see next column), it is converted to the numeric value of the corresponding date-time object. If it is an ODBC date, time, or timestamp (for example "{ts '2001-06-14 11:30:13'} "; or if it is expressed in a standard US date or time format, including the use of full or abbreviated month names, it is converted to the corresponding date-time value.

Days of week or unusual punctuation result in error.

Dashes, forward-slashes, and spaces are generally allowed.
String
Date Error The numeric value of the date-time object. Date An ODBC timestamp.
Complex types, such as arrays, queries, and COM objects, cannot be converted.
 
Type conversion notes
 
The following sections detail specific rules and considerations for converting between types.
 
Case insensitivity and Boolean conversion
 
Because ColdFusion expression evaluation is not case sensitive, Yes, YES, and yes are equivalent; False, FALSE, and false are equivalent; No, NO, and no are equivalent; and True, TRUE, and true are equivalent.
 
Converting binary data
 
ColdFusion cannot automatically convert binary data to other data types. To convert binary data use the ToBase64 and ToString functions. For more information, see Binary Data Type and Base64 Encoding.
 
Converting date and time data
 
To ensure that a date and time value is expressed as a real number, add 0 to the variable. The following example illustrates this use:
 
<cfset mynow = now()> <cfoutput>#mynow#</cfoutput> <cfset mynow = mynow + 0> <cfoutput>#mynow#</cfoutput>
At 1:45 PM on July 7, 2001, its output looked like this:
 
{ts '2001-07-06 13:45:30'}
37078.5732639
 
Converting numeric values
 
When ColdFusion evaluates an expression that includes both integers and real numbers, the result is a real number. To convert a real number to an integer, use a ColdFusion function. The Int, Round, Fix, and Ceiling functions convert real numbers to integers and differ in their treatment of the fractional part of the number.
 
If you use a hidden form field with a name that has the suffix _integer or _range to validate a form input field, ColdFusion truncates real numbers entered into the field and passes the resulting integer to the action page.
 
If you use a hidden form field with a name that has the suffix _integer, _float, or _range to validate a form input field, and the entered data contains a dollar amount (including a dollar sign) or a numeric value with commas, ColdFusion considers the input to be valid, removes the dollar sign or commas from the value, and passes the resulting integer or real number to the action page.
 
Evaluation and type conversion issues
 
This section explains several issues that you might encounter with type evaluation and conversion.
 
Comparing variables to TRUE or FALSE
 
You might expect the following two cfif tags to produce the same results:
 
<cfif myVariable> <cfoutput>myVariable equals #myVariable# and is TRUE </cfoutput> </cfif> <cfif myVariable IS TRUE> <cfoutput>myVariable equals #myVariable# and is TRUE </cfoutput> </cfif>
However, if myVariable has a numeric value such as 12, only the first example produces a result. In the second case, the value of myVariable is not converted to a Boolean data type, because the IS operator does not require a specific data type and just tests the two values for identity. Therefore, ColdFusion compares the value 12 with the constant TRUE. The two are not equal, so nothing is printed. If myVariable is 1, "Yes", or True, however, both examples print the same result, because ColdFusion considers these to be identical to Boolean TRUE.
 
If you use
 
<cfif myVariable IS NOT FALSE> <cfoutput>myVariable equals #myVariable# and IS NOT FALSE </cfoutput> </cfif>
The output statement does display because the contents of the variable, 12, is not equal to the Boolean constant FALSE.
 
Ambiguous type expressions and strings
 
When ColdFusion evaluates an expression that does not require strings, including all comparison operations such as IS or GT, it checks whether it can convert each string value to a number or date-time object. If so, ColdFusion converts it to the corresponding number or date-time value (which is stored as a number). It then uses the number in the expression.
 
With short strings such as 1a and 2P, this behavior can produce unexpected results. ColdFusion can interpret a single "A" as AM and a single "P" as PM. This can cause ColdFusion to interpret strings that are not so intended, as times as date-time values.
 
Similarly, if the strings can be interpreted as numbers, you can get unexpected results.
 
For example, ColdFusion interprets the following expressions as shown:
 
Expression Interpreted as
<cfif "1a" EQ "01:00"> If 1:00am is 1:00am
<cfif "1P" GT "2A"> If 1:00pm is later than 2:00am
<cfset age="4a">
<cfset age=age + 7>
Treat the variable age as 4:00 am, convert it to the date-time
value 0.16666666667, and 7 to make 7.16666666667.
<cfif "0.0" IS "0"> If 0 is 0
To prevent such ambiguities when you compare strings, use the ColdFusion string comparison functions Compare and CompareNoCase instead of the comparison operators.
 
You can also use the IsDate() function to determine whether a string can be interpreted as a date-time value, or to add characters to a string before comparison to avoid incorrect interpretation.
 
Date-time functions and queries when ODBC is not supported
 
ColdFusion creates Open Database Connectivity (ODBC) timestamp values when it converts date-time objects, such as the results returned by the ColdFusion Now, CreateDate, CreateTime, and CreateDateTime functions, to strings. As a result, you can get unexpected results when using dates with a database driver that does not support ODBC escape sequences or when you are using SQL in a query of queries.
 
If you use SQL to insert data into a database or in a WHERE clause to select data from a database, and the database driver does not support ODBC-formatted dates, use the DateFormat function to convert the date-time value to a valid format for the driver. This rule also applies to queries of queries.
 
For example, the following SQL statement uses the DateFormat function in a query of queries to select rows that have MyDate values in the future:
 
<cfquery name="MyQofQQ" dbtype="query"> SELECT * FROM DateQuery WHERE MyDate >= '#DateFormat(Now())#' </cfquery>
The following query of queries fails with the error message "Error: {ts is not a valid date," because ColdFusion Now function returns an ODBC timestamp:
 
<cfquery name="MyQofQQ" dbtype="query"> SELECT * FROM DateQuery WHERE MyDate >= '#now()#' </cfquery>
Using JavaCast with overloaded Java methods
 
You can overload Java methods so a class can have several identically named methods that differ only in parameter data types. At runtime, the VM attempts to resolve the specific method to use, based on the types of the parameters passed in the call. Because ColdFusion does not use explicit types, you cannot predict which version of the method the JVM will use.
 
The ColdFusion JavaCast function helps you ensure that the right method executes by specifying the Java type of a variable, as in the following code:
 
<cfset emp.SetJobGrade(JavaCast("int", JobGrade)>
The JavaCast function takes two parameters: a string representing the Java data type and the variable whose type you are setting. You can specify the following Java data types: bool, int, long, float, double, and String.
 
For more information on the JavaCast function, see CFML Reference.
 
The effect of quotes
 
To ensure that ColdFusion properly interprets string data, surround strings in single or double quotes. For example, ColdFusion evaluates "10/2/2001" as a string that can be converted into a date-time object. However, it evaluates 10/2/2001 as a mathematical expression 5/2001, which evaluates to 0.00249875062469.
 

 
Examples of Type Conversion in Expression Evaluation

The following examples demonstrate ColdFusion expression evaluation.
 
Example 1
2 * TRUE + "YES" - ('y' & "es")
Result value as string: "2"
Explanation: (2*TRUE) is equal to 2; ("YES"-"yes") is equal to 0; 2 + 0 equals 2.
 
Example 2
TRUE AND 2 * 3
Result value as string: "YES"
Explanation: 6 is converted to Boolean TRUE; TRUE AND TRUE is TRUE.
 
Example 3
"Five is " & 5
Result value as string: "Five is 5"
Explanation: 5 is converted to the string "5".
 
Example 4
DateFormat("October 30, 2001" + 1)
Result value as string: "31-Oct-01"
Explanation: The addition operator forces the string "October 30, 2001" to be converted to a date-time object and then to a number. The number is incremented by one. The DateFormat function requires its argument to be a date-time object; thus the result of the addition is converted to a date-and-time object. 1 is added to the date-time object, moving it ahead by one day to October 31, 2001.
 

 
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.
 

 
Scope Types

The following table lists the types of ColdFusion scopes and describes their uses. For more information on the function of each scope type, see Developing ColdFusion Applications.
 
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 (but 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")
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.
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.
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, which is represented as a structure, 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.
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.
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, they are stored in the system registry, but you can store them in a cookie or a database.
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 Session variables on server clusters where more than one computers can process requests from a single session.
Application Contains variables that are associated with one named application on a server. The cfapplication tag name attribute specifies the application name.
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.
function local Contains variables that are declared in a custom function and exist only while the function executes.

Caution: You must lock all code that uses Session, Application, or Server scope variables. For more information on locking, see the chapter "Using the Application Framework" in Developing ColdFusion Applications.
 

 
Creating and Using Scope Variables

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 on a page that calls a custom tag can be accessed in the custom tag by using its Caller scope, but 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.
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 Session 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.
(Function local, no prefix) Prohibited Within the body of a custom function, 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.
 
  1. Variables (local scope)
  2. CGI
  3. URL
  4. Form
  5. Cookie
  6. 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. ColdFusion releases through 5.0 have some limitations on using the Variables scope identifier, as described in the following section.
 
To access variables in the Attribute, Request, Session, Application, and Server scopes, you must use the scope identifier prefix.
 
Limitations on using scope names
 
The use of the scope identifiers is limited, as follows.
 
Using the Variables identifier with queries and structures
 
If you do not specify the Variables prefix when you create a query or structure, you cannot use the prefix when you reference the query object or structure.
 
If you do specify the Variables prefix when you create the query or structure, you must always use the prefix when you reference the query or structure.
 
For example, if you use the following cfquery code, you must always refer to the query variable as myQuery, not as Variables.myQuery.
 
<cfquery name="myquery" datasource="CompanyInfo">
Similarly, if you use the following cfquery code, you must always refer to the query variable as Variables.myQuery, not as myQuery.
 
<cfquery name="Variables.myquery" datasource="CompanyInfo">
The following two scripts correctly create and use structures:
 
<cfscript> st1 = structnew(); st1.key0 = "foo";</cfscript> <cfscript> Variables.st1 = structnew(); Variables.st1.key0 = "foo";</ cfscript>
The following script does not work as expected:
 
<cfscript> st1 = structnew(); Variables.st1.key0 = "foo";</cfscript>
The script appears to create a new structure, st1 and populate its element, st1.key0. In fact, it creates an empty structure st1 and a separate simple string variable Variables.st1.key0. The following code illustrates this behavior:
 
Scopes and CFX tags
 
ColdFusion scopes do not apply to CFX tags. 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.
 
Scopes available as structures
 
ColdFusion makes the following scopes available as structures:
 
  • Form
  • URL
  • Attributes
  • Request
  • CGI
  • Cookie
  • Session
  • Application
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.
 

Note: Do not use the StructClear function to clear session and application variables. This can cause the loss of SessionID, CFID, CFTOKEN, and application variables. To prevent this loss, store session data in session.foo.* and then clear session.foo, and store application data in application.foo.* and then clear application.foo.
 

<cfscript> st1 = structnew(); Variables.st1.key0 = "foo"; st1.key0 = "bar" </cfscript> <cfoutput> Variables.st1.key0: #Variables.st1.key0# st1.key0: #st1.key0# </cfoutput>