Read or write a BUFR data subset. More...

Functions/Subroutines
recursive subroutine	invmrg (lubfi, lubfj)
	Merge parts of data subsets which have duplicate space and time coordinates but different or unique observational data. More...

recursive integer function	ireadns (lunit, subset, idate)
	Call subroutine readns() and pass back its return code as the function value. More...

recursive integer function	ireadsb (lunit)
	Call subroutine readsb() and pass back its return code as the function value. More...

recursive integer function	lcmgdf (lunit, subset)
	Check whether the subset definition for a given message type contains any long character strings (greater than 8 bytes). More...

subroutine	msgupd (lunit, lun)
	Write an uncompressed BUFR data subset. More...

integer function	nwords (n, lun)
	Compute the length of a specified delayed replication sequence within a data subset. More...

subroutine	pad (ibay, ibit, ibyt, ipadb)
	Pad a BUFR data subset with zeroed-out bits up to the next byte boundary. More...

subroutine	rcstpl (lun, iret)
	Initialize a subset template within internal arrays. More...

recursive subroutine	rdmgsb (lunit, imsg, isub)
	Read a specified data subset from a BUFR file. More...

subroutine	rdtree (lun, iret)
	Read the next uncompressed BUFR data subset into internal arrays. More...

recursive subroutine	readns (lunit, subset, jdate, iret)
	Read the next data subset from a BUFR file. More...

recursive subroutine	readsb (lunit, iret)
	Read the next data subset from a BUFR message. More...

recursive subroutine	ufbpos (lunit, irec, isub, subset, jdate)
	Jump forwards or backwards to a specified data subset within a BUFR file. More...

subroutine	usrtpl (lun, invn, nbmp)
	Expand a subset template within internal arrays. More...

recursive subroutine	writsa (lunxx, lmsgt, msgt, msgl)
	Write a complete data subset into a BUFR message, and return each completed message within a memory array. More...

recursive subroutine	writsb (lunit)
	Write a complete data subset into a BUFR message, for eventual output to logical unit lunit. More...

subroutine	wrtree (lun)
	Pack a BUFR data subset. More...

Detailed Description

Read or write a BUFR data subset.

Author: J. Woollen

Date: 1994-01-06

Definition in file readwritesb.F90.

Function/Subroutine Documentation

◆ invmrg()

recursive subroutine invmrg	(	integer, intent(in)	lubfi,
		integer, intent(in)	lubfj
	)

Merge parts of data subsets which have duplicate space and time coordinates but different or unique observational data.

Parameters

lubfi	- Fortran logical unit number for input BUFR file
lubfj	- Fortran logical unit number for output BUFR file

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

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

Remarks

This subroutine cannot merge parts of data subsets which are contained within replication sequences.

Author: J. Woollen

Date: 1996-10-09

Definition at line 1497 of file readwritesb.F90.

References bort(), ibfms(), moda_usrint::inv, moda_tables::itp, moda_usrint::nval, nwords(), status(), moda_tables::typ, moda_usrint::val, and x84().

◆ ireadns()

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

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

The use of this function allows the return code from readns() 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 data subset that was read (see DX BUFR Tables for further information about Table A mnemonics)
idate	- Date-time stored within Section 1 of BUFR message containing data subset that was read, in format of either YYMMDDHH or YYYYMMDDHH, depending on the most recent call to subroutine datelen()

Returns

ireadns - return code:

0 = new BUFR data subset was successfully read into internal arrays
-1 = there are no more BUFR data subsets in the file connected to logical unit lunit

Author: J. Woollen

Date: 1994-01-06

Definition at line 238 of file readwritesb.F90.

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

Referenced by bufr_c2f_interface::ireadns_c().

◆ ireadsb()

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

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

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

Parameters

lunit - Fortran logical unit number for BUFR file

Returns

ireadsb - return code:

0 = new BUFR data subset was successfully read into internal arrays
-1 = there are no more BUFR data subsets in the BUFR message

Author: J. Woollen

Date: 1994-01-06

Definition at line 116 of file readwritesb.F90.

References readsb(), and x84().

