getvalnb.f

Go to the documentation of this file.

C> @file
C> @brief Read one data value from a data subset.

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> <p>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> @author J. Ator
C> @date 2012-09-12
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> <p>The current placeholder value for "missing" data can be determined
C> via a separate call to function getbmiss().
C>
C> <p>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> <b>Program history log:</b>
C> - 2012-09-12  J. Ator    -- Original author
C> - 2014-10-02  J. Ator    -- Modified to use fstag()
C> - 2014-12-10  J. Ator    -- Use modules instead of COMMON blocks
C>
    REAL*8 FUNCTION getvalnb ( LUNIT, TAGPV, NTAGPV, TAGNB, NTAGNB )

        USE modv_bmiss

    USE moda_usrint
    USE moda_msgcwd
    USE moda_tables

    CHARACTER*(*) tagpv, tagnb

C----------------------------------------------------------------------
C----------------------------------------------------------------------

    getvalnb = 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

    getvalnb = val(nnb,lun)
        
    RETURN
    END