= Managing DBT Files with PACPUS =

Pacpus framework offers a way to record data through DBT files. This is a binary format with timestamping functionalities. 

== Important notes == 

[=#point1 (1)] For this tutorial we will work with the trunk version of the pacpusframework repository. If you are using a specific tag or branch please change '''''trunk''''' by your specific '''''branch or tag path''''' for each link below. 

[=#point2 (2)] To deal with DBT files you need to link you application with !FileLib library. The source code can be found in [source:trunk/src/FileLib this] folder.

== How to create a new DBT file == 

=== Step 1: identify the type and the structure of the data === 

First you must identify the type of your data in this file [source:trunk/include/Pacpus/kernel/DbiteFileTypes.h DbiteFileTypes.h]. Remember note [#point1 (1)] and modify the path to fit with your installation of pacpusframework. If the type is already known by PACPUS, it is recommended to use it, else you need to create a new entry in this file. 

For example, if you need to add a support BMP images, you can change this code block:

{{{
#!cpp
enum BasicType
{
    FILE_IMAGE = 0
    , FILE_CAN
    , FILE_TEXT
    , FILE_IMAGE3D
    , FILE_DBT_UNKNOWN          ///< Unknown file type
    , FILE_JPEG
    , STREAM8POSITION = 100
};
}}}

in:

{{{
#!cpp
enum BasicType
{
    FILE_IMAGE = 0
    , FILE_CAN
    , FILE_TEXT
    , FILE_IMAGE3D
    , FILE_DBT_UNKNOWN          ///< Unknown file type
    , FILE_JPEG
    , FILE_MYSTRUCT                  ///< New MYSTRUCT file format (remark: the number of the ID will be 6 here) 
    , STREAM8POSITION = 100
};
}}}

''Warning, take care of using a free number in the file.''

After this, you need to create the new structure of your data. It is a just a header file containing the C structure of the data. It is recommended to use standard types like uint32_t, int8_t, ... This types are available via [source:trunk/include/Pacpus/kernel/cstdint.h cstdint.h] file. 

{{{
#!cpp
struct MYSTRUCT {
  uint32_t data1;
  int16_t data2; 
  uint8_t data3;
};
}}}

=== Step 2: creation of DBT file === 

First we create an instance of pacpus::!DbiteFile.

{{{
#!cpp
pacpus::DbiteFile dbtFile_; //!< DBT file.
}}}

After we open the DBT file in writing mode with the open method that takes in parameters: 
 - the name of the DBT file 
 - the management mode of DBT file (WriteMode, ReadMode)
 - the ID of data
 - the size of the data structure

{{{
#!cpp
try {
    dbtFile_.open("my_struct_file.dbt", WriteMode, FILE_MYSTRUCT, sizeof(MYSTRUCT));
} catch (DbiteException & e) {
    cerr << "error opening dbt file: my_struct_file.dbt, " << e.what() << endl;
    return;
}
}}}

The my_struct_file.dbt file will be created in the current path of the application (often it is the folder where you have launched the application !PacpusSensor). 

=== step 3: writing data in DBT file ===

{{{
#!cpp

MYSTRUCT data; 
data.data1 = 22; 
data.data2 = 42; 
data.data3 = 11;

road_time_t time = road_time(); // the timestamp of the data 
road_timerange_t timerange = 0; // if not use, please set the value to 0

try {
   dbtFile_.writeRecord(time, timerange, (char *) &data, sizeof(data));
} catch (DbiteException & e) {
   cerr << "error writing data: " << e.what() << endl;
   return;
}
}}}



=== step 4: closing DBT file === 

At the end of your program don't forget to close correctly the DBT file: 
{{{
#!cpp

dbtFile_.close();

}}}