-----------------------------------------------------------------
DESCRIPTION
-----------------------------------------------------------------
convert        Utility to convert Ashtech data files downloaded
               from the receiver, or recorded from the serial port,
               to the B,E,S and D files.

Version:       0.4     Apr 24 2001

Author:        Magellan Coropration/Ashtech Precision Products 

-----------------------------------------------------------------
QUICK INTRODUCTION
-----------------------------------------------------------------
This utility reads data files in internal receiver format and converts 
them to the format required by postprocessing software.

Supported input data:
R-file - file downloaded from Z12 receiver external memory
U-file - file downloaded from the Micro Z reveiver external memory
L-file - log file collected from the receiver serial port. The log 
         file should contain raw data SNV,MPC,PBN mesages.
Output data:
B,C,D,E,S files - see below for the detailed content of these files

-----------------------------------------------------------------
COMPILING convert
-----------------------------------------------------------------

This program was tested and built using GNU gcc version 2.7.2.3. We believe
there  should not be any major problems using other version of gcc or some 
another "ansi" compiler. 

To build the executable simply type 
make

To remove object backup and executable file, type:
make clean

-----------------------------------------------------------------
RUNNING convert
-----------------------------------------------------------------

Usage:  
        convert [-F|-f] <FileName> [<Directory>] [-ren] [<NewFileName>] 

Arguments:

<FileName> - name of the input file. Firts letter of file name defines the
             type of the input data.
R - Data downloaded from the external memory of one of the following receivers:
    Dimension, SuperCA, Z-12.
U - Data downloaded from the external memory of Micro-Z
L - "Real Time" raw data file

<Switches>
-F or -f  - convert  R-file (see <FileName>) with "ringbuf-data" only.  
-ren      - rename <FileName> to <NewFileName> (see Examples).

<Directory>
Directory name to store the output files.

Examples:       
        convert USITEV99.325
        convert Log.dat  user/result/data
        convert RSITEV99.325 user/result/data -ren SITXAXX.VAR 
        convert -f RSITEV99.325 user/result/data -ren SITXAXX.VAR 

       
-----------------------------------------------------------------
WHAT YOU HAVE (ARCHIVE CONTENTS)
-----------------------------------------------------------------

Makefile     -  make file
Mainucon.cpp -  the "main" function of the program. 
Download.cpp -  the external functions that write converted data in 
                B-, C-, E-, S-, D-, Almanac files. 
Transfor.cpp -  the external function that converts geodetic north latitude, 
                east longitude, and ellipsoidal height to cartesian X,Y, Z 
                coordinates.
Hosecom.cpp  -  the constructor of base class "Trans", functions that calculate 
                checksums and that read a given number of bytes from the file.
Hoseutil.cpp -  the function that selects receiver name by using the corresponding 
                descriptor in the response of the command "PASHQ,RID.".
Readinfo.cpp -  the receiver identification functions and reading headers 
                in the raw data session.
Computed.cpp -  the functions that convert from Intel format to Motorola 
                format and Visa-Versa, pack the bits to be right 
                justified 30-bit words stored in 32-bit units and that converts 
                GPS time.

Hoseazel.cpp  - the functions that calculate azimuth and elevation of satellites.
Imagemem.cpp  - the functions that open (close) raw data files and that read 
                headers of the raw data files.
Position.cpp  - navigation data's determination functions for converting Ranger1 
                or Ranger3 data without navigation data.
Rfromrec.cpp  - the function that converts R-file.
Rdstrct.cpp   - the functions that convert unpack structures to data for B-, E-, 
                D- files.
Rtinyben.cpp  - the functions that convert pack structures to data for B-file.
Rdranger.cpp  - the functions that convert pack structures of Ranger1, Ranger2,
                Ranger3 types to data  for B- or C- files.
Forsfile.cpp  - the function that forms data for S- file.
Rdrtime.cpp   - the constructor of  "RdRtime" class of heir "Trans", the 
                functions that convert "Real Time" raw data files.
Ggmemory.cpp  - the function that convert the raw data files of receivers with 
                file system (U-files Z- Surveyor).
