rdmgsb.f

Go to the documentation of this file.

C> @file
C> @brief Read a specified data subset from a BUFR file.
C>
C> @author J. Woollen @date 2003-11-04
 
C> Read a specified data subset from a BUFR file.
C>
C> This subroutine combines the functionality of openbf(), 
C> readmg(), and readsb().
C>
C> Logical unit LUNIT should not have already been opened via a
C> previous call to subroutine openbf(). This subroutine will 
C> open the file for input.
C>
C> Whenever this subroutine returns successfully, this indicates
C> that a new data subset was successfully read into internal arrays
C> within the NCEPLIBS-bufr software, and that subsequent calls can
C> immediately be made to any of the various
C> [values-reading subroutines](@ref hierarchy).
C>
C> Note that the value specified for IMSG should not include any
C> DX BUFR table messages which may be present in the file.
C> In other words, a value of 12 for IMSG means to read the 12th
C> message which contains actual report data.
C>
C> @param[in] LUNIT - integer: Fortran logical unit number for BUFR file.
C> @param[in] IMSG - integer: Number of BUFR message to be read from the
C> BUFR file, counting from the beginning of the file, but <b>not</b>
C> counting any DX BUFR table messages which may be present in the file
C> @param[in] ISUB - integer: Number of data subset to be read from the
C> (IMSG)th BUFR message, counting from the beginning of the message
C>
C> @author J. Woollen @date 2003-11-04
      RECURSIVE SUBROUTINE rdmgsb(LUNIT,IMSG,ISUB)
 
      USE moda_msgcwd
      USE moda_bitbuf
      USE modv_im8b
 
      CHARACTER*128 bort_str
      CHARACTER*8   subset
 
C-----------------------------------------------------------------------
C-----------------------------------------------------------------------
 
C  CHECK FOR I8 INTEGERS
C  ---------------------
      IF(im8b) THEN
         im8b=.false.
 
         CALL x84(lunit,my_lunit,1)
         CALL x84(imsg,my_imsg,1)
         CALL x84(isub,my_isub,1)
         CALL rdmgsb(my_lunit,my_imsg,my_isub)
 
         im8b=.true.
         RETURN
      ENDIF
 
C  OPEN THE FILE AND SKIP TO MESSAGE # IMSG
C  ----------------------------------------
 
      CALL openbf(lunit,'IN',lunit)
      CALL status(lunit,lun,il,im)
 
C     Note that we need to use subroutine READMG to actually read in all
C     of the messages (including the first (IMSG-1) messages!), just in
C     case there are any embedded dictionary messages in the file.
 
      DO i=1,imsg
        CALL readmg(lunit,subset,jdate,iret)
        IF(iret.LT.0) GOTO 901
      ENDDO
 
C  POSITION AT SUBSET # ISUB
C  -------------------------
 
      DO i=1,isub
        CALL readsb(lunit,iret)
        IF(iret.LT.0) GOTO 902
      ENDDO
 
C  EXITS
C  -----
 
      RETURN
901   WRITE(bort_str,'("BUFRLIB: RDMGSB - HIT END OF FILE BEFORE '//
     . 'READING REQUESTED MESSAGE NO.",I5," IN BUFR FILE CONNECTED TO'//
     . ' UNIT",I4)')  imsg,lunit
      CALL bort(bort_str)
902   WRITE(bort_str,'("BUFRLIB: RDMGSB - ALL SUBSETS READ BEFORE '//
     . 'READING REQ. SUBSET NO.",I3," IN REQ. MSG NO.",I5," IN BUFR '//
     . 'FILE CONNECTED TO UNIT",I4)') isub,imsg,lunit
      CALL bort(bort_str)
      END