Closes #995

[NathanGibbs3]

Fixes Issue #995 in the 5.22x branch.

Minor changes to the form of code in _adodb_getinsertsql((), function of code remains unchanged.

Documentation update requested by @dregad

====== getUpdateSql ======
~~NOTOC~~
<WRAP right box>
== See Also ==
[[v5:reference:adodb_quote_fieldnames|$ADODB_QUOTE_FIELDNAMES]]
[[v5:reference:adodb_force_type|$ADODB_FORCE_TYPE]]\\
[[v5:reference:connection:autoexecute|AutoExecute()]]\\

== Syntax ==
  string getUpdateSql(
        mixed $recordSet,
        string[] $fieldArray,
        optional bool $forceUpdate=false,
        optional bool $placeHolder=false,
        optional bool $forceType=null
       )
</WRAP>
===== Description =====
The function ''getUpdateSql()'' takes a set of parameters and returns an SQL statement that can be used to update a record in the database. It can automatically apply any necessary database specific quoting to character fields and exclude any unchanged variables.
------------------
===== Parameters =====
====  $recordSet ====
The parameter ''$recordSet'' is either 

  * a //recordset// obtained by [[v5:reference:connection:execute|executing]] a select statement to obtain an **empty recordset**. There is no need to read the row. <code php>
$SQL = "SELECT * FROM employees WHERE emp_no=-1";
$result = $db->execute($SQL);
$sql = $db->getUpdateSql($result,.....
</code>
  
  * a //string// specifying a table name <code php>
$table = 'employees';
$sql = $db->getInsertSql($table,....
</code> Note that in this case, due to the fact that the function passes the table name by reference, the following syntax is //not valid//: <code php>
/*
 * Incorrect syntax
 */
$sql = $db->getInsertSql('employees',....
</code> Also note that this usage causes ADOdb to read the recordset information for itself, which may cause performance issues.
-------------------------------------------------------------------------------
==== $fieldArray ====
''$fieldArray'' is an associative key=>value pair of fieldnames and values. The values in the pair will be inserted into the record. Note also
  * Any key in the array that does not match a field name in the table will be discarded before the SQL statement is produced.
  * The value of any field in the table that does not appear in the ''$fieldArray'' is controlled by the [[v5:reference:adodb_force_type|$ADODB_FORCE_TYPE]] variable.
  * Auto-increment fields should not be included in the field list.

<code php>
$ar = array('last_name'=>"John O'Reilly");
</code>
--------------------------------------------------------------------------------
==== $forceUpdate ====
''$forceUpdate'' forces the sql statement to include updates for fields that have not changed. It may be necessary to force updates when, for example, distinction needs to be made between null and zero in integer fields.

In addition, use of this parameter eliminates the need to add additional testing to determine if any fields have changed. In cases such as these, if the parameter is not set and there have been no modified fields, the getUpdateSql() method will return an empty string, causing [[v5:reference:execute]] to fail if passed this parameter.
-------------------------------------------------------------------------------
==== $placeHolder ====
This argument was previously used for information about deprecated PHP functionality, and is now ignored 
--------------------------------------------------------------------------------
<WRAP right tip 300px>
This parameter was designed to provide backwards compatibility with now unsupported versions of ADOdb and may be removed in future releases.
</WRAP>
==== $forceType ====

see [[v5:reference:adodb_force_type|$ADODB_FORCE_TYPE]]
-------------------------------------------
===== Usage =====
<code php>
/*
 * Sample uses the MySQL 'employees' demo database
 */

$SQL = "SELECT * FROM employees WHERE employee_no=10001";
$employeeRecord = $db->getAll($SQL);
/*
 * Employee record returns:
Array
(
    [emp_no] => 10001
    [birth_date] => 1953-09-02
    [first_name] => Georgi
    [last_name] => Facello
    [gender] => M
    [hire_date] => 1986-06-26
)
*/

$SQL = 'SELECT * FROM employees WHERE emp_no=10001';
$result = $db->execute($SQL);

$updateArray = array('first_name'=>'Jerry',
		     'last_name'=>"O'Reilly",
		     'gender'=>'M');

$SQL = $db->getUpdateSql($result, $updateArray);
/*
 * returns
 * UPDATE employees 
              SET FIRST_NAME='Jerry', 
                  LAST_NAME='O\'reilly' 
            WHERE emp_no=10001
 */
</code>
Note:
  *  The ''last_name'' **O'Reilly** was automatically quoted into an appropriate formatted for insertion into a MySQL database.
  * Because the value of the ''gender'' field was unchanged, it was discarded by the update statement.
If we want the returned statement to include all the supplied fields, we add the ''$forceUpdate'' option.

<code php>
$SQL = $db->getUpdateSql($result, $updateArray, true);
/*
 * returns
 * UPDATE employees SET FIRST_NAME='Jerry', 
                        LAST_NAME='O\'reilly', 
                        GENDER='M' 
                        WHERE emp_no=10001
 */
</code>