cfargument

<cfargument 
   name="string" 
   type="data type" 
   required="Yes or No" 
   default="default value" 
   displayname="descriptive name"
   hint="extended description"
   >

<!--- This example defines a function that takes a course number parameter 
and returns the course description. --->
<cffunction name="getDescript">
   <!--- Identify argument --->
   <cfargument name="Course_Number" type="numeric" required="true">
   <!--- Use the argument to get a course description from the database --->
   <cfquery name="Description" datasource="cfsnippets">
      SELECT Descript
      FROM Courses
      WHERE Number = '#Course_Number#'
   </cfquery>
   <!--- Specify the variable that the function returns --->
   <cfreturn Description.Descript>
</cffunction>

Comments

Corey Gilmore said on Oct 29, 2003 at 1:47 PM :

required="no" WILL NOT WORK WITH WEB SERVICES if you do not pass a value, even if you specify a default value!

Say you have a function in a component like this:
<CFFUNCTION NAME="GetSomething" RETURNTYPE="string" ACCESS="remote">
<CFARGUMENT NAME="DSN" REQUIRED="yes" TYPE="string" default="somedb">
<CFARGUMENT NAME="Max" REQUIRED="no" TYPE="numeric" DEFAULT="20">
...
</CFFUNCTION>

And invoke it as a component like:
<CFINVOKE COMPONENT="SampleCFC"
METHOD="GetSomething"
DSN="#Request.App.DSN#"
RETURNVARIABLE="foo">
</CFINVOKE>

It will work fine, and use the default value for Max.

If you invoke that as a Web Service though,
<CFINVOKE WEBSERVICE="http://127.0.0.1/SampleCFC.cfc?wsdl"
METHOD="GetSomething"
DSN="#Request.App.DSN#"
RETURNVARIABLE="foo">
</CFINVOKE>

It will not work! Instead you end up with an error like this:
Web service operation "GetSomething" with parameters {DSN={somedb},} could not be found.

mtangorre said on Oct 29, 2003 at 5:52 PM :

I think a distinction should be made about a UUID and a GUID.

A UUID follows the format:
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

whereas a GUID follows the format:
xxxxxxxx-xxxx-xxxx-xxxx-xxxx-xxxxxxxx

Users will run into issues for example if they use a GUID from a MS SQL server DB and try to interact with it as a UUID!

jrunrandy said on Oct 30, 2003 at 5:32 AM :

All arguments are required when invoked as a webservice, irrespective of how they are defined.

This is documented on "http://livedocs.macromedia.com/coldfusion/6.1/htmldocs/webser26.htm, but is missing on this page.

I have entered this as bug 53667.

halL said on Oct 30, 2003 at 6:59 AM :

We should probably make our description of the guid attribute clearer, but it is correct to refer to GUIDs and UUIDs as being the same. The real problem is that ColdFusion did not implement UUIDs correctly, so there are now "ColdFusion UUIDS" and "real UUID/GUIDs"

UUIDs existed well before Microsoft started using them. What became GUIDs probably started at Apollo Computer in the 1980s, for their Network Computing Architecture (NCA). NCA was contibuted to the Open Software Foundation's Distributed Computing Environment (DCE), and Microsoft took elements of DCE and in the process renamed UUIDs to GUIDs.

When ColdFusion started supporting a unique ID, the developer probably made a one-character error in the UUID string representation, which resulted in the dichotomy.

sethOlBoy said on Dec 2, 2003 at 3:07 PM :

required="true" or required="yes" WHICH ONE?

jrunrandy said on Dec 3, 2003 at 6:13 AM :

In Boolean expressions, True, nonzero numbers, and the string "Yes" are equivalent, and False, 0, and the string "No" are equivalent. This is documented on http://livedocs.macromedia.com/coldfusion/6.1/htmldocs/variab10.htm.

Sarge said on Mar 19, 2004 at 2:12 PM :

The description for the required attribute should state that it will accept any valid boolean,

Change the example function name to "getDescription" to better match its functionality.

first_drew said on May 9, 2004 at 3:36 AM :

