getvalnb.f

Go to the documentation of this file.

C> @file
C> @brief Read one data value from a data subset.
C>
C> @author J. Ator @date 2012-09-12
 
C> This function can be used to read a data value corresponding to
C> a specific occurrence of a mnemonic within a data subset, based on
C> its position relative to a different mnemonic within the subset.
C>
C> The function first searches for a specific occurrence of a pivot
C> mnemonic, counting from the beginning of the subset.  From there,
C> it then searches in either a forward or backward direction for a
C> specific occurrence of a nearby mnemonic, and if found
C> returns the data value from the corresponding location
C> within the subset.
C>
C> @param[in] LUNIT  -- integer: Fortran logical unit number for
C>                      BUFR file
C> @param[in] TAGPV  -- character*(*): Pivot mnemonic; the subroutine
C>                      will first search for the (NTAGPV)th occurrence
C>                      of this mnemonic, counting from the beginning
C>                      of the overall subset definition
C> @param[in] NTAGPV -- integer: Ordinal occurrence of TAGPV to search for,
C>                      counting from the beginning of the overall
C>                      subset definition
C> @param[in] TAGNB  -- character*(*): Nearby mnemonic; assuming TAGPV is
C>                      successfully found, the subroutine will then search
C>                      nearby for the (NTAGNB)th occurrence of TAGNB and
C>                      return the corresponding value
C> @param[in] NTAGNB -- integer: Ordinal occurrence of TAGNB to search for,
C>                      counting from the location of TAGPV within the
C>                      overall subset definition.  If NTAGNB is positive,
C>                      the subroutine will search in a forward direction
C>                      from the location of TAGPV; otherwise, if NTAGNB is
C>                      negative, it will instead search in a backwards
C>                      direction from the location of TAGPV.
C> @returns getvalnb -- real*8: Value corresponding to (NTAGNB)th occurrence
C>                      of TAGNB.  If for any reason this value cannot be
C>                      located, then the current placeholder value for
C>                      "missing" data will be returned instead.
C>
C> The current placeholder value for "missing" data can be determined
C> via a separate call to function getbmiss().
C>
C> Before calling this function, a BUFR data subset should already be
C> open for reading via a previous call to one of the BUFRLIB
C> [subset-reading subroutines](@ref hierarchy).
C>
C> @author J. Ator @date 2012-09-12
        RECURSIVE FUNCTION getvalnb
     .          ( lunit, tagpv, ntagpv, tagnb, ntagnb )
     .          result( r8val )
 
        USE modv_bmiss
        USE modv_im8b
 
        USE moda_usrint
        USE moda_msgcwd
        USE moda_tables
 
        CHARACTER*(*) tagpv, tagnb
 
        real*8 r8val
 
C----------------------------------------------------------------------
C----------------------------------------------------------------------
 
C       Check for I8 integers.
 
        IF(im8b) THEN
           im8b=.false.
 
           CALL x84(lunit,my_lunit,1)
           CALL x84(ntagpv,my_ntagpv,1)
           CALL x84(ntagnb,my_ntagnb,1)
           r8val=getvalnb(my_lunit,tagpv,my_ntagpv,tagnb,my_ntagnb)
 
           im8b=.true.
           RETURN
        ENDIF
 
        r8val = bmiss
 
C       Get LUN from LUNIT.
 
        CALL status (lunit, lun, il, im )
        IF ( il .GE. 0 ) RETURN
        IF ( inode(lun) .NE. inv(1,lun) ) RETURN
 
C       Starting from the beginning of the subset, locate the (NTAGPV)th
C       occurrence of TAGPV.
 
        CALL fstag( lun, tagpv, ntagpv, 1, npv, iret )
        IF ( iret .NE. 0 ) RETURN
 
C       Now, starting from the (NTAGPV)th occurrence of TAGPV, search
C       forward or backward for the (NTAGNB)th occurrence of TAGNB.
 
        CALL fstag( lun, tagnb, ntagnb, npv, nnb, iret )
        IF ( iret .NE. 0 ) RETURN
 
        r8val = val(nnb,lun)
 
        RETURN
        END