"@(#)diflatlon.txt	1.3	2009/12/10 NGS"
----------------------------------------------------------------------
            DOCUMENTATION for NGS program diflatlon
----------------------------------------------------------------------


PROGRAM FUNCTION:
----------------------------------------------------------------------
This program finds the differences in position, 
ellipsoid height and orthometric height 
for identical stations as reported in two different files.
Input files are horizontal format files, either Bluebook or Crefil format.

Differences are reported for latitude, longitude, ellipsoid height, orthometric height,
and horizontal geodetic distance (no elevation component).

Both PIDs and the SSNs, as listed in the second file,
are listed in the output to identify identical stations.

Stations can be matched by either SSN or PID,
but PID matching can only be used with Crefil format files.

The GRS80 ellipsoid is used in the inverse geodetic computation,
but since a relative difference is found,
differences from other models should be nominal.


PROGRAM OPERATION:
----------------------------------------------------------------------
Entering "diflatlon -h" (or any other single parameter),
results in a help screen displaying the program usage.

Entering only "diflatlon" results in prompts for data input.

The program may be run in a complete command line,
entering all required parameters in their proper order.

On a Unix system, the program my be run
by using the prompting script diflatlon_prompt.

Entering the program name with anything other than six command parameters
displays program version, date, function and usage.



Running the program requires the following parameters,
supplied either in response to prompts, or on the command line:

diflatlon <1st Filename> <2nd Filename> <Output Filename>
          <Shift Tolerance>
          <SSN/ISN Length in 2nd file>
          <Match Type>
Where:
  <1st Filename>
     A file with 80 and optionally 86 records.
     Orthometric heights from the 86 record overwrite
     the elevations from the 80 record.

  <2nd File>
     A file with 80 and optionally 86 records.
     Orthometric heights from the 86 record overwrite
     the elevations from the 80 record.

  <Output Filename>
     The output report file contains shifts for all stations.
     The program will add the extension ".out" to the given filename.
     The output report filename will be
     the basis for the statistical and message filenames.
     The statistical file (*.stt) lists only stations with large shifts.
     The message file (*.msg) reports non-fatal errors and warnings.
     All output files will overwrite an existing file of the same name.

  <Shift Tolerance> 
     Stations with a shift greater than this value will be printed:
      1) in the report file with an asterisk in column 80
      2) in the statistics file.

  <SSN Length>
     Length of the Station Serial Number (SSN) in the second file.
     Allowed values are { 3, 4, 5 } only.
     The length of the SSN's of the first file
     must be the same length in the second file,
     only if matching on SSN's.

  <Match Type>
     Indicates the search criteria:
         S or s    matches  Station Serial Number       (SSN)
         P or p    matches  Point IDentification number (PID)
     Matching on PID is available only with input files in Crefil format.



Script Line Execution:
----------------------------------------
Script diflatlon_prompt gives the option
for program information, performed by entering h or H, or
for program execution,   performed by simply pressing <return>,
or entering any other key.

The script prompts for each sucessive parameter.
The script exits if either input file cannot be found.
The output file will overwrite an existing file of the same name.
SSN length may only be 3, 4 or 5, 
and will continue to prompt until acceptable input is entered.
Match type can only accept p, P, s or S, and will
continue to prompt until acceptable input is entered.

The user then has the option of sorting the output files by designation.
The user is then prompted:

    Sort output file alphabetically by designation? (y/n): 

The response can only accept y, Y, n or N, and will
continue to prompt until acceptable input is entered.

If sorting is selected, then a system call will
sort by designation on the second input file,
and the results are written to a temporary file.
The program is then run using this temporary file,
and its random name will appear in the output files.
The temporary file is erased after running diflatlon and
before the end of the script file.



OUTPUT
----------------------------------------------------------------------
The output report file will show the differences in
  - geodetic latitude
  - geodetic longitude,
  - geodetic position (no elevation component)
  - elevation
Those position differences greater than the maximum allowable shift 
will be followed by a single asterisk in the report file
and printed to the statistics file.
Both SSN and PID are be displayed.
The  SSN from the second file is displayed.

Output report and statistics files are 89 characters wide, 
requiring landscape paper orientation for these two output files.

A statistics file, named as per the output file with ".stt" appended,
will state job parameters, max shift, min shift, average shift,
and all stations whose shifts are greater than the specified tolerance.
Only the statistics file header is printed to the display.

Output report and statistics files will be ordered as per the second input file.
That is, if the second input file is sorted by PID,
then the output files will be sorted by PID.
Script diflatlon_prompt gives the option for sorting by designation.

A message file is used to report all non-terminating errors and warnings.



PROGRAM METHOD:
----------------------------------------------------------------------

Data check:
-------------------------------
Parameters tested:
  SSN length must be { 3, 4, 5 }
  ID type    must be { S, s, P, p }

If files are successfully opened, then a short message is displayed.
If a file cannot be opened, the program ends with an error message.

Job run parameters are displayed.

Process:
-------------------------------
There are three data loops.

The first loop reads in data from the first file.
An 80 record is expected before an 86 record.
Data from an 80 record is read and parsed,
transforming position data from DMS to decimal degrees,
and stores for each data set:
  - north latitude           in decimal degrees
  - west longitude           in decimal degrees
  - PID
  - SSN
  - station designation

An 86 record is read for a previously loaded 80 record, and reads
  - orthometric height       in meters (MMMMmmm)
  - ellipsoidal height       in meters (MMMMmmm)

Files are kept in memory because the location of 80 and 86 records
are random, with no order to allow writing to a temporary file.

The second loop performs the same process with the second data file.


Then, the third loop reads in data from the second file,
and searches through the first file for the identical match item (ssn, pid).
If a match is found, then calculations are performed:
  - difference in latitude
  - difference in longitude
  - difference in ellipsoidal height
  - difference in orthometric height
  - a simple indirect geodetic invese, for length only.

Results are immediately formatted and printed to the report file,
and stored in a buffer for the statistical file.
Each buffer is formated for 66 lines per page,
Errors and warnings are printed to a message file.

At the end of the third loop,
a statistical summary is printed to display and to the statistics file,
then the buffer with statistical data is sent to its file,
appearing below the summary.


Program completion:
------------------------------
If the message file contains no entries, it is deleted.
A final message is displayed:
"End diflatlon ... bye!"



PROGRAMMERS NOTES:
----------------------------------------------------------------------
 1) Program version is SCCS based:
    If a function is significantly modified,
    edit then delta the main program 
    to increment the version and reset the program release date.

 2) All functions and headers have SCCSID constant strings.
    Inspect NGS source module versions on a unix system by entering:
      what diflatlon.txt | grep NGS

 3) See also original concept program DIFLATLON.



diflatlon.txt - end
----------------------------------------------------------------------

