! $Id: xlf_interfaces.f90 4071 2014-02-11 13:53:09Z frdo $

!****f* xlf_interfaces *
!
! NAME
!    xlf_interfaces - Interfaces to the AIX xlf95 POSIX routines.
!
! SYNOPSIS
!    When Fortran 90 programs call standard POSIX system calls but are
!    compiled with the IBM AIX xlf[95] Fortran 90/95 compiler, link the
!    resulting object code with a compiled version of this file.
!
!    CHARACTER (LEN=n) :: oldname, newname
!    INTEGER :: status
!    CALL RENAME(oldname, newname)
!    CALL EXIT(status)
!
! DESCRIPTION
!    The IBM xlf for AIX f95 compiler provides access to most standard
!    POSIX system routines via the usual names. But some don't work.

!    1. RENAME()
!    -----------
!    The IBM XL RENAME() routine doesn't do anything. This interface
!    provides a wrapper to a SYSTEM() call to use the shell 'mv' command.
!    Note that there is no consistent exit status from the SYSTEM() call,
!    so the user has to assume it worked (or check that a file with the
!    new name exists when it didn't exist before and/or the old name
!    no longer exists).
!
!    2. EXIT()
!    ---------
!    The IBM XL EXIT(n) routine has a bug preventing the argument values of
!    INTEGER::n from appearing in the shell variable $? as expected, but some
!    constant (but arbitrary) value is passed. Declaring 'n' as a non-default
!    INTEGER (e.g 4-byte) has no effect.
!    This bug has been brought to the attention of IBM, but they do
!    not plan to fix it. Their reply is to either use the supported exit_()
!    routine or to compile with the -qextname flag to automatically append
!    an underscore to routine names, thus effectively using exit_().
!    However, the latter would cause problems linking against 3rd party
!    libraries not compiled with this flag. Using the former would be
!    non-portable to other compilers.
!    Use of 'STOP n' is also a possible option, but while this is a valid
!    and ISO-standard Fortran 90 keyword with optional integer argument,
!    what actually happens is entirely compiler and OS-dependent. In some
!    cases, zero is always passed, whatever the value of n. Some compilers
!    restrict the number of digits (typically 5 or 6) and some also allow
!    a string constant instead of an integer. Exactly what is printed,
!    how it is formatted and to where (mostly stdout if the OS supports this
!    stream, but not always) is also compiler-dependent. Hence STOP is not
!    a very portable option if the application relies on a valid exit code.
!    As an alternative, this file provides a wrapper by way of defining
!    EXIT() to alias to exit_().

!    This file can be compiled with the AIX xlf[95] compiler and linked with
!    the routines using CALL RENAME() and CALL EXIT().
!
! NOTES
!    1. Compile this file togther with the application rather than compiling
!       separately and including an an object library, in case the linker
!       picks up the compiler's (buggy) version of EXIT() first.
!    2. Only link this file when compiling with the IBM AIX xlf compilers -
!       do not use with any non-IBM xlf compilers!
!    3. There is no return from this routine; the program buffers are
!       flushed and the execution stops immediately. The shell variable $?
!       should then get the expected exit value.
!    4. Only the RENAME() and EXIT() routines are aliased in this way; other
!       common POSIX system calls such as GETARG() and IARGC() behave as 
!       expected.Should other such calls not work POSIXly, but can be aliased
!       to the IBM equivalent in the same way, they could be included here.
!
! EXAMPLE
!    > uname
!    AIX
!    > cat myprog.f90
!    PROGRAM MYPROG
!     INTEGER :: exit_code = 1
!     CALL EXIT(exit_code)
!    END PROGRAM MYPROG
!    > xlf95 -o myprog myprog.f90
!    > myprog
!    > echo $?
!    16
!    > xlf95 -o myprog myprog.f90 xlf_interfaces.f90
!    > myprog
!    > echo $?
!    1
!
! SEE ALSO
!   https://www.ibm.com/developerworks/community/blogs/
!           b10932b4-0edd-4e61-89f2-6e478ccba9aa/entry/
!           calling_common_posix_functions_from_fortran9?lang=en
!
! AUTHOR
!    Dave Offiler, Met Office, Exeter    <dave.offiler@metoffice.com>
!
!****

SUBROUTINE RENAME (oldname, newname)
  CHARACTER(LEN = *) :: oldname, newname
  CALL SYSTEM("mv "//TRIM(oldname)//" "// TRIM(newname))
END SUBROUTINE RENAME


SUBROUTINE EXIT(status)
  INTEGER :: status
  CALL exit_(status)
END SUBROUTINE EXIT