Referenced by bufr_c2f_interface::ireadsb_c(), readbp(), readmp(), and ufbtab().

◆ lcmgdf()

recursive integer function lcmgdf	(	integer, intent(in)	lunit,
		character*8, intent(in)	subset
	)

Check whether the subset definition for a given message type contains any long character strings (greater than 8 bytes).

Parameters

lunit	- Fortran logical unit number for BUFR file
subset	- Table A mnemonic of message type to be checked

Returns

lcmgdf - Return code:

0 = subset does not contain any long character strings
1 = subset contains at least one long character string

Remarks

lunit may be open for either input or output operations via a previous call to subroutine openbf(). However, in either case, subset must already be defined within the BUFR tables that are associated with lunit, typically as DX BUFR tables information supplied via argument lundx when openbf() was called, or, if openbf() was called with IO = 'SEC3', then as master BUFR table information during a previous call to one of the message-reading subroutines.
Note that this function does not return mnemonic(s) associated with any long character string(s) found within subset; rather, it only checks whether at least one such mnemonic exists. If any are found, the application program can process them via a separate call to subroutine readlc() (when reading BUFR data subsets) or subroutine writlc() (when writing BUFR data subsets).

Author: J. Ator

Date: 2009-07-09

Definition at line 803 of file readwritesb.F90.

References bort(), moda_tables::ibt, moda_tables::isc, nemtba(), status(), moda_tables::typ, and x84().

◆ msgupd()

subroutine msgupd	(	integer, intent(in)	lunit,
		integer, intent(in)	lun
	)

Write an uncompressed BUFR data subset.

Pack up the current subset within memory (array ibay in module moda_bitbuf), then try to add it to the uncompressed BUFR message that is currently open within memory for LUNIT (array mbay in module moda_bitbuf). If the subset will not fit into the currently open message, or if the subset byte count exceeds 65530 (sufficiently close to the 16-bit byte counter upper limit of 65535), then that message is flushed to lunit and a new one is created in order to hold the current subset. Any subset with byte count > 65530 will be written into its own one-subset message. if the current subset is larger than the maximum message length, then the subset is discarded and a diagnostic is printed.

Parameters

lunit	- Fortran logical unit number for BUFR file.
lun	- File ID associated with lunit

Author: Woollen

Date: 1994-01-06

Definition at line 612 of file readwritesb.F90.

References moda_h4wlc::chh4wlc, errwrt(), moda_bitbuf::ibay, moda_bitbuf::ibit, moda_h4wlc::luh4wlc, moda_bitbuf::maxbyt, moda_bitbuf::mbay, moda_bitbuf::mbyt, msgini(), msgwrt(), mvb(), moda_h4wlc::nh4wlc, moda_msgcwd::nsub, pad(), pkb(), moda_h4wlc::sth4wlc, usrtpl(), and writlc().

Referenced by writsa(), and writsb().

◆ nwords()

integer function nwords	(	integer, intent(in)	n,
		integer, intent(in)	lun
	)

Compute the length of a specified delayed replication sequence within a data subset.

Parameters

n	- Starting index of delayed replication sequence
lun	- File ID

Returns: Complete length of delayed replication sequence within data subset

Author: Woollen

Date: 1996-10-09

Definition at line 1605 of file readwritesb.F90.

References moda_usrint::val.

Referenced by invmrg().

◆ pad()

subroutine pad	(	integer, dimension(*), intent(inout)	ibay,
		integer, intent(inout)	ibit,
		integer, intent(out)	ibyt,
		integer, intent(in)	ipadb
	)

Pad a BUFR data subset with zeroed-out bits up to the next byte boundary.

Pack the value for the number of bits being "padded", starting with bit ibit+1 and using eight bits in the packed array ibay (which represents a subset packed into ibit bits). Then, starting with ibit+9, pack zeroes (i.e., "pads") to the specified bit boundary (ipadb).

