writsa.f File Reference

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...

Detailed Description

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

Definition in file writsa.f.

Function/Subroutine Documentation

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.

Authors

J. Woollen

J. Ator

Date

1994-01-06

Parameters

[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 0 = No BUFR message was returned within 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.

Remarks

• There is a maximum size for any BUFR message that can be written by the BUFRLIB 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.

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