CFINVOKE  
Description

Invokes component methods from within a ColdFusion page or component. You use this tag to reference a WSDL file and consume a web service from within a block of CFML code.

This tag works as follows:

  • Instantiates a component or web service and invokes a method on it
  • Invokes a method on an instantiated component or web service

This tag can pass parameters to a method in the following ways:

  • With the cfinvokeargument tag
  • As named attribute-value pairs, one attribute per parameter
  • As a structure, in the argumentCollection attribute
 
Category

Extensibility tags

 
Syntax
    <!--- Syntax 1 - this syntax invokes a method of a component --->
<cfinvoke
   component = "component name or reference"
   method = "method name"
   returnVariable = "variable name"
   argumentCollection = "argument collection"
   ...>
OR
<!--- Syntax 2 - this syntax can invoke a method of a component only
   from within the component. --->
<cfinvoke
   method = "method name"
   returnVariable = "variable name"
   argumentCollection = "argument collection"
   ...
>
OR
<!--- Syntax 3 - this syntax invokes a web service --->
<cfinvoke 
   webservice = "URLtoWSDL_location" 
   method = "operation_name"
   username = user name"
   password = "password"
   inputParam1 = "value1"
   inputParam2 = "value2"
   ...
   returnVariable = "var_name"    
   ...>
OR
<!--- Syntax 4A - this syntax invokes a component.
This syntax shows instantiation with the cfobject tag. 
This cfinvoke syntax applies to instantiating a component 
with the cfobject tag and to instantiating a component 
with the createobject function. --->
<cfobject
   component = "component name"
   name = "mystringname for instantiated object">
<cfinvoke 
   <!--- value is object name, within pound signs --->
   component = "#mystringname for instantiated component#">
OR
<!--- Syntax 4B - this syntax invokes a web service.
This syntax shows instantiation with the cfobject tag. 
This cfinvoke syntax applies to instantiating a web service
with the cfobject tag and to instantiating a web service
with the createobject function. --->
<cfobject
   webservice = "web service name"
   name = "mystringname for instantiated object"
   method = "operation_name">
<cfinvoke 
   <!--- value is object name, within pound signs --->
   webservice = "#my stringname for instantiated web service#" >

  
 
See also

cfargument, cfcomponent, cffunction, cfinvokeargument, cfobject, cfproperty, cfreturn

 
History

New in ColdFusion MX: This tag is new.

 
Usage

The following table shows which attributes of this tag are required:

Specifying this attribute is required, optional or unnecessary (blank): For this cfinvoke tag syntax:
Syntax 1 Syntax 2 Syntax 3 Syntax 4A Syntax 4B

component

Required

Optional

 

Required

 

method

Required

Required

Required

 

 Required

returnVariable

Optional

Optional

Optional

 

 Optional

argumentCollection

Optional

Optional

Optional

 

 Optional

 

 

 

Optional

 

 Optional

 

 

 

Optional

 

 Optional

webservice

 

 

Required

 

 Required

input_params ...

Optional

Optional

Optional

 

 Optional

If the component attribute specifies a component name, the component with the corresponding name is instantiated, the requested method is invoked, and then the component instance is immediately destroyed. If the attribute contains a reference to an instantiated component object, no instantiation or destruction of the component occurs.

Method arguments can be passed in one of the following ways (and, if an argument is passed in more than one way with the same name, this order of precedence applies):

  1. Using the cfinvokeargument tag
  2. Passing directly as attributes of the cfinvoke tag (they cannot have the same name as a registered cfinvoke attribute: method, component, webservice, returnVariable)
  3. Passing as struct keys, using the argumentCollection attribute

For example, the params struct contains three keys: a=1, b=1, c=1. The following call is evaluated as if the arguments were passed to the method in the order a=3, b=2, c=1:

<cfinvoke ... a=2 b=2 argumentCollection=params>
      <cfinvokeargument name="a" value="3">
   </cfinvoke>
Note: The following cfinvoke tag attribute names are reserved; they cannot be used for parameter names: component, method, argumentCollection, and result.
 
Example 1

This example uses Syntax 1.

<!--- immediate instantiation and destruction --->
<cfinvoke 
   component="nasdaq.quote" 
   method="getLastTradePrice" 
   returnVariable="res">
   <cfinvokeargument 
      name="symbol" 
      value="macr">
</cfinvoke>
<cfoutput>#res#</cfoutput>
 
Example 2

This example uses Syntax 1.

<!--- passing the arguments using argumentCollection --->
<cfset args = StructNew()>
<cfset args.symbol = "macr">
<cfinvoke 
   component="nasdaq.quote" 
   method="getLastTradePrice" 
   argumentCollection="#args#" 
   returnVariable="res">
<cfoutput>#res#</cfoutput>
 
Example 3

This example uses Syntax 2.

<!--- called only from within a component, MyComponent--->
<cfinvoke
   method = "a method name of MyComponent"
   returnVariable = "variable name">
 
Example 4

This example uses Syntax 3.

<!--- using cfinvoke to consume a web service using a ColdFusion component --->
<!--- put the following code in a ColdFusion page named wscfml.cfm:--->
<cfinvoke 
   webservice='http://www.xmethods.net/sd/2001/BabelFishService.wsdl'
   method='BabelFish'
   translationmode="en_es" 
   sourcedata="Hello world, friend"
   returnVariable='foo'>
<cfoutput>#foo#</cfoutput>

For more information on the BabelFish web service example, see Developing ColdFusion MX Applications with CFML.

 
Example 5

This example uses Syntax 4A.

<!--- separate instantiation and method invocation; useful for 
   multiple invocations using different methods or values--->
<cfobject 
   name="quoteService" 
   component="nasdaq.quote">
<cfinvoke 
   component="#quoteService#" 
   method="getLastTradePrice" 
   symbol="macr" 
   returnVariable="res_macr">
<cfoutput>#res#</cfoutput>
<cfinvoke 
   component="#quoteService#" 
   method="getLastTradePrice" 
   symbol="mot" 
   returnVariable="res_mot">
<cfoutput>#res#</cfoutput>
USERNAME  
PASSWORD  
COMPONENT  
  See Usage section
 

String or component object; a reference to a component, or component to instantiate.

METHOD  
  See Usage section
 

Name of a method. For a web service, the name of an operation.

RETURNVARIABLE  
  Optional
 

Name of a variable for the invocation result.

ARGUMENTCOLLECTION  
  Optional
 

Name of a structure; associative array of arguments to pass to the method.

USERNAME  
  Optional
 

Overrides username specified in Administrator > Web Services.

PASSWORD  
  Optional
 

Overrides password specified in Administrator > Web Services.

WEBSERVICE  
  Required
 

The URL of the WSDL file for the web service.

INPUT_PARAMS ...  
   
 

Input parameters.