Note that it's the number of bits padded here that was packed in bits ibit+1 through ibit+8 - this is actually a delayed replication factor! ipadb must be a multiple of eight and represents the bit boundary on which the packed subset in ibay should end after padding. For example, if ipadb is "8", then the number of bits in ibay actually consumed by packed data (including the padding) will be a multiple of eight. If ipadb is "16", it will be a multiple of sixteen. in either (or any) case, this ensures that the packed subset will always end on a full byte boundary.

Parameters

ibay	- BUFR data subset: on input, contains BUFR data subset to be padded on output, contains BUFR data subset padded with zeroed-out bits up to ipadb
ibit	- Bit pointer: on input, contains bit pointer within ibay after which to begin padding on output, contains bit pointer within ibay to last bit that was padded
ibyt	- Number of bytes within ibay containing packed data, including padding
ipadb	- Bit boundary to pad to (must be a multiple of 8)

Author: Woollen

Date: 1994-01-06

Definition at line 749 of file readwritesb.F90.

References bort(), and pkb().

Referenced by msgupd().

◆ rcstpl()

subroutine rcstpl	(	integer, intent(in)	lun,
		integer, intent(out)	iret
	)

Initialize a subset template within internal arrays.

Initialize space in internal subset arrays in modules moda_usrint and moda_usrbit, according to the subset definition from subroutine makestab(). This is in preparation for the actual unpacking of the subset in subroutine rdtree().

Parameters

lun	- File ID
iret	- Return code: 0 = Normal return -1 = An error occurred, possibly due to a corrupt subset in the input message

Author: Woollen

Date: 1994-01-06

Definition at line 1155 of file readwritesb.F90.

References bort(), errwrt(), moda_tables::ibt, moda_msgcwd::inode, moda_usrint::inv, moda_tables::iseq, moda_tables::itp, moda_usrtmp::iutmp, moda_tables::jseq, moda_bitbuf::mbay, moda_usrbit::mbit, moda_usrbit::nbit, moda_usrint::nrfelm, moda_usrint::nval, strbtm(), moda_tables::tag, upbb(), moda_usrint::val, moda_tables::vali, and moda_usrtmp::vutmp.

Referenced by rdtree().

◆ rdmgsb()

recursive subroutine rdmgsb	(	integer, intent(in)	lunit,
		integer, intent(in)	imsg,
		integer, intent(in)	isub
	)

Read a specified data subset from a BUFR file.

This subroutine combines the functionality of openbf(), readmg(), and readsb().

Logical unit lunit should not have already been opened via a previous call to subroutine openbf(). This subroutine will open the file for input.

Whenever this subroutine returns successfully, this indicates that a new data subset was successfully read into internal arrays within the NCEPLIBS-bufr software, and that subsequent calls can immediately be made to any of the various values-reading subroutines.

Note that the value specified for imsg should not include any DX BUFR table messages which may be present in the file. In other words, a value of 12 for imsg means to read the 12th message which contains actual report data.

Parameters

lunit	- Fortran logical unit number for BUFR file
imsg	- Number of BUFR message to be read from the BUFR file, counting from the beginning of the file, but not counting any DX BUFR table messages which may be present in the file
isub	- Number of data subset to be read from the (imsg)th BUFR message, counting from the beginning of the message

Author: J. Woollen

Date: 2003-11-04

Definition at line 535 of file readwritesb.F90.

References bort(), openbf(), readmg(), readsb(), status(), and x84().

◆ rdtree()

subroutine rdtree	(	integer, intent(in)	lun,
		integer, intent(out)	iret
	)

Read the next uncompressed BUFR data subset into internal arrays.

Unpack the next uncompressed subset from the internal array mbay in module moda_bitbuf, and store the resulting values within the internal array val(*,lun) in module moda_usrint.

Parameters

lun	- File ID
iret	- Return code: 0 normal return -1 An error occurred, possibly due to a corrupt subset in the input message

Author: Woollen

Date: 1994-01-06

Definition at line 974 of file readwritesb.F90.

References moda_bitbuf::ibit, moda_tables::ibt, moda_usrint::inv, moda_tables::itp, moda_ival::ival, moda_bitbuf::mbay, moda_usrbit::mbit, moda_usrbit::nbit, moda_usrint::nval, rcstpl(), upb8(), upc(), ups(), and moda_usrint::val.

