====== getAssoc ======
~~NOTOC~~
<WRAP right box>
== syntax ==
   mixed getAssoc (
         string $sql
         optional string[] $bindvars=false
         optional bool $forceArray=false
         optional bool $first2Cols=false
         )
</WRAP>

===== Description =====
The function executes a statement and returns all of the returned rows in an array or false if the statement execution fails, or if only 1 column is requested in the SQL statement. If no records match the provided SQL statement, an empty array is returned.

The presentation of certain aspects of the returned data can be modified by the constant [[v5:reference:adodb_assoc_case|ADODB_ASSOC_CASE]] (see below for examples).

For a detailed description of the SQL and bind parameters passed, see [[v5:reference:connection:execute|execute()]].

In addition it should be noted that the presentation of the returned data is modified by the number of columns requested in the SQL statement and the setting of the optional parameters ''$forceArray'' and ''$first2Cols''.

==== Requesting two columns ====
When 2 columns are requested, the first column becomes the key and the second the value.
<code php>
/*
 * DB2 Connection assumed
*/
$ar = $db->getAssoc("SELECT ACTNO,ACTDESC FROM ACT");

/*
 * $ar returns:
Array
(
    [10] => MANAGE/ADVISE
    [20] => ESTIMATE COST
    [30] => DEFINE SPECS
    [40] => LEAD PROGRAM/DESIGN
 ......
)
*/
          
</code>
==== Requesting more than two columns ====
When more than 2 columns are requested, the first column becomes the key, all other columns become a numeric array beneath that key.
<code php>
/*
 * DB2 Connection assumed
*/
$ar = $db->getAssoc("SELECT * FROM ACT");

/*
 * $ar returns:
Array
(
    [10] => Array
        (
            [0] => MANAGE
            [1] => MANAGE/ADVISE
        )

    [20] => Array
        (
            [0] => ECOST
            [1] => ESTIMATE COST
        )

    [30] => Array
        (
            [0] => DEFINE
            [1] => DEFINE SPECS
        )

 ......
)
*/
          
</code>
==== Requesting two columns and setting the $forceArray flag ====
When 2 columns are requested and the ''$forceArray'' boolean is set, the first column becomes the key and the second becomes an array beneath that key.
<code php>
/*
 * DB2 Connection assumed
*/
$ar = $db->getAssoc("SELECT ACTNO,ACTDESC FROM ACT",false,true);

/*
 * $ar returns:
   Array
(
    [10] => Array
        (
            [0] => MANAGE/ADVISE
        )

    [20] => Array
        (
            [0] => ESTIMATE COST
        )

    [30] => Array
        (
            [0] => DEFINE SPECS
        )
 ......
)
*/
          
</code>      
==== Requesting more than two columns and setting the $first2Cols flag ====
When more than 2 columns are requested, and the ''$first2cols'' flag is set, the behaviour is the same as the default configuration. The ''$forceArray'' flag is ignored. All columns after the first two are discarded.

<code php>
/*
 * DB2 Connection assumed
*/
$ar = $db->getAssoc("SELECT * FROM ACT",false,false,true);

/*
 * $ar returns:
Array
(
    [10] => MANAGE/ADVISE
    [20] => ESTIMATE COST
    [30] => DEFINE SPECS
    [40] => LEAD PROGRAM/DESIGN
 ......
)
*/
          
</code>
===== How ADODB_ASSOC_CASE affects returned data =====
In certain instances, the ''ADODB_ASSOC_CASE'' constant changes the casing of inner keys. **The casing of outer keys is never affected**, so in this first example, the data will always be returned as it appears in the database
<code php>
/*
* Connection to mysql 'employees' database assumed.
*/
$SQL = "SELECT first_name,last_name from employees";
$r = $db->getAssoc($SQL);
print_r($r);
/*
* Returns: 
Array
(
    [Georgi] => Wielonsky
    [Bezalel] => Ranon
    [Parto] => Kambil
    ........
)
*/
</code>
Setting ADODB_ASSOC_CASE to ASSOC_CASE_LOWER:
<code php>
/*
* Connection to mysql 'employees' database assumed.
*/
$SQL = "SELECT first_name,last_name,emp_no from employees";
$r = $db->getAssoc($SQL);
print_r($r);
/*
* Returns: 
Array
(
    [Georgi] => Array
        (
            [last_name] => Wielonsky
            [emp_no] => 499814
        )

    [Bezalel] => Array
        (
            [last_name] => Ranon
            [emp_no] => 499846
        )

    [Parto] => Array
        (
            [last_name] => Kambil
            [emp_no] => 499529
        )
    .......
 )
*/ 
</code>
Setting ADODB_ASSOC_CASE to ASSOC_CASE_UPPER:
<code php>
/*
* Connection to mysql 'employees' database assumed.
*/
$SQL = "SELECT first_name,last_name,emp_no from employees";
$r = $db->getAssoc($SQL);
print_r($r);
/*
* Returns: 
Array
Array
(
    [Georgi] => Array
        (
            [LAST_NAME] => Wielonsky
            [EMP_NO] => 499814
        )

    [Bezalel] => Array
        (
            [LAST_NAME] => Ranon
            [EMP_NO] => 499846
        )

    [Parto] => Array
        (
            [LAST_NAME] => Kambil
            [EMP_NO] => 499529
        )
    .......
 )
*/ 
</code>

   
===== Using The Recordset Method =====
The method can also be used as a recordset method

<code php>
$ar = $db->Execute("SELECT * FROM ACT")->getAssoc();
</code>