grib1.doc

计算线性趋势 回归系数 主要用于气象站点值的线性趋势计算

                             GRIB1 USERS GUIDE (FORTRAN 90)

Contents:

- Introduction
- GRIB1 Encoding Routines
- GRIB1 Decoding Routine
- Extracting GRIB1 Fields from a GRIB1 file
- GRIB1 Tables
- GRIB1 Routine Docblocks

===============================================================================
 
                                Introduction

This document briefly describes the routines available for encoding/decoding
GRIB Edition 1 messages.  A basic familiarity with GRIB is assumed.

A GRIB message is a machine independent format for storing
one or more gridded data fields.  Each GRIB message consists of the 
following sections:

SECTION 0 - Indicator Section
SECTION 1 - Product Definition Section (PDS)
SECTION 2 - Grid Definition Section (GDS)
SECTION 3 - Bit-map Section (Optional)
SECTION 4 - Binary Data Section
SECTION 5 - End Section

===============================================================================

                       GRIB1 Encoding Routines

There are several routines that one can use to encode a GRIB1 message.
Subroutine W3FI72 can be used to encode a GRIB1 message which is passed
back to the calling program in a character array.  
It is the users responsibility to ensure that the character array that will
hold the packed GRIB1 message has been allocated large enough prior to 
calling W3FI72.  

Another option is subroutine PUTGB.  PUTGB encodes a GRIB1 message and writes 
it to a file.  The message is not returned to the calling routine.
The output GRIB1 data file must be opened with a call to subroutine BAOPEN 
(or BAOPENW) prior to the call to PUTGB.  A call to BACLOSE is recommended at 
the end of the program to close the output file properly.

Example usage:

      integer,dimension(200) :: KPDS,KGDS
      logical*1,allocatable :: LB(:)     ! bitmap
      real,allocatable :: F(:)           ! grid point data values
      lugb=50
  ! Open GRIB1 file 
      call baopenw(LUGB,"filename",iret)

  ! Set up bitmap and data field
      numpts=??????
      allocate(LB(numpts))
      allocate(F(numpts))
       
  ! Set GRIB1 field identification values to encode
      KPDS(?)=
      KGDS(?)=

  ! pack and write field to file
      CALL PUTGB(LUGB,numpts,KPDS,KGDS,LB,F,iret)

  ! Close file ...
      call baclose(LUGB,iret)
      
      stop
      end

There are other similar routines in the PUTGB family that can be used to 
encode GRIB1 messages and write them out to a file:
PUTGBEX - Used to encode GRIB1 messages with NCEP PDS 
          extensions to specify ensemble information.
PUTGN   - Allows users to specify a binary scale factor or limit amount of
          space each data point should occupy.

Please see the "GRIB1 Routine Docblocks" section below for subroutine
argument usage for the routines mentioned above.

===============================================================================

                      GRIB1 Decoding Routine

Subroutine W3FI63 can be used to decode a given GRIB1 message that resides
in a character array in memory.  This routine will return the unpacked values
in the PDS and GDS, a bitmap array, and the unpacked grid point data values.

It is the users responsibility to ensure that the returned arrays have
been allocated large enough prior to calling W3FI63.  

Please see the "GRIB1 Routine Docblocks" section below for subroutine
argument usage for the routine mentioned above.

===============================================================================

                Extracting GRIB1 Fields from a GRIB1 file

Subroutine GETGB can be used to extract a specified field from a file
containing many GRIB1 messages.  GETGB searches an index to find the 
location of the user specified field.  The index can be supplied from a
separate GRIB1 index file, or it can be generated internally.

The GRIB1 data file ( and the index file, if supplied ) must be opened with
a call to subroutine BAOPEN prior to the call to GETGB.

Users can request a particular field by specifying the PDS and GDS
values that they wish to match.  GETGB will return the PDS, GDS, bitmap,
and grid point data values.


Example usage:

      integer,parameter :: MAXPTS=??????
      integer,dimension(200) :: JPDS,JGDS,KPDS,KGDS
      logical*1,dimension(MAXPTS) :: LB        ! bitmap
      real,dimension(MAXPTS) :: F              !  grid point data values
      lugb=10
      lugi=0
  ! Open GRIB1 file 
      call baopenr(LUGB,"filename",iret)
       
  ! Set GRIB1 field identification values to search for
      j=0      ! search from beginning
      jpds(?)=
      jgds(?)=

  ! Get field from file
      CALL GETGB(LUGB,LUGI,MAXPTS,J,JPDS,JGDS,
     &                 KF,K,KPDS,KGDS,LB,F,IRET)

  ! Process field ...
      firstval=F(1)
      lastval=F(KF)
      fldmax=maxval(F)
      fldmin=minval(F)
      
      stop
      end
      