Referenced by readsb().

◆ readns()

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

Read the next data subset from a BUFR file.

This subroutine provides a handy way to combine the functionality of subroutines readmg() and readsb() within a single subroutine call.

Logical unit lunit should have already been opened for input operations via a previous call to subroutine openbf(). But once that is done, the application program can immediately call this subroutine to read each new data subset from the associated BUFR file, and the subroutine will automatically open and close each new BUFR message internally as needed, so that subsequent calls can immediately be made to any of the various values-reading subroutines.

Parameters

lunit	- Fortran logical unit number for BUFR file
subset	- Table A mnemonic for type of data subset that was read (see DX BUFR Tables for further information about Table A mnemonics)
jdate	- Date-time stored within Section 1 of BUFR message containing data subset 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 data subset was successfully read into internal arrays -1 = there are no more BUFR data subsets in the file connected to logical unit lunit

Author: J. Woollen

Date: 1994-01-06

Definition at line 167 of file readwritesb.F90.

References bort(), moda_msgcwd::idate, moda_msgcwd::inode, readmg(), readsb(), status(), moda_tables::tag, x48(), and x84().

Referenced by ireadns().

◆ readsb()

recursive subroutine readsb	(	integer, intent(in)	lunit,
		integer, intent(out)	iret
	)

Read the next data subset from a BUFR message.

Logical unit lunit should have already been opened for input operations via a previous call to subroutine openbf(), and a BUFR message should have already been read into internal arrays via a previous call to one of the message-reading subroutines.

Whenever this subroutine returns with iret = 0, this indicates that a new BUFR data subset (i.e. report) was successfully read into internal arrays within the NCEPLIBS-bufr software, and from where it can be manipulated or further parsed via calls to any of the values-reading subroutines".

If the subroutine returns with iret = -1 there are no more data subsets available within the current message; a new call needs to be made to one of the message-reading subroutines in order to read in the next message from logical unit lunit.

Parameters

lunit	- Fortran logical unit number for BUFR file
iret	- return code: 0 new BUFR data subset was successfully read into internal arrays -1 there are no more BUFR data subsets in the BUFR message

Author: J. Woollen

Date: 1994-01-06

Definition at line 31 of file readwritesb.F90.

References bort(), moda_bitbuf::ibit, moda_stcode::iscodes, moda_bitmaps::linbtm, moda_bitmaps::lstnod, moda_bitmaps::lstnodct, moda_bitbuf::mbay, moda_bitbuf::mbyt, moda_unptyp::msgunp, moda_msgcwd::msub, moda_bitmaps::nbtm, moda_msgcwd::nsub, rdcmps(), rdtree(), status(), upb(), x48(), and x84().

Referenced by cmpbqm(), copysb(), ireadsb(), rdmems(), rdmgsb(), readns(), rewnbf(), ufbinx(), and ufbpos().

◆ ufbpos()

recursive subroutine ufbpos	(	integer, intent(in)	lunit,
		integer, intent(in)	irec,
		integer, intent(in)	isub,
		character*8, intent(out)	subset,
		integer, intent(out)	jdate
	)

Jump forwards or backwards to a specified data subset within a BUFR file.

Reposition the file pointer to the beginning of a specified data subset within a specified message of a BUFR file, then read that data subset into internal arrays so that it can be further processed via subsequent calls to any of the values-reading subroutines.

The specified data subset may be before or after the current location of the file pointer within the BUFR file.

Remarks

Logical unit lunit should have already been opened for input operations via a previous call to subroutine openbf().
The value specified for irec should not include any messages which contain DX BUFR tables information.

Parameters

lunit	- Fortran logical unit number for BUFR file
irec	- Ordinal number of message to be read, counting from the beginning of the BUFR file, but not counting any messages which contain DX BUFR tables information
isub	- Ordinal number of data subset to be read from (irec)th message, counting from the beginning of the message
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()

Author: J. Woollen

Date: 1995-11-22

Definition at line 879 of file readwritesb.F90.

