NCEPLIBS-bufr  11.7.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> | Date | Programmer | Comments |
69 C> | -----|------------|----------|
70 C> | 2005-11-29 | J. Ator | Original author |
71 C> | 2006-04-14 | J. Ator | Added options for 'YCEN' and 'CENT'; restructured logic |
72 C>
73  FUNCTION iupbs01(MBAY,S01MNEM)
74 
75  dimension mbay(*)
76 
77  character*(*) s01mnem
78 
79  logical ok4cent
80 
81 C-----------------------------------------------------------------------
82 C This statement function checks whether its input value contains
83 C a valid century value.
84 
85  ok4cent(ival) = ((ival.GE.19).AND.(ival.LE.21))
86 C-----------------------------------------------------------------------
87 
88 C Call subroutine WRDLEN to initialize some important information
89 C about the local machine, just in case subroutine OPENBF hasn't
90 C been called yet.
91 
92  CALL wrdlen
93 
94 C Handle some simple requests that do not depend on the BUFR
95 C edition number.
96 
97  IF(s01mnem.EQ.'LENM') THEN
98  iupbs01 = iupb(mbay,5,24)
99  RETURN
100  ENDIF
101 
102  len0 = 8
103  IF(s01mnem.EQ.'LEN0') THEN
104  iupbs01 = len0
105  RETURN
106  ENDIF
107 
108 C Get the BUFR edition number.
109 
110  iben = iupb(mbay,8,8)
111  IF(s01mnem.EQ.'BEN') THEN
112  iupbs01 = iben
113  RETURN
114  ENDIF
115 
116 C Use the BUFR edition number to handle any other requests.
117 
118  CALL gets1loc(s01mnem,iben,isbyt,iwid,iret)
119  IF(iret.EQ.0) THEN
120  iupbs01 = iupb(mbay,len0+isbyt,iwid)
121  IF(s01mnem.EQ.'CENT') THEN
122 
123 C Test whether the returned value was a valid
124 C century value.
125 
126  IF(.NOT.ok4cent(iupbs01)) iupbs01 = -1
127  ENDIF
128  ELSE IF( (s01mnem.EQ.'YEAR') .AND. (iben.LT.4) ) THEN
129 
130 C Calculate the 4-digit year.
131 
132  iyoc = iupb(mbay,21,8)
133  icen = iupb(mbay,26,8)
134 
135 C Does ICEN contain a valid century value?
136 
137  IF(ok4cent(icen)) THEN
138 
139 C YES, so use it to calculate the 4-digit year. Note that,
140 C by international convention, the year 2000 was the 100th
141 C year of the 20th century, and the year 2001 was the 1st
142 C year of the 21st century
143 
144  iupbs01 = (icen-1)*100 + iyoc
145  ELSE
146 
147 C NO, so use a windowing technique to determine the
148 C 4-digit year from the year of the century.
149 
150  iupbs01 = i4dy(mod(iyoc,100)*1000000)/10**6
151  ENDIF
152  ELSE
153  iupbs01 = -1
154  ENDIF
155 
156  RETURN
157  END
function i4dy(IDATE)
This function converts a date-time with a 2-digit year (YYMMDDHH) to a date-time with a 4-digit year ...
Definition: i4dy.f:31
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:35
function iupbs01(MBAY, S01MNEM)
This function returns a specified value from within Section 0 or Section 1 of a BUFR message...
Definition: iupbs01.f:73