NCEPLIBS-bufr  12.1.0
readwritemg.F90 File Reference

Read or write a BUFR message. More...

Go to the source code of this file.

Functions/Subroutines

recursive subroutine closmg (lunin)
 Close the BUFR message that is currently open for writing within internal arrays associated with logical unit abs(lunin), then write the message to that logical unit. More...
 
recursive subroutine cnved4 (msgin, lmsgot, msgot)
 Convert a BUFR edition 3 message to BUFR edition 4. More...
 
recursive subroutine getlens (mbay, ll, len0, len1, len2, len3, len4, len5)
 Read the section lengths of a BUFR message, up to a specified point in the message. More...
 
recursive integer function ifbget (lunit)
 Check whether there are any more data subsets available to be read from a BUFR message. More...
 
integer function igetmxby ()
 Get the maximum length of a BUFR message that can be written to an output file by the NCEPLIBS-bufr software. More...
 
recursive integer function ireadmg (lunit, subset, idate)
 Call subroutine readmg() and pass back its return code as the function value. More...
 
integer function lmsg (sec0)
 Given a character string containing Section 0 from a BUFR message, determine the array size (in integers) needed to store the entire BUFR message. More...
 
recursive subroutine maxout (maxo)
 Specify the maximum length of a BUFR message that can be written to any output file by the NCEPLIBS-bufr software. More...
 
logical function msgfull (msiz, itoadd, mxsiz)
 Check whether the current data subset in the internal arrays will fit within the current BUFR message in the internal arrays, based on the prescribed maximum size of a BUFR message and the allowance of some extra "wiggle room" that may be needed later when writing out the message. More...
 
subroutine msgini (lun)
 Initialize, within the internal arrays, a new uncompressed BUFR message for output. More...
 
subroutine msgwrt (lunit, mesg, mgbyt)
 Perform final checks and updates on a BUFR message before writing it to a specified Fortran logical unit. More...
 
recursive integer function nmsub (lunit)
 Get the total number of data subsets available within the BUFR message that was most recently opened for reading via a call to one of the message-reading subroutines for a specified Fortran logical unit. More...
 
integer function nmwrd (mbay)
 Given an integer array containing Section 0 from a BUFR message, determine the array size (in integers) needed to store the entire BUFR message. More...
 
recursive subroutine openmb (lunit, subset, jdate)
 Open and initialize a new BUFR message within internal arrays, for eventual output to logical unit lunit. More...
 
recursive subroutine openmg (lunit, subset, jdate)
 Open and initialize a new BUFR message within internal arrays, for eventual output to logical unit lunit. More...
 
subroutine padmsg (mesg, lmesg, npbyt)
 Pad a BUFR message with zeroed-out bytes from the end of the message up to the next 8-byte boundary. More...
 
subroutine rdmsgw (lunit, mesg, iret)
 Read the next BUFR message from logical unit lunit as an array of integer words. More...
 
recursive subroutine readerme (mesg, lunit, subset, jdate, iret)
 Read a BUFR message from a memory array. More...
 
recursive subroutine readmg (lunxx, subset, jdate, iret)
 Read the next BUFR message from logical unit abs(lunxx) into internal arrays. More...
 

Detailed Description

Read or write a BUFR message.

Authors
J. Woollen, J. Ator
Date
1994-01-06

Definition in file readwritemg.F90.

Function/Subroutine Documentation

◆ closmg()

recursive subroutine closmg ( integer, intent(in)  lunin)

Close the BUFR message that is currently open for writing within internal arrays associated with logical unit abs(lunin), then write the message to that logical unit.

Logical unit abs(lunin) should have already been opened for output operations via a previous call to subroutine openbf().

If lunin < 0, then any message containing zero data subsets will not be written to logical unit abs(lunin) for the remainder of the life of the application program. This includes suppressing the writing of any "dummy" messages containing dump center and initiation times that normally appear in the first 2 messages of NCEP dump files.

