diff --git a/src/addfield.f b/src/addfield.f index 4cb9fed8..d0f0c492 100644 --- a/src/addfield.f +++ b/src/addfield.f @@ -1,97 +1,87 @@ - - +!> @file +!> @brief Contains subroutine which packs up Sections 4 through 7 for +!> a given field and adds them to a GRIB2 message. +!> @author Gilbert ORG: W/NP11 @date 2000-05-02 +!> +!> This subroutine packs up Sections 4 through 7 for a given field +!> and adds them to a GRIB2 message. They are Product Definition +!> Section, Data Representation Section, Bit-Map Section and Data +!> Section, respectively. +!> +!> This routine is used with routines "gribcreate", "addlocal", +!> "addgrid", and "gribend" to create a complete GRIB2 +!> message. Subroutine gribcreate must be called first to initialize +!> a new GRIB2 message. Also, subroutine addgrid must be called +!> after gribcreate and before this routine to add the appropriate +!> grid description to the GRIB2 message. Also, a call to gribend is +!> required to complete GRIB2 message after all fields have been +!> added. +!> +!> PROGRAM HISTORY LOG: +!> - 2000-05-02 Gilbert +!> - 2002-12-17 Gilbert - Added support for new templates using +!> PNG and JPEG2000 algorithms/templates. +!> - 2004-06-22 Gilbert - Added check to determine if packing algorithm failed. +!> +!> @param[inout] cgrib Character array to contain the GRIB2 message. +!> @param[in] lcgrib Maximum length (bytes) of array cgrib. +!> @param[in] ipdsnum Product Definition Template Number ( see Code +!> Table 4.0). +!> @param[in] ipdstmpl Contains the data values for the specified +!> Product Definition Template (N=ipdsnum). Each element of this +!> integer array contains an entry (in the order specified) of +!> Product Defintion Template 4.N +!> @param[in] ipdstmplen Max dimension of ipdstmpl coordlist Array +!> containg floating point values intended to document the vertical +!> discretisation associated to model data on hybrid coordinate +!> vertical levels. +!> @param[in] numcoord - number of values in array coordlist. +!> @param[in] idrsnum - Data Representation Template Number ( see +!> Code Table 5.0 ) +!> @param[in] idrstmpl Contains the data values for the specified +!> Data Representation Template (N=idrsnum). Each element of this +!> integer array contains an entry (in the order specified) of Data +!> Representation Template 5.N. Note that some values in this +!> template (eg. reference values, number of bits, etc...) may be +!> changed by the data packing algorithms. +!> Use this to specify scaling factors and order of +!> spatial differencing, if desired. +!> @param[in] idrstmplen Max dimension of idrstmpl. +!> @param[in] fld Array of data points to pack. +!> @parram[out] ngrdpts Number of data points in grid. i.e. size of +!> fld and bmap. +!> @param[out] ibmap Bitmap indicator (see Code Table 6.0). +!> - 0 = bitmap applies and is included in Section 6. +!> - 1-253 = Predefined bitmap applies +!> - 254 = Previously defined bitmap applies to this field +!> - 255 = Bit map does not apply to this product. +!> @param[out] bmap Logical*1 array containing bitmap to be added. +!> (if ibmap=0 or ibmap=254) +!> @param[out] ierr Error return code. +!> - 0 = no error +!> - 1 = GRIB message was not initialized. Need to call +!> routine gribcreate first. +!> - 2 = GRIB message already complete. Cannot add new section. +!> - 3 = Sum of Section byte counts does not add to total +!> byte count. +!> - 4 = Previous Section was not 3 or 7. +!> - 5 = Could not find requested Product Definition Template. +!> - 6 = Section 3 (GDS) not previously defined in message +!> - 7 = Tried to use unsupported Data Representationi Template +!> - 8 = Specified use of a previously defined bitmap, but one +!> does not exist in the GRIB message. +!> - 9 = GDT of one of 5.50 through 5.53 required to pack +!> using DRT 5.51 +!> - 10 = Error packing data field. +!> +!> @note Note that the Local Use Section (Section 2) can only follow +!> Section 1 or Section 7 in a GRIB2 message. +!> +!> @author Gilbert ORG: W/NP11 @date 2000-05-02 +!> subroutine addfield(cgrib,lcgrib,ipdsnum,ipdstmpl,ipdstmplen, & coordlist,numcoord,idrsnum,idrstmpl, & idrstmplen,fld,ngrdpts,ibmap,bmap,ierr) -!$$$ SUBPROGRAM DOCUMENTATION BLOCK -! . . . . -! SUBPROGRAM: addfield -! PRGMMR: Gilbert ORG: W/NP11 DATE: 2000-05-02 -! -! ABSTRACT: This subroutine packs up Sections 4 through 7 for a given field -! and adds them to a GRIB2 message. They are Product Definition Section, -! Data Representation Section, Bit-Map Section and Data Section, -! respectively. -! This routine is used with routines "gribcreate", "addlocal", "addgrid", -! and "gribend" to create a complete GRIB2 message. Subroutine -! gribcreate must be called first to initialize a new GRIB2 message. -! Also, subroutine addgrid must be called after gribcreate and -! before this routine to add the appropriate grid description to -! the GRIB2 message. Also, a call to gribend is required to complete -! GRIB2 message after all fields have been added. -! -! PROGRAM HISTORY LOG: -! 2000-05-02 Gilbert -! 2002-12-17 Gilbert - Added support for new templates using -! PNG and JPEG2000 algorithms/templates. -! 2004-06-22 Gilbert - Added check to determine if packing algorithm failed. -! -! USAGE: CALL addfield(cgrib,lcgrib,ipdsnum,ipdstmpl,ipdstmplen, -! coordlist,numcoord,idrsnum,idrstmpl, -! idrstmplen,fld,ngrdpts,ibmap,bmap,ierr) -! INPUT ARGUMENT LIST: -! cgrib - Character array to contain the GRIB2 message -! lcgrib - Maximum length (bytes) of array cgrib. -! ipdsnum - Product Definition Template Number ( see Code Table 4.0) -! ipdstmpl - Contains the data values for the specified Product Definition -! Template ( N=ipdsnum ). Each element of this integer -! array contains an entry (in the order specified) of Product -! Defintion Template 4.N -! ipdstmplen - Max dimension of ipdstmpl() -! coordlist- Array containg floating point values intended to document -! the vertical discretisation associated to model data -! on hybrid coordinate vertical levels. -! numcoord - number of values in array coordlist. -! idrsnum - Data Representation Template Number ( see Code Table 5.0 ) -! idrstmpl - Contains the data values for the specified Data Representation -! Template ( N=idrsnum ). Each element of this integer -! array contains an entry (in the order specified) of Data -! Representation Template 5.N -! Note that some values in this template (eg. reference -! values, number of bits, etc...) may be changed by the -! data packing algorithms. -! Use this to specify scaling factors and order of -! spatial differencing, if desired. -! idrstmplen - Max dimension of idrstmpl() -! fld() - Array of data points to pack. -! ngrdpts - Number of data points in grid. -! i.e. size of fld and bmap. -! ibmap - Bitmap indicator ( see Code Table 6.0 ) -! 0 = bitmap applies and is included in Section 6. -! 1-253 = Predefined bitmap applies -! 254 = Previously defined bitmap applies to this field -! 255 = Bit map does not apply to this product. -! bmap() - Logical*1 array containing bitmap to be added. -! ( if ibmap=0 or ibmap=254) -! -! OUTPUT ARGUMENT LIST: -! cgrib - Character array to contain the GRIB2 message -! ierr - Error return code. -! 0 = no error -! 1 = GRIB message was not initialized. Need to call -! routine gribcreate first. -! 2 = GRIB message already complete. Cannot add new section. -! 3 = Sum of Section byte counts does not add to total -! byte count. -! 4 = Previous Section was not 3 or 7. -! 5 = Could not find requested Product Definition Template. -! 6 = Section 3 (GDS) not previously defined in message -! 7 = Tried to use unsupported Data Representationi Template -! 8 = Specified use of a previously defined bitmap, but one -! does not exist in the GRIB message. -! 9 = GDT of one of 5.50 through 5.53 required to pack -! using DRT 5.51 -! 10 = Error packing data field. -! -! REMARKS: Note that the Local Use Section ( Section 2 ) can only follow -! Section 1 or Section 7 in a GRIB2 message. -! -! ATTRIBUTES: -! LANGUAGE: Fortran 90 -! MACHINE: IBM SP -! -!$$$ - use pdstemplates use drstemplates logical :: match