QueryAddColumn

Description

Adds a column to a query and populates its rows with the contents of a one-dimensional array. Pads query columns, if necessary, to ensure that all columns have the same number of rows.

Return value

The number of the column that was added.

Syntax

QueryAddColumn(query, column-name, array-name)

History

New in ColdFusion MX: If a user attempts to add a column whose name is invalid, ColdFusion throws an error. (In earlier releases, ColdFusion permitted the add operation, but the user could not reference the column after adding it.)

Parameters

Parameter Description

query
Name of a query that was created with QueryNew.

column-name
Name of the new column.

array-name
Name of an array whose elements are to populate the new column.

Parameter	Description
query	Name of a query that was created with `QueryNew`.
column-name	Name of the new column.
array-name	Name of an array whose elements are to populate the new column.

Usage

You can add columns to query objects such as queries retrieved with the cfquery tag or queries created with the QueryNew function. You cannot us the QueryAddColumn function on a cached query.

Useful for generating a query object from the arrays of output parameters that Oracle stored procedures can generate.

Example

<h3>QueryAddColumn Example</h3>
<p>This example adds three columns to a query object and then populates 
the columns with the contents of three arrays.</p> 
<p>After populating the query, the example shows, in tabular format, 
the contents of the columns.</p> 
<!--- make a query --->
<cfset myQuery = QueryNew("")>

<!--- create an array --->
<cfset FastFoodArray = ArrayNew(1)>
<cfset FastFoodArray[1] = "French Fries">
<cfset FastFoodArray[2] = "Hot Dogs">
<cfset FastFoodArray[3] = "Fried Clams">
<cfset FastFoodArray[4] = "Thick Shakes">

<!--- add a column to the query --->
<cfset nColumnNumber = QueryAddColumn(myQuery, "FastFood", FastFoodArray)>
<!--- create a second array --->
<cfset FineCuisineArray = ArrayNew(1)>
<cfset FineCuisineArray[1] = "Lobster">
<cfset FineCuisineArray[2] = "Flambe">
<!--- add a second column to the query --->
<cfset nColumnNumber2 = QueryAddColumn(myQuery, "FineCuisine", FineCuisineArray)>

<!--- create a third array --->
<cfset HealthFoodArray = ArrayNew(1)>
<cfset HealthFoodArray[1] = "Bean Curd">
<cfset HealthFoodArray[2] = "Yogurt">
<cfset HealthFoodArray[3] = "Tofu">

<!--- add a third column to the query --->
<cfset nColumnNumber3 = QueryAddColumn(myQuery, "HealthFood", HealthFoodArray)>

<table cellspacing = "2" cellpadding = "2" border = "0">
<tr>
  <th align = "left">Fast Food</th>
  <th align = "left">Fine Cuisine</th>
  <th align = "left">Health Food</th>
</tr>
<cfoutput query = "myQuery">
<tr>
  <td>#FastFood#</td>
  <td>#FineCuisine#</td>
  <td>#HealthFood#</td>
</tr>
</cfoutput>
</table>
<p><B>Note:</B> Because there are fewer elements in the Fine Cuisine 
and Health Food arrays, QueryAddColumn added padding to the 
corresponding columns in the query.</p>