Parameters
lunin- Absolute value is Fortran logical unit number for BUFR file
Author
J. Woollen, D. Keyser
Date
1994-01-06

Definition at line 532 of file readwritemg.F90.

References bort(), moda_bitbuf::mbay, moda_bitbuf::mbyt, moda_msglim::msglim, msgwrt(), moda_msgcwd::nmsg, moda_msgcwd::nsub, status(), wrcmps(), wtstat(), and x84().

Referenced by closbf(), makestab(), openmb(), openmg(), and writsa().

◆ cnved4()

recursive subroutine cnved4 ( integer, dimension(*), intent(in)  msgin,
integer, intent(in)  lmsgot,
integer, dimension(*), intent(out)  msgot 
)

Convert a BUFR edition 3 message to BUFR edition 4.

This subroutine reads an input BUFR message encoded using BUFR edition 3, then outputs an equivalent BUFR message encoded using BUFR edition 4.

This subroutine performs the same function as subroutine pkvs01() when the latter is called with s01mnem = 'BEN' and ival = 4, except that the latter subroutine operates on BUFR messages internally within the software, whereas this subroutine operates on a single BUFR message passed in via a memory array.

Parameters
msgin- BUFR message
lmsgot- Dimensioned size (in integers) of msgot; used by the subroutine to ensure that it doesn't overflow the msgot array
msgot- Copy of msgin encoded using BUFR edition 4
Remarks
  • msgin and msgot must be separate arrays.
  • BUFR edition 4 messages are usually longer in length than their BUFR edition 3 counterparts, so it's usually a good idea to allow for extra space when allocating msgot within the application program.
Author
J. Ator
Date
2005-11-29

Definition at line 1292 of file readwritemg.F90.

References bort(), getlens(), iupbs01(), mvb(), nmwrd(), pkb(), and x84().

Referenced by msgwrt().

◆ getlens()

recursive subroutine getlens ( integer, dimension(*), intent(in)  mbay,
integer, intent(in)  ll,
integer, intent(out)  len0,
integer, intent(out)  len1,
integer, intent(out)  len2,
integer, intent(out)  len3,
integer, intent(out)  len4,
integer, intent(out)  len5 
)

Read the section lengths of a BUFR message, up to a specified point in the message.

This subroutine will work on any BUFR message encoded using BUFR edition 2, 3, or 4.

Parameters
mbay- BUFR message
ll- Number of last section for which the length is to be read. In other words, setting ll = N means to read and return the lengths of Sections 0 through N (i.e. len0, len1,...,lenN). Any section lengths that are not specified to be read are returned with a default placeholder value of -1.
len0- Length (in bytes) of Section 0
len1- Length (in bytes) of Section 1
len2- Length (in bytes) of Section 2
len3- Length (in bytes) of Section 3
len4- Length (in bytes) of Section 4
len5- Length (in bytes) of Section 5
Remarks
  • The start of the BUFR message (i.e. the string 'BUFR') must be aligned on the first 4 bytes of mbay.
Author
J. Ator
Date
2005-11-29

Definition at line 1212 of file readwritemg.F90.

References iupb(), iupbs01(), x48(), and x84().

Referenced by atrcpt(), cktaba(), cnved4(), copysb(), iupbs3(), msgwrt(), stbfdx(), stndrd(), upds3(), wrdxtb(), and writlc().

◆ ifbget()

recursive integer function ifbget ( integer, intent(in)  lunit)

Check whether there are any more data subsets available to be read from a BUFR message.

The message that will checked is the one that's currently open for reading via the most recent call to any of the message-reading subroutines for the specified Fortran logical unit.

Parameters
lunit- Fortran logical unit number for BUFR file
Returns
ifbget - Return code:
  • 0 = there's at least one more data subset to be read from the message
  • -1 = there are no more data subsets to be read from the message
Author
J. Woollen
Date
1994-01-06

Definition at line 1401 of file readwritemg.F90.