Mzmemory.cpp  - the function that converts the raw data structures of U-files to 
                B-, C-, E-, S-, D-, Almanac files.
Rdrtdata.cpp  - the function that converts the raw data structures from "Real Time" 
                file to B-, C-, E-, Almanac files.   

-----------------------------------------------------------------
MAIN CLASS information
-----------------------------------------------------------------

Overwiew:

Trans   - a base class (definition in trans.hpp) includes functions to convert 
          raw data of R-files.
RdRtime - class (definition in rdrtime.cpp) heir of  "Trans" class, includes 
          the functions that convert "Real Time" and U- files from receivers 
          with file system (U-files Z-Surveyor).


Public functions of classes:

class Trans
  public:
    Trans();
    ~Trans(){};

    void   ControlRXCount();
    short  Get_curr_file_type();
    void   InitSNV_parameters();
    void   InitDownloadData(); 
    void   FormVarNamesFiles();
    short  FormSfile();
    void   setCountPercent(double _percent);
    void   write_headerCfile();
    short  ReceiverInfofromDumpMemory(const char* _pathImagefile);
    void   CloseDumpMemoryFile();
    void   Set_type_analyse(unsigned short vtype);
    void   Set_ring_buffer();
    short  AnalysReadfRec();
    short  ChangeSessionName();

Trans                      - the constructor of class.
~Trans                     - the destructor of class.
ControlRXCount             - the raw data size calculation in bytes.
Get_curr_file_type         - returns current type of raw data file.
InitSNV_parameters         - initializes parameters of data for E file.  
InitDownloadData           - initializes parameters of data for B, C, E, D files.
FormVarNamesFiles          - forms the variants of names for B, C, D, E, S 
                             files.
FormSfile                  - forms the data for S file.
SetCountPercent            - initializes number of percentage.
write_headerCfile          - forms the header of C file (for Ranger2 raw 
                             data structures). 
ReceiverInfofromDumpMemory - reads the header of R-file.
CloseDumpMemoryFile        - closes R-file.
Set_type_analyse           - initializes the type of data for first 
                             analysis in function  AnalysReadfRec.      
Set_ring_buffer            - sets flag of ring buffer in R-file.
AnalysReadfRec             - the function that converts the raw data from R-file.
ChangeSessionName          - new name of session for names of B, C, D, E, S files 
                             (at value week number  and receivers time from SNV and
                             MBEN structures of "Real Time" raw files).
                            
class RdRtime : public Trans
  public:
    RdRtime();

    short ansReceiverInfo(unsigned short numbytes);
    short AlmanacNameFile();
    void  Init_almanac_strct();
    
    short AnalysDataBlocks(); 
    short EndReadFile(short error);

    short ans_FileDirCountMZ(const char *ansFirstNext);
    short AvailabilityDownloadFile(const unsigned char *varrawfile_name);
    void  InitHeadYFile();
    void  InitforReadVWfile();
    void  CloseReadVWfile();
    short ReadBlocksUfile(const char* _pathVWfile);
                
    short OpenLogFile(const char* _pathImagefile);
    void  Init_analys_LogData();
    short ReadBuf();
    short AnalysRdRtime();
    void  RewriteHeaderBfile();

    unsigned long GetCurrbytesRawfiles();

RdRtime                   - the constructor of class.
AnsReceiverInfo           - the receiver identification functions, reading of 
                            receiver parameters in the response of the command 
                            "$PASHQ,RID" or its emulation.
AlmanacNameFile           - the function that forms the name of Almanac file. 
Init_almanac_strct        - initializes parameters of almanac structures. 
AnalysDataBlocks          - the function that converts raw data from U-file.
EndReadFil                - control of the end of reading U-file.
ans_FileDirCountMZ        - the function forming name of session and 
                            calculating U-file size.
AvailabilityDownloadFile  - the function that checks the presence of  U-file 
                            (not used).
