scrip_iounitsmod.f90

Go to the documentation of this file.

!|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
 
module scrip_iounitsmod
 
  !BOP
  !
  ! !MODULE: SCRIP_IOUnitsMod
  !
  ! !DESCRIPTION:
  ! This module contains an I/O unit manager for tracking, assigning
  ! and reserving I/O unit numbers.
  !
  ! There are three reserved I/O units set as parameters in this
  ! module. The default units for standard input (stdin), standard
  ! output (stdout) and standard error (stderr). These are currently
  ! set as units 5,6,6, respectively as that is the most commonly
  ! used among vendors. However, the user may change these if those
  ! default units are conflicting with other models or if the
  ! vendor is using different values.
  !
  ! The maximum number of I/O units per node is currently set by
  ! the parameter SCRIP\_IOMaxUnits.
  !
  ! !REFDOC:
  !
  ! !REVISION HISTORY:
  ! SVN:$Id: SCRIP_IOUnitsMod.F90 83 2008-02-22 17:26:54Z pwjones $
 
  ! !USES:
 
  use scrip_kindsmod
 
  implicit none
  private
  save
 
  ! !PUBLIC MEMBER FUNCTIONS:
 
  public :: scrip_iounitsget, &
       scrip_iounitsrelease, &
       scrip_iounitsreserve, &
       scrip_iounitsredirect, &
       scrip_iounitsflush
 
  ! !PUBLIC DATA MEMBERS:
 
  integer (SCRIP_i4), parameter, public :: &
       scrip_stdin = 5, &! reserved unit for standard input
       scrip_stdout = 6, &! reserved unit for standard output
       scrip_stderr = 6 ! reserved unit for standard error
 
  ! common formats for writing to stdout, stderr
 
  character (9), parameter, public :: &
       scrip_delimformat = "(72('-'))"
 
  character (5), parameter, public :: &
       scrip_blankformat = "(' ')"
 
  !EOP
  !BOC
  !-----------------------------------------------------------------------
  !
  ! private io unit manager variables
  !
  !-----------------------------------------------------------------------
 
  integer (SCRIP_i4), parameter :: &
       scrip_iounitsminunits = 11, & ! do not use unit numbers below this
       scrip_iounitsmaxunits = 99 ! maximum number of open units
 
  logical (SCRIP_Logical) :: &
       scrip_iounitsinitialized = .false.
 
  logical (SCRIP_Logical), dimension(SCRIP_IOUnitsMaxUnits) :: &
       scrip_iounitsinuse ! flag=.true. if unit currently open
 
  !EOC
  !***********************************************************************
 
