SUBROUTINE PKVS01(S01MNEM,IVAL)
C$$$ SUBPROGRAM DOCUMENTATION BLOCK
C
C SUBPROGRAM: PKVS01
C PRGMMR: ATOR ORG: NP12 DATE: 2005-11-29
C
C ABSTRACT: THIS SUBROUTINE IS USED TO SPECIFY A VALUE TO BE WRITTEN
C INTO A SPECIFIED LOCATION WITHIN SECTION 0 OR SECTION 1 OF ALL BUFR
C MESSAGES THAT WILL BE OUTPUT BY FUTURE CALLS TO ANY OF THE BUFR
C ARCHIVE LIBRARY SUBROUTINES WHICH CREATE SUCH MESSAGES (E.G. WRITCP,
C WRITSB, COPYMG, WRITSA, ETC.). IT WILL WORK ON ANY MESSAGE ENCODED
C USING BUFR EDITION 2, 3 OR 4, AND IT CAN BE CALLED AT ANY TIME,
C INCLUDING BEFORE THE FIRST CALL TO BUFR ARCHIVE LIBRARY SUBROUTINE
C OPENBF IF IT IS DESIRED FOR THE NEW VALUE TO ALSO BE INCLUDED IN ANY
C DX DICTIONARY TABLE MESSAGES THAT WILL BE OUTPUT BY BUFR ARCHIVE
C LIBRARY SUBROUTINE WRITDX. IN ANY CASE, THE LOCATION WITHIN WHICH
C TO STORE THE VALUE IS SPECIFIED VIA THE MNEMONIC S01MNEM, AS
C EXPLAINED IN FURTHER DETAIL BELOW. IF MULTIPLE VALUES ARE DESIRED
C TO BE CHANGED WITHIN SECTION 0 OR SECTION 1 OF FUTURE OUTPUT
C MESSAGES, THEN EACH SUCH VALUE (AND CORRESPONDING LOCATION)
C SHOULD BE SPECIFIED USING A SEPARATE CALL TO THIS SUBROUTINE.
C NOTE THAT EACH CALL TO THIS SUBROUTINE WITH A PARTICULAR LOCATION
C SPECIFICATION WILL OVERRIDE THE EFFECT OF ANY PREVIOUS CALL WITH
C THAT SAME SPECIFICATION (OR, IN THE CASE OF THE FIRST CALL WITH A
C PARTICULAR LOCATION SPECIFICATION, IT WILL OVERRIDE THE DEFAULT
C SECTION 0 OR SECTION 1 VALUE FOR THE CORRESPONDING LOCATION!).
C
C PROGRAM HISTORY LOG:
C 2005-11-29 J. ATOR -- ORIGINAL AUTHOR
C 2006-04-14 D. KEYSER -- UPDATED DOCBLOCK
C
C USAGE: CALL PKVS01(S01MNEM,IVAL)
C INPUT ARGUMENT LIST:
C S01MNEM - CHARACTER*(*): MNEMONIC SPECIFYING LOCATION WHERE IVAL
C IS TO BE STORED WITHIN SECTION 0 OR SECTION 1 OF ALL
C FUTURE OUTPUT BUFR MESSAGES:
C 'BEN' = BUFR EDITION NUMBER
C 'BMT' = BUFR MASTER TABLE
C 'OGCE' = ORIGINATING CENTER
C 'GSES' = ORIGINATING SUBCENTER
C (NOTE: THIS VALUE WILL BE STORED ONLY IN
C BUFR EDITION 3 OR 4 MESSAGES!)
C 'USN' = UPDATE SEQUENCE NUMBER
C 'MTYP' = DATA CATEGORY
C 'MSBTI' = DATA SUBCATEGORY (INTERNATIONAL)
C (NOTE: THIS VALUE WILL BE STORED ONLY IN
C BUFR EDITION 4 MESSAGES!)
C 'MSBT' = DATA SUBCATEGORY (LOCAL)
C 'MTV' = VERSION NUMBER OF MASTER TABLE
C 'MTVL' = VERSION NUMBER OF LOCAL TABLES
C 'YCEN' = YEAR OF CENTURY (1-100)
C (NOTE: THIS VALUE WILL BE STORED ONLY IN
C BUFR EDITION 2 AND 3 MESSAGES!)
C 'CENT' = CENTURY (I.E., 20 FOR YEARS 1901-2000,
C 21 FOR YEARS 2001-2100)
C (NOTE: THIS VALUE WILL BE STORED ONLY IN
C BUFR EDITION 2 AND 3 MESSAGES!)
C 'YEAR' = YEAR (4-DIGIT)
C (NOTE: THIS VALUE WILL BE STORED ONLY IN
C BUFR EDITION 4 MESSAGES!)
C 'MNTH' = MONTH
C 'DAYS' = DAY
C 'HOUR' = HOUR
C 'MINU' = MINUTE
C 'SECO' = SECOND
C (NOTE: THIS VALUE WILL BE STORED ONLY IN
C BUFR EDITION 4 MESSAGES!)
C 'INIT' = THIS IS A SPECIAL FLAG TO FORCE THE
C INITIALIZATION OF NS01V = 0 WITHIN
C COMMON /S01CM/; IN THIS CASE IVAL IS
C IGNORED
C (NOTE: AN APPLICATION PROGRAM SHOULD
C NEVER ITSELF NEED TO DO THIS!)
C IVAL - INTEGER: NEW VALUE FOR LOCATION POINTED TO BY S01MNEM
C
C REMARKS:
C THIS ROUTINE CALLS: BORT
C THIS ROUTINE IS CALLED BY: BFRINI
C Also called by application programs.
C
C ATTRIBUTES:
C LANGUAGE: FORTRAN 77
C MACHINE: PORTABLE TO ALL PLATFORMS
C
C$$$
INCLUDE 'bufrlib.prm'
COMMON /S01CM/ NS01V,CMNEM(MXS01V),IVMNEM(MXS01V)
CHARACTER*(*) S01MNEM
CHARACTER*128 BORT_STR
CHARACTER*8 CMNEM
DATA IFIRST/0/
SAVE IFIRST
C-----------------------------------------------------------------------
C-----------------------------------------------------------------------
IF(IFIRST.EQ.0) THEN
C NOTE THAT WE ARE INITIALIZING NS01V=0 HERE (RATHER THAN WITHIN
C SUBROUTINE BFRINI) IN ORDER TO ALLOW FOR THE POSSIBILITY THAT A
C USER MAY CALL SUBROUTINE PKVS01 PRIOR TO CALLING SUBROUTINE
C OPENBF (WHICH ITSELF CALLS BFRINI!). HOWEVER, IF THE USER DOES
C NOT DO THIS, THEN THE "CALL PKVS01('INIT',-99)" STATEMENT WITHIN
C BFRINI WILL ENSURE THAT THE REQUIRED INITIALIZATION OF NS01V=0
C STILL GETS DONE; OTHERWISE, WE WOULD RUN THE RISK OF NS01V BEING
C UNINITIALIZED WHEN REFERENCED LATER ON WITHIN SUBROUTINE MSGWRT!
NS01V = 0
IFIRST = 1
ENDIF
IF (S01MNEM.EQ.'INIT') THEN
RETURN
ENDIF
C IF AN IVAL HAS ALREADY BEEN ASSIGNED FOR THIS PARTICULAR S01MNEM,
C THEN OVERWRITE THAT ENTRY IN COMMON /S01CM/ USING THE NEW IVAL.
IF(NS01V.GT.0) THEN
DO I=1,NS01V
IF(S01MNEM.EQ.CMNEM(I)) THEN
IVMNEM(I) = IVAL
RETURN
ENDIF
ENDDO
ENDIF
C OTHERWISE, USE THE NEXT AVAILABLE UNUSED ENTRY IN COMMON /S01CM/.
IF(NS01V.GE.MXS01V) GOTO 900
NS01V = NS01V + 1
CMNEM(NS01V) = S01MNEM
IVMNEM(NS01V) = IVAL
C EXITS
C -----
RETURN
900 WRITE(BORT_STR,'("BUFRLIB: PKVS01 - CANNOT OVERWRITE MORE THAN '//
. '",I2," DIFFERENT LOCATIONS WITHIN SECTION 0 OR SECTION 1")')
. MXS01V
CALL BORT(BORT_STR)
END