libdas2 Documentation

Das2 Streams are a self-describing, streamable format that allows for the transmission of large and complex data sets between different systems and programming environments. A precise description of the Das Stream specification 2.2 is found elsewhere in the Das2 Interface Reference at http://www-pw.physics.uiowa.edu/das2.

This library of C functions provides utilities for more easily producing Das2 Streams that are correctly formatted and will be compatible with future versions of the Das2 Stream specification.

Writing Streams

A Das2 Stream is created by first opening the stream and getting a handle to it, then calling functions of this library that create and send out the various entities that live in Das2 Streams. There are functions for creating a packetDescriptor and then specifying what data will be in each packet, functions for populating the fields of the packet and sending out the packet onto the stream. Also there are functions for indicating progress and sending out messages on the stream for human consumption. The top level stream writing functions are defined in output.h.

Here is an illustration of a typical use of the library:

• Declare an output DasIO structure using new_DasIO_file() or new_DasIO_cfile().
• Call new_StreamDesc() to create a StreamDesc structure.
• Set global properties of the stream with the various DasDesc functions such as Desc_setPropString() and similar calls
• Write out the stream descriptor using DasIO_writeStreamDesc()
• Call new_PktDesc() to create a type of packet that will be found on the stream. Attach it to the stream using StreamDesc_addPktDesc()
• Create the data planes for the packet using new_PlaneDesc() and new_PlaneDesc_yscan(). Attach them to the packet using PktDesc_addPlane().
• Set extra properties such as labels for the data planes using DasDesc_setString() and similar functions.
• Call DasIO_writePktDesc() to send the packet descriptor out onto the stream.
• While reading through the records of input data do the following:
  • Call PlaneDesc_setValue() current values for each plane such as the current time and amplitudes.
  • Call DasIO_writePktData() to encode and output the current plane values
• close the stream using DasIO_close()

Reading Streams

A Das2 Stream is consumed by defining a set of callback functions that are invoked as the stream is read. Once the functions are set, program control is handed over to the library, and the callbacks are invoked until the entire stream is read. The top level stream reading functions are defined in input.h.

Here is an illustration of a typical use of the library to read a stream:

1. Declare an input DasIO structure using new_DasIO_file() or new_DasIO_cfile().
2. Declare a callback function of type StreamDescHandler to be triggered when a new das2 stream header is read in.
3. Declare a callback function of type PktDescHandler for handling packet headers.
4. Declare a callback function of type PktDataHandler for handling the incoming data packets.
5. Optionally declare functions for handling comments and exceptions. Often these are simply forwarded onto the output stream.
6. Fill out a StreamHandler structure to tie together your callbacks. If your callback functions need to maintain non-global state information use the StreamHandler::userData pointer to address a structure of your own design.
7. Call DasIO_readAll() to have the library read in the stream.
8. Exit after the DasIO_readAll() is completed.

Example Program

The program:

@b das2_bin_avg.c 

is a small filter for averaging Das2 Stream data into fixed size bins. Since it has to handle both input and output and does some minimal data processing, this short program provides a good example of using this library to read and write Das2 streams.

Compiling and Linking

There are about a half-dozen or so library headers, but you don't need to worry about finding the right ones if you don't want to. A roll-up header is included with the library that will grab all definitions. So including the header:

*    #include <das2/core.h>
* 

in your application source files will define everything you need.

Linking is handled by command line options similar to:

*   -L /YOUR/LIB/INSTALL/PATH -ldas2 -lexpat -lpthread -lz -lm // GCC
*   /LIBPATH C:\YOUR\LIB\INSTALL\PATH das2.lib expat.lib libz.lib // link.exe
* 

The exact details depend on your C tool-chain and installation locations.