ufbtab.f File Reference

Go to the source code of this file.

Functions/Subroutines
subroutine	ufbtab (LUNIN, TAB, I1, I2, IRET, STR)
	THIS SUBROUTINE EITHER OPENS A BUFR FILE CONNECTED TO ABS(LUNIN) FOR INPUT OPERATIONS (IF IT IS NOT ALREADY OPENED AS SUCH), OR SAVES ITS POSITION AND REWINDS IT TO THE FIRST DATA MESSAGE (IF BUFR FILE ALREADY OPENED), THE EXTENT OF ITS PROCESSING IS DETERMINED BY THE SIGN OF LUNIN. More...

Detailed Description

Author

WOOLLEN

Date

1994-01-06

Definition in file ufbtab.f.

Function/Subroutine Documentation

subroutine ufbtab	(		LUNIN,
		real*8, dimension(i1,i2)	TAB,
			I1,
			I2,
			IRET,
		character*(*)	STR
	)

THIS SUBROUTINE EITHER OPENS A BUFR FILE CONNECTED TO ABS(LUNIN) FOR INPUT OPERATIONS (IF IT IS NOT ALREADY OPENED AS SUCH), OR SAVES ITS POSITION AND REWINDS IT TO THE FIRST DATA MESSAGE (IF BUFR FILE ALREADY OPENED), THE EXTENT OF ITS PROCESSING IS DETERMINED BY THE SIGN OF LUNIN.

IF LUNIN IS GREATER THAN ZERO, THIS SUBROUTINE READS SPECIFIED VALUES FROM ALL DATA SUBSETS IN THE BUFR FILE INTO INTERNAL ARRAYS AND RETURNS THESE VALUES ALONG WITH A COUNT OF THE SUBSETS. IF LUNIN IS LESS THAN ZERO, THIS SUBROUTINE RETURNS THE BUFR ARCHIVE LIBRARY'S GLOBAL VALUE FOR MISSING (REGARDLESS OF THE MNEMONICS SPECIFIED IN STR) ALONG WITH A COUNT OF THE SUBSETS (SEE REMARKS 2). FINALLY, THIS SUBROUTINE EITHER CLOSES THE BUFR FILE IN ABS(LUNIN) (IF IT WAS OPENED HERE) OR RESTORES IT TO ITS PREVIOUS READ/WRITE STATUS AND POSITION (IF IT WAS NOT OPENED HERE). WHEN LUNIN IS GREATER THAN ZERO, THE DATA VALUES CORRESPOND TO MNEMONICS, NORMALLY WHERE THERE IS NO REPLICATION (THERE CAN BE REGULAR OR DELAYED REPLICATION, BUT THIS SUBROUTINE WILL ONLY READ THE FIRST OCCURRENCE OF THE MNEMONIC IN EACH SUBSET). UFBTAB PROVIDES A MECHANISM WHEREBY A USER CAN EITHER DO A QUICK SCAN OF THE RANGE OF VALUES CORRESPONDING TO ONE OR MORE MNEMNONICS AMONGST ALL DATA SUBSETS FOR AN ENTIRE BUFR FILE (WHEN LUNIN IS GREATER THAN ZERO), OR SIMPLY OBTAIN A COUNT OF SUBSETS IN THE BUFR FILE (WHEN LUNIN IS LESS THAN ZERO); NO OTHER BUFR ARCHIVE LIBRARY ROUTINES HAVE TO BE CALLED. THIS SUBROUTINE IS SIMILAR TO BUFR ARCHIVE LIBRARY SUBROUTINE UFBTAM EXCEPT UFBTAM READS SUBSETS FROM MESSAGES STORED IN INTERNAL MEMORY AND IT HAS NO OPTION FOR RETURNING ONLY A COUNT OF THE SUBSETS. IN ADDITION, UFBTAM CURRENTLY CANNOT READ DATA FROM COMPRESSED BUFR MESSAGES. UFBTAB CAN READ DATA FROM BOTH UNCOMPRESSED AND COMPRESSED BUFR MESSAGES.