InitHeadYFile             - initializes parameters of data for S file.
InitforReadVWfile         - initializes parameters of U-file reading.
CloseReadVWfile           - closes U-file.
ReadBlocksUfile           - the function that reads 5 blocks (each 512 bytes) 
                            from U-file.
OpenLogFile               - the function that opens "Real Time" raw file 
                            and calculates its size.  
Init_analys_LogData       - the function that initializes parameters of 
                            "Real Time" file reading, forms session.s 
                            name and variants of names for B, C, E files.
ReadBuf                   - the function that reads a given number of bytes from 
                            "Real Time" file.   
AnalysRdRtime             - the function that converts raw data from 
                            "Real Time" file.
RewriteHeaderBfile        - updating parameters of B-file header 
                            (week number from SNV structures of 
                            "Real Time" file).
GetCurrbytesRawfiles      - returns number of  bytes being read from U-file.  


-----------------------------------------------------------------
Format of input data
-----------------------------------------------------------------

R-file without ring buffer includes:
 
1.      Header of R-file (150 bytes), 
        definition in trans.hpp - image_head  (raw_image_header). 
2.      20 bytes not used.
3.      Header of raw data in R-file (80 bytes), 
        definition in trans.hpp - file_header (header_strct).
4.      Move the file pointer to 
        (sizeof(image_head)+ file_header.segbeg*2L) bytes 
        from beginning of R-file.
5.      Type of data (2 bytes), definition in trans.hpp:
         MBEN            1
         PBEN            2
         SNAV            3
         TINYTYPE        4
         TINYTINYTYPE    5
         EVENT           6
         TINYCODELESS    7
         PTINYTYPE       8
         ZTINYTYPE       9
         RNAV           10
         RALM           12
         ATT_3DF        20
         TINYRANGER1    21
         TINYRANGER2    22  
         TINYRANGER3    23      
6.      Packed structure (TINYTYPE, TINYTINYTYPE, TINYCODELESS, 
        PTINYTYPE, ZTINYTYPE, TINYRANGER1, TINYRANGER2, TINYRANGER3) 
        or unpacked (MBEN, PBEN, SNAV, EVENT, RNAV, RALM, ATT_3DF) 
        structure of raw data. For all packed structures, at first, 
        2 bytes are read for definition of their size. 

        Packed structures:

        TINYTYPE     - format for codeless receiver 
                       (L1 C/A & L2 CL code, channel data for nav version 
                       earlier than 5E).
        TINYTINYTYPE - format for codeless receiver (L1 C/A & L2 CL code, 
                       channel data for nav version 5E . 6E).
        TINYCODELESS - format for codeless receiver (L1 C/A & L2 CL code, 
                       channel data for nav version 6F and up).
        PTINYTYPE    - format for Super CA receiver (L1 C/A code) or for 
                       L1 C/A P & L2 P code.
        ZTINYTYPE    - format for L1 C/A P & L2 P code (channel data for 
                       nav version 6F and up).
        TINYRANGER1  - format for L1 code phase (without position data).
        TINYRANGER2  - format of position data to write in C-file.
        TINYRANGER3  - format for L1C/A P & L2 P code phase  
                       (without position data).      

        For unpacking of formats and convertion of raw data, see source code 
        rfromrec.cpp, rtinyben.cpp and rdranger.cpp.

        Unpacked structures:

        MBEN    - for L1 C/A code, definition in trans.hpp (mbenstrct).
        PBEN    - position data, definition in trans.hpp (pbenstrct).
        SNAV    - ephemeris data, definition in trans.hpp (snavstrct). 
        EVENT   - bar code data (see functions ReadHeadEVENT and ReadEVENT 
                  in source file rdstrct.cpp).
   
        RNAV    - raw ephemeris data, definition in trans.hpp (rnavstrct).
        RALM    - raw almanac data, definition in trans.hpp (ralmstrct).
        ATT_3DF - raw data for 3DF receiver only, definition in 
                  trans.hpp (sattdstrct).

Items 5. and 6. are repeated up to the end of the file.


R-file with ring buffer includes: 

1.      Header of R-file (150 bytes), 
        definition in trans.hpp - image_head  (raw_image_header). 
