Function: read_block()

0 int read_block(FILE *fp,short **here,int *n,float *tstart,float *srate,int allocate,int *nalloc,int seek, struct ld_binheader* bh,struct ld_mainheader* mh)
This function efficiently reads one block of data from one of the channel.* data files, operating in sequential (not random) access. On first entry, it detects the byte-ordering of the machine that it is running on, and swaps the byte order if the machine is ``little-endian" (the data was originally written in ``big-endian" format, and is distributed that way). It will also print a comment (on first entry) if the machine is not big-endian.

The arguments are:

fp: Input. A pointer to the channel.* file being read.

here: Input/Output. A pointer to an array of shorts, which is where the data will be found when read_block() returns. If allocate=0, then this pointer is input. If allocate is non-zero, then this pointer is output.

n: Output. A pointer to an integer, which is the number of data items read from the block, and written to *here. These data items are typically short integers, so the number of bytes output is twice *n.

tstart: Output. The time stamp (elapsed time since beginning of the run) at the start of the data block. Taken from the binary header.

srate: Output. The sample rate, in Hz, taken from the binary header.

allocate: Input. The read_block() function will place the data that it has read in a user defined array if allocate is zero. If allocate is set, it will use malloc() to allocate a block of memory, and set *here to point to that block of memory. Further calls to read_block() will then use calls to realloc() if necessary to re-allocate the size of the block of memory, to accommodate additional data points. Note that in either case, read_block() puts into the array only the data from the next block; it over-writes any existing data in memory.

nalloc: Input/Output. If allocate is zero, then this is used to tell read_block() the size (in shorts) of the array *here. An error message will be generated by read_block() if this array is too small to accommodate the data. If allocate is nonzero, then this integer is set (and reset, if needed) to the number of array entries allocated by malloc()/realloc(). In this case, be sure that *nalloc is zero before the first call to read_block(), or the function will think that it has already allocated memory!

seek: Input. If seek is set to zero, then the function reads data. If seek is set nonzero, then read_block() does not copy any data into *here. Instead it simply skips over the actual data.

bh: Output. A pointer to the binary header structure defined above.

mh: Output. A pointer to the main header structure defined above.

This is a low-level function, which reads a block of data. It is designed to either write the data into a user-defined array or block of memory, if allocate is off, or to allocate the memory itself. In the latter mode, the function uses nalloc to track the amount of memory allocated, and reallocates if necessary. It is often useful to be able to quickly skip over sections of data (for example, just after the interferometer locks, a few minutes is needed for the violin modes to damp down). Or if the IFO is out of lock, one needs to quickly read ahead to the next locked section. If seek is set, then this routine behaves exactly as it would in normal (read) mode but does not copy any data.

The function read_block() returns the number of data items that will be returned on the next call to read_block(). It returns -1 if it has just read the final block of data (implying that the next call will return 0). It returns 0 if it can not read any further data, because none remains.

Note that if the user has set allocate, then the read_block() will allocate memory using malloc()/realloc(). It is the users responsibility to free this block of memory when it is no longer needed, using free().

Author: Bruce Allen, ballen@dirac.phys.uwm.edu

Comments: This function was designed for variable-length blocks. It might be possible to simplify it for fixed-length block sizes.