cfdocs.org /

Description

Sets a value in ColdFusion. Used to create a variable, if it does not exist, and assign it a value. Also used to call functions.

Category

Variable manipulation tags

Syntax

<cfset  
    var variable_name = expression>

See also

cfcookie, cfparam, cfregistry, cfsavecontent, cfschedule; Elements of CFML in the Developing ColdFusion Applications

Attributes

Attribute

Req/Opt

Default

Description

variable_name

Required

 

A variable.

var

Optional

 

A keyword. Does not take a value. Identifies the variable as being local to a function. The variable only exists for the time of the current invocation of the function.

Usage

You use the cfset tag in several ways in your applications.

Calling functions

When you use the cfset tag to call a function, you do not have to assign the function return value to a variable if the function does not return a value or you do not have to use the value returned by the function. For example, the following line is a valid ColdFusion cfset tag for deleting the MyVariable variable from the Application scope:

<cfset StructDelete(Application, "MyVariable")> 

Arrays

The following example assigns a new array to the variable months:

<cfset months = ArrayNew(1)>

This example creates a variable Array_Length that resolves to the length of the Scores array:

<cfset Array_Length = ArrayLen(Scores)>

This example assigns, to index position two in the array months, the value February:

<cfset months[2] = "February">

Dynamic variable names

In this example, the variable name is itself a variable:

<cfset myvariable = "current_value"> 
<cfset "#myvariable#" = 5>

Function local variables

The var keyword specifies that the variable being defined is only available inside the body of a function that you define by using the cffunction tag. The variable value that is set in one invocation of the function is not available in any other invocation of the function. The var keyword is the equivalent of the var statement in CFScript. The following rules apply to the var keyword:

  • Any cfset tag that uses the var keyword must be inside the body of a cffunction tag. If you use the var keyword in a cfset tag outside a cffunction tag body, ColdFusion displays an error message.

  • Place all cfset tags that use the var keyword at the beginning of the cffunction tag body, before any other ColdFusion tags.

The following example shows how to use the new keyword:

<cffunction name="myFunct"> 
    <cfset var myVar = "This is a test"> 
    <cfreturn myVar & " Message."> 
</cffunction> 
<cfoutput>#myFunct()#</cfoutput>

In this example, the variable myVar exists only when the function myFunct executes, and it is not available elsewhere on the ColdFusion page.

COM objects

In this example, a COM object is created. A cfset tag defines a value for each method or property in the COM object interface. The last cfset creates a variable to store the return value from the COM object’s SendMail method.

<cfobject action = "Create"  
    name = "Mailer"  
    class = "SMTPsvg.Mailer">  
 
<cfset MAILER.FromName = form.fromname>  
<cfset MAILER.RemoteHost = RemoteHost>  
<cfset MAILER.FromAddress = form.fromemail>  
<cfset MAILER.AddRecipient("form.fromname", "form.fromemail")>  
<cfset MAILER.Subject = "Testing cfobject">  
<cfset MAILER.BodyText = "form.msgbody">  
<cfset Mailer.SMTPLog = "logfile">  
<cfset success = MAILER.SendMail()>  
<cfoutput> #success# </cfoutput>

Example

<!--- This example shows how to use cfset. ---> 
<cfquery name = "GetMessages" dataSource = "cfdocexamples"> 
    SELECT * 
    FROM Messages 
</cfquery> 
 
<h3>cfset Example</h3> 
<p>cfset sets and reassigns values to local or global variables within a page. 
 
<cfset NumRecords = GetMessages.recordCount> 
<p>For example, the variable NumRecords has been declared on this 
    page to hold the number of records returned from query 
    (<cfoutput>#NumRecords#</cfoutput>). 
 
<p>In addition, cfset can be used to pass variables from other pages,  
        such as this example, which takes the url parameter Test from this 
        link: <a href = "cfset.cfm?test = <cfoutput> 
        #URLEncodedFormat("hey, you, get off of my cloud")#                    </cfoutput> 
        ">click here</A>) to display a message:  
<p> 
<cfif IsDefined ("url.test") is "True"> 
    <cfoutput><b><I>#url.test#</i></b></cfoutput> 
<cfelse> 
    <h3>The variable url.test has not been passed from another page.</h3> 
</cfif> 
 
<p>cfset can also be used to collect environmental variables, such as the  
    time, the IP address of the user, or another function or expression. 
 
<cfset the_date = #DateFormat(Now())# & " " & #TimeFormat(Now())#> 
<cfset user_ip = CGI.REMOTE_ADDR> 
<cfset complex_expr = (23 MOD 12) * 3> 
<cfset str_example = Reverse(Left(GetMessages.body, 35))> 
 
<cfoutput>  
    <ul>  
        <li>The date: #the_date#  
        <li>User IP Address: #user_ip#  
        <li>Complex Expression ((23 MOD 12) * 3): #complex_expr#  
        <li>String Manipulation (the first 35 characters of  
                the body of the first message in our query)  
                <br><b>Reversed</b>: #str_example#  
                <br><b>Normal</b>: #Reverse(str_example)#  
    </ul>  
</cfoutput>