<!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/html; charset=utf-8" />
<title>Differences from KInterbasDB — FDB 1.1 documentation</title>
<link rel="stylesheet" href="_static/fdbtheme.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '1.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="FDB 1.1 documentation" href="index.html" />
<link rel="next" title="FDB Reference" href="reference.html" />
<link rel="prev" title="Compliance to Python Database API 2.0" href="python-db-api-compliance.html" />
<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Neuton&subset=latin" type="text/css" media="screen" charset="utf-8" />
<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Nobile:regular,italic,bold,bolditalic&subset=latin" type="text/css" media="screen" charset="utf-8" />
<!--[if lte IE 6]>
<link rel="stylesheet" href="_static/ie6.css" type="text/css" media="screen" charset="utf-8" />
<![endif]-->
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="reference.html" title="FDB Reference"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="python-db-api-compliance.html" title="Compliance to Python Database API 2.0"
accesskey="P">previous</a> |</li>
<li><a href="index.html">FDB 1.1 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="differences-from-kinterbasdb">
<h1>Differences from KInterbasDB<a class="headerlink" href="#differences-from-kinterbasdb" title="Permalink to this headline">¶</a></h1>
<div class="section" id="no-need-for-initialization">
<h2>No need for initialization<a class="headerlink" href="#no-need-for-initialization" title="Permalink to this headline">¶</a></h2>
<p>FDB doesn’t support various configurations of automatic type translations like
KDB, so it’s no longer necessary to initialize the driver before any feature is
used.</p>
</div>
<div class="section" id="distributed-transactions">
<h2>Distributed transactions<a class="headerlink" href="#distributed-transactions" title="Permalink to this headline">¶</a></h2>
<p>Support for <a class="reference internal" href="usage-guide.html#distributed-transactions"><em>Distributed Transactions</em></a> works in slightly
differently than in KDB. FDB uses <a class="reference internal" href="reference.html#fdb.ConnectionGroup" title="fdb.ConnectionGroup"><tt class="xref py py-class docutils literal"><span class="pre">ConnectionGroup</span></tt></a> class like KDB with the same
interface, but DT is not bound to main transaction of individual connections managed by group.
That means that <a class="reference internal" href="reference.html#fdb.Cursor" title="fdb.Cursor"><tt class="xref py py-class docutils literal"><span class="pre">Cursor</span></tt></a> instances obtained from <a class="reference internal" href="reference.html#fdb.Connection" title="fdb.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> don’t work in
DT if connection is part of ConnectionGroup, but work normally in connection context.
To get Cursor for specific connection that works in DT, use <a class="reference internal" href="reference.html#fdb.ConnectionGroup.cursor" title="fdb.ConnectionGroup.cursor"><tt class="xref py py-meth docutils literal"><span class="pre">fdb.ConnectionGroup.cursor()</span></tt></a>
method and pass the connection as parameter. We believe that this arrangement is more
logical and flexible than KDB’s way.</p>
<p>Transaction context for cursor objects depends on how cursor is obtained/created:</p>
<ol class="loweralpha simple">
<li><a class="reference internal" href="reference.html#fdb.Connection.cursor" title="fdb.Connection.cursor"><tt class="xref py py-meth docutils literal"><span class="pre">fdb.Connection.cursor()</span></tt></a> - Works in context of “main” transaction for connection.</li>
<li><a class="reference internal" href="reference.html#fdb.Transaction.cursor" title="fdb.Transaction.cursor"><tt class="xref py py-meth docutils literal"><span class="pre">fdb.Transaction.cursor()</span></tt></a> - Works in context of this transaction.</li>
<li><a class="reference internal" href="reference.html#fdb.ConnectionGroup.cursor" title="fdb.ConnectionGroup.cursor"><tt class="xref py py-meth docutils literal"><span class="pre">fdb.ConnectionGroup.cursor()</span></tt></a> - Works in context of Distributed Transaction</li>
</ol>
</div>
<div class="section" id="stream-blobs">
<h2>Stream BLOBs<a class="headerlink" href="#stream-blobs" title="Permalink to this headline">¶</a></h2>
<p>Firebird supports two types of BLOBs, stream and segmented. The database stores
segmented BLOBs in chunks. Each chunk starts with a two byte length indicator
followed by however many bytes of data were passed as a segment. Stream BLOBs
are stored as a continuous array of data bytes with no length indicators included.
Both types of BLOBs could be accessed by the same API functions, but only stream
BLOBs support seek operation (via isc_seek_blob function).</p>
<p>FDB implements stream BLOBs as file-like objects. On input, you can simply pass
any file-like object (only ‘read’ method required) as parameter value for BLOB
column. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">f</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="s">'filename.ext'</span><span class="p">,</span> <span class="s">'rb'</span><span class="p">)</span>
<span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s">'insert into T (MyBLOB) values (?)'</span><span class="p">,[</span><span class="n">f</span><span class="p">])</span>
<span class="n">f</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
<p>On output, stream BLOBs are represented by BlobReader instances on request. To
request streamed access to BLOB, you have to use prepared statement for your query
and call its set_stream_blob(column_name) method. Stream access is not allowed
for cursors because cursors cache prepared statements internally, which would
lead to dangerous situations (BlobReader life-time management) and anomalies
(stream access when it’s not required). Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">p</span> <span class="o">=</span> <span class="n">cursor</span><span class="o">.</span><span class="n">prep</span><span class="p">(</span><span class="s">'select first 1 MyBLOB from T'</span><span class="p">)</span>
<span class="n">p</span><span class="o">.</span><span class="n">set_stream_blob</span><span class="p">(</span><span class="s">'MyBLOB'</span><span class="p">)</span>
<span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">p</span><span class="p">)</span>
<span class="n">row</span> <span class="o">=</span> <span class="n">cur</span><span class="o">.</span><span class="n">fetchone</span><span class="p">()</span>
<span class="n">blob_reader</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
<span class="k">print</span> <span class="n">blob_reader</span><span class="o">.</span><span class="n">readlines</span><span class="p">()</span>
<span class="n">blob_reader</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
<p>Whenever you use stream access to BLOB, FDB opens or creates the underlying BLOB
value as stream one. On input it means that true stream BLOB is created in database,
but on output it depends on how BLOB value was actually created. If BLOB was
created as stream one, you can use the seek method of BlobReader, but if it was
created as regular BLOB, any call to seek will raise an error:</p>
<div class="highlight-python"><pre>SQLCODE: -685
- invalid ARRAY or BLOB operation
- invalid BLOB type for operation</pre>
</div>
<p>You can read BLOBs created as stream ones as fully materialized, and regular ones
in stream mode (without seek) without any problems, and that same apply for
input - you can create values in the same column as stream or regular ones
interchangeably. From your point of view, stream BLOBs are just different
interface to BLOB values, with single exception - BlobReader.seek() will throw
an exception if you’d call it on BLOB value that was not created as stream BLOB.</p>
<p>To work with stream BLOBs, you don’t need to use cursor.set_type_trans_in/out
methods, i.e. calls to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">cur</span><span class="o">.</span><span class="n">set_type_trans_in</span> <span class="p">({</span><span class="s">'BLOB'</span><span class="p">:</span> <span class="p">{</span><span class="s">'mode'</span><span class="p">:</span> <span class="s">'stream'</span><span class="p">}})</span>
<span class="n">cur</span><span class="o">.</span><span class="n">set_type_trans_out</span><span class="p">({</span><span class="s">'BLOB'</span><span class="p">:</span> <span class="p">{</span><span class="s">'mode'</span><span class="p">:</span> <span class="s">'stream'</span><span class="p">}})</span>
</pre></div>
</div>
<p>To write (create) stream BLOB value, simply pass file-like object as parameter
to your INSERT/UPDATE statements where BLOB value is expected. To read BLOB
value as stream, use prepared statement and register interest to get BlobReader
instead fully materialized value via set_stream_blob() calls for each BLOB value
(column name) you want to get this way.</p>
<p><a class="reference internal" href="reference.html#fdb.BlobReader" title="fdb.BlobReader"><tt class="xref py py-class docutils literal"><span class="pre">BlobReader</span></tt></a> supports iteration protocol, and read(), readline(), readlines(),
seek(), tell(), flush() (as noop) and close() methods. It does NOT support chunks()
method of KInterbasDB.BlobReader.</p>
<p>It is not strictly necessary to close BlobReader instances explicitly.
A BlobReader object will be automatically closed by its __del__ method when it
goes out of scope, or when its Connection, PreparedStatement closes,
whichever comes first. However, it is always a better idea to close resources
explicitly (via try...finally) than to rely on artifacts of the Python
implementation. You will also encounter errors if BLOB value was deleted from
database before BlobReader is closed, so the odds that this may happen are higher
if you do not close it explicitly.</p>
</div>
<div class="section" id="services-api">
<h2>Services API<a class="headerlink" href="#services-api" title="Permalink to this headline">¶</a></h2>
<p>Support for Firebird Services was <a class="reference internal" href="usage-guide.html#working-with-services"><em>completelly reworked</em></a> in FDB.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Differences from KInterbasDB</a><ul>
<li><a class="reference internal" href="#no-need-for-initialization">No need for initialization</a></li>
<li><a class="reference internal" href="#distributed-transactions">Distributed transactions</a></li>
<li><a class="reference internal" href="#stream-blobs">Stream BLOBs</a></li>
<li><a class="reference internal" href="#services-api">Services API</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="python-db-api-compliance.html"
title="previous chapter">Compliance to Python Database API 2.0</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="reference.html"
title="next chapter">FDB Reference</a></p>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="reference.html" title="FDB Reference"
>next</a> |</li>
<li class="right" >
<a href="python-db-api-compliance.html" title="Compliance to Python Database API 2.0"
>previous</a> |</li>
<li><a href="index.html">FDB 1.1 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2009-2012, David Rushby, Pavel Cisar.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
