The stor data storage library
C++ version

Marty Olevitch
Laboratory for Experimental Astrophysics
Physics Dept, Washington University in St. Louis
St. Louis, MO 63130 USA
marty-stor@cosray.wustl.edu

Contents

Introduction

The stor data storage library is a C++ class to aid in the storage of data acquired, especially in real-time situations such as saving data from balloon flight or accelerator experiments. Use of this class frees the programmer from dealing with the mechanics of saving the incoming data. After initialization, one simple function call saves data. Other calls can be used to find out how much data has been stored, etc.

Version 2.05 of the stor library has been run under UNIX (Linux) using the GNU C++ compiler.

General notes

Data directory layout

The diagram below shows a representation of the data directory tree. The root of the tree is noted in the diagram by datadir. This directory contains other directories, one for each ``run''. In the diagram, the runs are 5-digit numbers. In general, a new run is started each time your application program starts up. The root directory also contains a file called .stor_cur_run (in the DOS version, this file is called _cur_run) which contains the current run number. The library maintains this file to keep track of the run numbers. Delete it only at the risk of already saved data!

Inside each run directory are one or more data files. The names of these files are represented as 6-digit numbers. The size of each data file is specified by the programmer in the constructor call. When this limit is reached, the library will automatically open the next data file. Typically, a data file will hold many events. 



                    datadir
                       |
                       |
       ----------------------------------
       |      |   |     |     |         |
       |      |   |     |     |         |        <-- run directories
stor_comments | 00000 00001 00002 ... 00057
              |         |
	.stor_cur_run   |
			|
			|
       ---------------------------------------
       |      |   |        |       |         |
       |      |   |        |       |         |    <-- data files
stor_comments | 000000  000001  000002 ... nnnnnn
              |       
         .stor_cur_file

Typical usage

This code fragment illustrates the typical use of the library routines. 

#include <iostream>
#include <string>
#include <stor.hpp>
...
unsigned char dp[DSIZE];
int count;
int ret;
...
    /* initialize stor to save the data in the directory
     * rooted at /data/misc/exp1. Each data file will be
     * a maximum of 100,000 bytes */
    try {
	stor st("/data/misc/exp1", 100000);
    } catch (string e) {
	std::cerr << e << "\n";
	exit(1);
    }

    ...

    while (1) {
	/* read some data from the telemetry (not part of
	 * the stor library! */
	count = read_telemetry_data(dp);
	if (count > 0) {
	    /* save count bytes of data in the current data file */
	    
	    try {
		ret = st.save_data(dp, count);
	    } catch (std::string s) {
		std::cerr << s << "\n";
		exit(1);
	    }

	    switch (ret) {
		case 0:
		    /* okay */
		    break;
		case 1:
		    /* okay and started new data file */
		    cout << "started new file " << st.cur_file() << endl;
		    break;
		default:
		    cerr << "Bad return code " << ret << endl;
		    break;
	    }
	    /* print some statistics */
	    cout << "Total bytes saved: " << st.total_bytes() << endl;
	    cout << "Bytes in current file: " << st.bytes_cur_file() << endl;
	}
    }

Error handling

The routines which may have problems opening files or writing data, etc all throw a std::string as an exception. For example, see the code fragment above.

Comments

Each stor object maintains files of comments. One file is located in the root data directory and another is located in the current run directory. Both have the name ``stor_comments''.

By default, the constructor and destructor both insert a comment into the each file. The default comment can be suppressed by calling the constructor with the third parameter set to ``false''.

Additionally, an application program can insert its own comments using the member function stor::comment.

Reference

Primary routines

You can get by using just the following constructor and the save_data member function.

Status routines

The following routines are not absolutely necessary, but can be useful if you want to know some of the library's internal state.

Utility routines

The following routines are not necessarily needed in ordinary use. However, in special situtaions, they may be useful.