PROGRAM HISTORY LOG: 1994-01-06 J. WOOLLEN – ORIGINAL AUTHOR 1998-07-08 J. WOOLLEN – IMPROVED MACHINE PORTABILITY 1998-10-27 J. WOOLLEN – MODIFIED TO CORRECT PROBLEMS CAUSED BY IN- LINING CODE WITH FPP DIRECTIVES 1999-11-18 J. WOOLLEN – THE NUMBER OF BUFR FILES WHICH CAN BE OPENED AT ONE TIME INCREASED FROM 10 TO 32 (NECESSARY IN ORDER TO PROCESS MULTIPLE BUFR FILES UNDER THE MPI) 2000-09-19 J. WOOLLEN – MAXIMUM MESSAGE LENGTH INCREASED FROM 10,000 TO 20,000 BYTES 2002-05-14 J. WOOLLEN – REMOVED OLD CRAY COMPILER DIRECTIVES 2003-11-04 S. BENDER – ADDED REMARKS/BUFRLIB ROUTINE INTERDEPENDENCIES 2003-11-04 D. KEYSER – MODIFIED TO NOT ABORT WHEN THERE ARE TOO MANY SUBSETS COMING IN (I.E., .GT. "I2"), BUT RATHER JUST PROCESS "I2" REPORTS AND PRINT A DIAGNOSTIC; MAXJL (MAXIMUM NUMBER OF JUMP/LINK ENTRIES) INCREASED FROM 15000 TO 16000 (WAS IN VERIFICATION VERSION); MODIFIED TO CALL ROUTINE REWNBF WHEN THE BUFR FILE IS ALREADY OPENED, ALLOWS SPECIFIC SUBSET INFORMATION TO BE READ FROM A FILE IN THE MIDST OF ITS BEING READ FROM OR WRITTEN TO), BEFORE OPENBF WAS ALWAYS CALLED AND THIS WOULD HAVE LED TO AN ABORT OF THE APPLICATION PROGRAM (WAS IN VERIFICATION VERSION); UNIFIED/PORTABLE FOR WRF; ADDED DOCUMENTATION (INCLUDING HISTORY) 2004-08-09 J. ATOR – MAXIMUM MESSAGE LENGTH INCREASED FROM 20,000 TO 50,000 BYTES 2005-09-16 J. WOOLLEN – WORKS FOR COMPRESSED BUFR MESSAGES; ADDED OPTION TO RETURN ONLY SUBSET COUNT (WHEN INPUT UNIT NUMBER IS LESS THAN ZERO) 2006-04-14 J. ATOR – ADD DECLARATION FOR CREF 2007-01-19 J. ATOR – REPLACED CALL TO PARSEQ WITH CALL TO PARSTR 2009-04-21 J. ATOR – USE ERRWRT 2009-12-01 J. ATOR – FIX BUG FOR COMPRESSED CHARACTER STRINGS WHICH ARE IDENTICAL ACROSS ALL SUBSETS IN A SINGLE MESSAGE 2010-05-07 J. ATOR – WHEN CALLING IREADMG, TREAT READ ERROR AS END-OF-FILE CONDITION 2012-03-02 J. ATOR – USE FUNCTION UPS 2012-09-15 J. WOOLLEN – MODIFIED FOR C/I/O/BUFR INTERFACE; USE NEW OPENBF TYPE 'INX' TO OPEN AND CLOSE THE C FILE WITHOUT CLOSING THE FORTRAN FILE 2014-11-20 J. ATOR – ENSURE OPENBF HAS BEEN CALLED AT LEAST ONCE BEFORE CALLING STATUS 2014-12-10 J. ATOR – USE MODULES INSTEAD OF COMMON BLOCKS 2016-12-19 J. WOOLLEN – FIX BUG TO PREVENT INVENTORY OVERFLOW

USAGE: CALL UFBTAB (LUNIN, TAB, I1, I2, IRET, STR) INPUT ARGUMENT LIST: LUNIN - INTEGER: ABSOLUTE VALUE IS FORTRAN LOGICAL UNIT NUMBER FOR BUFR FILE I1 - INTEGER:

• IF LUNIN IS GREATER THAN ZERO: LENGTH OF FIRST DIMENSION OF TAB (MUST BE AT LEAST AS LARGE AS THE NUMBER OF BLANK-SEPARATED MNEMONICS IN STR)
• IF LUNIN IS LESS THAN ZERO: LENGTH OF FIRST DIMENSION OF TAB (RECOMMEND PASSING IN WITH VALUE OF 1 - SEE REMARKS 2) I2 - INTEGER: LENGTH OF SECOND DIMENSION OF TAB
• IF LUNIN IS GREATER THAN ZERO: MUST BE AT LEAST AS LARGE AS VALUE RETURNED IN IRET, OTHERWISE ONLY FIRST I2 SUBSETS ARE RETURNED IN TAB
• IF LUNIN IS LESS THAN ZERO: RECOMMEND PASSING IN WITH VALUE OF 1 - SEE REMARKS 2 STR - CHARACTER*(*):
• IF LUNIN IS GREATER THAN ZERO: STRING OF BLANK- SEPARATED TABLE B MNEMONICS IN ONE-TO-ONE CORRESPONDENCE WITH FIRST DIMENSION OF TAB, I1 (THE NUMBER OF MNEMONICS IN THE STRING MUST BE NO LARGER THAN I1)
  • THERE ARE THREE "GENERIC" MNEMONICS NOT RELATED TO TABLE B, THESE RETURN THE FOLLOWING INFORMATION IN CORRESPONDING TAB LOCATION: 'NUL' WHICH ALWAYS RETURNS BMISS ("MISSING") 'IREC' WHICH ALWAYS RETURNS THE CURRENT BUFR MESSAGE (RECORD) NUMBER IN WHICH THIS SUBSET RESIDES 'ISUB' WHICH ALWAYS RETURNS THE CURRENT SUBSET NUMBER OF THIS SUBSET WITHIN THE BUFR MESSAGE (RECORD) NUMBER 'IREC'
