========
Database
========
.. Modified: 2019-10-20/19:06-0400 btiffin
.. Copyright 2016 Brian Tiffin
.. This file is part of the Unicon Programming document
.. GPL 3.0+ :ref:`license`
.. image:: images/unicon.png
:align: center
.. only:: html
:ref:`genindex`
:floatright:`Unicon`
.. index:: database
.. _database:
Unicon databases
================
Unicon supports a couple of different database types.
- DBM
- ODBC
These are optional dependencies during compiler build. DBM requires a DBM
engine, GDBM for instance, and ODBC requires a Open Data Base Connection
layer. A third option is using the native :ref:`table
` datatype (or
other aggregate data structure) to handle memory based database management
.. index:: database; tables
Tables
------
:ref:`table ` data can be an easy way to handle ad-hoc database
problems.
The :ref:`IPL ` entries for ``xencode`` and ``xdecode`` can then be used
to add persistence.
.. literalinclude:: examples/table-db.icn
:language: unicon
:start-after: ##+
.. program-output:: unicon -s table-db.icn -x
:cwd: examples
.. note::
The ``xencode`` and ``xdecode`` procedures come in a couple of
different flavours; as ``link xcode`` or ``link xcodes``. ``xcodes``
makes handling :ref:`record ` definitions a little easier, and
provides for :ref:`file ` and :ref:`procedure `
structures that may not be present in the decoding program. Try and
use ``xcodes`` for most developments.
.. index:: database; dbm, dbm
.. _dbm:
DBM
---
When supported, :ref:`open ` mode "d" (and mode "dr" for read-only) will
open DBM database resources. Once opened, the resource is treated as a
persistent :ref:`table ` datatype. ``datum := dbm[s]`` will retrieve
data for key ``s``, and ``dbm[s] := "some data"`` will attempt to insert or
update the DBM information on disk. ``insert``, ``delete`` and ``fetch``
built-in functions can also be used. *Update and insert are blocked for mode
"dr" read-only data stores*.
.. literalinclude:: examples/dbm.icn
:language: unicon
:start-after: ##+
.. program-output:: unicon -s dbm.icn -x
:cwd: examples
The example above will create ``dbm.dat``, the user visible data file, and
also some internal files; ``dbm.dat.dir`` and ``dbm.dat.pag``.
DBM information is converted to :ref:`string ` form when written to
disk. Unlike memory tables, ``1`` and ``"1"`` are the same key in DBM mode.
Use ``xencode`` (and ``xdecode``) if you need to differentiate between string
and other datatypes for DBM keys and values.
.. index:: database; ODBC, ODBC
.. _ODBC:
ODBC
----
Unicon includes :ref:`SQL ` features, when built with ``ODBC`` support.
Documented in Unicon Technical Report, UTR1,
http://unicon.org/utr/utr1/utr1.htm by Federico Balbi and
:ref:`Clint `.
Requirements
............
- ODBC, ``unixodbc`` package (for instance)
- SQLiteODBC, ``libsqliteodbc`` package (or other ODBC driver)
- datasource definintion, ``~/.odbc.ini``
.. literalinclude:: examples/odbc.icn
:language: unicon
:start-after: ##+
With a ``unicon`` DSN (data source name) configuration of:
.. literalinclude:: examples/odbc.ini
:language: ini
Giving:
.. program-output:: unicon -s odbc.icn -x
:cwd: examples
That same code will work with MariaDB, PostgreSQL, Oracle, or any of the many
other ODBC drivers that are available for most operating systems and database
engines.
.. only:: html
..
--------
:ref:`genindex` | Next: :doc:`networking` | Previous: :doc:`graphics`
|