NCEPLIBS-bufr  11.7.0
 All Data Structures Files Functions Variables Pages
getcfmng.f
Go to the documentation of this file.
1 C> @file
2 C> @brief Decode the meaning of a numerical value from a code or flag table
3 
4 C> This subroutine searches for a specified Table B mnemonic and associated
5 C> value (code figure or bit number) within the master Code/Flag tables,
6 C> and if found returns the associated meaning as a character string.
7 C>
8 C> @author J. Ator
9 C> @date 2018-01-11
10 C>
11 C> @param[in] LUNIT -- integer: Fortran logical unit number for
12 C> BUFR file
13 C> @param[in] NEMOI -- character*(*): Mnemonic to search for
14 C> @param[in] IVALI -- integer: Value (code figure or bit number)
15 C> associated with NEMOI
16 C> @param[in] NEMOD -- character*(*): Optional second mnemonic upon
17 C> which the values NEMOI and IVALI depend; set to
18 C> all blank characters if the meanings of NEMOI and
19 C> IVALI do not depend on the value of any other
20 C> mnemonic
21 C> @param[in] IVALD -- integer: Value (code figure or bit number)
22 C> associated with NEMOD; set to (-1) whenever
23 C> NEMOD is set to all blank characters
24 C> @param[out] CMEANG -- character*(*): If the initial search of the
25 C> master Code/Flag tables was successful, then this
26 C> string contains the meaning corresponding to NEMOI
27 C> and IVALI (and to NEMOD and IVALD, if specified).
28 C> However, if the initial search was unsuccessful,
29 C> <b>and</b> if no optional second mnemonic and
30 C> associated value were specified on input,
31 C> <b>and</b> if a second search of the table
32 C> determines that the meaning of NEMOI and IVALI
33 C> indeed depends on one or more other possible
34 C> second mnemonics, then those possible second
35 C. mnemonics are returned within this string, as a
36 C> series of IRET successive 8-byte substrings.
37 C> An example of this scenario is included below
38 C> within the Remarks.
39 C> @param[out] LNMNG -- integer: Length (in bytes) of string returned in
40 C> CMEANG
41 C> @param[out] IRET -- integer: return code
42 C> - 0 = meaning found and stored in CMEANG string
43 C> - -1 = meaning not found
44 C> - >0 = meaning not found, <b>and</b> NEMOD and
45 C> IVALD were not specified on input,
46 C> <b>and</b> the meaning of NEMOI and IVALI
47 C> depends on the value of one of the
48 C> mnemonics stored in the first IRET 8-byte
49 C> substrings of CMEANG
50 C>
51 C> <p>As noted above, this subroutine first does an initial search of
52 C> the master Code/Flag tables based on the mnemonics and values provided.
53 C> The input parameters NEMOI and IVALI specify the mnemonic and
54 C> corresponding numerical code or flag table value for which the meaning
55 C> is sought, and the optional secondary parameters NEMOD and IVALD are
56 C> specified when needed to differentiate between multiple possible
57 C> results. An example of this particular scenario is included below
58 C> within the Remarks. Otherwise, if the meaning of NEMOD and IVALD
59 C> does not depend on the value associated with any other mnemonic, then
60 C> NEMOD should be set to a field of all blank characters, and IVALD
61 C> should be set to a value of (-1).
62 C>
63 C> <p>Subroutine codflg() must be called with a CF value of 'Y' prior to
64 C> calling this subroutine, in order to ensure that master Code/Flag
65 C> tables have been read into internal memory.
66 C>
67 C> <p>This subroutine can be called at any time after a BUFR message
68 C> has been read into internal arrays by one of the BUFRLIB
69 C> [message-reading subroutines](@ref hierarchy), and it
70 C> can be called for any code or flag table mnemonic defined within that
71 C> particular message. In most cases, this means that the mnemonic must
72 C> be contained within the subset definition (Section 3) of that message.
73 C> The only exceptions to this rule are for originating centers,
74 C> originating subcenters, data types and data subtypes, since those can
75 C> also be contained within the identification section (Section 1) of a
76 C> BUFR message.
77 C>
78 C> <p>It is the user's responsibility to provide sufficient allocated
79 C> space in CMEANG for the returned meaning string; otherwise, the
80 C> returned string will be truncated.
81 C>
82 C> @remarks
83 C> - An example of when secondary mnemonics NEMOD and IVALD would be
84 C> required is when a user is searching for the meaning of a numerical
85 C> code table value for an originating sub-center (i.e. mnemonic GSES).
86 C> The meaning of any originating sub-center value depends on the identity
87 C> of the originating center for which the sub-center in question is a
88 C> member, so in order for the subroutine to locate and return the proper
89 C> one, information about the originating center must also be provided. So
90 C> in this case the user would input GSES and the associated numerical
91 C> value as NEMOI and IVALI, respectively, but the user would also need to
92 C> specify an appropriate originating center mnemonic (e.g. GCLONG, OGCE
93 C> or ORIGC) and associated value from the same BUFR message as input
94 C> parameters NEMOD and IVALD, respectively, and then the subroutine will
95 C> be able to locate and return the appropriate meaning string. Otherwise,
96 C> if this information was not provided, the subroutine would return with
97 C> an IRET value of 3, and with each of the mnemonics GCLONG, OGCE and
98 C> ORIGC contained in successive 8-byte substrings of CMEANG (and with a
99 C> corresponding value of 24 returned for LNMNG), as a hint to the user
100 C> that more information needs to be input to the subroutine in order to
101 C> achieve the desired result.
102 C>
103 C> <b>Program history log:</b>
104 C> | Date | Programmer | Comments |
105 C> | -----|------------|----------|
106 C> | 2018-01-11 | J. Ator | Original author |
107 C> | 2018-02-08 | J. Ator | Add special handling for data types and subtypes in Section 1 |
108 C>
109  SUBROUTINE getcfmng ( LUNIT, NEMOI, IVALI, NEMOD, IVALD,
110  . cmeang, lnmng, iret )
111 
112  USE moda_tababd
113 
114  COMMON /tablef/ cdmf
115 
116  character*(*) nemoi, nemod, cmeang
117 
118  character*128 bort_str
119  character*8 nemo
120  character*1 cdmf, tab
121 
122  dimension ifxyd(10)
123 
124 C-----------------------------------------------------------------------
125 C-----------------------------------------------------------------------
126 
127  CALL status( lunit, lun, il, im )
128  IF ( il .EQ. 0 ) goto 900
129  IF ( il .GT. 0 ) goto 901
130  IF ( im .EQ. 0 ) goto 902
131 
132 C* Make sure the appropriate code/flag information has already been
133 C* read into internal memory.
134 
135  IF ( cdmf .NE. 'Y' ) goto 903
136 
137  itmp = ireadmt( lun )
138 
139 C* Check the validity of the input mnemonic(s). Include special
140 C* handling for originating centers, originating subcenters, data
141 C* types and data subtypes, since those can be reported in
142 C* Section 1 of a BUFR message as well as in Section 3, so if a
143 C* user requests those mnemonics we can't necessarily assume they
144 C* came from within Section 3.
145 
146  lcmg = len( cmeang )
147 
148  IF ( nemoi(1:4) .EQ. 'GSES' ) THEN
149  IF ( ( nemod(1:6) .EQ. 'GCLONG' ) .OR.
150  . ( nemod(1:4) .EQ. 'OGCE' ) .OR.
151  . ( nemod(1:5) .EQ. 'ORIGC' ) ) THEN
152  ifxyi = ifxy( '001034' )
153  ifxyd(1) = ifxy( '001035' )
154  ELSE
155  lnmng = min( 24, lcmg )
156  IF ( lnmng .EQ. 24 ) THEN
157  iret = 3
158  cmeang(1:24) = 'GCLONG OGCE ORIGC '
159  ELSE
160  iret = -1
161  END IF
162  RETURN
163  END IF
164  ELSE IF ( nemoi(1:6) .EQ. 'GCLONG' ) THEN
165  ifxyi = ifxy( '001031' )
166  ifxyd(1) = (-1)
167  ELSE IF ( nemoi(1:4) .EQ. 'OGCE' ) THEN
168  ifxyi = ifxy( '001033' )
169  ifxyd(1) = (-1)
170  ELSE IF ( nemoi(1:5) .EQ. 'ORIGC' ) THEN
171  ifxyi = ifxy( '001035' )
172  ifxyd(1) = (-1)
173  ELSE IF ( ( nemoi(1:7) .EQ. 'TABLASS' ) .OR.
174  + ( nemoi(1:7) .EQ. 'TABLASL' ) ) THEN
175  IF ( ( nemod(1:6) .EQ. 'TABLAT' ) ) THEN
176  IF ( nemoi(1:7) .EQ. 'TABLASS' ) THEN
177  ifxyi = ifxy( '055021' )
178  ELSE
179  ifxyi = ifxy( '055022' )
180  ENDIF
181  ifxyd(1) = ifxy( '055020' )
182  ELSE
183  lnmng = min( 8, lcmg )
184  IF ( lnmng .EQ. 8 ) THEN
185  iret = 1
186  cmeang(1:8) = 'TABLAT '
187  ELSE
188  iret = -1
189  END IF
190  RETURN
191  END IF
192  ELSE IF ( nemoi(1:6) .EQ. 'TABLAT' ) THEN
193  ifxyi = ifxy( '055020' )
194  ifxyd(1) = (-1)
195  ELSE
196  CALL parstr( nemoi, nemo, 1, ntg, ' ', .true. )
197  CALL nemtab( lun, nemo, ifxyi, tab, n )
198  IF ( ( n .EQ. 0 ) .OR. ( tab .NE. 'B' ) ) goto 904
199  IF ( ( tabb( n, lun )(71:74) .NE. 'CODE' ) .AND.
200  . ( tabb( n, lun )(71:74) .NE. 'FLAG' ) ) goto 905
201  IF ( nemod(1:1) .NE. ' ' ) THEN
202  CALL parstr( nemod, nemo, 1, ntg, ' ', .true. )
203  CALL nemtab( lun, nemo, ifxyd(1), tab, n )
204  IF ( ( n .EQ. 0 ) .OR. ( tab .NE. 'B' ) ) goto 904
205  IF ( ( tabb( n, lun )(71:74) .NE. 'CODE' ) .AND.
206  . ( tabb( n, lun )(71:74) .NE. 'FLAG' ) ) goto 905
207  ELSE
208  ifxyd(1) = (-1)
209  END IF
210  END IF
211 
212 C* Search the internal table for the requested meaning.
213 
214  CALL srchtbf( ifxyi, ivali, ifxyd, 10, ivald,
215  . cmeang, lcmg, lnmng, iret )
216  IF ( iret .LE. 0 ) RETURN
217 
218 C* The meaning of this value is dependent on the value of another
219 C* mnemonic in the report.
220 
221  iret2 = iret
222  lnmng = 0
223  iret = 0
224  DO ii = 1, iret2
225  CALL numtbd( lun, ifxyd(ii), nemo, tab, ierbd )
226  IF ( ( ierbd .GT. 0 ) .AND. ( tab .EQ. 'B' ) .AND.
227  . ( lcmg .GE. ( lnmng + 8 ) ) ) THEN
228  iret = iret + 1
229  cmeang(lnmng+1:lnmng+8) = nemo
230  lnmng = lnmng + 8
231  END IF
232  END DO
233  IF ( iret .EQ. 0 ) iret = -1
234 
235  RETURN
236 900 CALL bort('BUFRLIB: GETCFMNG - INPUT BUFR FILE IS CLOSED, IT '//
237  . 'MUST BE OPEN FOR INPUT')
238 901 CALL bort('BUFRLIB: GETCFMNG - INPUT BUFR FILE IS OPEN FOR '//
239  . 'OUTPUT, IT MUST BE OPEN FOR INPUT')
240 902 CALL bort('BUFRLIB: GETCFMNG - A MESSAGE MUST BE OPEN IN '//
241  . 'INPUT BUFR FILE, NONE ARE')
242 903 CALL bort('BUFRLIB: GETCFMNG - TO USE THIS SUBROUTINE, MUST '//
243  . 'FIRST CALL SUBROUTINE CODFLG WITH INPUT ARGUMENT SET TO Y')
244 904 WRITE(bort_str,'("BUFRLIB: GETCFMNG - MNEMONIC ",A,'//
245  . '" NOT FOUND IN TABLE B")') nemo
246  CALL bort(bort_str)
247 905 WRITE(bort_str,'("BUFRLIB: GETCFMNG - MNEMONIC ",A,'//
248  . '" IS NOT A CODE OR FLAG TABLE")') nemo
249  CALL bort(bort_str)
250  END
subroutine parstr(STR, TAGS, MTAG, NTAG, SEP, LIMIT80)
THIS SUBROUTINE PARSES A STRING CONTAINING ONE OR MORE SUBSTRINGS INTO AN ARRAY OF SUBSTRINGS...
Definition: parstr.f:37
This module contains array and variable declarations used to store DX BUFR tables internally for mult...
Definition: moda_tababd.F:10
subroutine numtbd(LUN, IDN, NEMO, TAB, IRET)
This subroutine searches for a descriptor within Table B and Table D of the internal DX BUFR tables...
Definition: numtbd.f:35
function ifxy(ADSC)
This function converts an FXY value from its 6 character representation to its bit-wise (integer) rep...
Definition: ifxy.f:42
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
subroutine nemtab(LUN, NEMO, IDN, TAB, IRET)
This subroutine returns information about a descriptor from the internal DX BUFR tables, based on the mnemonic associated with that descriptor.
Definition: nemtab.f:44
subroutine bort(STR)
This subroutine calls subroutine errwrt() to log an error message, then calls subroutine bort_exit() ...
Definition: bort.f:22
INTEGER function ireadmt(LUN)
This function checks the most recent BUFR message that was read via a call to one of the message-read...
Definition: ireadmt.f:42
subroutine getcfmng(LUNIT, NEMOI, IVALI, NEMOD, IVALD, CMEANG, LNMNG, IRET)
This subroutine searches for a specified Table B mnemonic and associated value (code figure or bit nu...
Definition: getcfmng.f:109
void srchtbf(f77int *, f77int *, f77int *, f77int *, f77int *, char *, f77int *, f77int *, f77int *)
This subroutine searches for a specified FXY number and associated value (code figure or bit number) ...
Definition: srchtbf.c:74