#######
Formats
#######


*********************************************
The OBItools3 Data Management System (OBIDMS)
*********************************************

An OBIDMS directory consists of : 
	* OBIDMS column files
	* OBIDMS release files
	* an OBIDMS history file


OBIDMS column files
===================
 
Each OBIDMS column file contains :
	* a header of a size equal to a multiple of PAGESIZE (PAGESIZE being equal to 4096 bytes 
	  on most systems) containing metadata
	* one column of data of the same type
	
OBIDMS column files are read-only.


File name
---------

Each file is named with the attribute associated to the data it contains, and the number of 
its version, separated by an ``@``, and with the extension ``.odc``.

Example : ``count@3.odc``


Header
------

The header of an OBIDMS column contains :
	
	* Endian byte order
	* PAGESIZE value / Size of the header
	
	* Number of lines (total or without the header?)
	* Data type (int, str...)
	* Date of creation
	* Version of the file
	* Eventual comments


Data
----

A column of data of the same type.


Versioning
----------

OBIDMS column files are read-only, and any modification leads to the creation of a new version 
of the column file. That means that one column is stored in one file (if there is only one version) 
or more (if there are several versions), and that there is one file per version. 

The first version of a column file is numbered 1, and each new version increments that 
number by 1.

The number of the latest version of an OBIDMS column is stored in an `OBIDMS release file <formats.html#obidms-release-files>`_.


Mandatory columns
-----------------

Some columns must exist in an OBIDMS directory :
	* sequence identifiers column


OBIDMS release files
====================
 
Each OBIDMS column is associated with an OBIDMS release file that contains the number of the latest
version of the column. 

File name
---------

OBIDMS release files are named with the attribute associated to the data contained in the column, and 
have the extension ``.odr``.

Example : ``count.odr``


OBIDMS history file
===================

An OBIDMS history file consists of data that can be represented in the form of a directed acyclic 
graph presenting the history of all the operations ever done in the OBIDMS directory.


OBIDMS views
============

An OBIDMS view corresponds to a list of OBIDMS columns and lines. A view includes one version 
of each mandatory column. Only one version of each column is included. All the columns of 
one view contain the same number of lines in the same order.


OBIDMS UML
==========

.. image:: ./images/OBIDMS_UML.png
:download:`html version of the OBIDMS UML file </ObiDMS_UML.class.violet.html>`


OBIIntColumn header file
========================

.. doxygenfile:: obiintcolumn.h