READ_DATREC_386_V1_1 READ_DATREC_386_V1_3 READ_DATREC_DG READ_PARMREC READ_PARMREC_386_V1_1 READ_PARMREC_386_V1_3 READ_PARMREC_DG FIND_DATREC
The FORTRAN routine read_datrec will continue to exist BUT the calling sequence for this routine has changed (see below).
It is no longer possible for the user to open the fitfiles himself. The user must call the routine fitropen.f to open a fit file.
It is no longer necessary to call the routine find_datrec before issuing your first read operation. If you want to start reading a file at some arbitrary time, you must now use the routine find_fit_rec instead of find_datrec.
The new routines:
All of the new routines except the new version of read_datrec are written in C. Note that in some cases this means that when using FORTRAN you will have to use calling sequences that make use of the %val mechanism to transfer and actual value instead of the address of the value. This mechanism is supported by the VAX/VMS FORTRAN compiler and most of the UNIX compilers (use the options -e -es).
headers: When writing new programs in C, you should include the following header (.h) files:
C calling sequence: FIT_FILE *fileptr; /* declare fileptr to be a pointer to a FIT_FILE */ FIT_FILE *fitropen(); /* declare the function that opens the file */ fileptr = fitropen( fname ) /* fname must be a character string giving the name of the file */ FORTRAN calling sequence: integer*4 fileptr, fitropen !declare the file pointer variable and function character*80 filename logical*1 fname(80) equivalence (filename, fname) filelptr = fitropen(fname)NOTE: You should not specify the extension .FIT in the filename. You may include the directory for the file. If no directory is included the routine will search a predefined list of directories in order. The directories must be specified by a logical name (on VMS machines) or an environment variable (on UNIX machines). This logical name (environment variable) must have the name SD_FITROPEN_PATH. Any number of directories can be included in this path list. UNIX (Korn Shell) example:
In this example the first directory is /radar/project/data, the second directory checked is /scratch, and the third is the current directory (the dot).
If the routine successfully opens the file it will return the address of a structure containing all the information the read routines need to read the file. If the open fails, the returned value will be 0.
If the routine successfully opens the file, it will read the header record, and output the contents of the header to your terminal (or standard output device in UNIX).
C calling sequence: int iostat; struct FIT_DATA fd; iostat = read_fit(fileptr, &fd);Although it is possible to call this routine from FORTRAN, it is probably easier to use the FORTRAN routine read_datrec. It will then make the call to read_fit for you and return the data in the common block /procdat/. This common block has the same structure as in previous versions of the FORTRAN software. Note, however, that using this method is slightly more time consuming, since an extra transfer of data is required to move the data from the structure returned by the C routine to the FORTRAN common block.
C calling sequence: FIT_FILE *fp; long int ret_code, time_req, time_found; long int find_fit_rec(); ret_code = find_fit_rec(fp, time_req, &time_found); FORTRAN calling sequence: integer*4 ret_code, time_req, time_found, find_fit_rec, fp ret_code=find_fit_rec(%val(fp),%val(time_req),time_found)NOTE: in the C calling sequence, the third argument must be a pointer. In the FORTRAN calling sequence the first two arguments must be passed by value.
NOTE: The mnemonics for the return values are defined in the header file fit_errno.h. The values that are returned are:
FORTRAN calling sequence:
include raddat386_1_3.inc integer*4 ret_code, file_ptr, read_datrec file_ptr = fitropen(filename) ret_code = read_datrec(file_ptr)A return code of 1 indicates a successful read.
The routines _makepath and _splitpathare used to set up the full path to a data file. The path name on UNIX systems is significantly different from VMS, and the VMS and UNIX versions of these routine are quite different. If these routines are ported into the MS-DOS/WINDOWS environment, a special version of these routines (and fitropen) will have to be written to make use of the DOS path names .
struct FIT_DATA {
long rec_time;
struct radops_parms p;
short int PULSE_PATTERN[PULSE_PAT_LEN];
short int LAG_TABLE[2][LAG_TAB_LEN];
char COMBF[COMBF_SIZE];
double noise_lev;
double noise_lag0;
double noise_vel;
double pwr_lag0[MAX_RANGE];
short int slist[MAX_RANGE];
short int nsel;
long qflag[MAX_RANGE];
double pwr_l[MAX_RANGE];
double pwr_l_err[MAX_RANGE];
double pwr_s[MAX_RANGE];
double pwr_s_err[MAX_RANGE];
double vel[MAX_RANGE];
double vel_err[MAX_RANGE];
double width_l[MAX_RANGE];
double width_l_err[MAX_RANGE];
double width_s[MAX_RANGE];
double width_s_err[MAX_RANGE];
double stnd_dev_l[MAX_RANGE];
double stnd_dev_s[MAX_RANGE];
double stnd_dev_phi[MAX_RANGE];
short int gscat[MAX_RANGE];
long x_qflag[MAX_RANGE];
double x_pwr_l[MAX_RANGE];
double x_pwr_l_err[MAX_RANGE];
double x_pwr_s[MAX_RANGE];
double x_pwr_s_err[MAX_RANGE];
double x_vel[MAX_RANGE];
double x_vel_err[MAX_RANGE];
double x_width_l[MAX_RANGE];
double x_width_l_err[MAX_RANGE];
double x_width_s[MAX_RANGE];
double x_width_s_err[MAX_RANGE];
double phi0[MAX_RANGE];
double phi0_err[MAX_RANGE];
double elev[MAX_RANGE];
double elev_low[MAX_RANGE];
double elev_high[MAX_RANGE];
double x_stnd_dev_l[MAX_RANGE];
double x_stnd_dev_s[MAX_RANGE];
double x_stnd_dev_phi[MAX_RANGE];
short int num_lags[MAX_RANGE];
};
rec_time
is the start time of the data in this record. It is given in the
standard SuperDARN format, seconds from the beginning of the year.
The structure radops_parms p is defined below. The array pwr_lag0 gives the power at lag 0 in each ACF. The value is given in dB with respect to the noise level defined by the value of noise_lev.
qflag is an array that defines the quality of the fit for each ACF. A 1 is a good fit. any other value indicates that the fitting process failed.
Two types of fits to the power are used, an exponential decay (lambda fit) and a Gaussian decay (sigma fit). All the parameters that are determined from the exponential fit are indicated by the string _l, while all those determined from the Gaussian fit are indicated by the string _s.
The power level is indicated by the variables pwr_l and pwr_s.
The spectral widths are indicated by the variables width_l and width_s.
The mean Doppler velocity is indicated by the variable vel (which is the same for both the exponential and Gaussian models).
If cross correlalations were being performed, the variables that start with x_ indicate the same things as their ACF counterparts, but with the fit performed on the cross correlation function (XCF) instead of the autocorrelation function.
In addition to the XCF values of power, width and velocity, the XCF data also determines the lag0 phase ( phi0 ) and associated with that value, the elevation angle ( elev ).
Every value has an associated error estimate indicated by the name of the variable with _err appended. There is one exception to this rule: because the error on the elevation angle is not a linear function of the error in phi0, the estimated 1-sigma error bars on the elevation are given by elev_low and elev_high. Note also that since the elevation angle can be aliased, it is possible for elev_low to be near the maximum of the elevation angle and be greater than elev itself. Similarly, elev_high can be near the minimum elevation angle and less than elev.
The parameter structure is defined by:
struct radops_parms
{
/* The first set of parameters are set by the RADOPS system */
/* There are a total of 24 words (16 bit) in the system parameter list */
struct
{
char MAJOR,MINOR;
} REV;/* REV.MAJOR is the major revision #, REV.MINOR is the minor # */
short int
NPARM, /* the total number of 16-bit words in the parameter block */
ST_ID, /* station ID code */
YEAR, /* date and start time of the record. Year=19xx */
MONTH,
DAY,
HOUR,
MINUT,
SEC,
TXPOW, /* transmitted power (kW) */
NAVE, /* number of times the pulse sequence was transmitted */
ATTEN, /* attenuation setting of the receiver (0-3) */
LAGFR, /* the lag to the first range (microsecs) (see note 2 below) */
SMSEP, /* the sample separation (microsecs) (see note 2) */
ERCOD, /* error flag (see error definitions) */
AGC_STAT, /* AGC status word */
LOPWR_STAT, /* Low power status word */
radops_sys_resS; /* reserved for future use */
long
NOISE, /* the noise level determined during the clear freq. search */
radops_sys_resL[2]; /* reserved for future use */
/* The second set of parameters are set by the user */
/* These parameters can either be set manually or by a RADLANG program */
/* There are a total of 24 words in this parameter list */
short int
INTT, /* the integration period */
TXPL, /* the pulse length (in micro seconds) */
MPINC, /* the basic lag separation (in microseconds) */
MPPUL, /* the number of pulses in the pulse pattern */
MPLGS, /* the number of lags in the pulse pattern (see note 1 below)
*/
NRANG, /* the number of range gates */
FRANG, /* the distance to the first range (see note 2 below) */
RSEP, /* the range separation (in km) */
BMNUM, /* beam number */
XCF, /* flag indicating if cross-correlations were being done */
TFREQ, /* the transmitted frequency (in KHz) */
SCAN; /* flag indicating the scan mode */
long
MXPWR, /* Maximum power allowed (see note 3) */
LVMAX; /* Maximum noise level allowed (see note 3) */
/* user defined variables */
long
usr_resL1,
usr_resL2;
short int
CP,
usr_resS1,
usr_resS2,
usr_resS3;
};
/* The total length of the parameter block is 48 words */
/* This does not include the length of the comment buffer,
the pulse table and the lag table */
/* ---------------------- NOTES ------------------------------ */
/*
1. The number of lags in the pulse pattern is the true number of
lags which are present in the table LAG_TABLE. It is NOT the
value of the maximum lag. If the maximum lag is 33 but only
22 out of the 33 lags are actually calculated then MPLGS is 22.
2. The user set the first range gate by specifying FRANG in km.
The system uses this value to set the lag to the first range
in microseconds.
Similarly, the user sets the range separation by specifying RSEP
in km. The system uses this value to set SMSEP in terms of microsecs.
3. During the gain setting routine, the system will attempt to add
enough attenuation so that the maximum reflected power is less than
MXPWR. If this is not possible, the system will set the error code
(ERCOD) to indicate the receiver overload condition.
During the clear frequency search, the system will find the clearest
frequency in the range specified. The Noise level determined for
that frequency will be stored in the parameter NOISE. If NOISE is
greater than LVMAX, the error code will be set to indicate the
no clear frequency condition.
*/
c RADDAT386.INC
c
c This include file defines the structure of the FIT data files
c and the resulting values that are created by READ_DATREC.
c This version is used with data files created by RADOPS386
c The version for use with the old Data General FIT files is
c RADDAT.INC
c
c Note that this file requires the structure /radops_parms/ which
c is defined in the include file, "RADOPS.PAR". Therefore, any
c program which uses this include file must also have the line
c include 'radops.par' BEFORE this file is included.
c
cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc
c
c The following parameters define the size of the pulse table and the
c lag table. In version 1.02 of FITACF these tables were set to 7
c and 17. In version 1.03 they are set to 16 and 48.
c
INTEGER*2 PULSE_PAT_LEN, LAG_TAB_LEN
parameter (PULSE_PAT_LEN = 16, LAG_TAB_LEN = 48)
c
c the following arrays are for the values returned from fitting
c the ACFs
c
integer*2 gscat(75)
integer*4 qflag(75)
real*4 pwr_l(75),pwr_l_err(75),pwr_s(75),pwr_s_err(75),
$ omega(75),omega_err(75),lamda(75),lamda_err(75),
% sigma(75),sigma_err(75),
& stnd_dev_l(75),stnd_dev_s(75),stnd_dev_phi(75)
real*4 vel(75),vel_err(75),width_l(75),width_l_err(75),
%
width_s(75),width_s_err(75),elev(75),elev_low(75),elev_high(75)
c
c the values prefixed with x_ are the values returned or calculated
c from the fit to the XCFs
c
integer*4 x_qflag(75)
real*4 x_pwr_l(75),x_pwr_l_err(75),x_pwr_s(75),x_pwr_s_err(75),
$
x_omega(75),x_omega_err(75),x_lamda(75),x_lamda_err(75),
% x_sigma(75),x_sigma_err(75),phi0(75),phi0_err(75),
& x_stnd_dev_l(75),x_stnd_dev_s(75),x_stnd_dev_phi(75)
real*4 x_vel(75),x_vel_err(75),x_width_l(75),x_width_l_err(75),
% x_width_s(75),x_width_s_err(75)
real*4 pwr_lag0(75),noise_lev,noise_lag0,noise_vel
integer*2 slist(75),num_lags(75),parm_list(70)
integer*4 rec_time
record /radops_parms/parms386
c
c The values for the ACF and the XCF data as well as lag0 power, etc
c are all placed into the common block /procdat/
c
c name type comment
c_____________________________________________________________________
c rec_time I4 time in seconds (from cnv$mdhms_sec)
c parms386 struct parameter list
c noise_lev R4 in A-to-D converter units
c noise_lag0 R4 the noise subtracted from lag0 pwr
c noise_vel R4 velocity found from the noise ACF
c pwr_lag0(75) R4 lag-0 power in dB
c slist(75) I2 range selection list
c qflag(75) I4 ACF quality flag (see below)
c pwr_l(75) R4 fitted power from lamda fit in dB
c pwr_l_err(75) R4 error in fitted power from lamda fit
c pwr_s(75) R4 fitted power from sigma fit in dB
c pwr_s_err(75) R4 error in fitted power from sigma fit
c vel(75) R4 velocity in m/s
c vel_err(75) R4 error in velocity
c width_l(75) R4 spectral width from lamda fit (m/s)
c width_l_err(75) R4 error in spectral width (lamda)
c width_s(75) R4 spectral width from sigma fit (m/s)
c width_s_err(75) R4 error in spectral width (sigma)
c stnd_dev_l(75) R4 Standard deviation of points from the lamda fit
c stnd_dev_s(75) R4 Standard deviation of points from the sigma fit
c stnd_dev_phi(75)R4 Standard deviation of points from the phase fit
c gscat(75) I2 logical*2: true if ACF is ground scatter
c x_qflag(75) I4 quality flag for XCF fit
c x_pwr_l(75) R4 fitted power of XCF (lamda fit) in dB
c x_pwr_l_err(75) R4 error in x_pwr_l
c x_pwr_s(75) R4 fitted power of XCF (sigma fit) in dB
c x_pwr_s_err(75) R4 error in x_pwr_s
c x_vel(75) R4 velocity from XCF fit (m/s)
c x_vel_err(75) R4 error in x_vel
c x_width_l(75) R4 width of XCF spectrum (lamda fit) (m/s)
c x_width_l_err(75) R4 error in x_width_l
c x_width_s(75) R4 width of XCF spectrum (sigma fit) (m/s)
c x_width_s_err(75) R4 error in x_width_s
c phi0(75) R4 XCF phase at lag0 (-180 to +180 degrees)
c phi0_err(75) R4 error in phi0
c elev(75) R4 elevation angle corresponding to phi0 (degrees)
c elev_low(75) R4 elevation angle low limit (from phi0_err)
c elev_high(75) R4 elevation angle high limit
c num_lags(75) I2 number of good lags for each fit
c
c The quality flags (qflag and x_qflag) have the following definitions:
c qflag value meaning
c -------------------------
c 0 no ACF or XCF done for this range
c 1 good ACF (or XCF)
c 2 bad ACF, lag0 power < noise level
c 4 bac ACF, insufficient number of good lags for a fit
c 8 bad ACF, bad data results in division by 0
c 16 bad ACF, oscillating value of omega
c 32 bad ACF, too many iterations to get omega
c
c NOTE: in a logical IF test in FORTRAN on a VAX, only the "good ACF"
c will test TRUE. all the other values of the quality flag will test
c FALSE.
c
c NOTE: for RADOPS386, only "good" values of qflag will occur since
c failures are not saved on the optical disk
c
common /procdat/rec_time,parm_list,noise_lev,noise_lag0,noise_vel,
@ pwr_lag0,slist,qflag,pwr_l,pwr_l_err,pwr_s,pwr_s_err,vel,vel_err,
# width_l,width_l_err,width_s,width_s_err,stnd_dev_l,stnd_dev_s,
$ stnd_dev_phi,gscat,x_qflag,x_pwr_l,x_pwr_l_err,x_pwr_s,x_pwr_s_err,
% x_vel,x_vel_err,x_width_l,x_width_l_err,x_width_s,x_width_s_err,
^ phi0,phi0_err,elev,elev_low,elev_high,x_stnd_dev_l,x_stnd_dev_s,
@ x_stnd_dev_phi,parms386,num_lags
c
c Note that the radops386 structure /radops_parms/ is used by the
c variable, 'parms386', which is also saved in the common block.
c
The parameter structure is defined in the file radops.par:
c
c This file contains the definitions of the radar operating parameters
c It is designed to be compatible with the orignal RADOPS Version 5
c parameter list (with Version 6 modifications), but at the same time
c provide the additional functions of RADOPS386 Version 1
c
c The RADOPS386 parameter structure is defined as a FORTRAN STRUCTURE
c with the name /radops_parms/. All new programs, and major revisions
c of old programs should utilize the new structure variables rather
c than the original parameter definitions
c
INTEGER*2
& PARMS(0:69), NPARM, YEAR, MONTH, DAY, HOUR, MINUT,
& SEC, INTT, NAVE, FMHZ, FKHZ, TXPOW, TXPL, MPINC,
& MPPUL, MPLGS, NRANG, LAGFR, SMSEP, BMNUM, MXPWR,
& ATTEN, MODE, DPARM, LVMAX, ERCOD, NOISE, XCF, NCHAR,
& COMBF(40),rsep,frang,tfreq
BYTE
& NSEL, NREQ, SEL(2), TXST(2), TXDB, ST_ID, combyts(80)
integer*4 noise4, mxpwr4, lvmax4
integer*2 pulse_pattern(16), lag_table(48,2)
EQUIVALENCE
! BYTE VARIABLES
& (NREQ, SEL(1)), !no. ranges requested
& (NSEL, SEL(2)), !no. ranges selected
& (TXDB, TXST(1)), !transmitted power (dB)
& (ST_ID, TXST(2)), !station ID number
& (combyts, combf),
! INTEGER VARIABLES
& (NPARM, PARMS(0) ), !number of words in parms
& (YEAR, PARMS(1) ), !date and time parameters
& (MONTH, PARMS(2) ),
& (DAY, PARMS(3) ),
& (HOUR, PARMS(4) ),
& (MINUT, PARMS(5) ),
& (SEC, PARMS(6) ),
& (INTT, PARMS(7) ), !integration time
& (NAVE, PARMS(8) ), !no. pts. in lag0 average
& (FMHZ, PARMS(9) ), !freq. (MHz part)
& (FKHZ, PARMS(10)), !freq, (KHz part)
& (TXPOW, PARMS(11)), !transmitted power
& (TXST, TXPOW), !(for byte variables)
& (TXPL, PARMS(12)), !pulse length (microsec)
& (MPINC, PARMS(13)), !lag separation
& (MPPUL, PARMS(14)), !number of pulses
& (MPLGS, PARMS(15)), !number of lags in acf
& (NRANG, PARMS(16)), !number of ranges
& (LAGFR, PARMS(17)), !delay to first range
& (SMSEP, PARMS(18)), !range separation
& (BMNUM, PARMS(19)), !beam number
& (MXPWR, PARMS(20)), !max. power allowed
& (ATTEN, PARMS(21)), !no. of attenuators
& (MODE, PARMS(22)), !normal/sounder/auto
& (DPARM, PARMS(23)), !display parameter
& (LVMAX, PARMS(24)), !max noise level allowed
& (ERCOD, PARMS(25)), !error code
& (NOISE, PARMS(26)), !noise level
& (SEL, PARMS(27)), !nreq and nsel
& (XCF, PARMS(28)), !cross-correlation flag
& (NCHAR, PARMS(29)), !length of comment buffer
& (COMBF(1), PARMS(30)) !comment buffer (max of 80)
c
c This is the beginning of thenew radops386 structure
c
structure /rev_no/ !this defines the revision number structure
byte major
byte minor
end structure
structure /radops_parms/ !this defines the full parameter set
record /rev_no/ rev !revision number
integer*2 nparm
integer*2 st_id
integer*2 year !the first batch of parameters are
integer*2 month !set by the system, not the radops386 user
integer*2 day
integer*2 hour
integer*2 minut
integer*2 sec
integer*2 txpow
integer*2 nave
integer*2 atten
integer*2 lagfr
integer*2 smsep
integer*2 ercod
integer*2 radops_sys_ress(3)
integer*4 noise
integer*4 radops_sys_resl(2)
integer*2 intt !the second batch of paramters are
integer*2 txpl !set by the user, either directly or
integer*2 mpinc !from a radops interpreter program
integer*2 mppul
integer*2 mplgs
integer*2 nrang
integer*2 frang
integer*2 rsep
integer*2 bmnum
integer*2 xcf
integer*2 tfreq
integer*2 scan
integer*4 mxpwr
integer*4 lvmax
integer*4 usr_resL1 !the final variables are user defined
integer*4 usr_resL2 ! i.e. they can mean different things
integer*2 cp ! programs. cp is an exception to this
integer*2 usr_resS1 ! rule. It identifies the COMMON PROGRAM
integer*2 usr_resS2 ! id number.
integer*2 usr_resS3
end structure
record /radops_parms/ rparms !this declares the variable "rparms"
c
c This is the end of the radar parameter definitions. The meaning
c of each parameter will be found in the documentation for RADOPS386
c
* Although we will refer to the data files produced by fitacf as FIT data files, it should be
remembered that there are always two files involved. The actual data file ends with the
extension .fit, but it is always accompanied by an index file with the
same name that ends in the extension .inx.
Note the section on System Dependent Information below.
*** The limited length of DOS file names represents a serious problem for fitropen. Our standard file name is of the form: yymmddhhR.fit Where yy indicates the year, mm the month, dd the day, and hh the hour. The R is a 1 character code identifying the radar (e.g. G=Goose Bay, T=Saskatoon). Thus we have a standard file name that contains 9 characters. Unfortunately DOS only allows 8 character file names. How file names are to be handled under DOS is a problem that the DOS/WINDOWS users will have to resolve for themselves.