ESMF_LocStreamCreateByBkgGrid Function

      function ESMF_LocStreamCreateByBkgGrid(locstream, &
                 background, keywordEnforcer, maskValues, &
                 unmappedaction, name, rc)

!
! !RETURN VALUE:
      type(ESMF_LocStream) :: ESMF_LocStreamCreateByBkgGrid

!
! !ARGUMENTS:
      type(ESMF_LocStream),           intent(in)            :: locstream
      type(ESMF_Grid),                intent(in)            :: background
type(ESMF_KeywordEnforcer), optional:: keywordEnforcer ! must use keywords below
      integer(ESMF_KIND_I4),          intent(in),  optional :: maskValues(:)
      type(ESMF_UnmappedAction_Flag), intent(in),  optional :: unmappedaction
      character (len=*),              intent(in),  optional :: name
      integer,                        intent(out), optional :: rc
!
! !DESCRIPTION:
!
!     Create an location stream from an existing one in accordance with 
!     the distribution of the background Grid.  The entries
!     in the new location stream are redistributed, so that they lie on the same PET
!     as the piece of Grid which contains the coordinates of the entries. The coordinates
!     of the entries are the data in the keys named ESMF:Lon, ESMF:Lat, ESMF:Radius in the 
!     case of a spherical system and ESMF:X, ESMF:Y, ESMF:Z for cartesian. To copy data in
!     Fields or FieldBundles built on {\tt locstream} to the new one simply use {\tt ESMF\_FieldRedist()}
!     or {\tt ESMF\_FieldBundleRedist()}.
!
!     The arguments are:
!     \begin{description}
!      \item[locstream]
!          Location stream from which the new location stream is to be created
!      \item[background]
!          Background Grid which determines the distribution of the entries in the new location stream.
!          The background Grid 
!          Note also that this subroutine uses the corner stagger location in the Grid for determining 
!          where a point lies, because this is the stagger location which fully contains the cell. 
!          A Grid must have coordinate data in this stagger location to be used in this subroutine. 
!          For a 2D Grid this stagger location is ESMF\_STAGGERLOC\_CORNER for a 3D Grid this 
!          stagger location is ESMF\_STAGGERLOC\_CORNER\_VFACE. Note that currently the background 
!          Grid also needs to have been created with indexflag=ESMF\_INDEX\_GLOBAL to be usable here. 
!     \item [{[maskValues]}]
!           List of values that indicate a background grid point should be masked out. 
!           If not specified, no masking will occur. 
!     \item [{[unmappedaction]}]
!           Specifies what should happen if there are destination points that
!           can't be mapped to a source cell. Please see Section~\ref{const:unmappedaction} for a 
!           list of valid options. If not specified, {\tt unmappedaction} defaults to {\tt ESMF\_UNMAPPEDACTION\_ERROR}. [NOTE: the {\tt unmappedaction=ESMF\_UNMAPPEDACTION\_IGNORE} option is currently not implemented.]
!      \item[{[name]}]
!          Name of the resulting location stream
!      \item[{[rc]}]
!          Return code; equals {\tt ESMF\_SUCCESS} if there are no errors.
!     \end{description}
!
!EOP
      type(ESMF_LocStreamType), pointer :: oldLStypep, newLStypep
      type(ESMF_UnmappedAction_Flag) :: localunmappedaction
      type(ESMF_Mesh) :: mesh
      type(ESMF_TypeKind_Flag) ::keyTypeKind
      character(len=ESMF_MAXSTR)    :: keytemp, string
      integer :: keyCount,i
      integer :: localrc
      integer :: pntDim, pntCount
      real(ESMF_KIND_R8),  pointer  :: pntList(:)
      integer, pointer :: petList(:), gidList(:)
      type(ESMF_StaggerLoc) :: staggerloc
      integer :: gridDimCount, isSphere


      ! Initialize return code; assume failure until success is certain
      if (present(rc)) rc = ESMF_RC_NOT_IMPL

      ! Check Variables
      ESMF_INIT_CHECK_DEEP(ESMF_LocStreamGetInit,locstream,rc)
      ESMF_INIT_CHECK_DEEP(ESMF_GridGetInit,background,rc)


      ! Get Grid dimension
      call ESMF_GridGet(background, dimCount=gridDimCount, rc=localrc)
      if (ESMF_LogFoundError(localrc, &
         ESMF_ERR_PASSTHRU, &
         ESMF_CONTEXT, rcToReturn=rc)) return


     ! Chose staggerloc based on dimension
     if (gridDimCount .eq. 2) then
        staggerLoc=ESMF_STAGGERLOC_CORNER
     else if (gridDimCount .eq. 3) then
        staggerLoc=ESMF_STAGGERLOC_CORNER_VFACE
     else 
        if (ESMF_LogFoundError(ESMF_RC_ARG_WRONG, &
           msg=" - only Grids of dimension 2 or 3 may be used as a background grid ", &
            ESMF_CONTEXT, rcToReturn=rc)) return
     endif

     ! Convert Grid to Mesh
     mesh=ESMF_GridToMesh(background, staggerLoc, 0, maskValues=maskValues, rc=localrc)
     if (ESMF_LogFoundError(localrc, &
         ESMF_ERR_PASSTHRU, &
         ESMF_CONTEXT, rcToReturn=rc)) return


     ! Create new locstream from Background Mesh
     ESMF_LocStreamCreateByBkgGrid=ESMF_LocStreamCreate(locstream, &
                 background=mesh, unmappedaction=unmappedaction, &
                 name=name, rc=localrc)
     if (ESMF_LogFoundError(localrc, &
         ESMF_ERR_PASSTHRU, &
         ESMF_CONTEXT, rcToReturn=rc)) return

     ! Get rid of mesh created above
     call ESMF_MeshDestroy(mesh, noGarbage=.true., rc=localrc)
     if (ESMF_LogFoundError(localrc, &
         ESMF_ERR_PASSTHRU, &
         ESMF_CONTEXT, rcToReturn=rc)) return      

     ! return success
     if (present(rc)) rc = ESMF_SUCCESS

   end function ESMF_LocStreamCreateByBkgGrid