/**
@class Valence_PHP_Toolkit.VvDb
The VvDb class provides a Valence-optimized SQL interface to the DB2 for i database.

*/

/**
@method execSql
 Executes an sql statement against the database and returns the results as a PHP array.  This method is used to perform sql
 statements as part of the normal business logic of your app.  For example, if you need to check the existence of a record
 you can use VvDb::execSql to execute the sql statement and then programmatically interrogate the response to determine how the
 program logic should proceed.  VvDb::execSql is also useful for performing sql inserts, updates and deletes.  Sql statements executed
 through this command will use the Valence environment library list associated with the current Valence Portal session.
 To use tables outside of the library list they must be specified explicitly as part of the sql statement.

 To easily send data directly to the browser see
 <a href="http://localhost:1841/#!/api/Valence_PHP_Toolkit.VvOut-method-execSqlToJson">VvOut:execSqlToJson</a>.


 @param {array (required)} options An array key/value pairs
##Valid keys for options are:

 - `start` - Starting record to return on a select (optional).
 - `limit` - Limits number of records returned on a select (optional).
 - `autoCount` - Whether to try to determine the count of records automatically (optional, defaults to false).
 - `params` - An array of parameter replacements to be used on an  statement that contains question marks and needs to be prepared (optional).

@param {string (required)} sql

A string containing the sql statement to run.

@param {string (optional)} countSql

A string representing the specific sql statement to run that will return the total count.

 @return {results} An array of key/value pairs

##Possible key/value pairs in the results are:

 - `success` - Will return true or false.
 - `dataset` - If success is true this dataset may contain an array of the results of the sql, if the sql statement is one that returns records.
 - `rows` - If autoCount was true, or if a countSql was passed, this key will contain the number or rows, or "count."
 - `sqlstate` - If there was an error this key will contain the sqlstate code.
 - `sqlmsg` - If there was an error this key will contain the sqlmsg, which will be an English description of the error.

##PHP Example 1

     // prepare sql replacement values
     $options['params'] = array(
        array(1, "ticketid", $ticketid, DB2_PARAM_IN),
        array(2, "ndate", $ndate, DB2_PARAM_IN),
        array(3, "note", $note, DB2_PARAM_IN),
        array(4, "vvuserid", $vvuserid, DB2_PARAM_IN)
     );

     // construct sql statement
     $stmt = 'insert into hdnote values(?,?,?,?)';

     // execute sql statement
     $results = VvDb::execSql($options, $stmt);

    // return success or fail (true or false)
    return $results['success'];

##PHP Example 2

     // get first 25 records of democmast file but return the total count of all records in the table
     $options = array(
        start => 1,
        limit => 25,
        autoCount => false
     );

     $sql = 'select * from democmast');
     $countSql = 'select count(*) from democmast';
     $results = VvDb::execSql($options, $sql, $countSql);

*/

/**
@method execStoredProcedure
 (Internal)
 Used by vvcall.php to execute certain stored procedures.

*/