openbf.f File Reference

Connect a new file to the library, or initialize the library, or change verbosity associated with already-connected file. More...

Go to the source code of this file.

Functions/Subroutines
recursive subroutine	openbf (LUNIT, IO, LUNDX)
	Connects a new file to the NCEPLIBS-bufr software for input or output operations, or initializes the library without connecting to a file, or changes the verbosity of the library for an already-connected BUFR file. More...

Detailed Description

Connect a new file to the library, or initialize the library, or change verbosity associated with already-connected file.

Authors

J. Woollen, J. Ator, D. Keyser

Date

1994-01-06

Definition in file openbf.f.

Function/Subroutine Documentation

openbf()

recursive subroutine openbf	(		LUNIT,
		character*(*)	IO,
			LUNDX
	)

Connects a new file to the NCEPLIBS-bufr software for input or output operations, or initializes the library without connecting to a file, or changes 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 LUBFR.

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

[in]	LUNIT	– integer: Fortran logical unit number for BUFR file (unless IO is set to 'FIRST' or 'QUIET', in which case this is a dummy argument)
[in]	IO	– character*(*): 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 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
[in]	LUNDX	– integer: 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 out 2 = all warning and informational messages are printed out

Authors

J. Woollen, J. Ator, D. Keyser

Date

1994-01-06

Definition at line 123 of file openbf.f.

References arallocf(), bfrini(), bort(), dxinit(), errwrt(), moda_msgcwd::idate, modv_ifopbf::ifopbf, modv_im8b::im8b, moda_msgcwd::inode, moda_sc3bfr::isc3, moda_stcode::iscodes, moda_lushr::lus, moda_msgcwd::msub, modv_nfiles::nfiles, moda_msgcwd::nmsg, moda_msgcwd::nsub, moda_nulbfr::null, posapx(), readdx(), status(), wrdlen(), writdx(), wtstat(), and x84().

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