• IF LUNIN IS LESS THAN ZERO: DUMMY {RECOMMEND PASSING IN STRING AS A 1-CHARACTER BLANK (i.e., ' ') - SEE REMARKS 2}

OUTPUT ARGUMENT LIST: TAB - REAL*8: (I1,I2):

• IF LUNIN IS GREATER THAN ZERO: STARTING ADDRESS OF DATA VALUES READ FROM BUFR FILE
• IF LUNIN IS LESS THAN ZERO: STARTING ADDRESS OF ARRAY OF VALUES ALL RETURNED WITH THE BUFRLIB'S GLOBAL VALUE FOR MISSING (BMISS) IRET - INTEGER: NUMBER OF DATA SUBSETS IN BUFR FILE
• IF LUNIN IS GREATER THAN ZERO: MUST BE NO LARGER THAN I2, OTHERWISE ONLY FIRST I2 SUBSETS ARE RETURNED IN TAB

REMARKS: 1) NOTE THAT UFBMEM CAN BE CALLED PRIOR TO THIS TO STORE THE BUFR MESSAGES INTO INTERNAL MEMORY.

2) BELOW ARE TWO EXAMPLES WHERE THE USER CALLS UFBTAB WITH LUNIN LESS THAN ZERO SO AS TO ONLY OBTAIN A COUNT OF SUBSETS IN A BUFR FILE (ALONG WITH THE BUFRLIB'S GLOBAL VALUE FOR "MISSING").

EXAMPLE 1) I1 AND I2 ARE SET TO 1 SUCH THAT TAB IS A SCALAR AND STR IS SET TO A 1-CHARACTER BLANK. THESE ARE THE RECOMMENDED VALUES FOR I1, I2 AND STR SINCE THEY USE THE LEAST AMOUNT OF MEMORY):

REAL(8) TAB .... .... CALL UFBTAB(-LUNIN,TAB,1,1,IRET,' ') .... ....

HERE IRET WILL RETURN THE COUNT OF SUBSETS IN THE BUFR FILE AND TAB WILL RETURN THE BUFRLIB'S GLOBAL VALUE FOR "MISSING" (BMISS).

EXAMPLE 2) I1 IS SET TO 4 AND I2 IS SET TO 8 SUCH THAT TAB IS A 32-WORD ARRAY, AND STR IS SET TO A NONSENSICAL STRING. THESE VALUES FOR I1, I2 AND STR WASTE MEMORY BUT GIVE THE SAME ANSWERS FOR TAB AND IRET AS IN EXAMPLE 1 (FOR THE SAME INPUT BUFR FILE!):

REAL(8) TAB(4,8) .... .... CALL UFBTAB(-LUNIN,TAB,4,8,IRET,'BUFR IS A WONDERFUL FMT') .... ....

HERE IRET WILL AGAIN RETURN THE COUNT OF SUBSETS IN THE BUFR FILE AND ALL 32 VALUES OF ARRAY TAB WILL RETURN THE BUFRLIB'S GLOBAL VALUE FOR "MISSING" (BMISS).

THE SIXTH ARGUMENT STR IS A DUMMY VALUE AND CAN BE SET TO ANY CHARACTER STRING (AGAIN, A 1-CHARACTER BLANK ' ' IS RECOMMENDED). THE THIRD ARGUMENT I1 HAS NO RELATIONSHIP WITH THE NUMBER OF BLANK-SEPARATED MNEMONICS IN STR AND CAN BE SET TO ANY INTEGER VALUE (AGAIN, 1 IS RECOMMENDED). THE FOURTH ARGUMENT I2 HAS NO RELATIONSHIP WITH THE NUMBER OF DATA SUBSETS IN THE BUFR FILE RETURNED IN IRET (AGAIN, 1 IS RECOMMENDED).

.....................................................................

THIS ROUTINE CALLS:        BORT     CLOSBF   ERRWRT   IREADMG
                           IREADSB  MESGBC   NMSUB    OPENBF
                           PARSTR   REWNBF   STATUS   STRING
                           UPB      UPBB     UPC      UPS
                           USRTPL
THIS ROUTINE IS CALLED BY: None
                           Normally called only by application
                           programs.

Definition at line 197 of file ufbtab.f.

References bort(), closbf(), errwrt(), ireadmg(), ireadsb(), mesgbc(), nmsub(), openbf(), parstr(), rewnbf(), status(), string(), upb(), upbb(), upc(), ups(), and usrtpl().