openclosebf.F90 File Reference

Open or close a file to the library. More...

Go to the source code of this file.

Functions/Subroutines
recursive subroutine	closbf (lunit)
	Close the connection between logical unit lunit and the NCEPLIBS-bufr software. More...
recursive subroutine	fortran_close (lunit, iret)
	Close a Fortran file on the local system. More...
recursive subroutine	fortran_open (filename, lunit, format, position, iret)
	Open a Fortran file on the local system. More...
recursive subroutine	openbf (lunit, io, lundx)
	Connect a new file to the NCEPLIBS-bufr software for input or output operations, or initialize the library without connecting to a file, or change the verbosity of the library for an already-connected BUFR file. More...
subroutine	posapx (lunxx)
	Position an output BUFR file for appending. More...
subroutine	rewnbf (lunit, isr)
	Store or restore parameters associated with a BUFR file. More...
recursive subroutine	status (lunit, lun, il, im)
	Check whether a specified Fortran logical unit number is currently connected to the NCEPLIBS-bufr software. More...
recursive subroutine	ufbcnt (lunit, kmsg, ksub)
	Get the current location of the file pointer within a BUFR file, in terms of a message number counting from the beginning of the file, and a data subset number counting from the beginning of that message. More...
recursive subroutine	ufbtab (lunin, tab, i1, i2, iret, str)
	Read through every data subset in a BUFR file and return one or more specified data values from each subset. More...
subroutine	wtstat (lunit, lun, il, im)
	Update file status in library internals. More...

Detailed Description

Open or close a file to the library.

Authors

J. Woollen, J. Ator, D. Keyser

Date

1994-01-06

Definition in file openclosebf.F90.

Function/Subroutine Documentation

closbf()

recursive subroutine closbf

(

integer, intent(in)

lunit

)

Close the connection between logical unit lunit and the NCEPLIBS-bufr software.

Remarks

• This subroutine will execute a Fortran "CLOSE" on logical unit lunit, even though subroutine openbf() didn't previously handle the corresponding Fortran "OPEN" of the same file.
• It's a good idea to call this subroutine for every lunit that was opened to the software via openbf(); however, it's especially important to do so when writing/encoding a BUFR file, in order to ensure that all output is properly flushed to lunit.

Parameters

lunit

- Fortran logical unit number for BUFR file

Author

J. Woollen, J. Ator

Date

1994-01-06

Definition at line 337 of file openclosebf.F90.

References closmg(), errwrt(), moda_nulbfr::null, status(), wtstat(), and x84().

Referenced by apxdx(), bufr_c2f_interface::closbf_c(), copybf(), datebf(), dumpbf(), exitbufr(), gettab(), mesgbc(), mesgbf(), split_by_subset(), ufbinx(), ufbmem(), ufbmex(), and ufbtab().

fortran_close()

recursive subroutine fortran_close	(	integer, intent(in)	lunit,
		integer, intent(out)	iret
	)

Close a Fortran file on the local system.

Parameters

lunit	- Fortran logical unit number for Fortran file
iret	- return code from the Fortran close statement

Author

Jeff Whitaker

Date

2015-08-30

Definition at line 48 of file openclosebf.F90.

References x48(), and x84().

fortran_open()

recursive subroutine fortran_open	(	character*(*), intent(in)	filename,
		integer, intent(in)	lunit,
		character*(*), intent(in)	format,
		character*(*), intent(in)	position,
		integer, intent(out)	iret
	)

Open a Fortran file on the local system.

Parameters

filename	- name of the file to be opened
lunit	- Fortran logical unit number for Fortran file
format	- format of the Fortran file
position	- to rewind or continue with open file
iret	- return code from the Fortran open statement

Author

Jeff Whitaker

Date

2015-08-30

Definition at line 15 of file openclosebf.F90.

References x48(), and x84().

openbf()

recursive subroutine openbf	(	integer, intent(in)	lunit,
		character*(*), intent(in)	io,
		integer, intent(in)	lundx
	)

Connect a new file to the NCEPLIBS-bufr software for input or output operations, or initialize the library without connecting to a file, or change the verbosity of the library for an already-connected BUFR file.

