NCEPLIBS-bufr  11.5.0
 All Data Structures Files Functions Variables Pages
iupbs01.f
Go to the documentation of this file.
1 C> @file
2 C> @brief Read a data value from Section 0 or Section 1 of a BUFR
3 C> message.
4 
5 C> This function returns a specified value from within Section 0 or
6 C> Section 1 of a BUFR message.
7 C>
8 C> <p>This function will work on any BUFR message encoded using BUFR
9 C> edition 2, 3, or 4. It is similar to function iupvs01(), except
10 C> that it operates on a BUFR message passed in via a memory array,
11 C> whereas iupvs01() operates on the BUFR message that was read into
12 C> internal arrays via the most recent call to any of the other
13 C> [message-reading subroutines](@ref hierarchy) for a specified
14 C> Fortran logical unit.
15 C>
16 C> @author J. Ator
17 C> @date 2005-11-29
18 C>
19 C> @param[in] MBAY - integer(*): BUFR message
20 C> @param[in] S01MNEM - character*(*): Value to be read from
21 C> Section 0 or Section 1 of MBAY
22 C> - 'LENM' = Length (in bytes) of BUFR message
23 C> - 'LEN0' = Length (in bytes) of Section 0
24 C> - 'LEN1' = Length (in bytes) of Section 1
25 C> - 'BEN' = BUFR edition number
26 C> - 'BMT' = BUFR master table
27 C> - 'OGCE' = Originating center
28 C> - 'GSES' = Originating subcenter
29 C> - 'USN' = Update sequence number
30 C> - 'ISC2' = Flag indicating absence/presence of
31 C> (optional) Section 2 in BUFR message:
32 C> - 0 = Section 2 absent
33 C> - 1 = Section 2 present
34 C> - 'MTYP' = Data category
35 C> - 'MSBTI' = Data subcategory (international)
36 C> - 'MSBT' = Data subcategory (local)
37 C> - 'MTV' = Version number of master table
38 C> - 'MTVL' = Version number of local tables
39 C> - 'YCEN' = Year of century (1-100)
40 C> - 'CENT' = Century (e.g., 20 for years 1901-2000,
41 C> 21 for years 2001-2100)
42 C> - 'YEAR' = Year (4-digit)
43 C> - 'MNTH' = Month
44 C> - 'DAYS' = Day
45 C> - 'HOUR' = Hour
46 C> - 'MINU' = Minute
47 C> - 'SECO' = Second
48 C> @returns iupbs01 - integer: Value corresponding to S01MNEM
49 C> - -1 = S01MNEM was invalid for the edition of BUFR
50 C> message in MBAY, or some other error
51 C> occurred
52 C>
53 C> @remarks
54 C> - The start of the BUFR message (i.e. the string 'BUFR') must be
55 C> aligned on the first 4 bytes of MBAY.
56 C> - Values corresponding to S01MNEM = 'GSES' can only be read from
57 C> BUFR messages encoded using BUFR edition 3 or 4.
58 C> - Values corresponding to S01MNEM = 'YCEN' or 'CENT' can only be
59 C> read from BUFR messages encoded using BUFR edition 2 or 3.
60 C> - When reading from BUFR messages encoded using BUFR edition 2
61 C> or 3, values corresponding to S01MNEM = 'YEAR' will be
62 C> calculated internally using the values for 'YCEN' and 'CENT',
63 C> or inferred using a windowing technique
64 C> - Values corresponding to S01MNEM = 'SECO' or 'MSBTI' can only
65 C> be read from BUFR messages encoded using BUFR edition 4.
66 C>
67 C> <b>Program history log:</b>
68 C> - 2005-11-29 J. Ator -- Original author
69 C> - 2006-04-14 J. Ator -- Added options for 'YCEN' and 'CENT';
70 C> restructured logic
71 C>
72  FUNCTION iupbs01(MBAY,S01MNEM)
73 
74  dimension mbay(*)
75 
76  character*(*) s01mnem
77 
78  logical ok4cent
79 
80 C-----------------------------------------------------------------------
81 C This statement function checks whether its input value contains
82 C a valid century value.
83 
84  ok4cent(ival) = ((ival.GE.19).AND.(ival.LE.21))
85 C-----------------------------------------------------------------------
86 
87 C Call subroutine WRDLEN to initialize some important information
88 C about the local machine, just in case subroutine OPENBF hasn't
89 C been called yet.
90 
91  CALL wrdlen
92 
93 C Handle some simple requests that do not depend on the BUFR
94 C edition number.
95 
96  IF(s01mnem.EQ.'LENM') THEN
97  iupbs01 = iupb(mbay,5,24)
98  RETURN
99  ENDIF
100 
101  len0 = 8
102  IF(s01mnem.EQ.'LEN0') THEN
103  iupbs01 = len0
104  RETURN
105  ENDIF
106 
107 C Get the BUFR edition number.
108 
109  iben = iupb(mbay,8,8)
110  IF(s01mnem.EQ.'BEN') THEN
111  iupbs01 = iben
112  RETURN
113  ENDIF
114 
115 C Use the BUFR edition number to handle any other requests.
116 
117  CALL gets1loc(s01mnem,iben,isbyt,iwid,iret)
118  IF(iret.EQ.0) THEN
119  iupbs01 = iupb(mbay,len0+isbyt,iwid)
120  IF(s01mnem.EQ.'CENT') THEN
121 
122 C Test whether the returned value was a valid
123 C century value.
124 
125  IF(.NOT.ok4cent(iupbs01)) iupbs01 = -1
126  ENDIF
127  ELSE IF( (s01mnem.EQ.'YEAR') .AND. (iben.LT.4) ) THEN
128 
129 C Calculate the 4-digit year.
130 
131  iyoc = iupb(mbay,21,8)
132  icen = iupb(mbay,26,8)
133 
134 C Does ICEN contain a valid century value?
135 
136  IF(ok4cent(icen)) THEN
137 
138 C YES, so use it to calculate the 4-digit year. Note that,
139 C by international convention, the year 2000 was the 100th
140 C year of the 20th century, and the year 2001 was the 1st
141 C year of the 21st century
142 
143  iupbs01 = (icen-1)*100 + iyoc
144  ELSE
145 
146 C NO, so use a windowing technique to determine the
147 C 4-digit year from the year of the century.
148 
149  iupbs01 = i4dy(mod(iyoc,100)*1000000)/10**6
150  ENDIF
151  ELSE
152  iupbs01 = -1
153  ENDIF
154 
155  RETURN
156  END
function i4dy(IDATE)
THIS FUNCTION CONVERTS AN EIGHT DIGIT INTEGER DATE (YYMMDDHH) TO TEN DIGITS (YYYYMMDDHH) USING THE Y2...
Definition: i4dy.f:49
function iupb(MBAY, NBYT, NBIT)
THIS FUNCTION UNPACKS AND RETURNS A BINARY INTEGER WORD CONTAINED WITHIN NBIT BITS OF A BUFR MESSAGE ...
Definition: iupb.f:36
subroutine gets1loc(S1MNEM, IBEN, ISBYT, IWID, IRET)
THIS SUBROUTINE RETURNS THE LOCATION (I.E.
Definition: gets1loc.f:80
subroutine wrdlen
This subroutine figures out some important information about the local machine on which the BUFRLIB s...
Definition: wrdlen.F:43
function iupbs01(MBAY, S01MNEM)
This function returns a specified value from within Section 0 or Section 1 of a BUFR message...
Definition: iupbs01.f:72