As of ADOdb version 6.0 , MetaCasing provides a complete, separate method of controlling key/value casing alternative to the effects of ADODB_ASSOC_CASE when used in metaFunctions. It provides a superior functionality:

• Provides consistent casing of keys in meta functions.
• Can be changed dynamically inside programs
• Is consistently supported by all database drivers.
• Improves performance when schema information is read multiple time, or used in the course of an update. For instance, when autoExecute() is used on the same table more than once, the second (and subsequent) record insertion/update occurs in 1/2 the time as under ADOdb version 5.
• Separates the 'business process' of ADOdb (management of schemas, update of records using helper routines such as autoExecute(),createTableSql() from the 'presentation layer' metaTables(),metaColumns(), etc.

Historically, ADOdb has provided a confusing set of functions, constants and variables that interact with each other to attempt to provide consistency of presentation layer, whilst allowing database updates with helper routines. The following non-exhaustive list shows some of these items

• ADODB_ASSOC_CASE
• ADODB_FORCE_QUOTES
• The $nameQuote option on autoExecute()

The end result has been that schema information must be sometimes re-read multiple times in order to obtain the necessary consistent presentation layer values, whilst configuring the tables and columns differently for table updates.

MetaCasing attempts to eliminate 90% of the confusing conflicts, as well as providing performance enhancements by storing and re-using database schema information instead of re-rereading the database multiple times.

Each time an element of the schema is read, such as tables, columns and indexes, the retrieved data is stored in the metaCache, so that any subsequent requests for that information, even through different methods will be retrieved through the cache. For example, a request for column name information via the metaColumnNames() method will cache information about the schema that can be used by the autoExecute() method.

The data in the metaCache is stored in 'native mode', that is, it follows casing conventions provided by the database management system. For that reason, the casing of keys in the cache should not be relied on to be of any specific type. The metaCasing system provides helper routines to provide API consistency for data returned. These helper routines post-process the retrieved information and allow the schema information to be presented without re-reading the database.

MetaCasing is disabled, and MetaCaching is enabled by default in ADOdb versions 6.0 and higher. The configurations of either can be modified at any time after creation of the ADOdb class. Configuration is not predicated on having established a connection to the database. In addition, configuration can be changed multiple times within a single procedure.

MetaCasing is controlled by a single method setMetaCasing(), which takes a single argument, which controls how the data is presented to the end user. It has no effect on how the schema information is retrieved from the database, the casing of data keys of retrieved recordsets when setFetchMode() is in associative mode, or the values of data is read and written into the database. The available values to control presentation of data is shown below

$db->setMetaCasing($db::METACASE_UPPER);
print_r($db->metaColumns('ACT');
/*
* Prints 
array(
    0=>ACTNO,
    1=>ACTDESC,
    2=ACTKWD
    )
*/
$db->setMetaCasing($db::METACASE_LOWER);
print_r($db->metaColumns('ACT');
/*
* Prints 
array(
    0=>actno,
    1=>actdesc,
    2=actkwd
    )
*/

Note in the above example, the table name requested was provided in upper case, bu the resulting column names were in lower case. One of the benefits of the metaCase system is that it is no longer necessary to know the correct casing of table or column names, they will be automatically converted to the correct values.

By default, metaCasing is switched off (Apart from the IBM DB2 driver). This means that the metaFunctions behave exactly as in previous versions. Once enabled, the ADODB_ASSOC_CASE constant value is ignored for metaFunctions.

void setMetacasing(
   int $casing
)

The method setMetaCasing() sets the default casing method for the next (and subsequent unless changed) call to Meta function. The valid options are described above.

int getMetacasing()

The method getMetaCasing() returns the currently set casing method for the next (and subsequent unless changed) call to a Meta function.

void clearMetaCache(
    optional string $tableName=false
)

The method clearMetaCache() flushes the metaCache for the specified table, or for all tables if no table name is supplied. Subsequent calls to metaFunctions will begin rebuilding the cache

void disableMetaCache()

The method disableMetaCache() disables metaCaching. Any cached metadata will be flushed. Subsequent calls to metaFunctions will always query the database directly. There may be overhead in data retrieval.

void enableMetaCache()

The method enableMetaCache() re-enables a previously disabled metaCache. Subsequent calls to metaFunctions will rebuild the metaCache.

void buildMetaCache()  

The method buildMetaCache() builds a metaCache array for all of the available tables, columns, indexes, keys and procedures for the currently selected database. For programs that make substantial use of metaFunctions, or helper functions like autoExecute() across multiple tables, there may be substantial performance benefits in using this function to build the metaCache before accessing specific table information

———————————–

Metacasing rules are applied to all Meta functions. Noting in particular the change to metaColumns() described below as well as the following functions that depend on Meta functions:

All of the above casing rules apply as above, plus another important change: If the metaCasing is set to METACASE_NATIVE, then this supersedes all of the $ADODB_QUOTE_FIELDNAMES options. Any setting currently in place when autoExecute() is called will be ignored. In addition, all table and columns will be quoted with the value defined in the $nameQuote class variable (not necessarily backticks). If compatibility is needed with old code, metacasing can be turned off prior to calling the autoExecute() function.

Metacasing will now produce a more formal SQL statement in preparation for insertion of a record.

• All tables and column names will be quoted, irrespective of their containing special characters
• Table and column names will be correctly cased, based on how they are held in the database

/*
* Connection assumed
*/
 
/*
* Use legacy metacasing
*/
$db->setMetaCasing($db::METACASE_LEGACY);
$table = 'ACT';
$fields = array('act-no'=>10,
                'DESCRIPTION'=>'A record to insert',
                'Balance'=>1024);
$sql = getInsertSql($table,$fields);
 
print_r($sql);
/*
* Keys are always upper cased
* Prints INSERT INTO ACT (`ACT-NO`,DESCRIPTION,BALANCE) VALUES (10,'A record to insert',1024);
*/
 
/*
* Set metacasing to native
*/
$db->setMetaCasing($db::METACASE_NATIVE);
$sql = getInsertSql($table,$fields);
 
print_r($sql);
/*
* Keys are used based on how they are held in the database
* Prints INSERT INTO `act` (`act-no`,`description`,balance`) VALUES (10,'A record to insert',1024);
*/

Any meta function to manages tables, columns or indexes now has the object name in question managed by metaCasing. The same rules that are applied to getInsertSQl and getUpdateSQl are applied to these items.