The logical unit numbers lunit and lundx must already be associated with actual filenames on the local system, typically via a Fortran "OPEN" statement. Multiple logical units can be connected to the NCEPLIBS-bufr software at any one time.

The argument io is a character string describing how the file connected to lunit will be used, e.g. 'IN' is used to access an existing file of BUFR messages for input (i.e. reading/decoding BUFR), and 'OUT' is used to access a new file for output (i.e. writing/encoding BUFR). An option 'APX' is also available which behaves like 'OUT', except that output is then appended to an existing BUFR file rather than creating a new one from scratch, and there are also some additional options 'NUL' and 'NODX' which can likewise be used instead of 'OUT' for some very special cases as needed. There's also an option 'SEC3' which can be used in place of 'IN' for certain cases when the user is attempting to read BUFR messages whose content and descriptor layout are unknown in advance. However, all of these additional options are basically just variations of 'IN' or 'OUT', again depending on whether the intent is to read or write BUFR messages from the file connected to lunit. The only exceptions are when io = 'FIRST' or 'QUIET'. When io = 'FIRST', the subroutine simply checks whether it has already been called from within the application program and, if not, goes ahead and initializes the library without actually connecting any files in lunit or lundx.

Alternatively, when io = 'QUIET', the subroutine simply sets or resets the internal print verbosity switch to the value of input argument lundx, overriding its previous value and/or its internal default value of 0.

The third and final call argument lundx identifies the logical unit which contains the definition of the DX BUFR tables to be associated with unit lunit. Except when io = 'SEC3', every BUFR file that is linked to the NCEPLIBS-bufr software must have a DX BUFR tables file associated with it, and these tables may be defined within a separate ASCII text file (see Description and Format of DX BUFR Tables for more info.) or, in the case of an existing BUFR file, may be embedded within the first few BUFR messages of the file itself, and in which case the user can denote this to the subroutine by setting lundx to the same value as lunit.

Remarks

• When an existing BUFR file is accessed for input (i.e. reading/decoding BUFR), the associated DX BUFR tables defined by lundx are stored internally within the NCEPLIBS-bufr software and are referenced during all subsequent processing of the file. Likewise, when a file is accessed for output (i.e. writing/encoding BUFR), the associated DX BUFR tables are still stored internally for subsequent reference; however, the output file itself is also initialized by writing the BUFR table information (as one or more BUFR messages) to the beginning of the file, except when io = 'NODX', and in which case the writing of these additional messages is suppressed.
• As noted above, 'SEC3' is the only value of io (other than 'FIRST' or 'QUIET') where it's not necessary to provide pre-defined DX BUFR tables via lundx. Instead, this option instructs the NCEPLIBS-bufr software to unpack the data description section (Section 3) from each BUFR message it reads and then decode the contents accordingly. In this case, it's necessary to provide a set of BUFR master tables containing listings of all possible BUFR descriptors (see Description and Format of master BUFR Tables for more info.), but otherwise no prior knowledge is required of the contents of the messages to be decoded.

Parameters

lunit	- Fortran logical unit number for BUFR file (unless io is set to 'FIRST' or 'QUIET', in which case this is a dummy argument)
io	- flag indicating how lunit is to be used by the software: 'IN' = input operations with table processing 'INX' = input operations w/o table processing 'OUX' = output operations w/o table processing 'OUT' = output operations with table processing 'SEC3' = same as 'IN', except use Section 3 of input messages for decoding rather than DX BUFR table information from lundx; in this case lundx is ignored, and the user must provide appropriate master BUFR tables within the directory specified by a subsequent call to subroutine mtinfo() 'NODX' = same as 'OUT', except don't write DX BUFR table messages to lunit 'APN' = same as 'NODX', except begin writing at end of file ("append") 'APX' = same as 'APN', except backspace before appending 'NUL' = same as 'OUT', except don't write any messages whatsoever to lunit (e.g. when subroutine writsa() is to be used) 'INUL' = same as 'IN', except don't read any messages whatsoever from lunit (e.g. when subroutine readerme() is to be used) 'QUIET' = lunit is ignored; this is an indicator that the value for iprt in common block /quiet/ is being reset to the value in lundx 'FIRST' = lunit and lundx are ignored; this is an indicator to initialize the NCEPLIBS-bufr software, in case this subroutine was never previously called
lundx	- Fortran logical unit number containing DX BUFR table information, except as noted below: If io is not set to 'FIRST' or 'QUIET' = Fortran logical unit number containing DX BUFR table information to be used in reading/writing from/to lunit (depending on the case); this value may be set equal to lunit if DX BUFR table information is already embedded in lunit If io is set to 'QUIET' = indicator for degree of printout: -1 = no printout except for ABORT messages 0 = limited printout (default) 1 = all warning messages are printed 2 = all warning and info messages are printed 3 = all warning, info and debug messages are printed

