NCEPLIBS-bufr
11.6.0
|
Write a data subset into a BUFR message, and return each completed message within a memory array. More...
Go to the source code of this file.
Functions/Subroutines | |
subroutine | writsa (LUNXX, LMSGT, MSGT, MSGL) |
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. More... | |
Write a data subset into a BUFR message, and return each completed message within a memory array.
Definition in file writsa.f.
subroutine writsa | ( | LUNXX, | |
LMSGT, | |||
dimension(*) | MSGT, | ||
MSGL | |||
) |
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.
[in] | LUNXX | – integer: Absolute value is Fortran logical unit number for BUFR file |
[in] | LMSGT | – integer: Dimensioned size (in integers) of MSGT; used by the subroutine to ensure that it doesn't overflow the MSGT array |
[out] | MSGT | – integer(*): BUFR message |
[out] | MSGL | – integer: Size (in integers) of BUFR message in MSGT
|
This subroutine looks and behaves a lot like subroutine writsb(). Specifically, it is called to indicate to the BUFRLIB software that all necessary values for a data subset (i.e. report) have been written, and thus that 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 BUFRLIB message-writing subroutines. Furthermore, all of the values for the data subset should have already been written into internal arrays via calls to any of the BUFRLIB values-writing subroutines
Where this subroutine differs from writsb() is that, in addition to doing all of the above, it also 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 BUFRLIB 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.
In other words, 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 BUFRLIB 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 BUFRLIB 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.
Program history log:
Date | Programmer | Comments |
---|---|---|
1994-01-06 | J. Woollen | Original author |
1998-07-08 | J. Woollen | Replaced call to Cray library routine "ABORT" with call to new internal routine bort(); modified to make Y2K compliant |
2000-09-19 | J. Woollen | Maximum message length increased from 10,000 to 20,000 bytes |
2003-11-04 | S. Bender | Added remarks and routine interdependencies |
2003-11-04 | D. Keyser | Unified/portable for WRF; added documentation; outputs more complete diagnostic info when routine terminates abnormally |
2004-08-18 | J. Ator | Add post msgupd() check for and return of message within MSGT in order to prevent loss of message in certain situations; maximum message length increased from 20,000 to 50,000 bytes |
2005-03-09 | J. Ator | Added capability for compressed messages |
2009-03-23 | J. Ator | Added LMSGT argument and check |
2014-12-10 | J. Ator | Use modules instead of COMMON blocks |
2019-05-09 | J. Ator | Added dimensions for MSGLEN and MSGTXT |
2020-09-22 | J. Ator | Added capability to return two BUFR messages within MSGT during the same call to this routine, in the rare instances where this can occur |
Definition at line 106 of file writsa.f.
References bort(), closmg(), msgupd(), status(), wrcmps(), and wrtree().