References bort(), moda_msgcwd::msub, moda_msgcwd::nsub, status(), and x84().

◆ igetmxby()

integer function igetmxby

Get the maximum length of a BUFR message that can be written to an output file by the NCEPLIBS-bufr software.

Returns
igetmxby - Maximum length of a BUFR message that can be written to an output file by the NCEPLIBS-bufr software

This maximum length value can be changed at any time via a separate call to subroutine maxout().

Author
J. Ator
Date
2016-06-27

Definition at line 1034 of file readwritemg.F90.

References moda_bitbuf::maxbyt.

Referenced by bufr_c2f_interface::igetmxby_c().

◆ ireadmg()

recursive integer function ireadmg ( integer, intent(in)  lunit,
character*8, intent(out)  subset,
integer, intent(out)  idate 
)

Call subroutine readmg() and pass back its return code as the function value.

The use of this function allows the return code from readmg() to be used as the target variable within an iterative program loop.

Parameters
lunit- Fortran logical unit number for BUFR file
subset- Table A mnemonic for type of BUFR message that was read (see DX BUFR Tables for further information about Table A mnemonics)
idate- 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()
Returns
ireadmg - 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 lunit
Author
J. Woollen
Date
1994-01-06

Definition at line 143 of file readwritemg.F90.

References readmg(), x48(), and x84().

Referenced by binv(), bufr_c2f_interface::ireadmg_c(), readbp(), readmp(), split_by_subset(), and ufbtab().

◆ lmsg()

integer function lmsg ( character*8, intent(in)  sec0)

Given a character string containing Section 0 from a BUFR message, determine the array size (in integers) needed to store the entire BUFR message.

This function is similar to function nmwrd(), except that it takes a character string as input rather than an integer array.

Parameters
sec0- Section 0 from a BUFR message
Returns
lmsg - Array size (in integers) needed to store entire BUFR message
Remarks
  • In some cases, the value returned may be slightly larger than the minimum number of integers needed to store the entire BUFR message.
Author
J. Woollen
Date
1994-01-06

Definition at line 1176 of file readwritemg.F90.

References nmwrd().

Referenced by readerme().

◆ maxout()

recursive subroutine maxout ( integer, intent(in)  maxo)

Specify the maximum length of a BUFR message that can be written to any output file by the NCEPLIBS-bufr software.

This subroutine can be called from within an application program at any time after the initial call to subroutine openbf(), and the specified value maxo will then be used for all future BUFR messages written by the software to all output files for the remainder of the program, unless another call is made to this same subroutine to reset the value of maxo again. Otherwise, if this subroutine is never called, a default maximum message length is used for all output files, as set via an initial internal call to subroutine bfrini().

Parameters
maxo- New maximum length (in bytes) for all BUFR messages written to all output files
  • 0 = Set maxo to the maximum value allowed by the NCEPLIBS-bufr software
Authors
J. Woollen, J. Ator
Date
2002-05-14

Definition at line 974 of file readwritemg.F90.

References errwrt(), moda_bitbuf::maxbyt, and x84().

Referenced by bufr_c2f_interface::maxout_c(), and split_by_subset().

◆ msgfull()

logical function msgfull ( integer, intent(in)  msiz,
integer, intent(in)  itoadd,
integer, intent(in)  mxsiz 
)

Check whether the current data subset in the internal arrays will fit within the current BUFR message in the internal arrays, based on the prescribed maximum size of a BUFR message and the allowance of some extra "wiggle room" that may be needed later when writing out the message.

Parameters
msiz- Size (in bytes) of current BUFR message
itoadd- Size (in bytes) of current data subset
mxsiz- Maximum size of a BUFR message
Returns
msgfull - Flag indicating whether the current data subset will fit within the current BUFR message
Author
J. Ator
Date
2009-03-23

Definition at line 917 of file readwritemg.F90.

References moda_msgstd::csmf, and moda_tnkrcp::ctrt.

