<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.12"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>FreeTDS API: How to add a new type</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">FreeTDS API
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.12 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">How to add a new type </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="intro"></a>
Introduction</h1>
<p>Adding a new type in FreeTDS is a quite complicated task involving different tasks.</p>
<p>To see an example you can look at <a href="https://github.com/FreeTDS/freetds/commit/adb893f1381fd3ea40564c775e30dc8cdc81dcf2">commit id adb893f1381fd3ea40564c775e30dc8cdc81dcf2</a> ("Implement big(date)time types") and parent changes in the source repository.</p>
<h1><a class="anchor" id="tds"></a>
libTDS changes</h1>
<ul>
<li>
<p class="startli">protocol. First thing to do is add the type to the protocol. A type usually have some mnemonic constant and a structure. Declare them in <code><a class="el" href="a00416_source.html">include/freetds/proto.h</a></code> file. Note that here you should declare the structure the server use not the structure to hold the data in libTDS. <br />
Cfr <a href="https://github.com/FreeTDS/freetds/commit/a74a06e1f97f3137f6cf1bc7319dd7a2cfb52b1f">commit id a74a06e1f97f3137f6cf1bc7319dd7a2cfb52b1f</a>.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">base information. Add the type to <code>misc/types.csv</code> file (I use LibreOffice Calc to do it). This table maintain the base information for a type. <br />
Cfr <a href="https://github.com/FreeTDS/freetds/commit/680cb3371e042bb372cbc5e6feb4054e50d40c1a">commit id 680cb3371e042bb372cbc5e6feb4054e50d40c1a</a>.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">data. There should be some code to handle this type to/from the server. This code is implemented in <code><a class="el" href="a00395_source.html">include/freetds/data.h</a></code> and <code><a class="el" href="a00260.html" title="Handle different data handling from network. ">src/tds/data.c</a></code>. You can either add a new set of functions to handle this new type or add the type handling do another set of types depending on how complicated is that type. One thing you have to to at this step is determine how you store that type in libTDS. This is quite important at upper level libraries will have to use these structures or even present these data to client code (like DB-Library usually do). Due to the way FreeTDS works now you would get a linker error in the ODBC part. You can either ignore the error and proceed with libTDS, add the code to ODBC or disable temporarily ODBC. <br />
Cfr <a href="https://github.com/FreeTDS/freetds/commit/680cb3371e042bb372cbc5e6feb4054e50d40c1a">commit id 680cb3371e042bb372cbc5e6feb4054e50d40c1a</a>.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">enable the type from server. In order to receive the new type from the server you have to tell the server that we support that type. This can be either done changing the protocol (usually Microsoft) or enabling some flags (capabilities for Sybase). <br />
Cfr <a href="https://github.com/FreeTDS/freetds/commit/a498703ff9e309c656b19dd990f4cad0283a47c7">commit id a498703ff9e309c656b19dd990f4cad0283a47c7</a>.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">conversions. Conversions are not hard to write but usually require quite a bit of coding. After extending CONV_RESULT type in <code><a class="el" href="a00392_source.html">include/freetds/convert.h</a></code> and adding the type to the script that generate the conversion tables in <code>src/tds/tds_willconvert.pl</code> you have to write the big part in <code>src/tds/covnert.c</code>. You have to implement all kind of conversions you declared in the previous file. Reuse the functions that are there (for instance there are some parser functions). Also if there are similar types it could be helpful to convert first your type to a super type then use the conversion for that type. For instance for SMALLINT type (<code>tds_convert_int2</code>) the type is just readed and then <code>tds_convert_int</code> is called which handle any int (actually 32 bit integer). Same for data where the <code><a class="el" href="a01077.html" title="this structure is not directed connected to a TDS protocol but keeps any DATE/TIME information...">TDS_DATETIMEALL</a></code> structure is used. Note that conversions to binary (which usually are implemented) are done in another function (<code>tds_convert_to_binary</code>). <br />
Cfr <a href="https://github.com/FreeTDS/freetds/commit/9ed52cb78f725607ac109c8c284ca7c4658d87a9">commit id 9ed52cb78f725607ac109c8c284ca7c4658d87a9</a>.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">string definition. Add string for your type to <code><a class="el" href="a00344.html" title="Contains all routines to get replies from server. ">src/tds/token.c</a></code> in <code>tds_prtype</code>. <br />
Cfr <a href="https://github.com/FreeTDS/freetds/commit/ac0d3b46db7d98436cd76f906b7d455f7651faae">commit id ac0d3b46db7d98436cd76f906b7d455f7651faae</a>.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">conversion tests. You probably will have done some mistake with conversions but don't mind, there are some tests which will help sorting this out. <code>src/tds/unittests/convert.c</code> try any possible combination of conversion to check if all conversion are implemented (it does not check the conversions themself). <code>src/tds/unittests/t0007.c</code> test that your conversion are working. Just add manually the conversions you want to try. <br />
Cfr <a href="https://github.com/FreeTDS/freetds/commit/abcc09c9a88acd0e9a45b46dab3ca44309917a02">commit id abcc09c9a88acd0e9a45b46dab3ca44309917a02</a>.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">parameter. Add type/parameter declaration in <code>tds_get_column_declaration</code> in <code>src/tds/query.c</code>. Also do any necessary step to initialize the parameter to send to server. <br />
Cfr <a href="https://github.com/FreeTDS/freetds/commit/54fdd3233e430c045cf5524ac385770738d9e92c">commit id 54fdd3233e430c045cf5524ac385770738d9e92c</a>, <a href="https://github.com/FreeTDS/freetds/commit/88cfea19d91245372779b8893a2d62b42696cd49">commit id 88cfea19d91245372779b8893a2d62b42696cd49</a>.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">emulated prepared/rpc. If needed handle your type in <code>tds_put_param_as_string</code> in <code>src/tds/query.c</code>. <br />
Cfr <a href="https://github.com/FreeTDS/freetds/commit/017b7bf2fee0f09847e64546d27382d2f2b756f4">commit id 017b7bf2fee0f09847e64546d27382d2f2b756f4</a>.</p>
<p class="endli"></p>
</li>
</ul>
<h1><a class="anchor" id="odbc"></a>
ODBC changes</h1>
<p>ODBC is the most complicated library to add a type to. Usually its data are different from libTDS so you have to add additional code for conversions which are not required by other libraries. </p><ul>
<li>
<p class="startli">type information. Every type in ODBC have related information. These information are set in <code>src/odbc/odbc_data.c</code>. Depending on the changes you did for data in libTDS you should handle the new type. <br />
Cfr <a href="https://github.com/FreeTDS/freetds/commit/71e189e206dc9b6f6513e0aa0e4133a4f8dec110">commit id 71e189e206dc9b6f6513e0aa0e4133a4f8dec110</a>.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">type information test. Related to the previous change there is <code>src/odbc/unittests/describecol.c</code> test. Add a test case for new type. You should attempt to run same test also on proprietary library if possible. <br />
Cfr <a href="https://github.com/FreeTDS/freetds/commit/8a8ec16a6a514a5d6ac66c2470eff51f6a8d4a53">commit id 8a8ec16a6a514a5d6ac66c2470eff51f6a8d4a53</a>.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">conversions from odbc. Define how the ODBC type should convert to the server and implement the conversion. <br />
Cfr <a href="https://github.com/FreeTDS/freetds/commit/29606cbf413c44e49ddfcfb8a93b8a6bd2565a84">commit id 29606cbf413c44e49ddfcfb8a93b8a6bd2565a84</a>, <a href="https://github.com/FreeTDS/freetds/commit/87c84e20a594472a72990b12d4a1451b22e6714b">commit id 87c84e20a594472a72990b12d4a1451b22e6714b</a>.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">conversions to binary. Binary representation in ODBC are usually different from server ones. If so implement the proper conversions. <br />
Cfr <a href="https://github.com/FreeTDS/freetds/commit/56009f35d3e0def339a0c5cb98d006e5e710d523">commit id 56009f35d3e0def339a0c5cb98d006e5e710d523</a>.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">conversions to characters. Same problem for character types. <br />
Cfr <a href="https://github.com/FreeTDS/freetds/commit/25ff091880dabc32f28a73f09bf31c01314aca2f">commit id 25ff091880dabc32f28a73f09bf31c01314aca2f</a>.</p>
<p class="endli"></p>
</li>
<li>
conversion test. You probably want to test ODBC conversions. This can be done changing <code>src/odbc/unittests/data.c</code> test and <code>src/odbc/unittests/genparams.c</code>. <br />
Cfr <a href="https://github.com/FreeTDS/freetds/commit/e69f7d564dac44884f7c5f0106cceafce4af168b">commit id e69f7d564dac44884f7c5f0106cceafce4af168b</a>. </li>
</ul>
<h1><a class="anchor" id="ctlib"></a>
CT-Library changes</h1>
<p>This is quite easy as usual the conversion in libTDS are fine for this library. </p><ul>
<li>
define type in <code><a class="el" href="a00359_source.html">include/cspublic.h</a></code> </li>
<li>
implement conversion in <code>src/ctlib/cs.h</code> </li>
<li>
set corrent conversion from cs types to server in <code>src/ctlib/ct.c</code> </li>
</ul>
<p>Cfr <a href="https://github.com/FreeTDS/freetds/commit/c5e71e5ad4a557038ecedcec457e2531ab02a77b">commit id c5e71e5ad4a557038ecedcec457e2531ab02a77b</a>.</p>
<h1><a class="anchor" id="dblib"></a>
DB-Library changes</h1>
<p>A bit more complicated than CT-Library but not that much. </p><ul>
<li>
add type and binding type to <code><a class="el" href="a00479.html" title="Primary include file for db-lib applications. ">include/sybdb.h</a></code> </li>
<li>
add NULL handling in <code>dbgetnull</code>, <code>dbsetnull</code> and <code>default_null_representation</code> in <code><a class="el" href="a00077.html" title="Main implementation file for db-lib. ">src/dblib/dblib.c</a></code> </li>
<li>
add binding to dbbindtype </li>
<li>
add support for conversion from/to server </li>
<li>
add printable size </li>
<li>
return correct type string </li>
</ul>
<p>Cfr <a href="https://github.com/FreeTDS/freetds/commit/99dd126e0eb248dd3079b2a7cf97437fe3bcd163">commit id 99dd126e0eb248dd3079b2a7cf97437fe3bcd163</a>.</p>
<h1><a class="anchor" id="apps"></a>
Applications changes</h1>
<p>datacopy application requires some changes too to support new types so add them to <code>src/apps/datacopy.c</code>. <br />
Cfr <a href="https://github.com/FreeTDS/freetds/commit/e59c48ac39c76abb036651f8ec238090eef321c9">commit id e59c48ac39c76abb036651f8ec238090eef321c9</a>. </p>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.12
</small></address>
</body>
</html>
