Differences

This shows you the differences between two versions of the page.

--- v5:reference:adodb_assoc_case [2016/01/21 01:27] – mnewnham
+++ v5:reference:adodb_assoc_case [2022/06/08 16:10] – [ADODB_ASSOC_CASE] fix incorrect indication of when constant must be declared dregad
@@ Line 1: / Line 1: @@
-====== ADODB_ASSOC_CASE =====
+====== ADODB_ASSOC_CASE ======
 ~~NOTOC~~
-The constant must be declared **before** including  adodb.inc.php. It is not possible to change the casing of recordset keys during a procedure.
+When returning data in **associative //[[v5:reference:connection:setfetchmode|fetch mode]]//**, the ''ADODB_ASSOC_CASE'' constant gives control over the casing of the retrieved recordsets' fields.
-The constant ''ADODB_ASSOC_CASE'' controls the key casing of retrieved recordsets when the [[v5:reference:connection:setfetchmode|fetch mode]] is set to associative. The default behavior for retrieval is controlled by the DBMS. When writing portable code, it is important to choose a default behavior and always use it.
+It must be declared **before** initializing the database connection with [[v5:reference:connection:adonewconnection|ADONewConnection()]].
+Being a constant, it is of course not possible to change its value later on.
- Use the constant ADODB_ASSOC_CASE to change the case of the keys. There are 3 possible values:
+Note that this setting has no effect on the casing of the actual data.
-===== Constants =====
+<WRAP info>
+Until ADOdb 5.20.14, the documentation contained several references to a global variable named ''$ADODB_ASSOC_CASE'', which was only used in [[v5:activerecord:activerecord_index]], but in an inconsistent manner.
+**As of 5.20.15, the only supported method to set fields case is the ''ADODB_ASSOC_CASE'' constant.**
+</WRAP>
+===== Possible values =====
 ^Name^Value^Description^
 |ADODB_ASSOC_CASE_LOWER|0|lowercase field names|
 |ADODB_ASSOC_CASE_UPPER|1|uppercase field names|
-|ADODB_ASSOC_CASE_NATIVE (Default)|2|use native-case field names|
+|ADODB_ASSOC_CASE_NATIVE (Default)|2|native-case field names|
+With the default behavior, ''ADODB_ASSOC_CASE_NATIVE'', ADOdb does not perform any transformation on field names, and returns them exactly as they are defined by the DBMS.
+<WRAP tip>
+When writing portable code, it is strongly recommended to choose either upper or lower case.
+Relying on the native case default will likely cause compatibility issues, as there is no consistent casing across databases and some DBMS may returned mixed-case keys.
+</WRAP>
 ===== Usage =====
 <code php>
-DEFINE(ADODB_ASSOC_CASE,0);
+define('ADODB_ASSOC_CASE', ADODB_ASSOC_CASE_LOWER);
-require "adodb/adodb.inc.php";
+require "adodb.inc.php";
+$ADODB_FETCH_MODE = ADODB_FETCH_ASSOC;
-/*
+// $db Connection assumed
- * connection assumed
-*/
+print_r($db->getAll("SELECT accountNo, accountName FROM table"));
+/* Response is:
-$SQL = "SELECT accountNo,accountName FROM table";
-$data = $db->getAll($SQL);
-print_r($data);
-/*
- * Response is:
  [0]=>array('accountno'=>1,
             'accountname'=>'The First Account'
@@ Line 34: / Line 46: @@
             'accountname'=>'The Second Account'
             )
-            )
 */
 </code>
@@ Line 41: / Line 51: @@
 or:
 <code php>
-DEFINE(ADODB_ASSOC_CASE,1);
+define('ADODB_ASSOC_CASE', ADODB_ASSOC_CASE_UPPER);
-require "adodb/adodb.inc.php";
+require "adodb.inc.php";
+$ADODB_FETCH_MODE = ADODB_FETCH_ASSOC;
-/*
+// $db Connection assumed
- * connection assumed
-*/
+print_r($db->getAll("SELECT accountNo, accountName FROM table"));
+/* Response is:
-$SQL = "SELECT accountNo,accountName FROM table";
-$data = $db->getAll($SQL);
-print_r($data);
-/*
- * Response is:
  [0]=>array('ACCOUNTNO'=>1,
             'ACCOUNTNAME'=>'The First Account'
@@ Line 59: / Line 67: @@
             'ACCOUNTNAME'=>'The Second Account'
             )
-            )
 */
 </code>
@@ Line 67: / Line 73: @@
 <code php>
-DEFINE(ADODB_ASSOC_CASE,3);
+define('ADODB_ASSOC_CASE', ADODB_ASSOC_CASE_NATIVE);
-require "adodb/adodb.inc.php";
+require "adodb.inc.php";
+$ADODB_FETCH_MODE = ADODB_FETCH_ASSOC;
-/*
+// $db Connection assumed
- * connection assumed
-*/
+print_r($db->getAll("SELECT accountNo, accountName FROM table"));
+/* Response is:
-$SQL = "SELECT accountNo,accountName FROM table";
-$data = $db->getAll($SQL);
-print_r($data);
-/*
- * Response is:
  [0]=>array('accountNo'=>1,
             'accountName'=>'The First Account'
@@ Line 85: / Line 89: @@
             'accountName'=>'The Second Account'
             )
-            )
 */
 </code>