Referenced by wrdxtb().

◆ msgini()

subroutine msgini ( integer, intent(in)  lun)

Initialize, within the internal arrays, a new uncompressed BUFR message for output.

Arrays are filled in common block msgptr and modules moda_msgcwd and moda_bitbuf.

Parameters
lun- file ID
Author
Woollen
Date
1994-01-06

Definition at line 777 of file readwritemg.F90.

References bort(), moda_msgcwd::idate, moda_msgcwd::inode, moda_ufbcpl::luncpy, moda_bitbuf::mbay, moda_bitbuf::mbyt, nemtab(), nemtba(), moda_msgcwd::nmsg, moda_msgcwd::nsub, pkb(), pkc(), and moda_tables::tag.

Referenced by cpyupd(), msgupd(), openmb(), and openmg().

◆ msgwrt()

subroutine msgwrt ( integer, intent(in)  lunit,
integer, dimension(*), intent(in)  mesg,
integer, intent(in)  mgbyt 
)

Perform final checks and updates on a BUFR message before writing it to a specified Fortran logical unit.

These final checks and updates include:

  • Standardizing the BUFR message, if requested via a previous call subroutine stdmsg()
  • Converting the BUFR message from edition 3 to edition 4, if requested via a previous call to subroutine pkvs01()
  • Storing any customized values into Section 0 or Section 1 of the BUFR message, if requested via one or more previous calls to subroutine pkvs01()
  • Storing a tank receipt time into Section 1 of the BUFR message, if requested via a previous call to subroutine strcpt()
  • For edition 3 BUFR messages, ensuring each section of the message contains an even number of bytes
  • Storing '7777' into the last four bytes of the BUFR message, and storing the final message length in Section 0
  • Appending zeroed-out bytes after the end of the BUFR message, up to the next machine word boundary
  • Encapsulating the BUFR message with IEEE Fortran control words, if requested via a previous call to subroutine setblock()
  • Storing a copy of the final message into internal arrays for possible later retrival via subroutine writsa()
Parameters
lunit- Fortran logical unit number for BUFR file
mesg- BUFR message
mgbyt- Size (in bytes) of BUFR message
Author
J. Woollen
Date
1994-01-06

Definition at line 597 of file readwritemg.F90.

References atrcpt(), blocks(), bort(), moda_s01cm::cmnem, cnved4(), moda_msgstd::csmf, moda_tnkrcp::ctrt, errwrt(), getlens(), moda_s01cm::ivmnem, moda_mgwa::mgwa, moda_mgwb::mgwb, moda_bufrmg::msglen, moda_bufrmg::msgtxt, moda_s01cm::ns01v, moda_nulbfr::null, padmsg(), pkb(), pkbs1(), pkc(), status(), and stndrd().

Referenced by closmg(), copybf(), copymg(), cpymem(), cpyupd(), msgupd(), wrcmps(), and wrdxtb().

◆ nmsub()

recursive integer function nmsub ( integer, intent(in)  lunit)

Get the total number of data subsets available within the BUFR message that was most recently opened for reading via a call to one of the message-reading subroutines for a specified Fortran logical unit.

The data subsets themselves do not need to have already been read via previous calls to any of the subset-reading subroutines.

Parameters
lunit- Fortran logical unit number for BUFR file
Returns
nmsub - Number of data subsets
Author
J. Woollen
Date
1994-01-06

Definition at line 1094 of file readwritemg.F90.

References bort(), moda_msgcwd::msub, status(), and x84().

Referenced by binv(), split_by_subset(), ufbmns(), ufbtab(), and ufbtam().

◆ nmwrd()

integer function nmwrd ( integer, dimension(*), intent(in)  mbay)

Given an integer array containing Section 0 from a BUFR message, determine the array size (in integers) needed to store the entire BUFR message.

This function is similar to function lmsg(), except that it takes an integer array as input rather than a character string.

