<html>
<head>
<link href="mmres://user_interface_reference.css" rel="stylesheet" type="text/css">
<title>CFQUERYPARAM</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
   <div id="Description">
   <table cellpadding="0" cellspacing="0" border="0" width="100%" class="main">
      <tr> 
         <td valign="top" class="name">CFQUERYPARAM</td>
         <td valign="top" nowrap class="compatibility">&nbsp;</td>
      </tr>
      <tr>
         <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
      </tr>


    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Description</span>
<p>
Verifies the data type of a query parameter and, for DBMSs that support bind variables, enables ColdFusion to use bind variables in the SQL statement. Bind variable usage enhances performance when executing a cfquery statement multiple times.
</p>

<p>
This tag is nested within a cfquery tag, embedded in a query SQL statement. If you specify optional parameters, this tag performs data validation.
</p>

<p>
Macromedia recommends that you use the cfqueryparam tag within every cfquery tag, to help secure your databases from unauthorized users. For more information, see Security Bulletin ASB99-04, "Multiple SQL Statements in Dynamic Queries," at www.macromedia.com/devnet/security/security_zone/asb99-04.html</a>, and Chapter&#160;20, "Accessing and Retrieving Data" in ColdFusion MX Developer's Guide.
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Category</span>
<p>
Database manipulation tags
</p>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="syntax"><span class="title">Syntax</span><pre>&lt;cfquery 
   name = &quot;query_name&quot;
   dataSource = &quot;ds_name&quot;
   ...other attributes...
   SQL STATEMENT column_name = 
   &lt;cfqueryparam value = &quot;parameter value&quot;
      CFSQLType = &quot;parameter type&quot;
      maxLength = &quot;maximum parameter length&quot;
      scale = &quot;number of decimal places&quot;
      null = &quot;yes&quot; or &quot;no&quot;
      list = &quot;yes&quot; or &quot;no&quot;
      separator = &quot;separator character&quot;&gt;
   AND/OR ...additional criteria of the WHERE clause...
   &lt;/cfquery&gt;
</pre>    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">See also</span>
<p>
cfinsert, cfprocparam, cfprocresult, cfquery, cfstoredproc, cftransaction, cfupdate; "Enhancing security with cfqueryparam" in Chapter&#160;20, "Accessing and Retrieving Data," in ColdFusion MX Developer's Guide
</p>

<p>

</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Usage</span>
<p>
Use the cfqueryparam tag in any SQL statement (for example, SELECT, INSERT, UPDATE, and DELETE) that uses ColdFusion variables. 
</p>

<p>
You cannot use the cfquery cachedAfter or cachedWithin attributes with cfqueryparam.
</p>

<p>
For maximum validation of string data, specify the maxlength attribute.
</p>

<p>
This tag does the following: 
</p>
<ul>

<li>Allows the use of SQL bind parameters, which improves performance.</li>

<li>Ensures that variable data matches the specified SQL type.</li>

<li>Allows long text fields to be updated from a SQL statement.</li>

<li>Escapes string variables in single-quotation marks.</li>
</ul>

<p>
To benefit from the enhanced performance of bind variables, you must use cfqueryparam for all ColdFusion variables, and your DBMS must support bind variables. If a DBMS does not support bind parameters, ColdFusion validates and substitutes the validated parameter value back into the string. If validation fails, it returns an error message.
</p>

<p>
The validation rules are as follows:
</p>
<ul>

<li>For these types, a data value can be converted to a numeric value: CF_SQL_SMALLINT, CF_SQL_INTEGER, CF_SQL_REAL, CF_SQL_FLOAT, CF_SQL_DOUBLE, CF_SQL_TINYINT, CF_SQL_MONEY, CF_SQL_MONEY4, CF_SQL_DECIMAL, CF_SQL_NUMERIC, and CF_SQL_BIGINT</li>

<li>For these types, a data value can be converted to a date supported by the target data source: CF_SQL_DATE, CF_SQL_TIME, CF_SQL_TIMESTAMP</li>

<li>For all other types, if the maxLength attribute is used, a data value cannot exceed the maximum length specified.</li>
</ul>

<p>
ColdFusion debug output shows the bind variables as question marks and lists the values beneath the query, in order of usage.
</p>
<table>
  <tr valign="top">
    <td width="30"><strong>Note: </strong></td>
    <td>To insert an empty string into a Microsoft Access table using the SequelLink ODBC Socket or SequelLink Access driver, the CFSQLType attribute must specify CF_SQL_LONGVARCHAR.</td>
  </tr>
</table>
<p>
The following table shows the mapping of ColdFusion SQL data types with JDBC SQL types and those of the listed database management systems:
</p>

<p>

</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Example</span><pre>&lt;!--- This example shows cfqueryparam with VALID input in Course_ID. ---&gt;
&lt;h3&gt;cfqueryparam Example&lt;/h3&gt;
&lt;cfset Course_ID = 12&gt;
&lt;cfquery name = &quot;getFirst&quot; dataSource = &quot;cfdocexamples&quot;&gt;
   SELECT * 
   FROM courses
   WHERE Course_ID = &lt;cfqueryPARAM value = &quot;#Course_ID#&quot;
   CFSQLType = &quot;CF_SQL_INTEGER&quot;&gt; 
