Function: fget_ch()

0 int fget_ch(struct fgetoutput *fgetoutput,struct fgetinput *fgetinput)
This is a general function for sequentially reading one or more channels of FRAME format data. It can be used to obtain either locked sections only, or both locked and unlocked sections, and to retrieve calibration information from the FRAME data. It concatenates multiple frames and multiple files containing frames as necessary, to return continuous-in-time sequences.

The inputs to the routine fget_ch() are contained in a structure:

struct fgetinput {
           int nchan;
           char **chnames;
           int npoint;
           short **locations;
           char *(*files)();
           int (*filedes)();
           int inlock;
           int seek;
           int calibrate;
           char *datatype; 
};

The different elements of the structure are:

nchan: Input. The number of channels that you want to retrieve ($\ge 1$).

chnames: Input. The list of channel names. Each element of chnames[0..nchan-1] is a pointer to a null-terminated string. Note that the number of channels requested, and their names, must not be changed after the first call to fget_ch. It is assumed that the first channel in the list has the fastest sample rate of any of the requested channels. As long as this assumption is satisfied, the channels may be accessed in any order.

npoint: Input. The number of points requested from the first channel. (May change with each call.)

locations: Input. The locations in memory where the arrays corresponding to each channel should be placed are locations[0..nchan-1]. (May change with each call.)

files(): Input. A pointer to a function, which takes no arguments, and returns a pointer to a null-terminated character string. This string is the name of the file to look in for FRAME format data. If no further frames remain in the file, then the function files() is called again. When this function returns a null pointer, it is assumed that no further data remains. A useful utility function called framefiles() has been provided with GRASP, and may be used as this argument. (May change with each call.)

filedes(): Input. This argument is used if and only if the previous argument, fgetinput.files is NULL. If fgetinput.files is not NULL then this argument is not used. This argument is a pointer to a function, which takes no arguments, and returns an integer file descriptor. The integer returned is a file descriptor for a file containing FRAME format data. If no further frames remain in the file, then the function filedes() is called again. When this function returns a negative file descriptor, it is assumed that no further data remains. (May change with each call.)

inlock: Input. Set to zero, return all data; set to non-zero, return only the locked sections of data. If set nonzero, then on output fgetoutput.locklow and fgetoutput.lockhi will be set.

seek: Input. Set to zero, return data. Set to non-zero, seek past the data, performing all normal operations, but do not actually write any data into the arrays pointed to by locations[0..nchan-1]. (May change with each call.) This is useful for skipping rapidly past uninteresting regions of data, for example, the first few minutes after coming into lock.

calibrate: Input. If set non-zero, return calibration information. If set to zero, do not return calibration information. (May change with each call.)

datatype: Output. A character string indicating the data type in each channel. The coding is: C = char, S = short, D = double, F = float, I = int, L = long, f = complex float, d = complex double, s = string, u = unsigned short, i = unsigned int, l = unsigned long, c = unsigned char.

Except as noted above, it is assumed that none of these input arguments are changed after the first call to fget_ch(). It is also assumed that within any given frame, the numbers of points contained in different channels are exact integer multiples or fractions of the numbers of points contained in the other channels.

The outputs from the routine fget_ch() are contained in a structure:

struct fgetoutput {
           double tstart;
           double tstart_gps;
           double srate;
           int *npoint;
           int *ratios;
           int discarded;
           double tfirst;
           double tfirst_gps;
           double dt;
           double lostlock;
           double lostlock_gps;
           double lastlock;
           double lastlock_gps;
           int returnval;
           int frinum;
           float *fri;
           int tcalibrate;
           int tcalibrate_gps;
           int locklow;
           int lockhi;
           char *filename;
           char *slow_names; 
};

The different elements of the structure are:

tstart: Output. Time stamp of the first point output in channel chnames[0]. Note: please see the comments in Section . Units are Unix-C time in seconds defined in Section .

tstart_gps: Output. Same as previous quantity, but with GPS time in seconds.

srate: Output. Sample rate (in Hz) of channel chnames[0].

npoint: Output. The number of points returned in channel chnames[i] is npoint[i]. Note that npoint[0] is precisely the number of points requested in the input structure fgetinput.npoint.

ratios: Output. The sample rate of channel chnames[0] divided by the sample rate of channel chnames[i] is given in ratios[i]. Thus ratios[0]=1.

discarded: The number of points discarded from channel chnames[0]. These points are discarded because there is a missing period of time between two consecutive frames, or because the instrument was not in lock for long enough to return the requested number of points (or for both reasons).

tfirst: Output. The time stamp of the first point returned in the first call to fget_ch(). Units are Unix-C time in seconds defined in Section .

tfirst_gps: Output. Same as previous quantity, but with GPS time in seconds.

dt: Output. By definition, tstart-tfirst, which is the elapsed time since the first time stamp.

