NCEPLIBS-bufr  11.5.0
 All Data Structures Files Functions Variables Pages
readmg.f File Reference

Read the next message from a BUFR file that was previously opened for reading. More...

Go to the source code of this file.

Functions/Subroutines

subroutine readmg (LUNXX, SUBSET, JDATE, IRET)
 This subroutine reads the next BUFR message from logical unit ABS(LUNXX) into internal arrays. More...
 

Detailed Description

Read the next message from a BUFR file that was previously opened for reading.

Definition in file readmg.f.

Function/Subroutine Documentation

subroutine readmg (   LUNXX,
character*8  SUBSET,
  JDATE,
  IRET 
)

This subroutine reads the next BUFR message from logical unit ABS(LUNXX) into internal arrays.

Logical unit ABS(LUNXX) should have already been opened for input operations via a previous call to subroutine openbf().

Authors
J. Woollen
J. Ator
Date
1994-01-06
Parameters
[in]LUNXX- integer: Absolute value is Fortran logical unit number for BUFR file
[out]SUBSET- character*8: Table A mnemonic for type of BUFR message that was read (see DX BUFR Tables for further information about Table A mnemonics)
[out]JDATE- integer: Date-time stored within Section 1 of BUFR message that was read, in format of either YYMMDDHH or YYYYMMDDHH, depending on the most recent call to subroutine datelen()
[out]IRET- integer: return code
  • 0 = new BUFR message was successfully read into internal arrays
  • -1 = there are no more BUFR messages in the file connected to logical unit ABS(LUNXX)

Whenever this subroutine returns with IRET = 0, this indicates that a new BUFR message of type SUBSET and date-time JDATE was successfully read into internal arrays within the BUFRLIB software, and from where it can then be easily manipulated or further parsed via a call to one of the subset-reading subroutines. Otherwise, if the subroutine returns with IRET = -1, then this indicates that there are no more BUFR messages (i.e. end-of-file) within the file connected to logical unit ABS(LUNXX).

Remarks
  • Any DX BUFR table messages encountered within ABS(LUNXX) will be automatically processed and stored internally, so a successful return from this subroutine will always result in a BUFR message containing actual data values within the internal arrays.
  • In prior versions of the BUFRLIB software, an input value of LUNXX < 0 was an indicator to the subroutine to treat any read error from ABS(LUNXX) the same as an end-of-file condition. This option is no longer supported, but the capability to call this subroutine with LUNXX < 0 is itself still supported for backwards-compatibility with certain legacy application programs.

Program history log:

  • 1994-01-06 J. Woollen – Original author
  • 1996-11-25 J. Woollen – Modified to exit gracefully when the BUFR file is positioned after an "end-of-file"
  • 1998-07-08 J. Woollen – Replaced call to Cray library routine "ABORT" with call to new internal BUFRLIB routine "BORT"; modified to make Y2K compliant
  • 1999-11-18 J. Woollen – The number of BUFR files which can be opened at one time increased from 10 to 32 (necessary in order to process multiple BUFR files under the MPI); modified with semantic adjustments to ameliorate compiler complaints from Linux boxes (increases portability)
  • 2000-09-19 J. Woollen – Removed message decoding logic that had been replicated in this and other read routines and consolidated it into a new routine cktaba(); maximum message length increased from 10,000 to 20,000 bytes
  • 2002-05-14 J. Woollen – Removed entry point datelen() (it became a separate routine in the BUFRLIB to increase portability to other platforms)
  • 2003-11-04 J. Ator – Added documentation
  • 2003-11-04 S. Bender – Added remarks and routine interdependencies
  • 2003-11-04 D. Keyser – Unified/portable for WRF; added history documentation; outputs more complete diagnostic info when routine terminates abnormally
  • 2004-08-09 J. Ator – Maximum message length increased from 20,000 to 50,000 bytes
  • 2005-11-29 J. Ator – Added rdmsgw() and rdmsgb calls to simulate readibm; added LUNXX < 0 option to simulate readft
  • 2009-03-23 J. Ator – Add logic to allow Section 3 decoding; add logic to process internal dictionary messages
  • 2012-06-07 J. Ator – Don't respond to internal dictionary messages if Section 3 decoding is being used
  • 2012-09-15 J. Woollen – Convert to C language I/O interface; remove code to reread message as bytes; replace Fortran BACKSPACE with C backbufr()
  • 2014-12-10 J. Ator – Use modules instead of COMMON blocks

Definition at line 99 of file readmg.f.

References backbufr(), bort(), cktaba(), errwrt(), idxmsg(), rdbfdx(), rdmsgw(), reads3(), status(), and wtstat().

Referenced by ireadmg(), rdmgsb(), readns(), rewnbf(), ufbinx(), and ufbpos().