ESMF_LogSetError Subroutine

      subroutine ESMF_LogSetError(rcToCheck, keywordEnforcer,  &
                                  msg, line, file, method, &
                                  rcToReturn, log)

! !ARGUMENTS:
!
      integer,          intent(in)              :: rcToCheck
type(ESMF_KeywordEnforcer), optional:: keywordEnforcer ! must use keywords below
      character(len=*), intent(in),    optional :: msg
      integer,          intent(in),    optional :: line
      character(len=*), intent(in),    optional :: file
      character(len=*), intent(in),    optional :: method
      integer,          intent(out),   optional :: rcToReturn
      type(ESMF_Log),   intent(inout), optional :: log

!
! !STATUS:
! \begin{itemize}
! \item\apiStatusCompatibleVersion{5.2.0r}
! \end{itemize}
!
! !DESCRIPTION:
!      This subroutine sets the {\tt rcToReturn} value to {\tt rcToCheck} if
!      {\tt rcToReturn} is present and writes this error code to the {\tt ESMF\_Log}
!      if an error is generated.  A predefined error message will added to the
!      {\tt ESMF\_Log} along with a user added {\tt msg}, {\tt line}, {\tt file}
!      and {\tt method}.
!
!      The arguments are:
!      \begin{description}
!
!      \item [rcToCheck]
!            rc value for set
!      \item [{[msg]}]
!            User-provided message string.
!      \item [{[line]}]
!            Integer source line number.  Expected to be set by
!            using the preprocessor macro {\tt \_\_LINE\_\_} macro.
!      \item [{[file]}]
!            User-provided source file name.
!      \item [{[method]}]
!            User-provided method string.
!      \item [{[rcToReturn]}]
!            If specified, copy the {\tt rcToCheck} value to {\tt rcToreturn}.
!            This is not the return code for this function; it allows
!            the calling code to do an assignment of the error code
!            at the same time it is testing the value.
!      \item [{[log]}]
!            An optional {\tt ESMF\_Log} object that can be used instead
!            of the default Log.
!
!      \end{description}
!
!EOP

    integer:: i
    logical:: masked
    type(ESMF_LogPrivate), pointer          :: alog
    character(len=ESMF_MAXSTR) :: errmsg
    integer :: msglen

    ESMF_INIT_CHECK_SET_SHALLOW(ESMF_LogGetInit,ESMF_LogInit,log)

    nullify(alog) ! ensure that the association status is well defined

    if (present(log)) then
      if (log%logTableIndex > 0) then
         alog => ESMF_LogTable(log%logTableIndex)
      endif
    else
      if (ESMF_LogDefault%logTableIndex > 0) then
        alog => ESMF_LogTable(ESMF_LogDefault%logTableIndex)
      end if
    endif

    if (associated(alog)) then

      ESMF_INIT_CHECK_SET_SHALLOW(ESMF_LogPrivateGetInit,ESMF_LogPrivateInit,alog)

      ! set default returns
      if (present(rcToReturn)) rcToReturn = ESMF_SUCCESS

      ! check the error code
      if (rcToCheck .NE. ESMF_SUCCESS) then
        masked = .false.
        do i=1, alog%errorMaskCount
          if (alog%errorMask(i) == rcToCheck) masked = .true.
        enddo
        if (.not.masked) then
          call ESMF_Breakpoint()  ! no-op to assist debugging
          call ESMF_LogRc2Msg (rcToCheck, errmsg, msglen)
          if (present(msg)) then
            errmsg = errmsg(:msglen) // " - " // msg
            msglen = len_trim (errmsg)
          end if
          call ESMF_LogWrite(errmsg(:msglen), ESMF_LOGMSG_ERROR,  &
            line=line, file=file, method=method, log=log)
          if (present(rcToReturn)) rcToReturn = rcToCheck
        endif
      endif
    else
      if (present(rcToReturn)) rcToReturn = ESMF_SUCCESS
    endif

end subroutine ESMF_LogSetError