====== alterColumnSql ======
<WRAP todo>
Add usage example, expand description of new table requirement
</WRAP>
~~NOTOC~~
<WRAP right box>
== See Also ==
[[v5:dictionary:column_attributes|Column Attributes Reference]] 
== Syntax ==
  array alterColumnSql(
      string $tableName,
      string $columnData,
      optional string $tableFields='',
      optional string $tableOptions=''
      )

</WRAP>
===== Description =====
The method ''alterColumnSql()'' creates the SQL statement necessary to modify an existing column on an existing table, given by ''$tableName'', with the attributes specified in the string ''$columnData''. The column must already exist in the specified table.

The information specified in the ''$columnData'' string must conform to the [[v5:dictionary:column_attributes|Column Attributes]] standard.

===== Limitations ====
Based on the database and column type, it may not be possible to modify the column to requested settings without prior action. The optional tableFields and tableOptions may help this by effectively:

  * Renaming the existing table
  * Creating a new table to the new specifications
  * Copy the data from the old to the new table
  * Dropping the renamed table
  
Some of the qualifying events that may require this action are:

  * Attempting to modify a column associated with a primary key or index
  * Attempting to reduce the length of a character field that already contains data
  * Attempting to switch the metaType of a field from say ''C'' to ''I''

In order to actually modify the column, the returned array must be passed to the [[v5:dictionary:executesqlarray|executeSqlArray()]] method. 

===== Usage =====
<code php>

/*
 * create a data dictionary object, using this connection
 */
$dict = NewDataDictionary($db);


$table = 'lctable';
$flds = 'col6 C(50)';

$sql = $dict->alterColumnSql($table,$flds);
/*
 * Sql looks like:
 *  ALTER TABLE "lctable" ALTER COLUMN "col6" SET DATA TYPE VARCHAR(50)
 */

/*
 * Complete the process by executing the statement
*/
$db->startTrans();
$dict->executeSqlArray($sql);
$db->completeTrans();
</code>