NCEPLIBS-bufr  11.6.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:

Date Programmer Comments
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 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; modified with semantic adjustments to ameliorate compiler complaints from Linux boxes
2000-09-19 J. Woollen Removed 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)
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 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 73 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().