Data File Format

This document describes the format of the spectrometer data file.

Overall structure

The data file is a binary file written as a number of discrete sections. Various definitions and functions for writing and reading these sections are found in the files "file_utils.c" and "file_utils.h".

Each section begins with a leader which consists of 2 longs:

  1. the number of bytes in the contents to follow,
  2. the section type as specified in "file_utils.h": 
    #define TIME_SECTION                    0
#define SYMBOL_TABLE_SECTION            1
#define PULSE_PROGRAM_SECTION           2
#define COMMENTS_SECTION                3
#define GLOBAL_SYMBOLS_SECTION          4
#define DATA_SECTION                    5
#define TERMINATION_STATUS_SECTION      6
The data file has the following structure:

The order of the sections is arbitrary.

Section formats

The pulse program attempts to include each section, writing a leader and then writing the contents in the following formats:
time
The current time is obtained using the system time() command. It is of type: time_t (=long). See the time(2) man page for further details.

symbol table
The symbol table contains names and values of user-defined pulse program variables. The ascii file "symbols.sym" is included verbatim into the data file.

pulse program
The pulse program name is obtained as argv[0] upon execution of the pulse program. The file obtained after appending ".c" is copied verbatim into the data file.

comments
The ascii file "comments.file" is included verbatim into the data file.

global symbols
The global symbol table contains pre-defined names and is uniform across user-written pulse programs. The contents must be filled in explicitly by the pulse program. Global symbols which are not used are initialized to zero.

The global symbols are found in a structure defined in "file_utils.h": 

typedef struct global_symbols_tag {
        double sw;
        double sf1;
        double sf2;
        double sf3;
        double size;
        double scans;
        double experiment;
} GLOBAL_SYMBOLS;
This structure is written into the data file.

data
The data are written as a series of data points as defined in "data_packet.h": 
typedef struct FID_point_tag {
        long int        real, imag;
} FID_POINT;
Pulse programs with multiple data sets will concatenate several data sections. Each data set will have its own leader:

termination status
The termination status is defined in "data_packet.h" and is one of: 
#define RUNNING         0x00
#define HALTED          0x01
#define ABORTED         0x02
#define ERROR           0x03
The termination status is of type: unsigned long.

Reading data files

Simple functions are available in "file_utils.c" to write out ascii versions of the data file sections.

A program which uses them is: 

/*
 * file_reader.c
 *
 * A test program for file support utilities.
 */

#include "file_utils.h"
#include "pulse.h"      /* Global variable "data_file" is here */

FILE * data_file;

void main( int argc, char *argv[] )
{
        if ((data_file = fopen("Out_File", "rb")) == NULL)
                fprintf(stderr,"\nCould not open Out_File.\n");

        while (1) { read_section( ); }

        fclose( data_file );
}
Additional functions which convert the contents of the data file to a particular format can be based on those found in "file_utils.c".

Jonathan Callahan