flibs/m_platform(n) 1.0 "flibs"

NAME

flibs/m_platform - Platform-dependent routines and features

    TABLE OF CONTENTS
    SYNOPSIS
    DESCRIPTION
    OVERVIEW
        Pre-processing macros
        Compile
        Operating System dependency
        System fortran extension
        Environment variables extension
        Change directory fortran extension
        File stat fortran extension
        Example of compiler settings
    ROUTINES
    COPYRIGHT

SYNOPSIS

use m_platform

platform_system (command ?, status?)

platform_get_os() result ( currentos )

platform_osstring (currentos)

platform_get_platform() result ( currentplatform )

platform_platformstring (currentplatform)

platform_get_environment_variable ( envvar , value)

platform_cd ( dirname ?, status?)

platform_stat ( filename , statarray ?, status?)

DESCRIPTION

The m_platform module contains parameters to identify the platform the program is running on and provides several routines to interact with the operating system.

OVERVIEW

The goal is to make the client source code as independent as possible from the particular environment, that is

independent from the operating system, so that the binaries can be used under Windows, Linux or any other specific OS without modifying the source code,
independent from the fortran compiler, so that the binaries can be generated with gfortran Intel Fortran, Absoft, or any other specific compiler without modifying the source code.

For instance, the m_platform module provides the following features :

The parameter PLATFORM_OS identifies the operating system and the parameter PLATFORM_PLATFORM identifies the general category.
The subroutine platform_system() hides the platform-specific details of running an external command or program.

