Developing ColdFusion MX Applications with CFML
Writing and Calling User-Defined Functions

Calling functions and using variables

You can call a function anywhere that you can use an expression, including in pound signs (#) in a cfoutput tag, in a CFScript, or in a tag attribute value. One function can call another function, and you can use a function as an argument to another function.

You call user-defined functions the same way you call any built-in ColdFusion functions.

Passing arguments

ColdFusion passes the following data types to the function by value:

• Integers
• Real numbers
• Strings (including lists)
• Date-time objects
• Arrays

As a result, any changes that you make in the function to these arguments do not affect the variable that was used to call the function, even if the calling code is on the same ColdFusion page as the function definition.

ColdFusion passes queries, structures, and external objects such as COM objects into the function by reference. As a result, any changes to these arguments in the function also change the value of the variable in the calling code.

For an example of the effects of passing arguments, see "Passing complex data".

Referencing caller variables

A function can use and change any variable that is available in the calling page, including variables in the caller's Variables (local) scope, as if the function was part of the calling page. For example, if you know that the calling page has a local variable called Customer_name (and there is no function scope variable named Customer_name) the function can read and change the variable by referring to it as Customer_name or (using better coding practice) Variables.Customer_name. Similarly, you can create a local variable inside a function and then refer to it anywhere in the calling page after the function call. You cannot refer to the variable before you call the function.

However, you should generally avoid using the caller's variables directly inside a function. Using the caller's variables creates a dependency on the caller. You must always ensure that the code outside the function uses the same variable names as the function. This can become difficult if you call the function from many pages.

You can avoid these problems by using only the function arguments and the return value to pass data between the caller and the function. Do not reference calling page variables directly in the function. As a result, you can use the function anywhere in an application (or even in multiple applications), without concern for the calling code's variables.

As with many programming practice, there are valid exceptions to this recommendation. For example you might do any of the following:

• Use a shared scope variable, such as an Application or Session scope counter variable.
• Use the Request scope to store variables used in the function, as shown in "Using the Request scope for static variables and constants".).
• Create context-specific functions that work directly with caller data if you always synchronize variable names.

Note:   If your function must directly change a simple variable in the caller (one that is not passed to the function by reference), you can place the variable inside a structure argument.

Using function-only variables

Make sure to use the var statement in CFScript UDFs to declare all function-specific variables, such as loop indexes and temporary variables that are required only for the duration of the function call. Doing this ensures that these variables are available inside the function only, and makes sure that the variable names do not conflict with the names of variables in other scopes. If the calling page has variables of the same name, the two variables are independent and do not affect each other.

For example, if a ColdFusion page has a cfloop tag with an index variable i, and the tag body calls a CFScript UDF that also has a loop with a function-only index variable i, the UDF does not change the value of the calling page loop index, and the calling page does not change the UDF index. so you can safely call the function inside the cfloop tag body.

In general, use the var statement to declare all UDF variables, other than the function arguments or shared-scope variables, that you use only inside CFScript functions. Use another scope, however, if the value of the variable must persist between function calls; for example, for a counter that the function increments each time it is called.

Using arguments

Function arguments can have the same names, but different values, as variables in the caller. Avoid such uses for clarity, however.

The following rules apply to argument persistence:

• Because simple variable and array arguments are passed by value, their names and values exist only while the function executes.
• Because structures, queries, and objects such as COM objects are passed by reference, the argument name exists only while the function executes, but the underlying data persists after the function returns and can be accessed by using the caller's variable name. The caller's variable name and the argument name can, and should, be different.

Note:   If a function must use a variable from another scope that has the same name as a function-only variable, prefix the external variable with its scope identifier, such as Variables or Form. (However, remember that using variables from other scopes directly in your code is often poor practice.)

Copyright © 2002, Macromedia Inc. All rights reserved.

Comments