References bort(), moda_msgcwd::nmsg, moda_msgcwd::nsub, readmg(), readsb(), status(), ufbcnt(), x48(), and x84().

◆ usrtpl()

subroutine usrtpl	(	integer, intent(in)	lun,
		integer, intent(in)	invn,
		integer, intent(in)	nbmp
	)

Expand a subset template within internal arrays.

Update a subset template within the internal subset arrays in module moda_usrint for cases of node expansion, such as when the node is either a Table A mnemonic or a delayed replication factor.

Parameters

lun	- File ID
invn	- Starting jump/link table index of the node to be expanded within the subset template
nbmp	- Number of times by which invn is to be expanded (i.e. number of replications of node)

Author: J. Woollen

Date: 1994-01-06

Definition at line 1306 of file readwritesb.F90.

References bort(), errwrt(), moda_tables::ibt, moda_msgcwd::inode, moda_usrint::inv, moda_stcode::iscodes, moda_tables::iseq, moda_ivttmp::itmp, moda_tables::itp, moda_tables::jmpb, moda_tables::jseq, moda_usrint::nval, moda_tables::tag, moda_tables::typ, moda_usrint::val, moda_tables::vali, and moda_ivttmp::vtmp.

Referenced by drfini(), drstpl(), msgupd(), openmb(), openmg(), rdcmps(), trybump(), ufbget(), ufbtab(), ufbtam(), wrcmps(), and writlc().

◆ writsa()

recursive subroutine writsa	(	integer, intent(in)	lunxx,
		integer, intent(in)	lmsgt,
		integer, dimension(*), intent(out)	msgt,
		integer, intent(out)	msgl
	)

Write a complete data subset into a BUFR message, and return each completed message within a memory array.

This subroutine is similar to subroutine writsb(), except that in addition to writing each completed message to a specified Fortran logical unit, it also returns a copy of each completed message to the application program within a memory array.

This subroutine is called to indicate that all necessary values for a data subset (i.e. report) have been written, and the subset is ready to be encoded and packed into the current message for the BUFR file associated with logical unit abs(lunxx). Logical unit abs(lunxx) should have already been opened for output operations via a previous call to subroutine openbf(), and a BUFR message should already be open for output within internal arrays via a previous call to one of the NCEPLIBS-bufr message-writing subroutines. All of the values for the data subset should have already been written into internal arrays via calls to any of the NCEPLIBS-bufr values-writing subroutines

This subroutine returns a copy of each completed BUFR message to the application program within a memory array. When using this subroutine, it is important to note that the NCEPLIBS-bufr software is designed to pack as many data subsets as possible into each message for output, and therefore not every call to this subroutine will result in a message being returned in msgt. In such cases, msgl will contain the value 0, indicating that no message was returned.

Only when msgl contains a value greater than 0 is there an actual BUFR message within msgt; otherwise, the message into which the data subset was packed remains internally within NCEPLIBS-bufr so that future data subsets can be packed into it as well, and the message will eventually be returned during some other future call to this subroutine. For this reason, there is a way to force the subroutine to return any message contained within the internal NCEPLIBS-bufr arrays, such as when there are no more data subsets to be encoded and we're ready to exit the application program. In this case, the application program should make one final call to this subroutine, but with lunxx set to a negative value; specifically, to the additive inverse of the Fortran logical unit number of the BUFR file. This signals to the subroutine that there are no more data subsets to be packed into the current message for logical unit abs(lunxx), and that the existing message should instead be immediately flushed to output and returned in msgt.

Remarks

There is a maximum size for any BUFR message that can be written by the NCEPLIBS-bufr software. This maximum message size is initially set to an internal default value within subroutine bfrini(), but it can be changed to a different value via a separate prior call to subroutine maxout().
As is the case for subroutine writsb(), this subroutine will also check to ensure that the data subset, when encoded and packed, will fit into the current BUFR message that is open within the internal arrays associated with logical unit abs(lunxx). If adding the data subset to the current message would cause the maximum message size to be exceeded, then the subroutine will automatically flush the current message to logical unit abs(lunxx) and to array msgt, then open and initialize a new internal message using the same subset and jdate values that were specified in the most recent call to one of the message-writing subroutines for abs(lunxx), then encode and pack the data subset into that new message.
If the user would prefer that output messages only be returned to the calling program via the msgt memory array and not also written to Fortran logical unit abs(lunxx), then this can be accomplished by setting io = 'NUL' when calling subroutine openbf() for abs(lunxx). In such cases, the logical unit number abs(lunxx) does not even need to be associated with an actual file on the local system.

