 
      CALL SEQUENCE...
       vsinth  XIN LNSP XOUT [ GTOP ] INPUT OUTPUT \ 
             [ -kind VAL1 [ VAL2 ] -scal VAL3 -l VAL4 -a VAL5 \ 
                                   -c    VAL6 -d VAL7 -i VAL8 \ 
                                   -def [VAL9] ]
 
 
      DESCRIPTION...
       vsinth  - VERTICAL SIGMA INTEGRAL FOR DATA ON ETA COORDINATES
 
 
      AUTHOR  - R. LAPRISE, FEB 16/88.
      LAST REVISION: $Header: /data/armnraid1/cvs/RMNLIB/utils/rdiag/lspgm/vsinth.ptn,v 4.24 2012/07/04 14:36:26 dugas Exp $
 
 
      PURPOSE - COMPUTES THE VERTICAL SIGMA INTEGRAL FOR DATA ON ETA
                (SIGMA/HYBRID/GEM) COORDINATES. THE PROGRAM IS UPWARD
                COMPATIBLE WITH THE FORMER VERSION (VSINT).
 
                THE DIFFERENCES ARE THAT:
                1) AN EXTRA INPUT FILE LNSP WHICH IS NOW REQUIRED;
                2) SPECTRAL FIELDS CAN ONLY BE HANDLED IN SIGMA COORD;
                3) THE TOP PRESSURE CAN BE READ FOR GEM-TYPE COORDINATES
 
 
      INPUT FILE...
       XIN  = INPUT SERIES OF ETA LEVEL GRID FIELDS .
       LNSP = INPUT SERIES OF LN(SURFACE PRESSURE) IN MB.
 
      (THE FOLLOWING FILE MAY ONLY BE READ WITH GEM LEVELS)
       GTOP   =  SERIES OF GRIDS OF PRESSURE AT TOP OF MODEL (! OPTIONAL !)
 
      OUTPUT FILE...
       XOUT = OUTPUT SERIES OF VERTICAL SIGMA INTEGRALS OF XIN.
 
 
      INPUT PARAMETERS...
 
       COORD  (kind 1) = INPUT VERTICAL COORDINATE: THE POSSIBLE OPTIONS ARE
                         'SIG'/'ETA' FOR SIGMA/ETA AND 'GEM'/'GEM2'/'GEM3'/'GEM4'
                         FOR ONE OF FOUR VERSIONS OF THE GEM COORDINATE. THE FILE
                         CONTENT itSelf IS USED TO DETERMINE THE RPN DEFAULT
                         ('GEM2','GEM3' OR 'GEM4').
       LEVTYP (kind 2) = 'FULL' FOR MOMENTUM VARIABLE, AND
                         'HALF' FOR THERMODYNAMIC ONE.
       CONST  (scal)   = SCALES THE OUTPUT FIELD (DEF 1.0)
       LAY    (l)      = DEFINES THE POSITION OF LAYER INTERFACES IN RELATION
                         TO LAYER CENTRES, IN THE FOLLOWING FASHION:
                         - ('SIG' OR 'ETA' OPTIONS), SEE BASCAL:
                            DEFAULTS TO THE FORMER STAGGERING CONVENTION.
                         - ('GEMx' OPTIONS), LAY=1 IMPLIES THAT THE LAYER
                            CENTRES ARE POSITIONNED USING THE ARITHMETIC MEANS
                            OF THE DATA LEVELS. A VALUE OF 2 IMPLIES GEOMETRIC
                            MEANS. NOTE THAT THE LATTER IS ALSO THE DEFAULT.
       SIGTOP (a)      = VALUE OF SIGMA AT TOP OF DOMAIN FOR VERTICAL INTEGRAL.
                         IF .LT.0., THEN INTERNALLY DEFINED BASED ON LEVTYP
                         FOR UPWARD COMPATIBILITY.
       PTOIT  (c)      = PRESSURE (PA) AT THE MODEL LID.
       PREF   (d)      = REF PRESSURE USED WHEN COORD='GEM2' OR 'GEM3' (DEF 80000 PA).
       R      (i)      = EXPONENT USED ONLY WHEN COORD='GEM2' OR 'GEM3' (DEF 1.0)
 
       Notes:   1) When COORD(1:3)='GEM', LEVTYP and SIGTOP are ignored.
                2) When COORD='GEM', PTOIT is only used if GTOP is empty
                3) When COORD(1:3)='GEM', top and bottom boundary conditions
                   are provided by the levels found in the file XIN.
                4) When COORD='ETA'/'SIG', LAY and LEVTYP define the type
                   of levelling for the variable.
                5) 'GEM' is the original gem coordinate, while GEM2 is the
                   original hybrid coordinate as implemented by Edouard &
                   Gravel in GEM/DM v2.2.0. GEM3 is the normalized version
                   that was implemented in the v2.3.1 GEM/DM. 'GEM4' is the
                   coordinate version of GEM/DM from v4.0.6.
                6) The default value of COORD is determined by the file type
                   and the program will also try to determine it by the
                   (internal) coding used for the coordinate itself.
                7) Specifying "-def AABB" will force the attempt to read
                   a text file called aabb.nml, containing a FORTRAN
                   namelist AABB_NML, which in turns will hold two arrays,
                   A and B such that the local pressure at level K, PL(K),
                   can be calculated as "A(K)+B(K)*PS". This then by-passes
                   all of the normal COORD-related calculations for PL(K).
 
       READ( 5,5000) LEVTYP,CONST,LAY,COORD,SIGTOP,PTOIT,PREF,R
 5000  FORMAT(11X,A4,E10.0,I5,1X,A4,E5.0,3E10.0)
 
 
      EXAMPLE OF INPUT CARD...
 
  VSINTH.  HALF        1.    0  GEM  -1.      pression_au_toit
 
         0123456789012345678901234567890123456789012345678901234567890
         1         2         3         4         5         6         7
 
 
      EXIT CONDITIONS...
        0 NO PROBLEMS
        1 PREMATURE EOF ON XIN
        2 NOT ENOUGH OR TOO MANY LEVELS IN FIRST SET OF XIN
        3 CANNOT TREAT SPECTRAL ETA LEVELS    
        4 PREMATURE EOF ON LNSP
        5 XIN AND LNSP ARE NOT COMPARABLE
        6 UNKNOWN (AND UNSUPPORTED) LEVEL TYPE
        7 UNABLE TO READ FIRST LNSP RECORD
        8 UNABLE TO READ/FIND MATCHING XIN SET
        9 UNABLE TO READ FIRST XIN SET
       10 PREMATURE EOF ON INPUT
       11 VERT COORDINATE NOT MONOTONIC
       12 MISSING GTOP FIELD
       13 LNSP AND GTOP NOT THE SAME SIZE
       14 MORE THAN ONE SIZE IN GTOP
       15 ILLEGAL GEM/LAY VALUE
       16 PTOIT GREATER THAN TOP MODEL LEVEL (=ETA(TOP)*PREF)
       17 UNSUPPORTED VERTICAL COORDINATE IN XIN
       18 COORD PARAMETRE AND XIN DATA MISMATCH
       19 MORE THAN ONE VERTICAL COORDINATE IN XIN 
       20 UNABLE TO READ AABB NAMELIST
       21 LNSP DOES NOT CONTAIN LN(SURFACE PRESSURES) FOR EARTH
 