Authors

J. Woollen, J. Ator, D. Keyser

Date

1994-01-06

Definition at line 168 of file openclosebf.F90.

References arallocf(), bfrini(), bort(), errwrt(), moda_msgcwd::idate, moda_msgcwd::inode, moda_sc3bfr::isc3, moda_stcode::iscodes, moda_lushr::lus, moda_msgcwd::msub, moda_msgcwd::nmsg, moda_msgcwd::nsub, moda_nulbfr::null, posapx(), readdx(), status(), writdx(), wtstat(), and x84().

Referenced by apxdx(), binv(), cmpbqm(), copybf(), datebf(), dumpbf(), fdebufr_c(), gettab(), mesgbc(), mesgbf(), bufr_c2f_interface::openbf_c(), pkvs01(), rdmgsb(), readbp(), readmp(), sinv(), split_by_subset(), ufbinx(), ufbmem(), ufbmex(), and ufbtab().

posapx()

subroutine posapx

(

integer, intent(in)

lunxx

)

Position an output BUFR file for appending.

Read to the end of the file pointed to by abs(lunxx) and position it for appending. The file must have already been opened for output operations. If lunxx < 0, then the file is not backspaced before being positioned for append.

Parameters

lunxx

- Absolute value is Fortran logical unit number for BUFR file

Author

Woollen

Date

1994-01-06

Definition at line 630 of file openclosebf.F90.

References bort(), moda_mgwa::mgwa, rdbfdx(), rdmsgw(), and status().

Referenced by openbf().

rewnbf()

subroutine rewnbf	(	integer, intent(in)	lunit,
		integer, intent(in)	isr
	)

Store or restore parameters associated with a BUFR file.

Depending on the value of isr, either:

• Store the current parameters associated with a BUFR file connected to lunit (read/write pointers, etc.), set the file status to read, then rewind the BUFR file and position it such that the next BUFR message read will be the first message in the file containing actual subsets with data; or
• Restore the BUFR file connected to lunit to the parameters it had prior to the previous call, and using the information that was saved previously

This allows information to be extracted from a particular subset in a BUFR file which is in the midst of being read from or written to by an application program. Note that, for any given BUFR file, a call to this subroutine with isr = 0 must precede a call to this same subroutine with isr = 1. An application program might first call this subroutine with isr = 0, then call either subroutine rdmgsb() or ufbinx() to get information from a subset, then call this routine again with isr = 1 to restore the pointers in the BUFR file to their original location. For example, this subroutine is called internally by subroutine ufbtab() whenever the BUFR file it is acting upon is already open for input or output.

Parameters

lunit	- Fortran logical unit number for BUFR file.
isr	- Switch: 0 = Store current parameters associated with BUFR file, set file status to read, and rewind file such that next message read is first message containing subset data 1 = Restore BUFR file with parameters saved from the previous call to this routine with isr = 0

Author

Woollen

Date

2003-11-04

Definition at line 693 of file openclosebf.F90.

References bort(), moda_bitbuf::ibit, moda_bufrsr::jbay, moda_bufrsr::jbit, moda_bufrsr::jbyt, moda_bufrsr::jill, moda_bufrsr::jimm, moda_bufrsr::jmsg, moda_bufrsr::jsr, moda_bufrsr::jsub, moda_bufrsr::junn, moda_bitbuf::mbay, moda_bitbuf::mbyt, moda_msgcwd::nmsg, moda_msgcwd::nsub, readmg(), readsb(), status(), and wtstat().