lostlock: Output. The time at which we last lost lock (if searching only for locked segments). Units are Unix-C time in seconds defined in Section .

lostlock_gps: Output. Same as previous quantity, but with GPS time in seconds.

lastlock: Output. The time at which we last regained lock (if searching only for locked segments). Units are Unix-C time in seconds defined in Section .

lastlock_gps: Output. Same as previous quantity, but with GPS time in seconds.

returnval: Output. The return value of fget_ch(): 0 if it is unable to satisfy the request, 1 if the request has been satisfied by beginning a new locked or continuous-in-time section, and 2 if the data returned is part of an ongoing locked or continuous-in-time sequence.

frinum: Output. Three times the number of frequency values for which we are returning static calibration information. If this number is not divisible by three, something is wrong!

fri: Output. A pointer to the array of calibration data. This data is arranged with a frequency, then the real part, then the imaginary part of the response, followed by another frequency, then real part, then imaginary part, etc. So fri[0]=$f_0$, fri[1]=$r_0$, fri[2]=$i_0$, fri[3]=$f_1$, fri[4]=$r_1$, fri[5]=$i_1$,... and the total length of the array is fri[0..frinum-1].

tcalibrate: Output. The time at which the current calibration information became valid. Units are Unix-C time in seconds defined in Section .

tcalibrate_gps: Output. Same as previous quantity, but with GPS time in seconds.

locklow. Output. The minimum value (inclusive) for "in-lock" in the lock channel. Set if and only if fgetinput.inlock is nonzero.

lockhi. Output. The maximum value (inclusive) for "in-lock" in the lock channel. Set if and only if fgetinput.inlock is nonzero.

filename. Output. Points to a static character string containing the name of the frame file currently in use, or NULL is there is no frame file open.

slow_names. Output. Names of the slow channels packed into one fast channel ``SLOW''.

Note that the time-stamps available in two different formats: Unix-C time in seconds and GPS time in seconds. The relationship between these is described in detail in Section . In general, in new code the GPS time stamps should be used, and taken as the more fundamental quantity. The Unix-C time is the number of seconds after 00:00:00 Jan 1, 1970 UTC. This is also known as ``Calendar Time" on Unix systems. It is the quantity returned by the Standard C-library function time(). Note that starting with versions of the Frame library greater than 3.23, the time stored in the frames is GPS time, which is (roughly - up to leap seconds) defined as the Unix-C time minus $315964811$ (this value may be found in the defined constant UTCTOGMT in the grasp.h header file. The origin of GPS time is 00:00:00 January 6, 1980 UTC, which was

$$\begin{eqnarray*} 315964811 \ {\rm sec} &= & 3600 {\rm\ sec/hour} \times 24 {\rm... ...mes 2 {\rm\ years}+ 5 {\rm\ days}) \& & + 11 {\rm\ leap\ sec} \end{eqnarray*}$$

after 00:00:00 Jan 1, 1970 UTC.

This routine is a useful interface to the FRAME library. It reads frames from files. To get the name of the first file to open, this routine calls the function files() specified in the input structure. Then, whenever there are no remaining frames in this file, it calls files() again. This function must return the name of the desired file, or NULL if no files remain. For example:

static char *filelist[]={
"C1-94_11_19_23_50_46", "C1-94_11_19_23_53_28",
"C1-94_11_19_23_56_10", "C1-94_11_19_23_58_52",
"C1-94_11_20_00_01_34", "C1-94_11_20_00_04_16" };

char *files() {
     static int entry=0;
     if (entry>=6)
          return NULL;
     else
          return filelist[entry++];
}

or the exact same fragment of code, but with:

static char *filelist[]={
"C1-468915467.F","C1-468915629.F","C1-468915791.F",
"C1-468915953.F","C1-468916115.F","C1-468916278.F" };

The difference between the labeling of the frame files here is that in the first instance (early versions of the frame library) the files are assumed to be labeled by the UTC time in ``human-readable" form, and in the latter case they are assumed to be labeled by the GPS time in seconds. Further details may be found in Section  and Section .

The function fget_ch() returns 0 if it is unable to satisfy the request for fgetinput.npoint points. It returns 1 if the request has been satisfied, and it is beginning a new locked section (or if the frames were not contiguous in time, and it is beginning with a new frame). It returns 2 if the data returned is part of an ongoing locked or continuous sequence.

When several channels are requested, and they have different sample rates, the first channel requested must always have the fastest sample rate. Other requested channels may have this same sample rate, but none may have a faster sample rate. Points are returned from the slower channels if and only if they satisfy the following condition. Suppose that $r$ is the ratio of the channel 0 sample rate to the channel K sample rate, and label the points in channel 0 by $i=0,\cdots,n r - 1$, and the points in channel K by $j=0,\cdots,n-1$. Then point $j$ in channel K is returned if and only if point $i=rj$ is returned from channel 0.

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

Comments: None.