ufbint.f File Reference

Read/write one or more data values from/to a data subset. More...

Go to the source code of this file.

Functions/Subroutines
subroutine	ufbint (LUNIN, USR, I1, I2, IRET, STR)
	This subroutine reads or writes one or more data values from or to the BUFR data subset that is currently open within the BUFRLIB internal arrays. More...

Detailed Description

Read/write one or more data values from/to a data subset.

Definition in file ufbint.f.

Function/Subroutine Documentation

subroutine ufbint	(		LUNIN,
		real*8, dimension(i1,i2)	USR,
			I1,
			I2,
			IRET,
		character*(*)	STR
	)

This subroutine reads or writes one or more data values from or to the BUFR data subset that is currently open within the BUFRLIB internal arrays.

The direction of the data transfer is determined by the context of ABS(LUNIN):

• If ABS(LUNIN) points to a file that was previously opened for input using subroutine openbf(), then data values are read from the current data subset.
• If ABS(LUNIN) points to a file that was previously opened for output using subroutine openbf(), then data values are written to the current data subset.

This subroutine is specifically designed for use with Table B mnemonics which are part of a delayed-replication sequence, or for which there is no replication at all. See also subroutines ufbrep(), ufbseq() and ufbstp(), which can also be used to read/write one or more data values from/to a data subset but are designed for different use cases. A more detailed discussion of these different use cases, including examples, is available in DX BUFR Tables.

Author

J. Woollen

Date

1994-01-06

Parameters

[in]	LUNIN	- integer: Absolute value is Fortran logical unit number for BUFR file
[in,out]	USR	- real*8(*,*): Data values If ABS(LUNIN) was opened for input, then USR is output from this subroutine and contains data values that were read from the current data subset. If ABS(LUNIN) was opened for output, then USR is input to this subroutine and contains data values that are to be written to the current data subset.
[in]	I1	- integer: Actual first dimension of USR as allocated within the calling program
[in]	I2	- integer: If ABS(LUNIN) was opened for input, then I2 must be set equal to the actual second dimension of USR as allocated within the calling program If ABS(LUNIN) was opened for output, then I2 must be set equal to the number of replications of STR that are to be written to the data subset
[out]	IRET	- integer: Number of replications of STR that were actually read/written from/to the data subset
[in]	STR	- character*(*): String of blank-separated Table B mnemonics in one-to-one correspondence with the number of data values that will be read/written from/to the data subset within the first dimension of USR (see DX BUFR Tables for further information about Table B mnemonics)

It is the user's responsibility to ensure that USR is dimensioned sufficiently large enough to accommodate the number of data values that are to be read from or written to the data subset. Note also that USR is an array of real*8 values; therefore, any data that are to be written out as character (i.e. CCITT IA5) values in BUFR must be converted from character into real*8 format within the application program before calling this subroutine. Conversely, when this subroutine is being used to read character values from a data subset, the value that is returned will be in real*8 format and must be converted back into character format by the application program before it can be used as such. Alternatively, there are different subroutines such as readlc() and writlc() which can be used to read/write character data directly from/to a data subset without the need to convert from/to real*8 format as an intermediate step.

Numeric (i.e. non-character) data values within USR are always in the exact units specified for the corresponding mnemonic within the relevant DX or master BUFR table, without any scale or reference values applied. Specifically, this means that, when writing data values into an output subset, the user only needs to store each respective value into USR using the units specified within the table, and the BUFRLIB software will take care of any necessary scaling or referencing of the value before it is actually encoded into BUFR. Conversely, when reading data values from an input subset, the values returned in USR are already de-scaled and de-referenced and, thus, are already in the exact units that were defined for the corresponding mnemonics within the table.

"Missing" values in USR are always denoted by a unique placeholder value. This placeholder value is initially set to a default value of 10E10_8, but it can be reset to any substitute value of the user's choice via a separate call to subroutine setbmiss(). In any case, and whenever this subroutine is used to read data values from an input subset, any returned value in USR can be easily checked for equivalence to the current placeholder value via a call to function ibfms(), and a positive result means that the value for the corresponding mnemonic was encoded as "missing" in BUFR (i.e. all bits set to 1) within the original data subset. Conversely, whenever this subroutine is used to write data values to an output subset, the current placeholder value can be obtained via a separate call to function getbmiss(), and the resulting value can then be stored into the USR array whereever the user desires a BUFR "missing" value (i.e. all bits set to 1) to be encoded for the corresponding mnemonic within the output subset.

Remarks

• If LUNIN < 0, and if ABS(LUNIN) points to a file that is open for output (writing BUFR), then the subroutine will treat the file pointed to by ABS(LUNIN) as though it was open for input (reading BUFR). This is a special capability for use by some applications that need to read certain values back out from a BUFR file during the same time that it is in the process of being written to.
• If ABS(LUNIN) points to a file that is open for input (reading BUFR), STR may contain a Table D mnemonic that is replicated using either 8-bit or 16-bit delayed replication (as noted using replication indicators {} or (), respectively, within the assocated DX BUFR table), and the corresponding location in USR will contain the total number of replications of that mnemonic within the data subset. Note that, when using this option, the applicable replication indicators must be included in STR along with the mnemonic itself, as shown in an example in the discussion of DX BUFR Tables.
• If ABS(LUNIN) points to a file that is open for input (reading BUFR), there are a few additional special mnemonics that can be included within STR when calling this subroutine, and which in turn will result in special information being returned within the corresponding location in USR. These special mnemonics are not considered to be part of Table B or Table D and therefore do not need to be definied within the DX or master table file associated with ABS(LUNIN):
  • NUL - returns the "missing" value
  • IREC - returns the number of the BUFR message within the file pointed to by ABS(LUNIN) (counting from the beginning of the file) in which the current data subset resides
  • ISUB - returns the number of the current data subset within the BUFR message pointed to by IREC, counting from the beginning of the message

Program history log:

• 1994-01-06 J. Woollen – Original author
• 1996-11-25 J. Woollen – Modified to add a return code when mnemonics are not found when reading
• 1996-12-17 J. Woollen – Modified to always initialize USR array to "missing" when BUFR file is being read
• 1998-07-08 J. Woollen – Replaced call to Cray library routine ABORT with call to new internal routine bort()
• 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)
• 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, unusual things happen or for informational purposes
• 2004-08-18 J. Ator – Added SAVE for IFIRST1 and IFIRST2 flags
• 2009-04-21 J. Ator – Use errwrt()
• 2014-12-10 J. Ator – Use modules instead of COMMON blocks

Definition at line 160 of file ufbint.f.

References bort(), bort2(), errwrt(), status(), string(), trybump(), and ufbrw().

Referenced by bufr_c_interface_mod::ufbint_c(), ufbinx(), and ufbrms().