Referenced by ufbinx(), and ufbtab().

status()

recursive subroutine status	(	integer, intent(in)	lunit,
		integer, intent(out)	lun,
		integer, intent(out)	il,
		integer, intent(out)	im
	)

Check whether a specified Fortran logical unit number is currently connected to the NCEPLIBS-bufr software.

If the unit number is already connected, then the subroutine returns information about the associated file. Otherwise, it returns the next available file ID that could be used to connect the associated file to the software via a subsequent call to subroutine wtstat().

Parameters

lunit	- Fortran logical unit number for BUFR file
lun	- File ID associated with lunit 0 = lunit is not already connected to the software, and there is no remaining internal space available that could be used to connect it
il	- File status: 0 = lunit is not already connected to the software, but lun contains a file ID that could be used to connect it via a subsequent call to subroutine wtstat() 1 = lunit is already connected to the software for output operations (i.e. writing/encoding BUFR) -1 = lunit is already connected to the software for input operations (i.e. reading/decoding BUFR)
im	- Message status, indicating whether there is already a message open within internal arrays for lunit: 0 = No 1 = Yes

Author

J. Woollen

Date

1994-01-06

Definition at line 405 of file openclosebf.F90.

References bort(), errwrt(), moda_stbfr::iolun, moda_stbfr::iomsg, x48(), and x84().

Referenced by closbf(), closmg(), copybf(), copymg(), copysb(), cpdxmm(), cpymem(), datebf(), drfini(), dumpbf(), dxdump(), getabdb(), getcfmng(), gettab(), gettagpr(), gettagre(), getvalnb(), ifbget(), igetsc(), invmrg(), iupvs01(), lcmgdf(), mesgbc(), minimg(), msgwrt(), nemdefs(), nemspecs(), nmsub(), openbf(), openmb(), openmg(), posapx(), rdmemm(), rdmems(), rdmgsb(), rdmsgw(), readdx(), readerme(), readlc(), readmg(), readns(), readsb(), rewnbf(), rtrcpt(), setvalnb(), bufr_c2f_interface::status_c(), stndrd(), ufbcnt(), ufbcpy(), ufbcup(), ufbdmp(), ufbevn(), ufbget(), ufbin3(), ufbint(), ufbinx(), ufbmem(), ufbmms(), ufbovr(), ufbpos(), ufbqcd(), ufbqcp(), ufbrep(), ufbrms(), ufbseq(), ufbstp(), ufbtab(), ufbtam(), ufdump(), upftbv(), wrcmps(), wrdxtb(), writlc(), writsa(), and writsb().

ufbcnt()

recursive subroutine ufbcnt	(	integer, intent(in)	lunit,
		integer, intent(out)	kmsg,
		integer, intent(out)	ksub
	)

Get the current location of the file pointer within a BUFR file, in terms of a message number counting from the beginning of the file, and a data subset number counting from the beginning of that message.

Remarks

• Logical unit lunit should have already been opened via a previous call to subroutine openbf(). If lunit was opened for input operations, then kmsg is incremented with each call to any of the message-reading subroutines, and ksub is incremented with each call to any of the subset-reading subroutines for that message. Otherwise, if lunit was opened for output operations, then kmsg is incremented with each call to any of the message-writing subroutines, and ksub is incremented with each call to any of the subset-writing subroutines for that message.
• The value returned for kmsg does not include any messages which contain DX BUFR tables information.

Parameters

lunit	- Fortran logical unit number for BUFR file
kmsg	- Ordinal number of current message, counting from the beginning of the BUFR file, but not counting any messages which contain DX BUFR tables information
ksub	- Ordinal number of current data subset within (kmsg)th message, counting from the beginning of the message

Author

J. Woollen

Date

1994-01-06

Definition at line 585 of file openclosebf.F90.

References bort(), moda_msgcwd::nmsg, moda_msgcwd::nsub, status(), x48(), and x84().

Referenced by cmpbqm(), readbp(), and ufbpos().

ufbtab()

recursive subroutine ufbtab	(	integer, intent(in)	lunin,
		real*8, dimension(i1,i2), intent(out)	tab,
		integer, intent(in)	i1,
		integer, intent(in)	i2,
		integer, intent(out)	iret,
		character*(*), intent(in)	str
	)