Parameters

lunxx	- Absolute value is Fortran logical unit number for BUFR file
lmsgt	- Dimensioned size (in integers) of msgt; used by the subroutine to ensure that it doesn't overflow the msgt array
msgt	- BUFR message
msgl	- Size (in integers) of BUFR message in msgt (0 for no message)

Author: J. Woollen; J. Ator

Date: 1994-01-06

Definition at line 422 of file readwritesb.F90.

References bort(), moda_msgcmp::ccmf, closmg(), moda_bufrmg::msglen, moda_bufrmg::msgtxt, msgupd(), status(), wrcmps(), wrtree(), x48(), and x84().

◆ writsb()

recursive subroutine writsb ( integer, intent(in) lunit )

Write a complete data subset into a BUFR message, for eventual output to logical unit lunit.

This subroutine is called when all necessary values for a data subset (i.e. report) have been written, and the subset is ready to be encoded and packed into the current message for the BUFR file associated with logical unit lunit. Logical unit lunit should have already been opened for output operations via a previous call to subroutine openbf(), and a BUFR message should already be open for output within internal arrays via a previous call to one of the NCEPLIBS-bufr message-writing subroutines. All of the values for the data subset should have already been written into internal arrays via calls to any of the NCEPLIBS-bufr values-writing subroutines.

There is a maximum size for any BUFR message that can be written by the NCEPLIBS-bufr software. This maximum message size is initially set to an internal default value within subroutine bfrini(), but it can be changed to a different value via a separate prior call to subroutine maxout().

This subroutine will always check to ensure that the data subset, when encoded and packed, will fit into the current BUFR message that is already open within the internal arrays associated with logical unit lunit. If adding the data subset to the current message would cause the maximum message size to be exceeded, then the subroutine will automatically flush the current message to logical unit lunit, then open and initialize a new internal message using the same subset and jdate values that were specified in the most recent call to one of the message-writing subroutines for lunit, then encode and pack the data subset into that new message.

Parameters

lunit - Fortran logical unit number for BUFR file

Author: J. Woollen

Date: 1994-01-06

Definition at line 302 of file readwritesb.F90.

References bort(), moda_msgcmp::ccmf, msgupd(), status(), wrcmps(), wrtree(), and x84().

Referenced by copysb(), and writcp().

◆ wrtree()

subroutine wrtree ( integer, intent(in) lun )

Pack a BUFR data subset.

Convert values from the internal array val(*,lun) (in module moda_usrint) into scaled integers, and then pack those scaled integers into the internal array ibay in module moda_bitbuf.

Parameters

lun - File ID

Author: J. Woollen

Date: 1994-01-06

Definition at line 1063 of file readwritesb.F90.

References moda_bitbuf::ibay, moda_bitbuf::ibit, moda_tables::ibt, moda_usrint::inv, ipkm(), moda_tables::itp, moda_ival::ival, moda_ufbcpl::luncpy, moda_usrint::nval, pkb8(), pkc(), readlc(), moda_tables::tag, moda_tables::typ, and moda_usrint::val.

Referenced by writsa(), and writsb().

Functions/Subroutines

Detailed Description

Function/Subroutine Documentation

◆ invmrg()

◆ ireadns()

◆ ireadsb()

◆ lcmgdf()

◆ msgupd()

◆ nwords()

◆ pad()

◆ rcstpl()

◆ rdmgsb()

◆ rdtree()

◆ readns()

◆ readsb()

◆ ufbpos()

◆ usrtpl()

◆ writsa()

◆ writsb()

◆ wrtree()