NCEPLIBS-bufr  12.0.1
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

recursive subroutine writsa (LUNXX, LMSGT, MSGT, MSGL)
 Write a data subset into a BUFR message, and return each completed message within a memory array. More...
 

Detailed Description

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

Author
J. Woollen
J. Ator
Date
1994-01-06

Definition in file writsa.f.

Function/Subroutine Documentation

◆ writsa()

recursive subroutine writsa (   LUNXX,
  LMSGT,
dimension(*)  MSGT,
  MSGL 
)

Write a 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 BUFRLIB 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 BUFRLIB 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 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.

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.
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 for no message).
Author
J. Woollen
J. Ator
Date
1994-01-06

Definition at line 90 of file writsa.f.

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