The function platform_get_os() returns an integer which identifies the operating system and the function platform_get_platform() identifies the general category. For example, the file separator is different on windows ("\"), unix ("/") and Mac (":"). In the following example, extracted from the m_vfile module included with flibs, the platform_get_platform() function is used to configure the separator for the current platform.

use m_platform, only : & platform_get_platform , & PLATFORM_PLATFORM_WINDOWS ,& PLATFORM_PLATFORM_UNIX , & PLATFORM_PLATFORM_MAC integer :: platform character (len=1) :: VFILE_PLATFORM_SEPARATOR platform = platform_get_platform () select case ( platform ) case ( PLATFORM_PLATFORM_WINDOWS ) VFILE_PLATFORM_SEPARATOR = VFILE_PLATFORM_SEPARATOR_WINDOWS case ( PLATFORM_PLATFORM_UNIX ) VFILE_PLATFORM_SEPARATOR = VFILE_PLATFORM_SEPARATOR_UNIX case ( PLATFORM_PLATFORM_MAC ) VFILE_PLATFORM_SEPARATOR = VFILE_PLATFORM_SEPARATOR_MAC case default print *, "I come from Vega." return end select

The subroutine platform_system() allows to execute an external program at the system level. This routine is generally provided by the fortran compiler as an extension to standard fortran. But some compilers provide the feature as a subroutine (for example gfortran), while other compilers provide the feature as a function (for example Intel Fortran). In the following example, one execute a Monte-Carlo simulation with no dependency on the specific compiler.

use m_platform, only platform_system call platform_system ( "montecarlo.exe" , status )

This is a sketch of available routines :

platform_system Executes an external command on the system
platform_get_os Returns the current operating system
platform_get_platform Returns the current platform
platform_get_environment_variable Get to one environment variable
platform_cd Change the system current directory
platform_stat Get status of a file

Pre-processing macros

The source code of m_platform is based on pre-processing macro, which must be configured for the specific couple (OS,compiler) at use. With most compilers, defining a pre-processing macro simply consists in enabling the pre-processing with a specific option and adding "-D<macro>" options on the command-line.

The only mandatory pre-processing macro which must be defined is the _PLATFORM_OS_<your OS> macro. Optionnaly, other pre-processing macros may be defined so that the client code may access to additionnal features. If a feature is used and the associated macros have not been defined, the "status" integer of the associated routine will have the value PLATFORM_ERROR_UNDEFINED_SERVICE.

Compile

The "make" directory provided with flibs should help the use to compile m_platform. The "make/makefile" contains all the makefiles necessary for the project, include specific settings for several compilers. the "make/visualstudio" directory include all projects .nfproj and solutions .sln files necessary to compile the project with Intel Fortran 8 and Visual Studio 2003.

Operating System dependency

The m_platform module must be informed of the specific OS for which it is compiled. One of the following pre-processing macros must be defined to set the spefic OS at use :

_PLATFORM_OS_WINDOWS_95
_PLATFORM_OS_WINDOWS_NT
_PLATFORM_OS_MAC
_PLATFORM_OS_SUN
_PLATFORM_OS_LINUX
_PLATFORM_OS_UNIX

System fortran extension

The SYSTEM fortran extension allows to execute an external program. Depending on the compiler, the SYSTEM fortran extension is provided as a subroutine or a function. The m_platform module may be informed of the particular version of the SYSTEM extension at use and one of the following pre-processing macro must be defined :

_PLATFORM_SYSTEM_SUBROUTINE
_PLATFORM_SYSTEM_FUNCTION

See in your compiler manual for the specific settings. For example, this is a short list of compilers and the SYSTEM provided :

function : Intel Fortran, g95.
subroutine : gfortran,

Environment variables extension

The fortran 2003 standard introduces a standard way of accessing to the environment variables. Older compilers does not match that standard but provide extensions to access to environment variables. To inform the m_platform module of the particular environment variable extension, one of the following pre-processing macro may be defined :

_PLATFORM_INTEL_FORTRAN_PORTABILITY_ROUTINES
_PLATFORM_FORTRAN_2003

Change directory fortran extension

Depending on the compiler, the "CHDIR" fortran extension is provided as a subroutine or a function. To inform the m_platform module of the particular CHDIR extension, one of the following pre-processing macro may be defined :

_PLATFORM_CHDIR_SUBROUTINE
_PLATFORM_CHDIR_FUNCTION

See in your manual for the specific settings. For example, this is a short list of compilers and their particular CHDIR provided :

function : Intel Fortran, g95, gfortran
subroutine : gfortran

File stat fortran extension

Depending on the compiler, the "STAT" fortran extension is provided as a subroutine or a function. For example, this is a short list of compilers and their particular STAT provided :

function : Intel Fortran, g95
subroutine : gfortran

To inform the m_platform module of the particular STAT extension, one of the following pre-processing macro may be defined :

_PLATFORM_STAT_SUBROUTINE
_PLATFORM_STAT_FUNCTION

Example of compiler settings

This is an abstract of all pre-processing macros for several compilers.

Compiler : gfortran

_PLATFORM_FORTRAN_2003
_PLATFORM_CHDIR_SUBROUTINE
_PLATFORM_STAT_SUBROUTINE
_PLATFORM_SYSTEM_SUBROUTINE

Compiler : Intel Fortran

_PLATFORM_INTEL_FORTRAN_PORTABILITY_ROUTINES
_PLATFORM_CHDIR_FUNCTION
_PLATFORM_STAT_FUNCTION
_PLATFORM_SYSTEM_FUNCTION

Compiler : g95

_PLATFORM_FORTRAN_2003
_PLATFORM_CHDIR_FUNCTION
_PLATFORM_STAT_FUNCTION
_PLATFORM_SYSTEM_FUNCTION

ROUTINES

The module contains the following routines.

use m_platform

To import the subroutines, use this module.

platform_system (command ?, status?)

character(len=*) :: command
integer, intent ( out ), optional :: status

Run an external command or program, optionally retrieving the status of that command. Under Windows the "call system" may generate the display of a console. Optional argument status contains the execution status. Notice that the information contained in it is not very reliable - some systems do not give any information. The command to run is quite likely platform-dependent.

platform_get_os() result ( currentos )

integer :: currentos

Return the type of operating system, one of: PLATFORM_OS_WINDOWS_95, PLATFORM_OS_WINDOWS_NT, PLATFORM_OS_MACOS, PLATFORM_OS_SUNOS, PLATFORM_OS_LINUX, PLATFORM_OS_UNIX. The actual integer value should not be used directly ; instead, it should be compared against the PLATFORM_OS_* public variables.

platform_osstring (currentos)

character(len=*), intent(out) :: currentos

Returns a string containing the current operating system running on the current machine, one of "Windows 95", "Windows NT", "MacOS", "SunOS", "Linux" or "Unix".

platform_get_platform() result ( currentplatform )

integer :: currentplatform

Return the category of platform, one of: PLATFORM_PLATFORM_WINDOWS, PLATFORM_PLATFORM_MAC, PLATFORM_PLATFORM_UNIX The actual integer value should not be used directly ; instead, it should be compared against the PLATFORM_PLATFORM_* public variables.

platform_platformstring (currentplatform)

character(len=*), intent(out) :: currentplatform

Returns a string containing the current platform running on the current machine, one of "Windows", "Mac", "Unix".

platform_get_environment_variable ( envvar , value)

character(len=*) :: envvar
character(len=*) :: value

Retrieve the value of the environment variable envvar. There is no indication of whether the variable indeed exists and it is up to the calling program to provide a string argument sufficiently long to hold the value. The environment variable envvar is case-sensitive on some platforms, case-insensitive on others. This is entirely up to the platform. As the underlying routines give no indication of the existence of the environment variable, it is probably best to fill the value with a known value first (like: "????") to check it.

platform_cd ( dirname ?, status?)

character(len=*), intent(in) :: dirname
integer, intent(out) , optional :: status

Change working directory to dirname. If status is supplied, it contains 0 on success or nonzero error code upon return

platform_stat ( filename , statarray ?, status?)

character(len=*), intent(in) :: filename
integer, dimension (1:13) , intent(out) :: filename
integer, intent(out) , optional :: status

Get status of the file filename and fills the array statarray with the following content.

statarray(1) Device ID
statarray(2) Inode number
statarray(3) File mode
statarray(4) Number of links
statarray(5) Owner's uid
statarray(6) Owner's gid
statarray(7) ID of device containing directory entry for file (0 if not available)
statarray(8) File size (bytes)
statarray(9) Last access time
statarray(10) Last modification time
statarray(11) Last file status change time
statarray(12) Preferred I/O block size (-1 if not available)
statarray(13) Number of blocks allocated (-1 if not available)

If status is supplied, it contains 0 on success or nonzero error code upon return