&lt;/cfquery&gt;
&lt;cfoutput query = &quot;getFirst&quot;&gt;
   &lt;p&gt;Course Number: #Course_ID#&lt;br&gt; Description: #descript#&lt;/p&gt;
&lt;/cfoutput&gt;

&lt;!--- This example shows the use of CFQUERYPARAM when INVALID string data is
   in Course_ID. ----&gt; 
&lt;p&gt;This example throws an error because the value passed in the CFQUERYPARAM 
tag exceeds the MAXLENGTH attribute&lt;/p&gt; 

&lt;cfset LastName=&quot;Peterson; DELETE employees WHERE LastName=&#39;Peterson&#39;&quot;&gt;
&lt;!------- Note that for string input you must specify the MAXLENGTH attribute 
   for validation. --------------------------------------------------&gt; 
&lt;cfquery 
   name=&quot;getFirst&quot; datasource=&quot;cfdocexamples&quot;&gt; 
   SELECT * 
   FROM employees 
   WHERE LastName=&lt;cfqueryparam 
                        value=&quot;#LastName#&quot; 
                        cfsqltype=&quot;CF_SQL_VARCHAR&quot; 
                        maxlength=&quot;17&quot;&gt; 
&lt;/cfquery&gt; 
&lt;cfoutput 
   query=&quot;getFirst&quot;&gt;       &lt;p&gt;
      Course Number: #FirstName# #LastName# 
      Description: #Department# &lt;/p&gt; 
&lt;/cfoutput&gt; 
</pre>
         </td>
      </tr>
   </table>
   </div>

<p>CF_SQL_ARRAY</p>

<p>ARRAY</p>

<p>&#160;</p>

<p>&#160;</p>

<p>&#160;</p>

<p>&#160;</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_BIGINT</p>

<p>BIGINT</p>

<p>Bigint</p>

<p>int8, serial8</p>

<p>&#160;</p>

<p>&#160;</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_BINARY</p>

<p>BINARY</p>

<p>Char for Bit Data</p>

<p>&#160;</p>

<p>&#160;</p>

<p>binary</p>
<p>timestamp</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_BIT</p>

<p>BIT</p>

<p>&#160;</p>

<p>boolean</p>

<p>&#160;</p>

<p>bit</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_BLOB</p>

<p>BLOB</p>

<p>Blob</p>

<p>blob</p>

<p>blob, bfile</p>

<p>&#160;</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_CHAR</p>

<p>CHAR</p>

<p>Char</p>

<p>char, </p>
<p>nchar</p>

<p>char,</p>
<p>nchar</p>

<p>char, nchar,</p>
<p>uniqueidentifier</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_CLOB</p>

<p>CLOB</p>

<p>Clob</p>

<p>clob</p>

<p>clob,nclob</p>

<p>&#160;</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_DATE</p>

<p>DATE</p>

<p>Date</p>

<p>date, datetime, year to day</p>

<p>&#160;</p>

<p>&#160;</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_DECIMAL</p>

<p>DECIMAL</p>

<p>Decimal</p>

<p>decimal, money</p>

<p>number</p>

<p>decimal, money, smallmoney</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_DISTINCT</p>

<p>DISTINCT</p>

<p>&#160;</p>

<p>&#160;</p>

<p>&#160;</p>

<p>&#160;</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_DOUBLE</p>

<p>DOUBLE</p>

<p>Double</p>

<p>&#160;</p>

<p>&#160;</p>

<p>&#160;</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_FLOAT</p>

<p>FLOAT</p>

<p>Float</p>

<p>float</p>

<p>number</p>

<p>float</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_IDSTAMP</p>

<p>CHAR</p>

<p>Char</p>

<p>char, nchar</p>

<p>char, nchar</p>

<p>char, nchar, uniqueidentifier</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_INTEGER</p>

<p>INTEGER</p>

<p>Integer</p>

<p>integer, serial</p>

<p>&#160;</p>

<p>int</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_LONGVARBINARY</p>

<p>LONGVARBINARY</p>

<p>Long Varchar for Bit Data</p>

<p>byte</p>

<p>long raw</p>

<p>image</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_LONGVARCHAR</p>

<p>LONGVARCHAR</p>

<p>Long Varchar</p>

<p>text</p>

<p>long</p>

<p>text, ntext</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_MONEY</p>

<p>DOUBLE</p>

<p>Double</p>

<p>&#160;</p>

<p>&#160;</p>

<p>&#160;</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_MONEY4</p>

<p>DOUBLE</p>

<p>Double</p>

<p>&#160;</p>

<p>&#160;</p>

<p>&#160;</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_NULL</p>

<p>NULL</p>

<p>&#160;</p>

<p>&#160;</p>

<p>&#160;</p>

<p>&#160;</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_NUMERIC</p>

<p>NUMERIC</p>

<p>Numeric</p>

<p>&#160;</p>

<p>&#160;</p>

