
Contents > Developing ColdFusion MX Applications > Writing and Calling User-Defined Functions > Using UDFs effectively > Handling errors in UDFs Providing status information

Providing status information

In some cases, such as those where the function cannot provide a corrective action, the function cannot, or should not, handle the error directly. In these cases, your function can return information to the calling page. The calling page must handle the error information and act appropriately.

Consider the following mechanisms for providing status information:

Use the return value to indicate the function status only. The return value can be a Boolean success/failure indicator. The return value can also be a status code, for example where 1 indicates success, and various failure types are assigned known numbers. With this method, the function must set a variable in the caller to the value of a successful result.
Set a status variable that is available to the caller (not the return variable) to indicate success or failure and any information about the failure. With this method, the function can return the result directly to the caller. In this method, the function should use only the return value and structure arguments to pass the status back to the caller.

Each of these methods can have variants, and each has advantages and disadvantages. Which technique you use should depend on the type of function, the application in which you use it, and your coding style.

The following example, which modifies the function used in A User-defined function example, uses one version of the status variable method. It provides two forms of error information:

It returns -1, instead of an interest value, if it encounters an error. This value can serve as an error indicator because you never pay negative interest on a loan.
It also writes an error message to a structure that contains an error description variable. Because the message is in a structure, it is available to both the calling page and the function.

The TotalInterest function

After changes to handle errors, the TotalInterest function looks like the following. Code that is changed from the example in A User-defined function example is in bold.

<cfscript>
function TotalInterest(principal, annualPercent, months, status) {
   Var years = 0;
   Var interestRate = 0;
   Var totalInterest = 0;
   principal = trim(principal);
   principal = REReplace(principal,"[\$,]","","ALL");
   annualPercent = Replace(annualPercent,"%","","ALL");
   if ((principal LE 0) OR (annualPercent LE 0) OR (months LE 0)) {
      Status.errorMsg = "All values must be greater than 0";
      Return -1;
   }
   interestRate = annualPercent / 100;
   years = months / 12;
   totalInterest = principal*(((1+ interestRate)^years)-1);
   Return DollarFormat(totalInterest);
}
</cfscript>

Reviewing the code

The following table describes the code that has been changed or added to the previous version of this example. For a description of the initial code, see A User-defined function example.

Code	Description
function TotalInterest(principal, annualPercent, months, status)	The function now takes an additional argument, a status structure. Uses a structure for the status variable so that changes that the function makes affect the status structure in the caller.
if ((principal LE 0) OR (annualPercent LE 0) OR (months LE 0)) { Status.errorMsg = "All values must be greater than 0"; Return -1; }	Checks to make sure the principal, percent rate, and duration are all greater than zero. If any is not, sets the errorMsg key (the only key) in the Status structure to a descriptive string. Also, returns -1 to the caller and exits the function without processing further.

Code

Description

function TotalInterest(principal, 
   annualPercent, months, status)

The function now takes an additional argument, a status structure. Uses a structure for the status variable so that changes that the function makes affect the status structure in the caller.

if ((principal LE 0) OR 
   (annualPercent LE 0) OR 
   (months LE 0)) {
   Status.errorMsg = "All values 
      must be greater than 0";
   Return -1;
}

Checks to make sure the principal, percent rate, and duration are all greater than zero.

If any is not, sets the errorMsg key (the only key) in the Status structure to a descriptive string. Also, returns -1 to the caller and exits the function without processing further.

Calling the function

The code that calls the function now looks like the following. Code that is changed from the example in A User-defined function example is in bold.

<cfset status = StructNew()>
<cfset myInterest = TotalInterest(Form.Principal, 
   Form.AnnualPercent,Form.Months, status)>
<cfif myInterest EQ -1>
   <cfoutput>
      ERROR: #status.errorMsg#<br>
   </cfoutput>
<cfelse>
   <cfoutput> 
      Loan amount: #Form.Principal#<br>
      Annual percentage rate:
         #Form.AnnualPercent#<br>
      Loan duration: #Form.Months# months<br>
      TOTAL INTEREST: #myInterest#<br>
   </cfoutput>
</cfif>

Reviewing the code

The following table describes the code that has been changed or added:

Code	Description
<cfset status = StructNew()>	Creates a structure to hold the function status.
<cfset myInterest = TotalInterest (Form.Principal, Form.AnnualPercent, Form.Months, status)>	Calls the function. This time, the function requires four arguments, including the status variable.
<cfif myInterest EQ -1> <cfoutput> ERROR: #status.errorMsg#<br> </cfoutput>	If the function returns -1, there must be an error. Displays the message that the function placed in the status.errorMsg structure key.
<cfelse> <cfoutput> Loan amount: #Form.Principal#<br> Annual percentage rate: #Form.AnnualPercent#<br> Loan duration: #Form.Months# months<br> TOTAL INTEREST: #myInterst#<br> </cfoutput> </cfif>	If the function does not return -1, it returns an interest value. Displays the input values and the function return value.


Contents > Developing ColdFusion MX Applications > Writing and Calling User-Defined Functions > Using UDFs effectively > Handling errors in UDFs Providing status information

Version 6.1

Comments are no longer accepted for ColdFusion MX 6.1. ColdFusion 8 is the current version.