====== setCustomMetaType ======
~~NOTOC~~
<WRAP right box>
**From Version 5.22**\\
==See Also==
[[v5:reference:connection:getcustommetatypes|getCustomMetaTypes]]\\
== Syntax ==
  bool setCustomMetaType(
         string $metaType,
         string $actualType,
         string $dictionayType,
         mixed $handleAsType=false,
         mixed $callBack=false
         )
</WRAP>
===== Description =====
The function ''setCustomMetaType()'' takes an input string that represents a database-specific data type, and creates an ADOdb [[v5:dictionary:metatype|metaType]] associated with it. If any combination of parameters passed are already bound to an existing metaType, the new setting overrides the old. 
-------------------------------------------------------
===== $metaType =====
An existing or new type. The type definition should be an uppercase alpha-numeric value, e.g. **P**

===== $actualType =====
The physical data type as provided by the database, for example the POINT data type in the mySQL returns 255.  

===== $dictionaryType =====
A Database specific field type, mapped to the metaType, e.g. **POINT**. This tells ADOdb how to handle the database will handle the record.

===== $handleAsType ====
One of the standard [[v5:dictionary:dictionary_index|metaTypes]]. This indicates what type of data the new type is, and how it should be handled prior to insertion. If not set, then no attempt is made to process the data, and an attempt is made to insert the data in the format that it was provided.

=====$callback =====

The handler can be one of these types:
  - Not set: No pre-processing of data prior to insertion of data.
  - Object: An anonymous function that can be used to process data.

The callback function can be used to apply any changes to the data **prior** to the processing as type.
===== Examples =====
==== Using A Passthrough Handler  ====
In this example, the system can be expanded to accept geometry type data types by creating a new data type

<code php>

/*
* $db = MySQL connection assumed
*/


/*
* A type 'P' is associated with a physical data type of 255 (MYSQLI_TYPE_GEOMETRY) 
* and we describe it as 'POINT' in the insertion statement. Because we do not want 
* any changes to the input value, we do not define any processing rules
*/
$ok = $db->setCustomMetaType('P',MYSQLI_TYPE_GEOMETRY, 'POINT');

/*
* Insert a record with a point column
*/
$ar = array();
$ar['geo_column'] = 'POINT(1,2)';

</code>

==== Using a closure ====
In this example all character fields are converted to lowercase by the anonymous function, and are then processed normally as character
<code php>

/*
* $db = MySQL connection assumed
*/
$callback = function($val) { 
	return strtolower($val); 
	};

$ok = $db->setCustomMetaType('C',MYSQLI_TYPE_CHAR, 'CHAR','C', $callback);
</code>

===== Using The Custom Type In DataDict Functions ======
In this example, we use a custom definition to create a JSON column in a table under MySQL
<code php>
/*
* We must define the custom type before loading the data dictionary
*/
$ok = $db->setCustomMetaType('J', MYSQLI_TYPE_JSON, 'JSON');

/*
* Then create a data dictionary object, using this connection
*/
$dict = NewDataDictionary($db);

$tabname = "mt_test";
$flds = " 
   COL1 I  NOTNULL AUTO PRIMARY,
   COL2 C(32) NOTNULL DEFAULT 'abc',
   COL3 N(12.2),
   COL4 J
  ";

$sqlarray = $dict->createTableSQL($tabname, $flds);
print_r($sqlarray);

/*
* Returns
CREATE TABLE mt_test (
COL1                     INTEGER NOT NULL AUTO_INCREMENT,
COL2                     VARCHAR(32) NOT NULL DEFAULT 'abc',
COL3                     NUMERIC(12,2),
COL4                     JSON,
                 PRIMARY KEY (COL1)
                 )
*/
</code>