French | Spanish | Portuguese | Italian | German | Japanese | Chinese | Korean | Russian | Arabic

You can call functions by using two CFML tags: CFINVOKE and CFINVOKEARGUMENT. The following code is a function:

<cfscript>
   function add2(firstNumber, secondNumber) {
   return firstNumber + secondNumber;
   }
 </cfscript>

Following is how we would call that function by using the standard syntax:

<cfoutput>#add2(1,2)#</cfoutput>

If we call that function by using CFINVOKE, it looks as follows:

<cfinvoke method=”add2” returnvariable=”theSum”>
   <cfinvokeargument name=”firstNumber” value=”7”>
   <cfinvokeargument name=”secondNumber” value=”3”>
   </cfinvoke>
   <cfoutput>#theSum#</cfoutput>

Notice that, in using CFINVOKE, we specify the name of the variable in the calling template into which the result of the function is returned. This is necessary because we are not simply outputting an inline function call: Some container must be there for the result that is external to the tag-based function invocation code. CFINVOKEARGUMENT also enables you to conditionally include or modify arguments, because it is a tag-based construction, as the following example shows:

<cfinvoke method=”add2” returnvariable=”theSum”>
   <cfinvokeargument name=”firstNumber” value=”7”>
   <cfif secNum GT 100>
   <cfinvokeargument name=”secondNumber” value=”100”>
   <cfelse>
   <cfinvokeargument name=”secondNumber” value=”#secNum#”>
   </cfif>
   </cfinvoke>
   <cfoutput>#theSum#</cfoutput>

Note that when using CFINVOKEARGUMENT, you must always provide a name for every parameter, so you can’t use positional notation with CFINVOKEARGUMENT. You have another option for calling a function by using CFINVOKE. You can put the function’s arguments into a structure named argumentcollection and pass the structure to CFINVOKE, as follows:

<cfset myStruct = StructNew()>
   <cfset myStruct[“firstNumber”] = 7>
   <cfset myStruct[“secondNumber”] = 3>
   <cfinvoke method=”SumArgs” returnvariable=”theSum”
   argumentcollection=”#myStruct#”>

All the keys in myStruct become the arguments to the SumArgs() function; in essence, myStruct becomes the function’s Arguments collection. The advantage to this method is that you can assemble the arguments into the structure well before the function is called and then just pass the single structure to the function. The disadvantage is that you must always use named notation; you can have no unnamed arguments. You have yet another option for calling CFINVOKE. The arguments to the function can be passed as extra attributes to CFINVOKE, as follows:

<cfinvoke method=”SumArgs” returnvariable=”theSum” firstNumber=”7”
   secondNumber=”3”>

You face one caveat in using CFINVOKE. Attempting to pass argumentcollection and separate argument attributes at the same time causes CFINVOKE to ignore the argumentcollection, causing some of your function’s arguments to be undefined. Strangely enough, changing argumentcollection to attributecollection corrects the problem. This has been verified by Macromedia and may be changed in the future, so don’t rely on this behavior. Not all functions must return a value. The function in the following code, for example, converts all the values in an array to uppercase:

<cfscript>
   function UCaseArray(arArray) {
   for(i = 1; i LTE ArrayLen(arArray); i = i + 1) {
   arArray[i] = UCase(arArray[i]);
   }
   return arArray;
   }
 </cfscript>
 <cfset myArray = ArrayNew(1)>
 <cfset myArray[1] = “My String”>
 <cfset myArray[2] = “Your String”>
 <cfset myArray[3] = “Our String”>
 <cfscript>
 myArray = UCaseArray(myArray);
 </cfscript>
 <cfdump var=”#myArray#”>

In this case, we needed to return myArray because we had modified the elements in a copy of the original array. If we write the function to modify the keys of a structure, however, we don’t need to return a value, as the following example shows:

<cfscript>
   function UCaseStruct(myStruct) {
   for(item in myStruct) {
   myStruct[item] = UCase(myStruct[item]);
   }
   return;
   }
 </cfscript>
 <cfset myStruct[“Mine”] = “My String”>
 <cfset myStruct[“Yours”] = “Your String”>
 <cfset myStruct[“Ours”] = “Our String”>
 <cfscript>
 UCaseStruct(myStruct);
 </cfscript>
 <cfdump var=”#myStruct#”>

Because the structure is passed by reference, we can just modify the values in the original structure, and we don’t need to return anything, because referencing the same structure after the function is called yields the newly modified key values. This is not the case in ColdFusion 5, however, where all functions must return a value. UDFs can be separately placed in each template that requires them, but this isn’t exactly efficient coding. A better technique is to place related UDFs in a single template by themselves and then CFINCLUDE that template wherever one or more of its functions are needed. Building a library of related functions is a better practice than placing all UDFs in a single template, as ColdFusion must still process these functions as they are included, and this process takes time. Including a library containing 127 UDFs when you need to use only one of them doesn’t make sense. A much better practice is to have one UDF library template for each category of UDFs, so you may create a library template named StringUDFs.cfm that contains all UDFs related to string manipulation and another library template named FinancialUDFs.cfm that contains all financially-oriented UDFs. This way, you create a healthy balance between ease of code maintenance and time wasted processing unneeded UDFs. User-defined functions enable you to extend ColdFusion’s built-in library of functions with your own. If you use the new CFFUNCTION syntax, your functions can do anything from simple string or number operations to database calls. You see how truly useful functions are and you can probably already imagine good uses for them in your existing code. In this article you learned how to create functions with both CFSCRIPT and CFFUNCTION. You also learned how to call functions with positional and named notation, and you learned about some of the caveats that occur when you use CFINVOKE and CFINVOKEARGUMENT.