<p>numeric</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_OTHER</p>

<p>OTHER</p>

<p>&#160;</p>

<p>&#160;</p>

<p>&#160;</p>

<p>&#160;</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_REAL</p>

<p>REAL</p>

<p>Real</p>

<p>smallfloat</p>

<p>&#160;</p>

<p>real</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_REFCURSOR</p>

<p>REF</p>

<p>&#160;</p>

<p>&#160;</p>

<p>&#160;</p>

<p>&#160;</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_SMALLINT</p>

<p>SMALLINT</p>

<p>Smallint</p>

<p>smallint</p>

<p>&#160;</p>

<p>smallint</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_STRUCT</p>

<p>STRUCT</p>

<p>&#160;</p>

<p>&#160;</p>

<p>&#160;</p>

<p>&#160;</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_TIME</p>

<p>TIME</p>

<p>Time</p>

<p>datetime hour to second</p>

<p>&#160;</p>

<p>&#160;</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_TIMESTAMP</p>

<p>TIMESTAMP</p>

<p>Timestamp</p>

<p>datetime year to fraction(5), datetime year to second</p>

<p>date</p>

<p>datetime, smalldatetime</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_TINYINT</p>

<p>TINYINT</p>

<p>&#160;</p>

<p>&#160;</p>

<p>&#160;</p>

<p>tinyint</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_VARBINARY</p>

<p>VARBINARY</p>

<p>Rowid</p>

<p>&#160;</p>

<p>raw</p>

<p>varbinary</p>

  </td>
  </tr>
  </table>
</div>

<p>CF_SQL_VARCHAR</p>

<p>VARCHAR</p>

<p>Varchar</p>

<p>varchar, nvarchar, lvarchar</p>

<p>varchar2, nvarchar2</p>

<p>varchar, nvarchar, sysname</p>

  </td>
  </tr>
  </table>
</div>
<div id="VALUE">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">VALUE</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">Required</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">



<p>Value that ColdFusion passes to the right of the comparison operator in a where clause. </p>
<p>If CFSQLType is a date or time option, ensure that the date value uses your DBMS-specific date format. Use the CreateODBCDateTime or DateFormat and TimeFormat functions to format the date value.</p>

  </td>
  </tr>
  </table>
</div>
<div id="CFSQLTYPE">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">CFSQLTYPE</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">Optional</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">

<strong>Default value:</strong> "CF_SQL_CHAR"


<p>SQL type that parameter (any type) is bound to: </p><ul>

<li>CF_SQL_BIGINT</li>

<li>CF_SQL_BIT</li>

<li>CF_SQL_CHAR </li>

<li>CF_SQL_BLOB </li>

<li>CF_SQL_CLOB</li>

<li>CF_SQL_DATE</li>

<li>CF_SQL_DECIMAL</li>

<li>CF_SQL_DOUBLE</li>

<li>CF_SQL_FLOAT</li>

<li>CF_SQL_IDSTAMP</li>

<li>CF_SQL_INTEGER</li>

<li>CF_SQL_LONGVARCHAR</li>

<li>CF_SQL_MONEY</li>

<li>CF_SQL_MONEY4</li>

<li>CF_SQL_NUMERIC</li>

<li>CF_SQL_REAL</li>

<li>CF_SQL_REFCURSOR</li>

<li>CF_SQL_SMALLINT</li>

<li>CF_SQL_TIME</li>

<li>CF_SQL_TIMESTAMP</li>

<li>CF_SQL_TINYINT</li>

<li>CF_SQL_VARCHAR</li>
</ul>


  </td>
  </tr>
  </table>
</div>
<div id="MAXLENGTH">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">MAXLENGTH</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">Optional</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">

<strong>Default value:</strong> "Length of string in value attribute"


<p>Maximum length of parameter. Ensures that the length check is done by ColdFusion before the string is sent to the DBMS, thereby helping to prevent the submission of malicious strings.</p>

  </td>
  </tr>
  </table>
</div>
<div id="SCALE">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">SCALE</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">Optional</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">

<strong>Default value:</strong> "0"


<p>Number of decimal places in parameter. Applies to CF_SQL_NUMERIC and CF_SQL_DECIMAL.</p>

  </td>
  </tr>
  </table>
</div>
<div id="NULL">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">NULL</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">Optional</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">

<strong>Default value:</strong> "No"


<p>Whether parameter is passed as a null value:</p><ul>

<li>Yes: tag ignores the value attribute.</li>

<li>No</li>
</ul>


  </td>
  </tr>
  </table>
</div>
<div id="LIST">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">LIST</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">Optional</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">

<strong>Default value:</strong> "No"

<ul>

<li>Yes: the value attribute value is a delimited list.</li>

<li>No</li>
</ul>


  </td>
  </tr>
  </table>
</div>
<div id="SEPARATOR">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">SEPARATOR</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">Required, if you specify a list in value attribute</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">

<strong>Default value:</strong> ", (comma)"


<p>Character that separates values in list, in value attribute. </p>

  </td>
  </tr>
  </table>
</div>

  </body>
</html>