There are other similar routines in the GETGB family that can be used to 
extract data from a GRIB1 file:
GETGBEX - Used to search for and decode GRIB1 messages using NCEP PDS 
          extensions used to specify ensemble information.
GETGBP  - Returns the requested packed GRIB message instead of the unpacked
          bitmap and data values.
GETGBH  - Returns the full PDS and GDS values of the requested field 
          without having to unpack the bitmap and grid point data values.


Please see the "GRIB1 Routine Docblocks" section below for subroutine
argument usage for the routines mentioned above.

===============================================================================

                         GRIB1 Tables

WMO's GRIB1 guide "A GUIDE TO THE CODE FORM FM 92-IX Ext. GRIB"
contains a description of the GRIB1 code form and the master code
table information.  This document can be found at
http://www.wmo.ch/web/www/WDM/Guides/Guide-binary.html

In addition, NCEP Office Note 388 (http://www.nco.ncep.noaa.gov/pmb/docs/on388)
also contains a description of GRIB1 along with master and local NCEP 
Code Table values.

===============================================================================

                       GRIB1 Routine Docblocks

C$$$  SUBPROGRAM DOCUMENTATION BLOCK
C                .      .    .                                       .
C SUBPROGRAM:  W3FI72        MAKE A COMPLETE GRIB MESSAGE
C   PRGMMR: FARLEY           ORG: NMC421      DATE:94-11-22
C
C ABSTRACT: MAKES A COMPLETE GRIB MESSAGE FROM A USER SUPPLIED
C   ARRAY OF FLOATING POINT OR INTEGER DATA.  THE USER HAS THE
C   OPTION OF SUPPLYING THE PDS OR AN INTEGER ARRAY THAT WILL BE
C   USED TO CREATE A PDS (WITH W3FI68).  THE USER MUST ALSO
C   SUPPLY OTHER NECESSARY INFO; SEE USAGE SECTION BELOW.
C
C PROGRAM HISTORY LOG:
C   91-05-08  R.E.JONES
C   92-07-01  M. FARLEY    ADDED GDS AND BMS LOGIC.  PLACED EXISTING
C                          LOGIC FOR BDS IN A ROUTINE.
C   92-10-02  R.E.JONES    ADD ERROR EXIT FOR W3FI73
C   93-04-30  R.E.JONES    REPLACE DO LOOPS TO MOVE CHARACTER DATA
C                          WITH XMOVEX, USE XSTORE TO ZERO CHARACTER
C                          ARRAY. MAKE CHANGE SO FLAT FIELD WILL PACK.
C   93-08-06  CAVANAUGH    MODIFIED CALL TO W3FI75
C   93-10-26  CAVANAUGH    ADDED CODE TO RESTORE INPUT FIELD TO ORIGINAL
C                          VALUES IF D-SCALE NOT 0
C   94-01-27  CAVANAUGH    ADDED IGDS ARRAY IN CALL TO W3FI75 TO PROVIDE
C                          INFORMATION FOR BOUSTROPHEDONIC PROCESSING
C   94-03-03  CAVANAUGH    INCREASED SIZE OF GDS ARRAY FOR THIN GRIDS
C   94-05-16  FARLEY       CLEANED UP DOCUMENTATION
C   94-11-10  FARLEY       INCREASED SIZE OF PFLD/IFLD ARRARYS FROM
C                          100K TO 260K FOR .5 DEGREE SST ANAL FIELDS
C   94-12-04  R.E.JONES    CHANGE DOCUMENT FOR IPFLAG.
C   95-10-31  IREDELL      REMOVED SAVES AND PRINTS
C   98-05-19  Gilbert      Increased array dimensions to handle grids
C                          of up to 500,000 grid points.
C   95-10-31  IREDELL      GENERALIZED WORD SIZE
C   98-12-21  Gilbert      Replaced Function ICHAR with mova2i.
C   99-02-01  Gilbert      Changed the method of zeroing out array KBUF.
C                          the old method, using W3FI01 and XSTORE was
C                          incorrect with 4-byte integers and 8-byte reals.
C 2001-06-07  Gilbert      Removed calls to xmovex.
C                          changed IPFLD from integer to character.
C
C USAGE:  CALL W3FI72(ITYPE,FLD,IFLD,IBITL,
C        &            IPFLAG,ID,PDS,
C        &            IGFLAG,IGRID,IGDS,ICOMP,
C        &            IBFLAG,IBMAP,IBLEN,IBDSFL,
C        &            IBDSFL,
C        &            NPTS,KBUF,ITOT,JERR)
C
C   INPUT ARGUMENT LIST:
C     ITYPE    - 0 = FLOATING POINT DATA SUPPLIED IN ARRAY 'FLD'
C                1 = INTEGER DATA SUPPLIED IN ARRAY 'IFLD'
C     FLD      - REAL ARRAY OF DATA (AT PROPER GRIDPOINTS) TO BE
C                CONVERTED TO GRIB FORMAT IF ITYPE=0.
C                SEE REMARKS #1 & 2.
C     IFLD     - INTEGER ARRAY OF DATA (AT PROPER GRIDPOINTS) TO BE
C                CONVERTED TO GRIB FORMAT IF ITYPE=1.
C                SEE REMARKS #1 & 2.
C     IBITL    - 0 = COMPUTER COMPUTES LENGTH FOR PACKING DATA FROM
C                    POWER OF 2 (NUMBER OF BITS) BEST FIT OF DATA
C                    USING 'VARIABLE' BIT PACKER W3FI58.
C                8, 12, ETC. COMPUTER RESCALES DATA TO FIT INTO THAT
C                    'FIXED' NUMBER OF BITS USING W3FI59.
C                SEE REMARKS #3.
C
C     IPFLAG   - 0 = MAKE PDS FROM USER SUPPLIED ARRAY (ID)
C                1 = USER SUPPLYING PDS
C                NOTE: IF PDS IS GREATER THAN 30, USE IPLFAG=1.
C                THE USER COULD CALL W3FI68 BEFORE HE CALLS
C                W3FI72. THIS WOULD MAKE THE FIRST 30 BYTES OF
C                THE PDS, USER THEN WOULD MAKE BYTES AFTER 30.
C     ID       - INTEGER ARRAY OF  VALUES THAT W3FI68 WILL USE
C                TO MAKE AN EDITION 1 PDS IF IPFLAG=0.  (SEE THE
C                DOCBLOCK FOR W3FI68 FOR LAYOUT OF ARRAY)
C     PDS      - CHARACTER ARRAY OF VALUES (VALID PDS SUPPLIED
C                BY USER) IF IPFLAG=1. LENGTH MAY EXCEED 28 BYTES
C                (CONTENTS OF BYTES BEYOND 28 ARE PASSED
C                THROUGH UNCHANGED).
C
C     IGFLAG   - 0 = MAKE GDS BASED ON 'IGRID' VALUE.
C                1 = MAKE GDS FROM USER SUPPLIED INFO IN 'IGDS'
C                    AND 'IGRID' VALUE.
C                SEE REMARKS #4.
C     IGRID    - #   = GRID IDENTIFICATION (TABLE B)
C                255 = IF USER DEFINED GRID; IGDS MUST BE SUPPLIED
C                      AND IGFLAG MUST =1.
C     IGDS     - INTEGER ARRAY CONTAINING USER GDS INFO (SAME
C                FORMAT AS SUPPLIED BY W3FI71 - SEE DOCKBLOCK FOR
C                LAYOUT) IF IGFLAG=1.
C     ICOMP    - RESOLUTION AND COMPONENT FLAG FOR BIT 5 OF GDS(17)
C                0 = EARTH ORIENTED WINDS
C                1 = GRID ORIENTED WINDS
C
C     IBFLAG   - 0 = MAKE BIT MAP FROM USER SUPPLIED DATA
C                # = BIT MAP PREDEFINED BY CENTER
C                SEE REMARKS #5.
C     IBMAP    - INTEGER ARRAY CONTAINING BIT MAP
C     IBLEN    - LENGTH OF BIT MAP WILL BE USED TO VERIFY LENGTH
C                OF FIELD (ERROR IF IT DOESN'T MATCH).
C
C     IBDSFL   - INTEGER ARRAY CONTAINING TABLE 11 FLAG INFO
C                BDS OCTET 4:
C                (1) 0 = GRID POINT DATA
C                    1 = SPHERICAL HARMONIC COEFFICIENTS
C                (2) 0 = SIMPLE PACKING
C                    1 = SECOND ORDER PACKING
C                (3) ... SAME VALUE AS 'ITYPE'
C                    0 = ORIGINAL DATA WERE FLOATING POINT VALUES
C                    1 = ORIGINAL DATA WERE INTEGER VALUES
C                (4) 0 = NO ADDITIONAL FLAGS AT OCTET 14
C                    1 = OCTET 14 CONTAINS FLAG BITS 5-12
C                (5) 0 = RESERVED - ALWAYS SET TO 0
C         BYTE 6 OPTION 1 NOT AVAILABLE (AS OF 5-16-93)
C                (6) 0 = SINGLE DATUM AT EACH GRID POINT
C                    1 = MATRIX OF VALUES AT EACH GRID POINT
C         BYTE 7 OPTION 0 WITH SECOND ORDER PACKING N/A (AS OF 5-16-93)
C                (7) 0 = NO SECONDARY BIT MAPS
C                    1 = SECONDARY BIT MAPS PRESENT
C                (8) 0 = SECOND ORDER VALUES HAVE CONSTANT WIDTH
C                    1 = SECOND ORDER VALUES HAVE DIFFERENT WIDTHS
C
C   OUTPUT ARGUMENT LIST:
C     NPTS     - NUMBER OF GRIDPOINTS IN ARRAY FLD OR IFLD
C     KBUF     - ENTIRE GRIB MESSAGE ('GRIB' TO '7777')
C                EQUIVALENCE TO INTEGER ARRAY TO MAKE SURE IT
C                IS ON WORD BOUNARY.
C     ITOT     - TOTAL LENGTH OF GRIB MESSAGE IN BYTES
C     JERR     - = 0, COMPLETED MAKING GRIB FIELD WITHOUT ERROR
C                  1, IPFLAG NOT 0 OR 1
C                  2, IGFLAG NOT 0 OR 1
C                  3, ERROR CONVERTING IEEE F.P. NUMBER TO IBM370 F.P.
C                  4, W3FI71 ERROR/IGRID NOT DEFINED
C                  5, W3FK74 ERROR/GRID REPRESENTATION TYPE NOT VALID
C                  6, GRID TOO LARGE FOR PACKER DIMENSION ARRAYS
C                     SEE AUTOMATION DIVISION FOR REVISION!
C                  7, LENGTH OF BIT MAP NOT EQUAL TO SIZE OF FLD/IFLD
C                  8, W3FI73 ERROR, ALL VALUES IN IBMAP ARE ZERO
C
C   OUTPUT FILES:
C     FT06F001 - STANDARD FORTRAN OUTPUT PRINT FILE
C
C   SUBPROGRAMS CALLED:
C     LIBRARY:
C       W3LIB    - W3FI58, W3FI59, W3FI68, W3FI71, W3FI73, W3FI74
C                  W3FI75, W3FI76
C       FORTRAN 90 INTRINSIC - BIT_SIZE
C
C REMARKS:
C   1)  IF BIT MAP TO BE INCLUDED IN MESSAGE, NULL DATA SHOULD
C       BE INCLUDED IN FLD OR IFLD.  THIS ROUTINE WILL TAKE CARE
C       OF 'DISCARDING' ANY NULL DATA BASED ON THE BIT MAP.
C   2)  UNITS MUST BE THOSE IN GRIB DOCUMENTATION:  NMC O.N. 388
C       OR WMO PUBLICATION 306.
C   3)  IN EITHER CASE, INPUT NUMBERS WILL BE MULTIPLIED BY
C       '10 TO THE NTH' POWER FOUND IN ID(25) OR PDS(27-28),
C       THE D-SCALING FACTOR, PRIOR TO BINARY PACKING.
C   4)  ALL NMC PRODUCED GRIB FIELDS WILL HAVE A GRID DEFINITION
C       SECTION INCLUDED IN THE GRIB MESSAGE.  ID(6) WILL BE
C       SET TO '1'.
C       - GDS WILL BE BUILT BASED ON GRID NUMBER (IGRID), UNLESS