                                  GVH user guide
 
 
                                Leonid Petrov
 
 
                                2005.11.18
 
 
Questions and comments about this guide should be sent to:
 
Leonid Petrov ( http://gemini.gsfc.nasa.gov/pet )
 
 
                                Table of contents:
 
 
1 ................ Overview
 
 
2 ................ Usage
 
   2.1 ........... Initialization routines
   2.2 ........... Put routines
   2.3 ........... Get routines
 
________________________________________________________________________________
 
        1 Overview
        ==========
 
  GVH stands for Geodetic VLBI database Handler. It provides
a library of calls for reading from and writing into files in either
binary or ascii GVH format.
 
        2 Usage
        =======
 
                2.1 Initialization routines
                ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
GVH_INIT ( GVH, IUER ) -- initialization routine. Should be called
           before the first call to other GVH routines.
 
GVH_RELEASE ( GVH, IUER ) -- release of dynamic memory allocated by
              GVH. Should be called after and of working with the
              current VLBI experiment
 
                2.2 Put routines
                ~~~~~~~~~~~~~~~~
 
GVH_PPREA ( GVH, ISEG, KEYWORD, VALUE, IUER ) -- puts the record
            to preamble of the ISEG-th section. The record is added
            to the end of the list of records.
 
GVH_PTEXT_CHP ( GVH, ISEG, TITLE, NLINES, BUF, IUER ) -- puts the text
                chapter with title TITLE and the the BUF which consists
                of NLINES into the next chapter of ISEG-th segment of
                GVH internal data structure. The trailing blanks are
                ignored in BUF. The text and the title should not
                contain characters with decimal codes 10 and 26.
 
GVH_PTOC ( GVH, LCODE, TYP, CLASS, DIM1, DIM2, DESCR, ISEG, IUER ) --
           adds the definition of the new lcode to the table of
           contents of the ISEG-th segment.
 
GVH_PLCODE ( GVH, LCODE, NOBS, NSTA, ARRAY, IUER ) -- puts contents
             of lcode LCODE into the GVH internal data structure.
             The contents is the array of fixed dimension ARRAY which
             corresponds to the observation NOBS at the baseline with
             the station NSTA (either #1 or #2). The type and dimension
             of array LCODE is defined in the definition of LCODE and
             stored in GVH. Routine GVH_PREPUT should be called before
             the first use of GVH_PLCODE. Contents of the array is
             added in the DATA section of the appropriate segment
             of GVH.
 
GVH_PHLCODE ( GVH, LCODE, NOBS, NSTA, DIM1, DIM2, ARRAY, IUER ) --
              puts contents of lcode LCODE into the GVH internal data
              structure. The contents is the array of variable dimension
              ARRAY which corresponds to the observation NOBS at the
              baseline with the station NSTA (either #1 or #2). The type
              and and maximal dimension of array LCODE is defined in the
              definition of LCODE and stored in GVH. Routine GVH_PREPUT
              should be called before the first use of GVH_PHLCODE.
              Contents of the array is added in the HEAP section of the
              appropriate segment of GVH.
 
GVH_PREPUT ( GVH, NUMOBS, NUMSCA, NUMSTA, NOBS_STA, C_STA, OBS_TAB, IUER ) --
             inserts in the internal data structure values of 5 mandatory
             lcodes, creates caches table and sorts it. It is assumed that
             all lcodes have already been defined using GVH_PTOC. After
             running GVH_PREPUT contents of non-mandatory lcodes can be
             added to GVH by calling GVH_PLCODE or GVH_PHLCODE. Routine
             GVH_PREPUT must be run after the last call to GVH_PTOC and
             before the first call of GVH_PLCODE of GVH_PHLCODE.
 
GVH_WRITE_AGV ( GVH, ISEG, OPCODE, FILENAME, IUER ) -- writes the contents
                of one or more segments into the output file in ASCII GVH
                format. If ISEG=0, then all segments are written into the
                file. If ISEG is not equal to zero, then the ISEG-th
                segment is written. If OPCODE = GVH__CRT, then the new
                file is created. If OPCODE = GVH__APP, then the contents
                is appended to the existing file.
 
GVH_WRITE_BGV ( GVH, ISEG, OPCODE, FILENAME, IUER ) -- writes the contents
                of one or more segments into the output file in binary GVH
                format. If ISEG=0, then all segments are written into the
                file. If ISEG is not equal to zero, then the ISEG-th segment
                is written. If OPCODE = GVH__CRT, then the new file is
                created. If OPCODE = GVH__APP, then the contents is appended
                to the existing file.
 
                2.3 Get routines
                ~~~~~~~~~~~~~~~~
 
GVH_READ_AGV ( GVH, ISEG, FILENAME, IUER ) -- reads the contents of one
               or more segments of the input file in ASCII GVH format.
               If ISEG=0, then it reads from the file segments. If ISEG
               is not equal to zero, then the ISEG-th segment is read.
               NB: argument ISEG corresponds to the segment counter
               counted from the beginning of the file starting from 1.
               This may not correspond to the segments counter of GVH!
               GVH_READ_AGV increments segment counter before reading
               each new segment, except the case when no segments have
               been loaded in GVH, i.e. it was  just initialized.
               In that case GVH_READ_AGV will put the first segment from
               the input file to the first segment of GVH.
 
GVH_READ_BGV ( GVH, ISEG, FILENAME, REMAINED_BYTES, IUER ) -- reads the
               contents of one or more segments of the input file in
               binary GVH format. If ISEG=0, then it reads from the file
               segments. If ISEG is not equal to zero, then the ISEG-th
               segment is read. NB: argument ISEG corresponds to the
               segment counter counted from the beginning of the file
               starting from 1. This may not correspond to the segments
               counter of GVH! GVH_READ_BGV increments segment counter
               before reading each new segment, except the case when
               no segments have been loaded in GVH, i.e. it was just
               initialized. In that case GVH_READ_BGV will put the first
               segment from the input file to the first segment of GVH.
 
GVH_GPREA ( GVH, ISEG, IND_REC, KEYWORD, VALUE, IUER ) -- gets
            the IND_REC-th record from the preamble of the ISEG-th section:
            the keyword and the value. The argument ISEG should be in the
            range of available segments. The argument IND_REC should be
            in the range [1, GVH%PREA(ISEG)%NKWD].
 
GVH_GTEXT_CHP ( GVH, ISEG, N_CHP, M_LIN, L_LIN, TITLE, BUF, IUER ) --
                gets the title and contents of the N_CHP-th text chapter
                of the ISEG-th segment of the GVH internal data structure.
 
GVH_PREGET ( GVH, IUER ) -- creates caches table and sorts it. Routine
             GVH_PREGET shoujld be called after reading the last
             segment of data from external files and before the first
             call of GVH_GLCODE for extraction information related to
             lcodes.
 
GVH_GLCODE ( GVH, LCODE, IND_OBS, IND_STA, MLEN, ADIM1, ADIM2, ARRAY, IUER )
             -- gets contents of lcode LCODE into the GVH internal data
             structure. The contents is the array of ARRAY corresponds to
             the observation with index IND_OBS at the baseline with the
             station IND_STA (either #1 or #2). The type and dimension
             of array LCODE is defined in the definition of LCODE and
             stored in GVH. Routine GVH_PREGET should be called before
             the first use of GVH_GLCODE.
