genegu [ parameter=value ... ] [ inputfile ... ]
Parameters are user defined [yes or no]
genegu is a generic function stored in $ROOT/lib as an object file. It has to be linked with the developer - supplied platform specific function processing DCS data in one point.
Following is the description of genegu functionality, which will allow the Terascan developer to create the platform type - specific function for processing DCS data.
Input dataset should contain the following variables:
datefR - The date the message was received.
time - The time the message was received.
platform_id - The identification number of the message sender.
dcs_doppler - The unprocessed DCS doppler shift number.
dcs_quality - The message quality. 0 indicates a good data. 1 indicates that the data is questionable.
dcs_count - The number of 4 byte quantities in dcs_data, ranges between 0 and 7.
dcs_data - The unprocessed DCS message.
latitude, longitude and elevation of platform.
The file with these variables can be obtained after running sequentially dcsin and dcsloc functions.
Lack of any of those variables will cause the program to terminate.
What genegu main routine does:
1. It calls developer's function egu_process for the first time to get information about the output variables: their number, names, types and units and also to get the number and the names of the flags the user will be prompted from the command line.
2. It reads DCS constants from dcs_data data file.
3. It tries to find the developer-defined output variables in the input file and defines ones that were not found.
4. It sorts all records in the dataset using (platform_id, date, time) as a multiple key (if input is not too big and enough memory can be allocated).
5. It reads one record at a time, puts all information in the structure and calls developer's function egu_process(). Therefore, egu_process() should provide the single-record data conversion facility only. Before egu_process() is called, all output values are assigned to bad.
The following actions are performed depending on the return code of egu_process():
a) < 0: Unrecoverable failure. Program exits.
b) > 0: it fills the output with the bad value for newly created variable or leaves the old values if variable already existed in the input dataset.
c) = 0: Success. Writes the data found by egu_process() into the output.
5. Reads the next record.
How egu_process() should work:
The developer's function egu_process() has an integer type.
It has only one parameter - pointer to the structure EGU_data defined in genegu.h header file.
This structure is used to exchange the information between the main() and egu_process(). It contains all information the developer may need both for calculations and making a report.
The following fields are read-only ones, fixed or automatically updated by main().
initialize - if main() wants egu_process() to define flags and output variables.
nfiles - number of files to process.
file - current file number, starting from 0.
set_name - current file name.
npts - number of records in the current input dataset.
point - number of the current record.
The following fields are to be filled during the initialization:
nflags - number of [yes/no] flags.
flag[i].name - flags names, i = 0...(nflags-1)
nvars - number of output variables.
outvar[i].name - out variable name , i = 0...(nvars-1)
outvar[i].units - out variable units, i = 0...(nvars-1)
outvar[i].type - out variable type , i = 0...(nvars-1)
The following fields of .dcs_block substructure are used as input-only and provide with the input DCS data for the current record: platform_id, date, time, dcs_data[40], quality, dcs_count, lat, lon, elevation.
The fields aws and awscor points to AWS_ST and AWS_COR_ST structures filled by the information from dcs_data file specific for the current record:
AWS_ST:
plat_id - current platform id
start_date - starting date that the plat_id was first used at this site
plat_type - platform type (0 - reference, 1 - fixed, 2 - movable).
cx , cy, cz - platform specific calibration coefficients
la - latitude of the station, deg., +n, -s
lo - longitude of the station, deg., +e, -w
ht - height of the station, in meters
plat_name - platform/site name
AWS_COR_ST: arh, brh, adt, bdt, wdc, pc - platform specific calibration coefficients,
st - sensor type, see file: dcs_data
See dcs_data (5) for more information on dcs_data file.
The following fields of .outvar[i].value union (i = 0...(nvars-1)) should be used as an OUTPUT to return the values for the current record to the main():
ch - for character data,
sh - for short data,
in - for integer data,
fl - for float data,
db - for double precision data,
str - for string data.
The following actions should be performed by developer's function to produce the meaningful output and not to corrupt the data:
1. If .initialize field is set, initialize the output variables and flags and immediately exit. It happens only once as a first call to egu_process().
2. If the platform type is not one function is interested in, it should return 1 without changing the output data fields.
3. If the platform type is right and the data was successfully converted, return 0.
IMPORTANT NOTICE: if some of the values can't be calculated, egu_process() simply should not change them. Since they were originally assigned to the bad values, the correct output will be produced. THE DEVELOPER'S FUNCTION SHOULD NOT ASSIGN ITS OWN BAD VALUES.
If the entire message was diagnosed as bad, the function still should return 0 without changing the output data fields. It will make the main routine put the bad values into the output.
egu_demo.c in $ROOT/share/programs directory has a sample egu_process() function to process the New Italian Platforms ( type 11 in $ROOT/refdata/dcs_data file).
genegu.h in $ROOT/share/programs has the definition of EGU_DATA_ST structure which is (the only) Input/Output parameter for egu_process(). Since genegu.h is used by the main() routine, its contents can not be changed.
dcsegu.h in $ROOT/share/programs has many useful definitions for variables names, units, platform types, sensor types etc. The developer is strongly recommended to include this file and use its definitions for convenience and also for names consistency which will help egu_process() to be compatible with other DCS-related functions. The new information can be added in this file by the developer.
EGUmake in $ROOT/share/programs is a makefile for egu_demo executable.
dcs_data - has more information on dcs_data file.
Last Update: $Date: 1999/05/10 21:16:30 $