cfset

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.

Syntax

<cfset 
   var variable_name = expression
   >

Attributes

Attribute	Req/Opt	Default	Description
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.
variable_name	Required		A variable.

Usage

The following sections provide detailed descriptions of some of the uses for the cfset tag.

Calling functions

When you use the cfset tag to call a function, you do not need to assign the function return value to a variable if the function does not return a value or you do not need 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 array Scores:

<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 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.
You must 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 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>

View comments in LiveDocs