Why wasn't cfargument TYPE not given an attribute of 'List' ?
cfqueryparam will not work in a cfc function with the syntax below if you were expecting a 'List' to be passed in.
<cfqueryparam value="#arguments.permissionList#" cfsqltype="CF_SQL_INTEGER" list="yes">
as a 'List' has to be declared as a 'String'.
I don't want to run my queries without queryparam, but it seems I'm left with no choice.

Thanks for any info
Drew

cdr-80 said on Jul 28, 2004 at 6:30 AM :

Why isn't it possible to use a string variable as the argument's type parameter?

This makes using CFC's very hard:
If I've created a cfc which resides in
D:\my_development_directory\mycfc.cfc and I want reference it from another CFC which is NOT in the same directory (which is a common when they do not share functionality) the only way to reference it seems to be an absoluut path. Ofcourse deploying my app on a production server becomes a big problem...
Any one solved this?

cedgar said on Nov 11, 2004 at 9:40 AM :

I cannot see an appropriate use of <cfargument> with attribute type values of NUMERIC and DATE when passing down an empty value.

tinu8805 said on Nov 16, 2004 at 10:31 AM :

I think the doc should state how arguments are passed: either by value or by reference. I thought that an argument of type ARRAY is called by reference but learned that it cannot be like that .... unfortunately.

My code
---
caller_arr = ArrwaNew(1);

<cffunction name="xy">
<cfargument name="arg_arr" type="array">
...
<cfset arg_arr[ArrayLen(arg_arr)+1] = "some 2nd text"
</cffunction>

<cfset caller_arr[1] = "Init">
<cfscript>
xy (caller_arr);
</cfscript>
---

<cfdump var=#caller_arr#> gives me only "ini" (1 column)

PopularAuthor said on Jan 4, 2005 at 11:58 PM :

Corey Gilmore's statement on Oct 29, 2003 at 1:47 PM seemingly received no response. Is this person an authority on coldFusion and making a correction to the documentation?
I ask this because I am having precisely this problem and it seems ridiculous that this problem would not be noted as a caveat to the usage of this technology other than a person who is ostensibly not an authority.
It is not in the known issues of CFMX 6.1.

jrunrandy said on Jan 6, 2005 at 9:54 AM :

I'm sorry for the confusion. We should have confirmed the accuracy of Corey Gilmore's comment, because it is accurate.

No screen name said on May 13, 2005 at 5:05 AM :

It's not mentioned in the docs above, but using the UUID type attribute and passing in a UUID that's not all uppercase causes an error stating that the UUID isn't valid. The same UUID in uppercase works just fine.

ultrafresh said on May 17, 2005 at 10:17 AM :

i am passing in a structure like this:
<cfset args = structNew()>
<cfset dummy = structInsert(args, "a", 1)>
<cfset dummy = structInsert(args, "b", 2)>
<cfset dummy = structInsert(args, "c", 3)>
<cfset dummy = structInsert(args, "d", 4)>

...
argumentcollection="#args#"


in the function i have:

<cfargument name="aaa1" required="Yes">
<cfargument name="aab2" required="Yes">
<cfargument name="aac3" required="Yes">
<cfargument name="aad4" required="Yes">

so you would think
aaa1 = 1
aab2 = 2
aac3 = 3
aad4 = 4

however it is:
aaa1 = 3
aab2 = 4
aac3 = 2
aad4 = 1

how come???

Glizman said on Jun 14, 2006 at 8:37 AM :

cedgar, I'm running into the same issue with type-errors because of null values. NULL ("") is a valid string in CF, but I'd rather use the type I'm working with. It's a lot of extra work setting cfparams to values not being used that are properly typed prior to each function invocation. I find documenting the value--null in disguise--to be helpful to remember the purpose months down the road. I would think null is of every type. In SQL, when I insert a null into a nullable integer field, I don't need to set it to another number before reaching the database. It's just NULL.

Glizman said on Jun 23, 2006 at 9:36 AM :

In the time since I posted the above response, I found a way to keep the type numeric while allowing NULL parameters to be passed in. It's not as elegant as allowing NULLs.

<cfargument type="numeric" name="paramName" default="-1" required="false" />

Then in the function code, handle the value -1 for the parameter being NULL. That's the downside: switching from isDefined() or len() to neq -1 for a valid value. There is nothing special about the -1--any number will do. Picking a number that will not be used will help avoid logic errors.

HTH