2.      Header of ring buffer (14 bytes), 
        definition in trans.hpp - ring_head (ring_header_strct).
3.      Ephemeris data (4224 bytes), 32 snavstrct structures (132 bytes). 
        (definition in trans.hpp) 
4.      Move the file pointer to given number bytes 
        (function GetRingAddrOffset in source code readinfo.cpp) 
        from beginning of R-file.
5.      Structures TINYRANGER3 - number of structures from ring_head structure 
        (see source code rfromrec.cpp).


U-file includes:

1.      The file consists of blocks (each 512 bytes). Each block has 4 bytes 
        with the time tag. Proper convertion procedure first would exclude that
        time tag, and then converts the record.      
2.      Type of data (4 bytes), definition in rdrtime.hpp 
        (const long idf_header_Ufile[9]):
        
        YREC     - format for S-file 
                   (see function GetYbody in mzmemory.cpp).
        BHDR     - format for header B-file 
                   (see function GetHeaderBfile in   mzmemory.cpp).
        BRX00X09 - format ZTINYTYPE.
        WHX00X16 - format TINYRANGER2.
        WRDT     - format for C-file 
                   (see function ReadTINYDRANGER2 in rdranger.cpp).
        EREC     - format SNAV.
        AREC     - format for Almanac file, definition in trans.hpp 
                   (see function Read_ALMstrct in mzmemory.cpp).
        MREC     - photogrammetry data 
                   (see function GetPhotoData  in mzmemory.cpp).
        DRC_     - bar code data for D-file (see functions CompLengthEvent 
                   and GetEventData in mzmemory.cpp).
       
3.      The raw data of one of the types referred above.

Items 2. and 3. are repeated to the end of the file.


L-file of logged "Real Time" data  includes:

1.      Raw data of real time ($PASHR,.)  one by one:
        $PASHR,MBN  - old format for L1 code phase, definition in rdrtime.hpp 
                      mben_old (mbenstrct_old). 
        $PASHR,MCA  - format for L1 C/A code phase, definition in rdrtime.hpp
                      mben_L1 (mbenstrct_L1).
        $PASHR,MCL  - format for L1 C/A & L2 CL code phase, definition in 
                      rdrtime.hpp mben_L2C (mbenstrct_L2C).
        $PASHR,MP1  - format for L1C/A P code phase, definition in rdrtime.hpp 
                      mben_L1CL12P (mbenstrct_L1CL12P).
        $PASHR,MP2  - format for L1 C/A & L2 P code phase, definition in 
                      rdrtime.hpp mben_L1CL12P (mbenstrct_L1CL12P).
        $PASHR,MPC  - format for L1 C/A P & L2 P code phase, definition in 
                      rdrtime.hpp mben_L1CPL2P (mbenstrct_L1CPL2P). 
        $PASHR,PBN  - PBEN position data structure.    
        $PASHR,SNV  - SNAV ephemeris data structure.
        $PASHR,SAL  - raw data for Almanac file, definition 
                      in rdrtime.hpp rt_alm (rt_almstrct).
        $PASHR,ALM  - The same as $PASHR,SAL
     
-----------------------------------------------------------------
Format of output data
-----------------------------------------------------------------

 
B-file  - includes rawheader, rawnav, rawdata structures 
          (rawnav and rawdata are continue to the 
          end of the file), definition in trans.hpp
          (see function oneEpoch_forBfile in readinfo.cpp).

C-file  - includes position data ASCII file (see source code rdranger.cpp).

E-file  - includes number of satellite, navstrct structure, 
          definition in trans.hpp (see source code rdstrct.cpp).
         
S-file  - includes descriptor data ASCII file (see forsfile.cpp).

D-file  - includes bar code data ASCII file (see functions ReadHeadEVENT 
          and ReadEVENT (rdstrct.cpp), CompLengthEvent, GetEventData 
          (mzmemory.cpp)).
         
Almanac - file includes almanac data in Motorola format of GPS satellites 
          (32 structures), definition in trans.hpp alm[32] (almstrct).
