Parameters
mbay- Section 0 from a BUFR message
Returns
nmwrd - Array size (in integers) needed to store entire BUFR message
Remarks
  • In some cases, the value returned may be slightly larger than the minimum number of integers needed to store the entire BUFR message.
Author
J. Ator
Date
2005-11-29

Definition at line 1144 of file readwritemg.F90.

References iupbs01().

Referenced by cnved4(), lmsg(), ufbmem(), and ufbmex().

◆ openmb()

recursive subroutine openmb ( integer, intent(in)  lunit,
character*(*), intent(in)  subset,
integer, intent(in)  jdate 
)

Open and initialize a new BUFR message within internal arrays, for eventual output to logical unit lunit.

Logical unit lunit should have already been opened for output operations via a previous call to subroutine openbf().

This subroutine is similar to subroutine openmg(), except that it will only open a new message if either subset or jdate has changed since the previous call to this subroutine. Otherwise, it will leave the existing internal message unchanged so that the next data subset can be written into the same internal message, thereby improving overall storage efficiency by allowing the maximum number of data subsets to be stored within each output BUFR message. For this reason, openmb() is much more widely used than openmg().

If this subroutine does need to open and initialize a new BUFR message for output (e.g. if the value of subset or jdate has changed since the previous call to this subroutine), then any existing message within the internal arrays will be automatically flushed and written to logical unit lunit via an internal call to subroutine closmg(). In this case, the behavior of this subroutine then becomes exactly like that of subroutine openmg().

Parameters
lunit- Fortran logical unit number for BUFR file
subset- Table A mnemonic for type of BUFR BUFR message to be opened (see DX BUFR Tables for further information about Table A mnemonics)
jdate- Date-time to be stored within Section 1 of BUFR message being opened, in format of either YYMMDDHH or YYYYMMDDHH
Author
J. Woollen
Date
1994-01-06

Definition at line 396 of file readwritemg.F90.

References bort(), closmg(), i4dy(), moda_msgcwd::idate, moda_msgcwd::inode, msgini(), nemtba(), status(), usrtpl(), wtstat(), and x84().

Referenced by bufr_c2f_interface::openmb_c().

◆ openmg()

recursive subroutine openmg ( integer, intent(in)  lunit,
character*(*), intent(in)  subset,
integer, intent(in)  jdate 
)

Open and initialize a new BUFR message within internal arrays, for eventual output to logical unit lunit.

Logical unit lunit should have already been opened for output operations via a previous call to subroutine openbf().

This subroutine is similar to subroutine openmb(), except that it will always open a new message for output, regardless of the values of subset and jdate. Any existing message within the internal arrays will be automatically flushed and written to logical unit lunit via an internal call to subroutine closmg().

Parameters
lunit- Fortran logical unit number for BUFR file
subset- Table A mnemonic for type of BUFR message to be opened (see DX BUFR Tables for further information about Table A mnemonics)
jdate- Date-time to be stored within Section 1 of BUFR message being opened, in format of either YYMMDDHH or YYYYMMDDHH
Author
J. Woollen
Date
1994-01-06

Definition at line 468 of file readwritemg.F90.

References bort(), closmg(), i4dy(), moda_msgcwd::idate, moda_msgcwd::inode, msgini(), nemtba(), status(), usrtpl(), wtstat(), and x84().

◆ padmsg()

subroutine padmsg ( integer, dimension(*), intent(inout)  mesg,
integer, intent(in)  lmesg,
integer, intent(out)  npbyt 
)

Pad a BUFR message with zeroed-out bytes from the end of the message up to the next 8-byte boundary.

Parameters
mesg- BUFR message:
  • on input, contains BUFR message to be padded
  • on output, contains BUFR message with npbyt zeroed-out bytes appended to the end
lmesg- Dimensioned size (in integer words) of mesg; used by the subroutine to ensure that it does not overflow the mesg array
npbyt- Number of zeroed-out bytes appended to mesg
Author
Ator
Date
2005-11-29

