NCEPLIBS-bufr  11.6.0
 All Data Structures Files Functions Variables Pages
ufbpos.f
Go to the documentation of this file.
1 C> @file
2 C> @brief Jump forwards or backwards to a specified data subset within
3 C> a BUFR file
4 
5 C> This subroutine repositions the file pointer to the beginning of a
6 C> specified data subset within a specified message of a BUFR file,
7 C> then reads that data subset into internal arrays so that it can be
8 C> further processed via subsequent calls to any of the
9 C> [values-reading subroutines](@ref hierarchy).
10 C>
11 C> The specified data subset may be before or after the current location
12 C> of the file pointer within the BUFR file.
13 C>
14 C> @author J. Woollen
15 C> @date 1995-11-22
16 C>
17 C> @param[in] LUNIT -- integer: Fortran logical unit number for BUFR file
18 C> @param[in] IREC -- integer: Ordinal number of message to be read,
19 C> counting from the beginning of the BUFR file, but
20 C> not counting any messages which contain DX BUFR
21 C> tables information
22 C> @param[in] ISUB -- integer: Ordinal number of data subset to be
23 C> read from (IREC)th message, counting from the
24 C> beginning of the message
25 C> @param[out] SUBSET -- character*8: Table A mnemonic for type of BUFR
26 C> message that was read
27 C> (see [DX BUFR Tables](@ref dfbftab)
28 C> for further information about Table A mnemonics)
29 C> @param[out] JDATE -- integer: Date-time stored within Section 1 of
30 C> BUFR message that was read, in format of either
31 C> YYMMDDHH or YYYYMMDDHH, depending on the most
32 C> recent call to subroutine datelen()
33 C>
34 C> @remarks
35 C> - Logical unit LUNIT should have already been opened for input
36 C> operations via a previous call to subroutine openbf().
37 C> - The value specified for IREC should <b>not</b> include any messages
38 C> which contain DX BUFR tables information.
39 C>
40 C> <b>Program history log:</b>
41 C> | Date | Programmer | Comments |
42 C> | -----|------------|----------|
43 C> | 1995-11-22 | J. Woollen | Original author |
44 C> | 2005-03-04 | D. Keyser | Added documentation |
45 C> | 2006-04-14 | J. Ator | Remove unnecessary MOIN initialization |
46 C> | 2009-03-23 | J. Ator | Modified to handle embedded BUFR table (dictionary) messages |
47 C> | 2014-12-10 | J. Ator | Use modules instead of COMMON blocks |
48 C> | 2021-10-08 | J. Ator | Use readsb() to read all subsets from IREC(th) message |
49 C>
50  SUBROUTINE ufbpos(LUNIT,IREC,ISUB,SUBSET,JDATE)
51 
52  USE moda_msgcwd
53  USE moda_bitbuf
54 
55  CHARACTER*128 bort_str
56  CHARACTER*8 subset
57 
58 C-----------------------------------------------------------------------
59 C----------------------------------------------------------------------
60 
61 C MAKE SURE A FILE IS OPEN FOR INPUT
62 C ----------------------------------
63 
64  CALL status(lunit,lun,il,im)
65  IF(il.EQ.0) goto 900
66  IF(il.GT.0) goto 901
67 
68  IF(irec.LE.0) goto 902
69  IF(isub.LE.0) goto 903
70 
71 C SEE WHERE POINTERS ARE CURRENTLY LOCATED
72 C ----------------------------------------
73 
74  CALL ufbcnt(lunit,jrec,jsub)
75 
76 C REWIND FILE IF REQUESTED POINTERS ARE BEHIND CURRENT POINTERS
77 C -------------------------------------------------------------
78 
79  IF(irec.LT.jrec .OR. (irec.EQ.jrec.AND.isub.LT.jsub)) THEN
80  CALL cewind(lun)
81  nmsg(lun) = 0
82  nsub(lun) = 0
83  CALL ufbcnt(lunit,jrec,jsub)
84  ENDIF
85 
86 C READ SUBSET #ISUB FROM MESSAGE #IREC FROM FILE
87 C ----------------------------------------------
88 
89  DO WHILE (irec.GT.jrec)
90  CALL readmg(lunit,subset,jdate,iret)
91  IF(iret.LT.0) goto 904
92  CALL ufbcnt(lunit,jrec,jsub)
93  ENDDO
94 
95  DO WHILE (isub.GT.jsub)
96  CALL readsb(lunit,iret)
97  IF(iret.NE.0) goto 905
98  CALL ufbcnt(lunit,jrec,jsub)
99  ENDDO
100 
101 C EXITS
102 C -----
103 
104  RETURN
105 900 CALL bort('BUFRLIB: UFBPOS - INPUT BUFR FILE IS CLOSED, IT MUST'//
106  . ' BE OPEN FOR INPUT')
107 901 CALL bort('BUFRLIB: UFBPOS - INPUT BUFR FILE IS OPEN FOR OUTPUT'//
108  . ', IT MUST BE OPEN FOR INPUT')
109 902 WRITE(bort_str,'("BUFRLIB: UFBPOS - REQUESTED MESSAGE NUMBER '//
110  . 'TO READ IN (",I5,") IS NOT VALID")') irec
111  CALL bort(bort_str)
112 903 WRITE(bort_str,'("BUFRLIB: UFBPOS - REQUESTED SUBSET NUMBER '//
113  . 'TO READ IN (",I5,") IS NOT VALID")') isub
114  CALL bort(bort_str)
115 904 WRITE(bort_str,'("BUFRLIB: UFBPOS - REQUESTED MESSAGE NUMBER '//
116  . 'TO READ IN (",I5,") EXCEEDS THE NUMBER OF MESSAGES IN THE '//
117  . 'FILE (",I5,")")') irec,jrec
118  CALL bort(bort_str)
119 905 WRITE(bort_str,'("BUFRLIB: UFBPOS - REQ. SUBSET NUMBER TO READ'//
120  . ' IN (",I3,") EXCEEDS THE NUMBER OF SUBSETS (",I3,") IN THE '//
121  . 'REQ. MESSAGE (",I5,")")') isub,ksub,irec
122  CALL bort(bort_str)
123  END
subroutine ufbpos(LUNIT, IREC, ISUB, SUBSET, JDATE)
This subroutine repositions the file pointer to the beginning of a specified data subset within a spe...
Definition: ufbpos.f:50
subroutine status(LUNIT, LUN, IL, IM)
This subroutine checks whether a specified Fortran logical unit number is currently connected to the ...
Definition: status.f:55
void cewind(f77int *nfile)
This subroutine rewinds a BUFR file back to its beginning.
Definition: cread.c:100
subroutine ufbcnt(LUNIT, KMSG, KSUB)
This subroutine returns 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.
Definition: ufbcnt.f:45
subroutine bort(STR)
This subroutine calls subroutine errwrt() to log an error message, then calls subroutine bort_exit() ...
Definition: bort.f:22
This module contains array and variable declarations used to store BUFR messages internally for multi...
Definition: moda_bitbuf.F:10
subroutine readmg(LUNXX, SUBSET, JDATE, IRET)
This subroutine reads the next BUFR message from logical unit ABS(LUNXX) into internal arrays...
Definition: readmg.f:73
subroutine readsb(LUNIT, IRET)
This subroutine reads the next data subset from a BUFR message into internal arrays.
Definition: readsb.f:47