Standard Function Call

From BriansWiki

This is an example of a standard function in a ColdFusion CFC that uses input and return structs:

• Arguments are passed into the function in a struct, rather than as individual arguments.
• All function variables are defined as local variables.
• Results are returned as a struct with several default variables (with one exception, see below):
  • success(boolean): Success/failure of the function.
  • message(string): Text response (if any) from function for display or logging purposes.
  • error(string): Error message returned from function. This contains the CFCATCH responses.
  • qList(query): If the function creates a results query set, return it in qList.
  • calculateValue (numeric): If the function creates a numeric value, return it in calculatedValue.
  • strValue (string): If the function creates a string value (list, text, etc), return it in strValue.
• Always have a TRY/CATCH block around the function. Nested try/catches are good, too, just remember to either throw your error or manually place it in the top level error variable.
• Functions that return results to other functions within the same component may return simple values (numeric, string, etc.) rather than a struct.

<!--- myFunction(sArgs) --->
<cffunction name="myFunction" access="public" output="false" returntype="struct" hint="This is what my function does">
	<cfargument name="sArgs" type="struct" default="#structNew()#">

	<cfscript>
                var sInput = arguments.sArgs;
		var sResults = structNew();
                sResults.success = '0';
                sResults.message = "";
	</cfscript>
	
	<cftry>
		<!--- code goes here --->	



		<!--- default return fields --->	

		<!--- the message returned for logging or screen display --->	
		<cfset sResults.message = "this is what happened in the function" />	

                <!--- query results are returned in the key qList --->
		<cfset sResults.qList= ""  />	

                <!--- if everything works, set the success bit to true --->
		<cfset sResults.success= '1' />	


	<cfcatch type="any">
		<cfset sResults.message = CFCATCH.Message & " " & CFCATCH.Detail & "#CFCATCH.TAGCONTEXT[1]['LINE']#">
	</cfcatch>
	</cftry>

	<cfreturn sResults />
</cffunction>

Here is what a call to this function would look like:

<cftry>
	<cfscript>
		
		// reference the gateway object 
		//(assuming you have created it in the Application.cfc)
		oReports = application.oReportsGateway;
		
		// create the input struct
		sInput = structNew();
		sInput.maxrows = 100;
		sInput.fieldList = "techID, isActive, title";
		sInput.whereclause = "isActive=1";
		sResults = oReports.getAllAsQuery(sInput);
		
	</cfscript>
	
	<!--- Make sure we have a good query --->
	<cfif sResults.success eq 0>
		<cfthrow detail="Error looking up Tech Info" message="#sResults.message#" type="Database">
	</cfif>
	
	<!--- Make sure we have records --->
	<cfif sResults.qList.RecordCount eq 0>
		
		<!--- This is not a problem, --->
		<!--- there are just no more techs to process --->
		<cfabort>
	</cfif>
	
	<cfoutput query="qTechs">
		<!--- create a report on this tech --->
		<!--- your code here --->
	</cfoutput>
	
	<cfcatch type="any">
		<cfset msgText = CFCATCH.MESSAGE & " " & CFCATCH.Detail>
		<cflog text="IT Admin | agent_techScorecard.cfm | #CFCATCH.MESSAGE# #CFCATCH.Detail#" log="APPLICATION" file="ITAdmin" type="Warning" thread="yes" date="yes" time="yes" application="yes">
	</cfcatch>
</cftry>

Now, I know we could be accused of recreating Coldfusion's "Try and Catch" functions with this success thing, but the way I think of it is the Success property is for errors I have anticipated and the Catch is for random errors (We are still debating this internally so if anyone has an opinion we would love to hear it).

Thanks also to Catherine for the standard function description and example.