contains
 
  !***********************************************************************
  !BOP
  ! !IROUTINE: SCRIP_IOUnitsGet
  ! !INTERFACE:
 
  subroutine scrip_iounitsget(iunit)
 
    ! !DESCRIPTION:
    ! This routine returns the next available i/o unit and marks it as
    ! in use to prevent any later use.
    ! Note that {\em all} processors must call this routine even if only
    ! the master task is doing the i/o. This is necessary insure that
    ! the units remain synchronized for other parallel I/O functions.
    !
    ! !REVISION HISTORY:
    ! same as module
 
    ! !OUTPUT PARAMETERS:
 
    integer (SCRIP_i4), intent(out) :: &
         iunit ! next free i/o unit
 
    !EOP
    !BOC
    !-----------------------------------------------------------------------
    !
    ! local variables
    !
    !-----------------------------------------------------------------------
 
    integer (SCRIP_i4) :: n ! dummy loop index
 
    logical (SCRIP_Logical) :: alreadyinuse
 
    !-----------------------------------------------------------------------
    !
    ! check to see if units initialized and initialize if necessary
    !
    !-----------------------------------------------------------------------
 
    if (.not. scrip_iounitsinitialized) then
      scrip_iounitsinuse = .false.
      scrip_iounitsinuse(scrip_stdin) = .true.
      scrip_iounitsinuse(scrip_stdout) = .true.
      scrip_iounitsinuse(scrip_stderr) = .true.
 
      scrip_iounitsinitialized = .true.
    endif
 
    !-----------------------------------------------------------------------
    !
    ! find next free unit
    !
    !-----------------------------------------------------------------------
 
    srch_units: do n=scrip_iounitsminunits, scrip_iounitsmaxunits
      if (.not. scrip_iounitsinuse(n)) then ! I found one, I found one
 
        !*** make sure not in use by library or calling routines
        INQUIRE (unit=n,opened=alreadyinuse)
 
        if (.not. alreadyinuse) then
          iunit = n ! return the free unit number
          scrip_iounitsinuse(iunit) = .true. ! mark iunit as being in use
          exit srch_units
        else
          !*** if inquire shows this unit in use, mark it as
          !*** in use to prevent further queries
          scrip_iounitsinuse(n) = .true.
        endif
      endif
    end do srch_units
 
    if (iunit > scrip_iounitsmaxunits) &
         stop 'SCRIP_IOUnitsGet: No free units'
 
    !-----------------------------------------------------------------------
    !EOC
 
  end subroutine scrip_iounitsget
 
  !***********************************************************************
  !BOP
  ! !IROUTINE: SCRIP_IOUnitsRelease
  ! !INTERFACE:
 
  subroutine scrip_iounitsrelease(iunit)
 
    ! !DESCRIPTION:
    ! This routine releases an i/o unit (marks it as available).
    ! Note that {\em all} processors must call this routine even if only
    ! the master task is doing the i/o. This is necessary insure that
    ! the units remain synchronized for other parallel I/O functions.
    !
    ! !REVISION HISTORY:
    ! same as module
 
    ! !INPUT PARAMETER:
 
    integer (SCRIP_i4), intent(in) :: &
         iunit ! i/o unit to be released
 
    !EOP
    !BOC
    !-----------------------------------------------------------------------
    !
    ! check for proper unit number
    !
    !-----------------------------------------------------------------------
 
    if (iunit < 1 .or. iunit > scrip_iounitsmaxunits) then
      stop 'SCRIP_IOUnitsRelease: bad unit'
    endif
 
    !-----------------------------------------------------------------------
    !
    ! mark the unit as not in use
    !
    !-----------------------------------------------------------------------
 
    scrip_iounitsinuse(iunit) = .false. ! that was easy...
 
    !-----------------------------------------------------------------------
    !EOC
 
  end subroutine scrip_iounitsrelease
 
  !***********************************************************************
  !BOP
  ! !IROUTINE: SCRIP_IOUnitsReserve
  ! !INTERFACE:
 
  subroutine scrip_iounitsreserve(iunit)
 
    ! !DESCRIPTION:
    ! This routine marks an IO unit as in use to reserve its use
    ! for purposes outside of SCRIP IO. This is necessary for
    ! cases where you might be importing code developed elsewhere
    ! that performs its own I/O and open/closes units.
    ! Note that {\em all} processors must call this routine even if only
    ! the master task is doing the i/o. This is necessary insure that
    ! the units remains synchronized for other parallel I/O functions.
    !
    ! !REVISION HISTORY:
    ! same as module
 
    ! !INPUT PARAMETER:
 
    integer (SCRIP_i4), intent(in) :: &
         iunit ! i/o unit to be reserved
 
    !EOP
    !BOC
    !-----------------------------------------------------------------------
    !
    ! local variables
    !
    !-----------------------------------------------------------------------
 
    logical (SCRIP_Logical) :: alreadyinuse
 
    !-----------------------------------------------------------------------
    !
    ! check for proper unit number
    !
    !-----------------------------------------------------------------------
 
    if (iunit < scrip_iounitsminunits .or. &
         iunit > scrip_iounitsmaxunits) then
      stop 'SCRIP_IOUnitsReserve: invalid unit'
    endif
 
    !-----------------------------------------------------------------------
    !
    ! check to see if SCRIP already using this unit
    !
    !-----------------------------------------------------------------------
 
    if (scrip_iounitsinuse(iunit)) then
      stop 'SCRIP_IOUnitsReserve: unit already in use by SCRIP'
    endif
 
    !-----------------------------------------------------------------------
    !
    ! check to see if others already using this unit
    !
    !-----------------------------------------------------------------------
 
    INQUIRE (unit=iunit, opened=alreadyinuse)
    if (alreadyinuse) then
      stop 'SCRIP_IOUnitsReserve: unit already in use by others'
    endif
 
    !-----------------------------------------------------------------------
    !
    ! mark the unit as in use
    !
    !-----------------------------------------------------------------------
 
    scrip_iounitsinuse(iunit) = .true.
 
    !-----------------------------------------------------------------------
    !EOC
 
  end subroutine scrip_iounitsreserve
 
  !***********************************************************************
  !BOP
  ! !IROUTINE: SCRIP_IOUnitsRedirect
  ! !INTERFACE:
 
  subroutine scrip_iounitsredirect(iunit, filename)
 
    ! !DESCRIPTION:
    ! This routine enables a user to redirect stdin, stdout, stderr to
    ! a file instead of to the terminal. It is only permitted for these
    ! special units. The SCRIP IO file operators should be used for
    ! normal I/O.
    ! Note that {\em all} processors must call this routine even if only
    ! the master task is doing the i/o. This is necessary insure that
    ! the units remains synchronized for other parallel I/O functions.
    !
    ! !REVISION HISTORY:
    ! same as module
 
    ! !INPUT PARAMETER:
 
    integer (SCRIP_i4), intent(in) :: &
         iunit ! i/o unit to be redirected to file
 
    character (*), intent(in) :: &
         filename ! filename, including path, to which
    ! i/o should be directed
 
    !EOP
    !BOC
    !-----------------------------------------------------------------------
    !
    ! check for proper unit number and open file
    !
    !-----------------------------------------------------------------------
 
    if (iunit == scrip_stdin) then ! open input file for stdin
      open(unit=iunit, file=filename, status='old', form='formatted')
 
    else if (iunit == scrip_stdout) then ! open output file for stdout
      open(unit=iunit, file=filename, status='unknown', form='formatted')
 
    else if (iunit == scrip_stderr .and. scrip_stderr /= scrip_stdout) then
      ! open output file for stderr
      open(unit=iunit, file=filename, status='unknown', form='formatted')
 
    else
      stop 'SCRIP_IOUnitsRedirect: invalid unit'
 
    endif
 
    !-----------------------------------------------------------------------
    !EOC
 
  end subroutine scrip_iounitsredirect
 
  !***********************************************************************
  !BOP
  ! !IROUTINE: SCRIP_IOUnitsFlush
  ! !INTERFACE:
 
  subroutine scrip_iounitsflush(iunit)
 
    ! !DESCRIPTION:
    ! This routine enables a user to flush the output from an IO unit
    ! (typically stdout) to force output when the system is buffering
    ! such output. Because this system function is system dependent,
    ! we only support this wrapper and users are welcome to insert the
    ! code relevant to their local machine.
    !
    ! !REVISION HISTORY:
    ! same as module
 
    ! !INPUT PARAMETER:
 
    integer (SCRIP_i4), intent(in) :: &
         iunit ! i/o unit to be flushed
 
    !EOP
    !BOC
    !-----------------------------------------------------------------------
    !
    ! insert your system code here
    !
    !-----------------------------------------------------------------------
 
    !-----------------------------------------------------------------------
    !EOC
 
  end subroutine scrip_iounitsflush
 
  !***********************************************************************
 
end module scrip_iounitsmod
 
!|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||