"compVecs.txt - 1.2 - 2006/02/16"
----------------------------------------------------------------------------
         DOCUMENTATION FOR NGS PROGRAM  compVecs
----------------------------------------------------------------------------

 TO EXECUTE:
   Command line usage:
     compVecs <horz_bbk filename> <gfile filename> <output filename>
   where:
     <horz_bbk filename> horizontal bluebook with *80* records
     <gfile filename>    GPS file with redundant baseline observations
     <output filename>   at the user's discretion

   Entering "compVecs" with other than three parameters displays brief usage.

   Prompts/Windows DOS box usage:
     compVecs   (user is queried for filenames)


 FUNCTION:
   Program compVecs  compares redundant vectors in a gfile.

   1) The horizontal bluebook file is opened and read.

   If a position record (*80*) is found, then in a function call, 
   the Station Serial Number(SSN), latitude and longitude
   are parsed, and stored in a data structure.
   The latitude and longitude are stored in the NGS default format,
   with leading hemisphere, degrees, minutes, seconds 
   and decimal seconds to five digits right of decimal.
   The data structure is then stored in a 
   dynamically allocated container of positions.

   Orthometric and ellipsoid heights from either
   position records (*80*) or elevation records (*86*)
   are not parsed.  Changes in ellipsoid heights are found from
   the relative differences between redundant observations only.

   The horizontal bluebook file is then closed, and a message is displayed,
   "Reading of positions    file (bbk)   is complete."


   2) The GPS observation file (gfile) is read.

   If either a C or an F record is found, then in a function call, 
   the reject code, session number, SSN_from, SSN_to, and the
   dX, dY, dZ values are parsed and stored in a data structure.

   If a C-record is found: 
    - the 4-character ID for the from station is read from cols 65-68
    - the reject code ('R') is read from column 58

   If a F-record is found: 
    - no 4-character IDs exist, so are not read
    - the reject code ('O') is read from column 64

   The data is then ordered by SSN's,
   setting the smaller value number as the SSN_from, and
   setting the larger  value number as the SSN_to.
   If the SSN's are swapped, then the dX, dY and dZ values
   are inverted by multiplying by -1.0, and an invert flag is set as "s".
   If the stations are not swapped, then  the  invert flag is set as " ".

   The data structure is then stored into a dynamically allocated container
   of observations.

   The gfile is then closed, and a message is displayed,
   "Reading of observations file (gfile) is complete".


   3) Next, the observations are sorted by SSN_from and SSN_to.

   To facilitate this sort, an extra data item is added 
   to the observation data structure, and consists of
   the concatinated SSN_from and SSN_to.
   Sorting is then applied to this data item.

   When sorting is finished, a messaage is displayed,
   "Sorting of observations is complete".


   4) Next, baseline comparisons are processed.

   Header strings are printed to the output file.
   An extra observation data structure is allocated for the 
   previously read data set.

   Observation data structures in the container are read in a loop, then
   Position    data structures in the container are read in a loop.

   If the Position SSN matched the Observation's SSN_from, then
   the observation's dX,dY,dZ are copied to a local variable,
   and the dE,dN,dU are calculated at the Position's latitude and longitude.
   The dE,dN,dU values are stored in the current observation data structure.

   A) If the SSNs for the previously read data structure
     MATCHES the current data structure,
     then a redundant baseline vector is found, and
     a line is sent to the output file with:
      - invert code ("s" if baseline is swapped)
      - reject code ("R" if baseline is rejected)
      - session number
      - dX difference     (1st baseline's dX     - this baseline's dX)
      - dY difference     (1st baseline's dY     - this baseline's dY)
      - dZ difference     (1st baseline's dZ     - this baseline's dZ)
      - dE difference     (1st baseline's dE     - this baseline's dE)
      - dN difference     (1st baseline's dN     - this baseline's dN)
      - dU difference     (1st baseline's dU     - this baseline's dU)
      - length difference (1st baseline's length - this baseline's length)

     Statistical data is gathered for future computations
     are computed and stored for those observation NOT rejected.
     The elements for computing the mean and standard deviation, 
     and the magnitude of the dX,dY,dZ differences (residuals) 
     is calculated and stored.

   B) If the SSNs for the previously read data structure
     DO NOT MATCH the current data structure,
     then a new set of baselines are found, and
     a line is sent to the output file with:
      - 4char ID from
      - 4char ID to
      - SSN from
      - SSN to
      - invert code ("s" if baseline is swapped)
      - reject code ("R" if baseline is rejected in the gfile's C-record)
                    ("O" if baseline is rejected in the gfile's F-record)
      - session number
      - dX value           (this baseline's dX)
      - dY value           (this baseline's dY)
      - dZ value           (this baseline's dZ)
      - dE value           (this baseline's dE)
      - dN value           (this baseline's dN)
      - dU value           (this baseline's dU)
      - baseline length    (this baseline's length)

   Hence, each observation dataset is computed in turn,
   once the SSN_from is matched so the latitude and longitude 
   of that SSN is found, to be used in the coordinate transform.


   After all observations are processed, 
   statistics of the component differences are calulated and 
   sent to the output file.

   The output file is then closed, the program is finished, 
   and a messaage is displayed,
   "Normal end of program compVecs ... bye"


compVecs.txt - end
--------------------