Definition at line 1055 of file readwritemg.F90.

References bort(), and pkb().

Referenced by msgwrt().

◆ rdmsgw()

subroutine rdmsgw ( integer, intent(in)  lunit,
integer, dimension(*), intent(out)  mesg,
integer, intent(out)  iret 
)

Read the next BUFR message from logical unit lunit as an array of integer words.

Parameters
lunit- Fortran logical unit number for BUFR file.
mesg- BUFR message.
iret- return code:
  • 0 normal return.
  • -1 end-of-file encountered while reading from lunit.
Author
J. Ator
Date
2005-11-29

Definition at line 344 of file readwritemg.F90.

References errwrt(), and status().

Referenced by copybf(), cpdxmm(), datebf(), dumpbf(), mesgbc(), mesgbf(), posapx(), rdbfdx(), readmg(), ufbmem(), and ufbmex().

◆ readerme()

recursive subroutine readerme ( integer, dimension(*), intent(in)  mesg,
integer, intent(in)  lunit,
character*8, intent(out)  subset,
integer, intent(out)  jdate,
integer, intent(out)  iret 
)

Read a BUFR message from a memory array.

This subroutine is similar to subroutine readmg(), except that it reads a BUFR message from an array passed as input, whereas readmg() reads a BUFR message from a file on the local system.

This subroutine can be used in any context in which readmg() might otherwise be used, and from that point on, the application program can proceed with a call to one of the subset-reading subroutines (and then, subsequently, to any of the values-reading subroutines).

When using this subroutine, it's necessary for the application program to have previously called subroutine openbf() in order to associate a DX BUFR tables file with the message that is being input via mesg; it's also necessary to pass in the relevant lunit value as a call argument, even though in this case the subroutine will not actually try to read from the associated Fortran logical unit.

If mesg contains a DX BUFR table message, the subroutine will store the contents internally and use them to process any future BUFR messages associated with lunit. In this case, the subroutine will return with iret = 11, and any number of DX BUFR table messages passed in via consecutive calls to this subroutine will accumulate internally and be treated as a single DX BUFR table, up until a call is made where mesg no longer contains a DX BUFR table message.

Parameters
mesg- BUFR message
lunit- Fortran logical unit number for BUFR file
subset- Table A mnemonic for type of BUFR message that was read (see DX BUFR Tables or further information about Table A mnemonics)
jdate- 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()
iret- return code:
  • 0 mesg was successfully read
  • 11 mesg contained a DX BUFR table message
  • -1 mesg contained an unrecognized Table A message type
Authors
J. Woollen J. Ator
Date
1995-06-28

Definition at line 216 of file readwritemg.F90.

References bort(), cktaba(), dxinit(), errwrt(), moda_idrdm::idrdm, idxmsg(), moda_sc3bfr::isc3, iupbs3(), lmsg(), makestab(), moda_bitbuf::mbay, reads3(), status(), stbfdx(), wtstat(), x48(), and x84().

Referenced by fdebufr_c().

◆ readmg()

recursive subroutine readmg ( integer, intent(in)  lunxx,
character*8, intent(out)  subset,
integer, intent(out)  jdate,
integer, intent(out)  iret 
)

Read 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().

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 NCEPLIBS-bufr 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 NCEPLIBS-bufr 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.
Parameters
lunxx- Absolute value is Fortran logical unit number for BUFR file
subset- Table A mnemonic for type of BUFR message that was read (see DX BUFR Tables for further information about Table A mnemonics)
jdate- 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()
iret- 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)
Authors
J. Woollen, J. Ator
Date
1994-01-06

Definition at line 43 of file readwritemg.F90.

References bort(), cktaba(), errwrt(), moda_msgcwd::idate, idxmsg(), moda_msgcwd::inode, moda_sc3bfr::isc3, moda_bitbuf::mbay, rdbfdx(), rdmsgw(), reads3(), status(), wtstat(), x48(), and x84().

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