Das2 Stream Utilities 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:

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:

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 find 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/das2.h>

in your application source files will define all the needed data structures.

Linking is handled by command line options similar to:

   -L /YOUR/LIB/INSTALL/PATH -l das2            // GCC
   /LIBPATH C:\YOUR\LIB\INSTALL\PATH das2.lib   // link.exe

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

 All Data Structures Files Functions Variables Typedefs Enumerations Defines

Generated on 11 Sep 2016 for Das2 Stream Utilities by  doxygen 1.6.1