- Generated by
1.9.1
|
NCEPLIBS-bufr
12.1.0
|
Read or write data values within a BUFR data subset. More...
Go to the source code of this file.
Functions/Subroutines | |
| recursive subroutine | drfini (lunit, mdrf, ndrf, drftag) |
| Explicitly initialize delayed replication factors and allocate a corresponding amount of space within internal arrays, thereby allowing the subsequent use of subroutine ufbseq() to write data into delayed replication sequences. More... | |
| recursive real *8 function | getvalnb (lunit, tagpv, ntagpv, tagnb, ntagnb) |
| Read a data value corresponding to a specific occurrence of a mnemonic within a data subset, based on its position relative to a different mnemonic within the subset. More... | |
| recursive subroutine | hold4wlc (lunit, chr, str) |
| Write a long character string (greater than 8 bytes) to a data subset. More... | |
| integer function | nevn (node, lun, inv1, inv2, i1, i2, i3, usr) |
| Read one or more data values from a stacked data event within a specified portion of the current data subset. More... | |
| recursive subroutine | readlc (lunit, chr, str) |
| Read a long character string (greater than 8 bytes) from a data subset. More... | |
| recursive subroutine | setvalnb (lunit, tagpv, ntagpv, tagnb, ntagnb, r8val, iret) |
| Write a data value corresponding to a specific occurrence of a mnemonic within a data subset, based on its position relative to a different mnemonic within the subset. More... | |
| subroutine | trybump (lun, usr, i1, i2, io, iret) |
| Try to expand a delayed replication sequence. More... | |
| recursive subroutine | ufbevn (lunit, usr, i1, i2, i3, iret, str) |
| Read one or more data values from an NCEP prepbufr file. More... | |
| recursive subroutine | ufbget (lunit, tab, i1, iret, str) |
| Read one or more data values from a data subset without advancing the subset pointer. More... | |
| recursive subroutine | ufbin3 (lunit, usr, i1, i2, i3, iret, jret, str) |
| Read one or more data values from an NCEP prepfits file. More... | |
| recursive subroutine | ufbint (lunin, usr, i1, i2, iret, str) |
| Read or write one or more data values from or to a data subset. More... | |
| recursive subroutine | ufbinx (lunit, imsg, isub, usr, i1, i2, iret, str) |
| Read one or more data values from a specified data subset. More... | |
| recursive subroutine | ufbovr (lunit, usr, i1, i2, iret, str) |
| Overwrite one or more data values within a data subset. More... | |
| recursive subroutine | ufbrep (lunin, usr, i1, i2, iret, str) |
| Read or write one or more data values from or to a data subset. More... | |
| subroutine | ufbrp (lun, usr, i1, i2, io, iret) |
| Write or read specified data values to or from the current BUFR data subset within internal arrays, with the direction of the data transfer determined by the context of io. More... | |
| subroutine | ufbrw (lun, usr, i1, i2, io, iret) |
| Write or read specified values to or from the current BUFR data subset within internal arrays, with the direction of the data transfer determined by the context of io. More... | |
| recursive subroutine | ufbseq (lunin, usr, i1, i2, iret, str) |
| Read or write an entire sequence of data values from or to a data subset. More... | |
| subroutine | ufbsp (lun, usr, i1, i2, io, iret) |
| Write or read specified values to or from the current BUFR data subset within internal arrays, with the direction of the data transfer determined by the context of io. More... | |
| recursive subroutine | ufbstp (lunin, usr, i1, i2, iret, str) |
| Read or write one or more data values from or to a data subset. More... | |
| recursive subroutine | writlc (lunit, chr, str) |
| Write a long character string (greater than 8 bytes) to a data subset. More... | |
Read or write data values within a BUFR data subset.
Definition in file readwriteval.F90.
| recursive subroutine drfini | ( | integer, intent(in) | lunit, |
| integer, dimension(*), intent(in) | mdrf, | ||
| integer, intent(in) | ndrf, | ||
| character*(*), intent(in) | drftag | ||
| ) |
Explicitly initialize delayed replication factors and allocate a corresponding amount of space within internal arrays, thereby allowing the subsequent use of subroutine ufbseq() to write data into delayed replication sequences.
| lunit | - Fortran logical unit number for BUFR file |
| mdrf | - Array of delayed replication factors, in one-to-one correspondence with the number of occurrences of drftag within the overall subset definition, and explicitly defining how much space (i.e. how many replications) to allocate within each successive occurrence |
| ndrf | - Number of delayed replication factors within mdrf |
| drftag | - Table D sequence mnemonic, bracketed by appropriate delayed replication notation (e.g. {}, () OR <>) |
Logical unit lunit should have already been opened for output operations (i.e. writing/encoding BUFR) via a previous call to subroutine openbf(), and a message for output should have already been opened via a previous call to one of the [message-writing subroutines].
The use of this subroutine is only required when writing data into delayed replication sequences using ufbseq(), or for cases where ufbint() or ufbrep() are being used to write data into delayed replication sequences which occur more than once within an overall subset definition. In such cases, the use of this subroutine allows the application code to explicitly specify how many replications of the sequence are to be allocated to each occurrence of the delayed replication sequence within the overall subset definition, prior to storing all of the actual data values themselves via a single subsequent call to ufbint() or ufbrep(). In contrast, the use of this subroutine is not required when ufbint() or ufbrep() are to be called to store data values for a delayed replication sequence which only occurs one time within an overall subset definition, because in that case the same type of initialization and space allocation functionality will be automatically handled internally within subroutine ufbint() or ufbrep().
Definition at line 1587 of file readwriteval.F90.
References moda_usrint::inv, moda_tables::itp, moda_usrint::nval, status(), moda_tables::tag, usrtpl(), and x84().
| recursive real*8 function getvalnb | ( | integer, intent(in) | lunit, |
| character*(*), intent(in) | tagpv, | ||
| integer, intent(in) | ntagpv, | ||
| character*(*), intent(in) | tagnb, | ||
| integer, intent(in) | ntagnb | ||
| ) |
Read a data value corresponding to a specific occurrence of a mnemonic within a data subset, based on its position relative to a different mnemonic within the subset.
The function first searches for a specific occurrence of a pivot mnemonic, counting from the beginning of the subset. From there, it then searches in either a forward or backward direction for a specific occurrence of a nearby mnemonic, and if found returns the data value from the corresponding location within the subset.
| lunit | - Fortran logical unit number for BUFR file |
| tagpv | - Pivot mnemonic; the subroutine will first search for the (ntagpv)th occurrence of this mnemonic, counting from the beginning of the overall subset definition |
| ntagpv | - Ordinal occurrence of tagpv to search for, counting from the beginning of the overall subset definition |
| tagnb | - Nearby mnemonic; assuming tagpv is successfully found, the subroutine will then search nearby for the (ntagnb)th occurrence of tagnb and return the corresponding value |
| ntagnb | - Ordinal occurrence of tagnb to search for, counting from the location of tagpv within the overall subset definition
|
The current placeholder value for "missing" data can be determined via a separate call to function getbmiss().
Before calling this function, a BUFR data subset should already be open for reading via a previous call to one of the NCEPLIBS-bufr subset-reading subroutines.
Definition at line 121 of file readwriteval.F90.
References fstag(), moda_msgcwd::inode, moda_usrint::inv, status(), moda_usrint::val, and x84().
| recursive subroutine hold4wlc | ( | integer, intent(in) | lunit, |
| character*(*), intent(in) | chr, | ||
| character*(*), intent(in) | str | ||
| ) |
Write a long character string (greater than 8 bytes) to a data subset.
Normally, subroutine writlc() is used to write a long character string to a data subset. However, subroutine writlc() can only be called after a call to one of the subset-writing subroutines, so it will not work for cases when one of those subroutines flushes the message containing the data subset in question to logical unit lunit during the same call to that subroutine, such as when the data subset contains more than 65530 bytes. When this happens, there is no longer any way for a subsequent writlc() call to write a long character string into that data subset, because the data subset has already been flushed from internal memory. This subroutine solves that problem, by allowing a long character string to be specified before calling one of the subset-writing subroutines, and the string value will be held and stored automatically (via an internal call to subroutine writlc()) at the proper time during the subsequent call to the subset-writing subroutines.
| lunit | - Fortran logical unit number for BUFR file |
| chr | - Value corresponding to str |
| str | - Table B mnemonic of long character string to be written, possibly supplemented with an ordinal occurrence notation |
If there is more than one occurrence of str within the data subset definition, then each occurrence can be written via a separate call to this subroutine, and by appending the ordinal number of the occurrence to str in each case. For example, if there are 5 occurrences of mnemonic LSTID within a given data subset definition, then 5 separate calls should be made to this subroutine, once each with str set to 'LSTID#1', 'LSTID#2', 'LSTID#3', 'LSTID#4' and 'LSTID#5'. However, the first notation is superfluous, because omitting the ordinal number always defaults to the first occurrence of a particular string, so a user could just specify 'LSTID' instead of 'LSTID#1'.
Definition at line 1977 of file readwriteval.F90.
References moda_h4wlc::chh4wlc, errwrt(), moda_h4wlc::luh4wlc, moda_h4wlc::nh4wlc, moda_h4wlc::sth4wlc, strsuc(), and x84().
| integer function nevn | ( | integer, intent(in) | node, |
| integer, intent(in) | lun, | ||
| integer, intent(in) | inv1, | ||
| integer, intent(in) | inv2, | ||
| integer, intent(in) | i1, | ||
| integer, intent(in) | i2, | ||
| integer, intent(in) | i3, | ||
| real*8, dimension(i1,i2,i3), intent(out) | usr | ||
| ) |
Read one or more data values from a stacked data event within a specified portion of the current data subset.
Search for all stacked data events within the portion of the current subset buffer bounded by the indices inv1 and inv2. All such events are accumulated and returned to the calling program within array usr. The value of the function itself is the total number of events found.
| node | - Jump/link table index of node for which to return stacked values |
| lun | - File ID |
| inv1 | - Starting index of the portion of the subset buffer in which to look for stack values |
| inv2 | - Ending index of the portion of the subset buffer in which to look for stack values |
| i1 | - First dimension of usr as allocated within the calling program |
| i2 | - Second dimension of usr as allocated within the calling program |
| i3 | - Third dimension of usr as allocated within the calling program |
| usr | - Starting address of data values read from data subset; events are returned in the third dimension for a particular data value and level in the first and second dimensions |
Definition at line 2888 of file readwriteval.F90.
References bort(), moda_usrint::inv, invwin(), lstjpb(), and moda_usrint::val.
Referenced by ufbin3().
| recursive subroutine readlc | ( | integer, intent(in) | lunit, |
| character*(*), intent(out) | chr, | ||
| character*(*), intent(in) | str | ||
| ) |
Read a long character string (greater than 8 bytes) from a data subset.
The data subset should have already been read into internal arrays via a previous call to one of the subset-reading subroutines.
If there is more than one occurrence of str within the data subset definition, then each occurrence can be retrieved via a separate call to this subroutine, and by appending the ordinal number of the occurrence to str in each case.
For example, if there are 5 occurrences of mnemonic LSTID within a given data subset definition, then 5 separate calls should be made to this subroutine, once each with str set to 'LSTID#1', 'LSTID#2', 'LSTID#3', 'LSTID#4' and 'LSTID#5'.
Omitting the ordinal number always defaults to the first occurrence of a particular string, so a user could just specify 'LSTID' instead of 'LSTID#1'.
| lunit | - Fortran logical unit number for BUFR file |
| chr | - Value corresponding to STR |
| str | - Table B mnemonic of long character string to be retrieved, possibly supplemented with an ordinal occurrence notation |
Definition at line 406 of file readwriteval.F90.
References bort(), moda_rlccmn::crtag, errwrt(), moda_usrint::inv, ipkm(), moda_rlccmn::irbit, moda_rlccmn::irnch, moda_tables::itp, moda_bitbuf::mbay, moda_usrbit::mbit, moda_unptyp::msgunp, moda_usrbit::nbit, moda_rlccmn::nrst, moda_usrint::nval, parstr(), parutg(), status(), moda_tables::tag, upc(), and x84().
Referenced by bufr_c2f_interface::readlc_c(), ufbdmp(), ufdump(), and wrtree().
| recursive subroutine setvalnb | ( | integer, intent(in) | lunit, |
| character*(*), intent(in) | tagpv, | ||
| integer, intent(in) | ntagpv, | ||
| character*(*), intent(in) | tagnb, | ||
| integer, intent(in) | ntagnb, | ||
| real*8, intent(in) | r8val, | ||
| integer, intent(out) | iret | ||
| ) |
Write a data value corresponding to a specific occurrence of a mnemonic within a data subset, based on its position relative to a different mnemonic within the subset.
The subroutine first searches for a specific occurrence of a pivot mnemonic, counting from the beginning of the subset. From there, it then searches in either a forward or backward direction for a specific occurrence of a nearby mnemonic, and if found stores the specified data value in the corresponding location within the subset.
Before calling this subroutine, a BUFR message should already be opened and initialized for output via a previous call to one of the NCEPLIBS-bufr message-writing subroutines.
| lunit | - Fortran logical unit number for BUFR file |
| tagpv | - Pivot mnemonic; the subroutine will first search for the (ntagpv)th occurrence of this mnemonic, counting from the beginning of the overall subset definition |
| ntagpv | - Ordinal occurrence of tagpv to search for, counting from the beginning of the overall subset definition |
| tagnb | - Nearby mnemonic; assuming tagpv is successfully found, the subroutine will then search nearby for the (ntagnb)th occurrence of tagnb and store r8val as the corresponding value |
| ntagnb | - Ordinal occurrence of tagnb to search for, counting from the location of tagpv within the overall subset definition
|
| r8val | - Value to be stored corresponding to (ntagnb)th occurrence of tagnb within the subset |
| iret | - return code:
|
Definition at line 37 of file readwriteval.F90.
References fstag(), moda_msgcwd::inode, moda_usrint::inv, status(), moda_usrint::val, x48(), and x84().
| subroutine trybump | ( | integer, intent(in) | lun, |
| real*8, dimension(i1,i2), intent(inout) | usr, | ||
| integer, intent(in) | i1, | ||
| integer, intent(in) | i2, | ||
| integer, intent(in) | io, | ||
| integer, intent(out) | iret | ||
| ) |
Try to expand a delayed replication sequence.
Check the first node associated with a character string (parsed into arrays in common block /usrstr/) in order to determine if it represents a delayed replication sequence. If so, then the delayed replication sequence is initialized and expanded (i.e. "bumped") to the value of input argument i2. A call is then made to subroutine ufbrw() in order to write user data into the newly expanded replication sequence.
This subroutine is usually called from ufbint() whenever that routine receives a non-zero return code from ufbrw(). The cause of a bad return from ufbrw() is usually a delayed replication sequence which isn't expanded enough to hold the array of data the user is trying to write. So this subroutine is one last chance to try to resolve that situation.
| lun | - File ID |
| usr | - Data values |
| i1 | - First dimension of usr as allocated within the calling program |
| i2 | - Number of levels of data values that are to be written to the data subset |
| io | - Status indicator for BUFR file:
|
| iret | - Number of ldevels of data values that were written to the data subset |
Definition at line 2068 of file readwriteval.F90.
References moda_usrint::inv, moda_usrint::nval, ufbrw(), usrtpl(), and moda_usrint::val.
| recursive subroutine ufbevn | ( | integer, intent(in) | lunit, |
| real*8, dimension(i1,i2,i3), intent(out) | usr, | ||
| integer, intent(in) | i1, | ||
| integer, intent(in) | i2, | ||
| integer, intent(in) | i3, | ||
| integer, intent(out) | iret, | ||
| character*(*), intent(in) | str | ||
| ) |
Read one or more data values from an NCEP prepbufr file.
This subroutine is specifically designed for use with NCEP prepbufr files, which contain a third dimension of data events for every reported data value at every replicated vertical level. It is similar to subroutine ufbin3(), except that ufbin3() is used for NCEP prepfits files and has one extra argument containing the maximum number of data events for any data value, whereas this subroutine is used for NCEP prepbufr files and stores the same information internally within a common block.
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 the data subset. Note also that usr is an array of real*8 values; therefore, any character (i.e. CCITT IA5) value in the data subset will be returned in real*8 format and must be converted back into character format by the application program before it can be used as such.
"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, 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.
| lunit | - Fortran logical unit number for NCEP prepbufr file |
| usr | - Data values |
| i1 | - First dimension of usr as allocated within the calling program |
| i2 | - Second dimension of usr as allocated within the calling program |
| i3 | - Third dimension of usr as allocated within the calling program |
| iret | - Number of replications of str that were read from the data subset, corresponding to the second dimension of usr |
| str | - 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) |
Definition at line 2267 of file readwriteval.F90.
References bort(), conwin(), errwrt(), getwin(), moda_msgcwd::inode, moda_usrint::inv, nvnwin(), nxtwin(), status(), string(), moda_usrint::val, x48(), and x84().
| recursive subroutine ufbget | ( | integer, intent(in) | lunit, |
| real*8, dimension(i1), intent(out) | tab, | ||
| integer, intent(in) | i1, | ||
| integer, intent(out) | iret, | ||
| character*(*), intent(in) | str | ||
| ) |
Read one or more data values from a data subset without advancing the subset pointer.
The data values to be read must be one-dimensional (i.e. non-replicated).
| lunit | - Fortran logical unit number for BUFR file |
| tab | - Data values |
| i1 | - Size of tab as allocated within the calling program |
| iret | - Return code:
|
| str | - String of blank-separated Table B mnemonics in one-to-one correspondence with the number of data values that will be read from the data subset into tab |
Definition at line 2756 of file readwriteval.F90.
References bort(), moda_tables::ibt, moda_usrint::inv, invwin(), moda_tables::itp, moda_bitbuf::mbay, moda_usrbit::mbit, moda_bitbuf::mbyt, moda_msgcwd::msub, moda_usrbit::nbit, moda_msgcwd::nsub, moda_usrint::nval, status(), string(), upb8(), upc(), ups(), usrtpl(), x48(), and x84().
| recursive subroutine ufbin3 | ( | integer, intent(in) | lunit, |
| real*8, dimension(i1,i2,i3), intent(out) | usr, | ||
| integer, intent(in) | i1, | ||
| integer, intent(in) | i2, | ||
| integer, intent(in) | i3, | ||
| integer, intent(out) | iret, | ||
| integer, intent(out) | jret, | ||
| character*(*), intent(in) | str | ||
| ) |
Read one or more data values from an NCEP prepfits file.
This subroutine is specifically designed for use with NCEP prepfits files, which contain a third dimension of data events for every reported data value at every replicated vertical level. It is similar to subroutine ufbevn(), except that ufbevn() is used for NCEP prepbufr files and stores the maximum number of data events for any data value within an internal common block, whereas this subroutine is used for NCEP prepfits files and has one extra argument which returns the same information to the calling program.
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 the data subset. Note also that usr is an array of real*8 values; therefore, any character (i.e. CCITT IA5) value in the data subset will be returned in real*8 format and must be converted back into character format by the application program before it can be used as such.
"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, 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.
| lunit | - Fortran logical unit number for NCEP prepfits file |
| usr | - Data values |
| i1 | - First dimension of usr as allocated within the calling program |
| i2 | - Second dimension of usr as allocated within the calling program |
| i3 | - Third dimension of usr as allocated within the calling program |
| iret | - Number of replications of str that were read from the data subset, corresponding to the second dimension of usr |
| jret | - Maximum number of data events for any data value that was read from the data subset at any replicated vertical level, and corresponding to the third dimension of usr |
| str | - 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) |
Definition at line 2471 of file readwriteval.F90.
References bort(), conwin(), errwrt(), getwin(), moda_msgcwd::inode, moda_usrint::inv, nevn(), nxtwin(), status(), string(), x48(), and x84().
| recursive subroutine ufbint | ( | integer, intent(in) | lunin, |
| real*8, dimension(i1,i2), intent(inout) | usr, | ||
| integer, intent(in) | i1, | ||
| integer, intent(in) | i2, | ||
| integer, intent(out) | iret, | ||
| character*(*), intent(in) | str | ||
| ) |
Read or write one or more data values from or to a data subset.
The direction of the data transfer is determined by the context of abs(lunin):
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.
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 NCEPLIBS-bufr 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.
| lunin | - Absolute value is Fortran logical unit number for BUFR file |
| usr | - Data values
|
| i1 | - First dimension of usr as allocated within the calling program |
| i2 | - Second dimension of usr
|
| iret | - Number of replications of str that were read/written from/to the data subset |
| str | - 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) |
Definition at line 645 of file readwriteval.F90.
References bort(), bort2(), errwrt(), moda_msgcwd::inode, moda_usrint::inv, status(), string(), trybump(), ufbrw(), x48(), and x84().
Referenced by cmpbqm(), readbp(), bufr_c2f_interface::ufbint_c(), ufbinx(), and ufbrms().
| recursive subroutine ufbinx | ( | integer, intent(in) | lunit, |
| integer, intent(in) | imsg, | ||
| integer, intent(in) | isub, | ||
| real*8, dimension(i1,i2), intent(out) | usr, | ||
| integer, intent(in) | i1, | ||
| integer, intent(in) | i2, | ||
| integer, intent(out) | iret, | ||
| character*(*), intent(in) | str | ||
| ) |
Read one or more data values from a specified data subset.
If logical unit lunit has already been opened for input operations via a previous call to subroutine openbf(), then this subroutine will save the current file position, rewind the file to the beginning, reposition the file to a specified data subset within a specified message, read one or more specified data values from that data subset via an internal call to ufbint(), and then restore the file to its previous position.
Otherwise, if logical unit lunit has not already been opened for input operations via a previous call to subroutine openbf(), then this subroutine will open it via an internal call to subroutine openbf(), position the file to a specified data subset within a specified message, read one or more specified data values from that data subset via an internal call to ufbint(), and then close the file via an internal call to subroutine closbf().
| 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 |
| usr | - Data values |
| i1 | - First dimension of usr as allocated within the calling program |
| i2 | - Second dimension of usr as allocated within the calling program |
| iret | - Number of replications of str that were read from the data subset |
| str | - String of blank-separated Table B mnemonics in one-to-one correspondence with the number of data values that will be read from the data subset within the first dimension of usr (see DX BUFR Tables for further information about Table B mnemonics) |
Definition at line 2662 of file readwriteval.F90.
References bort(), closbf(), openbf(), readmg(), readsb(), rewnbf(), status(), ufbint(), x48(), and x84().
| recursive subroutine ufbovr | ( | integer, intent(in) | lunit, |
| real*8, dimension(i1,i2), intent(inout) | usr, | ||
| integer, intent(in) | i1, | ||
| integer, intent(in) | i2, | ||
| integer, intent(out) | iret, | ||
| character*(*), intent(in) | str | ||
| ) |
Overwrite one or more data values within a data subset.
Overwrite specified values which exist in current internal BUFR subset arrays in a file open for output. The data values correspond to mnemonics which are part of a delayed-replication sequence, or for which there is no replication at all. Either subroutine openmg() or openmb() must have been previously called to open and initialize a BUFR message within memory for this lunit. In addition, subroutine writsb() or invmrg() must have previously been called to store the data values that are now intended to be overwritten within the internal output subset arrays.
| lunit | - Fortran logical unit number for BUFR file |
| usr | - Data values |
| i1 | - First dimension of usr as allocated within the calling program |
| i2 | - Number of replications of str that are to be written to the data subset |
| iret | - Number of replications of str that were written to the data subset |
| str | - String of blank-separated Table B mnemonics in one-to-one correspondence with the number of data values that will be written to the data subset within the first dimension of usr (see DX BUFR Tables for further information about Table B mnemonics) |
Definition at line 2128 of file readwriteval.F90.
References bort(), bort2(), errwrt(), moda_msgcwd::inode, moda_usrint::inv, status(), string(), trybump(), x48(), and x84().
| recursive subroutine ufbrep | ( | integer, intent(in) | lunin, |
| real*8, dimension(i1,i2), intent(inout) | usr, | ||
| integer, intent(in) | i1, | ||
| integer, intent(in) | i2, | ||
| integer, intent(out) | iret, | ||
| character*(*), intent(in) | str | ||
| ) |
Read or write one or more data values from or to a data subset.
The direction of the data transfer is determined by the context of abs(lunin):
This subroutine is specifically designed for use with Table B mnemonics which are part of a fixed (i.e. non-delayed) replication sequence, or for mnemonics which are replicated by being directly listed more than once within an overall subset definition. See also subroutines ufbint(), 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.
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 NCEPLIBS-bufr 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.
| lunin | - Absolute value is Fortran logical unit number for BUFR file |
| usr | - Data values
|
| i1 | - First dimension of usr as allocated within the calling program |
| i2 | - Second dimension of usr
|
| iret | - Number of replications of str that were read/written from/to the data subset |
| str | - 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) |
Definition at line 885 of file readwriteval.F90.
References bort(), bort2(), errwrt(), moda_msgcwd::inode, moda_usrint::inv, status(), string(), ufbrp(), x48(), and x84().
Referenced by bufr_c2f_interface::ufbrep_c().
| subroutine ufbrp | ( | integer, intent(in) | lun, |
| real*8, dimension(i1,i2), intent(inout) | usr, | ||
| integer, intent(in) | i1, | ||
| integer, intent(in) | i2, | ||
| integer, intent(in) | io, | ||
| integer, intent(out) | iret | ||
| ) |
Write or read specified data values to or from the current BUFR data subset within internal arrays, with the direction of the data transfer determined by the context of io.
The data values correspond to internal arrays representing parsed strings of mnemonics which are either part of a fixed (i.e. non-delayed) replication sequence, or for mnememonics which are replicated by being directly listed more than once within an overall subset definition.
This subroutine should never be directly called by an application program; instead, an application program should directly call ufbrep() which will internally call this subroutine.
| lun | - File ID |
| usr | - Data values |
| i1 | - Length of first dimension of usr |
| i2 | - Length of second dimension of usr |
| io | - Status indicator for BUFR file associated with lun:
|
| iret | - Number of "levels" of data values read from or written to data subset |
Definition at line 1792 of file readwriteval.F90.
References moda_usrint::nval, and moda_usrint::val.
Referenced by ufbrep().
| subroutine ufbrw | ( | integer, intent(in) | lun, |
| real*8, dimension(i1,i2), intent(inout) | usr, | ||
| integer, intent(in) | i1, | ||
| integer, intent(in) | i2, | ||
| integer, intent(in) | io, | ||
| integer, intent(out) | iret | ||
| ) |
Write or read specified values to or from the current BUFR data subset within internal arrays, with the direction of the data transfer determined by the context of io.
The data values correspond to internal arrays representing parsed strings of mnemonics which are part of a delayed-replication sequence, or for which there is no replication at all.
This subroutine should never be directly called by an application program; instead, an application program should directly call ufbint() which will internally call this subroutine.
| lun | - File ID |
| usr | - Data values |
| i1 | - Length of first dimension of usr |
| i2 | - Length of second dimension of usr |
| io | - Status indicator for BUFR file associated with lun:
|
| iret | - Number of "levels" of data values read from or written to data subset
|
Definition at line 1654 of file readwriteval.F90.
References conwin(), drstpl(), errwrt(), getwin(), moda_msgcwd::inode, newwin(), nxtwin(), moda_tables::tag, and moda_usrint::val.
| recursive subroutine ufbseq | ( | integer, intent(in) | lunin, |
| real*8, dimension(i1,i2), intent(inout) | usr, | ||
| integer, intent(in) | i1, | ||
| integer, intent(in) | i2, | ||
| integer, intent(out) | iret, | ||
| character*(*), intent(in) | str | ||
| ) |
Read or write an entire sequence of data values from or to a data subset.
The direction of the data transfer is determined by the context of abs(lunin):
This subroutine is specifically designed for use with a single Table A or Table D mnemonic. In the latter case, the mnemonic may be replicated within the overall subset definition, and in which case the subroutine will return all data values within all replications of the sequence defined by the mnemonic. But in either case, the mnemonic itself may contain, within its own sequence definition, any number of data values defined by Table B mnemonics and/or subsequences of data values defined by other Table D mnemonics, and any such subsequences may themselves be replicated using any manner of fixed or delayed replication. See DX BUFR Tables for more details including an example use case, and see also subroutines ufbint(), ufbrep() and ufbstp() which are also used to read/write one or more data values from/to a data subset but cannot themselves be directly used with Table A or Table D 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 NCEPLIBS-bufr 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.
| lunin | - Absolute value is Fortran logical unit number for BUFR file |
| usr | - Data values
|
| i1 | - First dimension of usr as allocated within the calling program |
| i2 | - Second dimension of usr
|
| iret | - Number of replications of str that were read/written from/to the data subset |
| str | - String consisting of a single Table A or Table D mnemonic whose sequence definition is 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 A and Table D mnemonics) |
Definition at line 1319 of file readwriteval.F90.
References bort(), errwrt(), moda_msgcwd::inode, moda_usrint::inv, invtag(), invwin(), moda_tables::isc, moda_tables::itp, moda_tables::jmpb, moda_tables::link, moda_usrint::nval, parstr(), status(), moda_tables::tag, moda_tables::typ, moda_usrint::val, x48(), and x84().
Referenced by bufr_c2f_interface::ufbseq_c().
| subroutine ufbsp | ( | integer, intent(in) | lun, |
| real*8, dimension(i1,i2), intent(inout) | usr, | ||
| integer, intent(in) | i1, | ||
| integer, intent(in) | i2, | ||
| integer, intent(in) | io, | ||
| integer, intent(out) | iret | ||
| ) |
Write or read specified values to or from the current BUFR data subset within internal arrays, with the direction of the data transfer determined by the context of io.
The data values correspond to internal arrays representing parsed strings of mnemonics which are either part of a fixed (i.e. non-delayed) replication sequence, or for mnememonics which are replicated by being directly listed more than once within an overall subset definition.
This subroutine should never be directly called by an application program; instead, an application program should directly call ufbstp() which will internally call this subroutine.
This subroutine is similar to subroutine ufbrp(), but it is designed for different use cases. For a more detailed explanation of how subroutine ufbstp() differs from subroutine ufbrep(), and therefore how this subroutine differs from subroutine ufbrp(), see the discussion in DX BUFR Tables.
| lun | - File ID |
| usr | - Data values |
| i1 | - Length of first dimension of usr |
| i2 | - Length of second dimension of usr |
| io | - Status indicator for BUFR file associated with lun:
|
| iret | - Number of "levels" of data values read from or written to data subset |
Definition at line 1876 of file readwriteval.F90.
References moda_usrint::nval, and moda_usrint::val.
Referenced by ufbstp().
| recursive subroutine ufbstp | ( | integer, intent(in) | lunin, |
| real*8, dimension(i1,i2), intent(inout) | usr, | ||
| integer, intent(in) | i1, | ||
| integer, intent(in) | i2, | ||
| integer, intent(out) | iret, | ||
| character*(*), intent(in) | str | ||
| ) |
Read or write one or more data values from or to a data subset.
The direction of the data transfer is determined by the context of abs(lunin):
This subroutine is specifically designed for use with Table B mnemonics which are part of a fixed (i.e. non-delayed) replication sequence, or for mnemonics which are replicated by being directly listed more than once within an overall subset definition. It is very similar to subroutine ufbrep(), but it differs in how it processes the input mnemonic string str. For more details, see the discussion and example use case in DX BUFR Tables. See also subroutines ufbint() and ufbseq(), which can also be used to read/write one or more data values from/to a data subset but are also designed for different use cases as noted in DX BUFR Tables.
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 NCEPLIBS-bufr 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.
| lunin | - Absolute value is Fortran logical unit number for BUFR file |
| usr | - Data values
|
| i1 | - First dimension of usr as allocated within the calling program |
| i2 | - Second dimension of usr
|
| iret | - Number of replications of str that were read/written from/to the data subset |
| str | - 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) |
Definition at line 1098 of file readwriteval.F90.
References bort(), bort2(), errwrt(), moda_msgcwd::inode, moda_usrint::inv, status(), string(), ufbsp(), x48(), and x84().
| recursive subroutine writlc | ( | integer, intent(in) | lunit, |
| character*(*), intent(in) | chr, | ||
| character*(*), intent(in) | str | ||
| ) |
Write a long character string (greater than 8 bytes) to a data subset.
The data subset should have already been written into a BUFR message before calling this subroutine to write a long character string into the subset.
If there is more than one occurrence of str within the data subset definition, then each occurrence can be written via a separate call to this subroutine, and by appending the ordinal number of the occurrence to STR in each case. For example, if there are 5 occurrences of mnemonic LSTID within a given data subset definition, then 5 separate calls should be made to this subroutine, once each with str set to 'LSTID#1', 'LSTID#2', 'LSTID#3', 'LSTID#4' and 'LSTID#5'. However, the first notation is superfluous, because omitting the ordinal number always defaults to the first occurrence of a particular string, so a user could just specify 'LSTID' instead of 'LSTID#1'.
Character strings which are 8 bytes or less in length can be written by converting the string into a real*8 value within the application program, and then using the real*8 usr array within a call to one of the NCEPLIBS-bufr values-writing subroutines prior to calling one of the subset-writing subroutines for the data subset.
| lunit | - Fortran logical unit number for BUFR file |
| chr | - Value corresponding to str |
| str | - Table B mnemonic of long character string to be written, possibly supplemented with an ordinal occurrence notation |
Definition at line 199 of file readwriteval.F90.
References bort(), moda_comprs::catx, errwrt(), getlens(), moda_bitbuf::ibit, moda_tables::ibt, moda_usrint::inv, moda_tables::itp, iupbs3(), moda_comprs::matx, moda_bitbuf::mbay, moda_comprs::ncol, moda_msgcwd::nsub, moda_usrint::nval, parstr(), parutg(), pkc(), status(), moda_tables::tag, moda_tables::typ, upb(), upbb(), usrtpl(), and x84().
Referenced by msgupd().
1.9.1