Read through every data subset in a BUFR file and return one or more specified data values from each subset.

This provides a useful way to scan the ranges of one or more specified data values across all of the data subsets within an entire BUFR file. It is similar to subroutine ufbtam(), except that ufbtam() works on data subsets within internal arrays.

It is the user's responsibility to ensure that tab is dimensioned sufficiently large enough to accommodate the number of data values that are to be read from the BUFR file. Specifically, each row of tab will contain the data values read from a different data subset, so the value i2 must be at least as large as the total number of data subsets in the BUFR file.

If logical unit abs(lunin) has already been opened via a previous call to subroutine openbf(), then this subroutine will save the current file position, rewind the file to the beginning, read through the entire file, and then restore it to its previous file position. Otherwise, if logical unit abs(lunin) has not already been opened via a previous call to subroutine openbf(), then this subroutine will open it via an internal call to subroutine openbf(), read through the entire file, and then close it via an internal call to subroutine closbf().

Remarks

• If lunin < 0, the number of data subsets in the BUFR file will still be returned in iret; however, str will be ignored, and all of the values returned in tab will contain the current placeholder value for "missing" data.
• If any of the Table B mnemonics in str are replicated within the data subset definition for the BUFR file, then this subroutine will only return the value corresponding to the first occurrence of each such mnemonic (counting from the beginning of the data subset definition) within the corresponding row of tab.
• 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 tab:
  • 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

Parameters

lunin	- Absolute value is Fortran logical unit number for BUFR file
tab	- Data values
i1	- First dimension of tab as allocated within the calling program
i2	- Second dimension of tab as allocated within the calling program
iret	- Number of data subsets in BUFR file
str	- String of blank-separated Table B mnemonics, in one-to-one correspondence with the number of data values that will be read from each data subset within the first dimension of tab (see DX BUFR Tables for further information about Table B mnemonics)

Author

J. Woollen

Date

1994-01-06

Definition at line 856 of file openclosebf.F90.

References bort(), closbf(), errwrt(), moda_bitbuf::ibit, moda_tables::ibt, moda_usrint::inv, ireadmg(), ireadsb(), moda_tables::itp, moda_bitbuf::mbay, moda_bitbuf::mbyt, moda_unptyp::msgunp, moda_msgcwd::msub, moda_msgcwd::nmsg, nmsub(), moda_msgcwd::nsub, moda_usrint::nval, openbf(), parstr(), rewnbf(), status(), string(), up8(), upb(), upb8(), upc(), ups(), usrtpl(), x48(), and x84().

Referenced by sinv().

wtstat()

subroutine wtstat	(	integer, intent(in)	lunit,
		integer, intent(in)	lun,
		integer, intent(in)	il,
		integer, intent(in)	im
	)

Update file status in library internals.

This subroutine can be used to connect or disconnect a specified Fortran logical unit number to/from the NCEPLIBS-bufr software, and it can also be used to set or reset the internal message status associated with that logical unit number.

Note

Before this subroutine is called to connect any lunit to the software, a previous call should have been made to subroutine status() to confirm that internal space is available to connect the associated file, as well as to obtain an lun value to use in connecting it. Once a file is connected, the corresponding lunit and lun values remain linked to each other for as long as the file is connected to the software.

Parameters

lunit	- Fortran logical unit number for BUFR file
lun	- File ID associated with lunit
il	- File status update option: 0 Disconnect lunit from the software 1 Connect lunit to the software for output operations (i.e. writing/encoding BUFR), if not already connected -1 Connect lunit to the software for input operations (i.e. reading/decoding BUFR), if not already connected
im	- Message status update option, indicating whether a message is currently open within the internal arrays for lunit: 0 No 1 Yes

Author

J. Woollen

Date

1994-01-06

Definition at line 508 of file openclosebf.F90.

References bort(), moda_stbfr::iolun, and moda_stbfr::iomsg.

Referenced by closbf(), closmg(), openbf(), openmb(), openmg(), rdmemm(), readerme(), readmg(), and rewnbf().