pm_sysShell::isFailedGetOutput Interface Reference

Generate and return failed = .false. if the output of the input system command is successfully retrieved in the allocatable argument output.
Otherwise, return failed = .true. indicating the occurrence of an error. More...

Detailed Description

Generate and return failed = .false. if the output of the input system command is successfully retrieved in the allocatable argument output.
Otherwise, return failed = .true. indicating the occurrence of an error.

To do so, the procedures under this generic interface call the system to run the requested command while redirecting its output to a temporary file for subsequent retrieval and return to the user.

Warning

Use this functionality responsibly and with caution.
Due to their simplicity, the procedures under this generic interface have high potential of abuse by passing system commands that can wreak havoc.
The responsible usage of this functionality must be currently guaranteed by the user.

Parameters

[in]	command	: The input scalar character of default kind SK containing the system command whose output must be retrieved.
[out]	output	: The output allocatable scalar character of default kind SK containing the output from the system command call. The output may contain the text redirected to the standard error if the specified command fails, even though the processor calls it and returns successfully. This can be verified by testing whether the optional output argument exitstat is non-zero (implying the failure of the specified command to return successfully). The allocation status of output remains undefined if the procedure returns failed set to .true.. Always check the returned value of failed before using output. This behavior is sensible because when the procedure fails, the contents of output is garbage and should not be subsequently used.
[in,out]	errmsg	: The input/output scalar character of default kind SK of arbitrary length type parameter. If an error occurs, errmsg will be set to a descriptive message about the nature of the runtime error. A length of LEN_IOMSG characters is likely sufficient to capture most error messages in full. (optional. If missing, no error message will be output if an error occurs.)
[out]	exitstat	: The output scalar integer of default kind IK, representing the exit code returned by the input command. For more information, see the corresponding argument of isFailedExec. The specific returned value of exitstat is processor and application dependent. However, a zero exitstat frequently implies the specified command returned the control successfully to the processor, while non-zero exitstat implies command failure. See also the corresponding output argument of isFailedExec. (optional, If missing, user may find it difficult to tell whether the contents of output are from stdout or strerr.)

Returns

failed : The output scalar logical of default kind LK. It is .true. if and only if the process of retrieving the command output fails at any point.

Possible calling interfaces ⛓

use pm_sysShell, only: isFailedGetOutput
 
failed = isFailedGetOutput(command, output, exitstat = exitstat)
failed = isFailedGetOutput(command, output, errmsg, exitstat = exitstat)

Warning

User must always verify the function output failed is .false. before using the output.

Example usage ⛓

program example
 
    use pm_kind, only: LK, IK, SK
    use pm_io, only: display_type
    use pm_sysShell, only: isFailedGetOutput
 
    implicit none
 
    logical(LK) :: failed
    character(255, SK) :: errmsg = SK_""
    character(:, SK), allocatable :: output
 
    type(display_type) :: disp
    disp = display_type(file = "main.out.F90")
 
    call disp%skip()
    call disp%show("failed = isFailedGetOutput(SK_'ls', output) ! List all files in the current directory (works on POSIX-compliant systems).")
                    failed = isFailedGetOutput(SK_'ls', output)
    call disp%show("failed ! Check if any error has occurred.")
    call disp%show( failed )
    call disp%show(.not."if ( failed) call disp%show( output , deliml = SK_'''' )")
                    if (.not. failed) call disp%show( output , deliml = SK_'''' )
    call disp%skip()
 
    call disp%skip()
    call disp%show("failed = isFailedGetOutput(SK_'dir', output) ! List all files in the current directory (works on Windows-compliant systems).")
                    failed = isFailedGetOutput(SK_'dir', output)
    call disp%show("failed ! Check if any error has occurred.")
    call disp%show( failed )
    call disp%show(.not."if ( failed) call disp%show( output , deliml = SK_'''' )")
                    if (.not. failed) call disp%show( output , deliml = SK_'''' )
    call disp%skip()
 
    call disp%skip()
    call disp%show("failed = isFailedGetOutput(SK_'if shell syntax error happens, output remains unallocated.', output, errmsg).")
                    failed = isFailedGetOutput(SK_'if shell syntax error happens, output remains unallocated.', output, errmsg)
    call disp%show("failed ! Check if any error has occurred.")
    call disp%show( failed )
    call disp%show("if (failed) then; call disp%show( trim(errmsg) , deliml = SK_'''' ); else; call disp%show( output , deliml = SK_'''' ); end if")
                    if (failed) then; call disp%show( trim(errmsg) , deliml = SK_'''' ); else; call disp%show( output , deliml = SK_'''' ); end if
    call disp%skip()
 
    call disp%skip()
    call disp%show("failed = isFailedGetOutput(SK_'ls', output)")
                    failed = isFailedGetOutput(SK_'ls', output)
    call disp%show("failed ! Check if any error has occurred.")
    call disp%show( failed )
    call disp%show(.not."if ( failed) call disp%show( output , deliml = SK_'''' )")
                    if (.not. failed) call disp%show( output , deliml = SK_'''' )
    call disp%skip()
 
    call disp%skip()
    call disp%show("failed = isFailedGetOutput(SK_'ls -lhtr', output, errmsg) ! Gracefully handle runtime errors and capture the error message.")
                    failed = isFailedGetOutput(SK_'ls -lhtr', output, errmsg)
    call disp%show("failed ! Check if any error has occurred.")
    call disp%show( failed )
    call disp%show("if (failed) then; call disp%show( trim(errmsg) , deliml = SK_'''' ); else; call disp%show( output , deliml = SK_'''' ); end if")
                    if (failed) then; call disp%show( trim(errmsg) , deliml = SK_'''' ); else; call disp%show( output , deliml = SK_'''' ); end if
    call disp%skip()
 
end program example

Example Unix compile command via Intel ifort compiler ⛓

#!/usr/bin/env sh
rm main.exe
ifort -fpp -standard-semantics -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe
./main.exe

Example Windows Batch compile command via Intel ifort compiler ⛓

del main.exe
set PATH=..\..\..\lib;%PATH%
ifort /fpp /standard-semantics /O3 /I:..\..\..\include main.F90 ..\..\..\lib\libparamonte*.lib /exe:main.exe
main.exe

Example Unix / MinGW compile command via GNU gfortran compiler ⛓

#!/usr/bin/env sh
rm main.exe
gfortran -cpp -ffree-line-length-none -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe
./main.exe

Example output ⛓

 
failed = isFailedGetOutput(SK_'ls', output) ! List all files in the current directory (works on POSIX-compliant systems).
failed ! Check if any error has occurred.
F
if (.not. failed) call disp%show( output , deliml = SK_'''' )
'CMakeCache.txt
CMakeFiles
CMakeLists.txt
Makefile
build.sh
cmake_install.cmake
main.F90
main.exe
main.out.F90'
 
 
failed = isFailedGetOutput(SK_'dir', output) ! List all files in the current directory (works on Windows-compliant systems).
failed ! Check if any error has occurred.
F
if (.not. failed) call disp%show( output , deliml = SK_'''' )
'CMakeCache.txt CMakeLists.txt  build.sh         main.F90  main.out.F90
CMakeFiles  Makefile    cmake_install.cmake  main.exe'
 
 
failed = isFailedGetOutput(SK_'if shell syntax error happens, output remains unallocated.', output, errmsg).
failed ! Check if any error has occurred.
T
if (failed) then; call disp%show( trim(errmsg) , deliml = SK_'''' ); else; call disp%show( output , deliml = SK_'''' ); end if
'@pm_sysShell@isFailedGetOutputMsg()@line(241): Failed to fetch command output. Cannot open file '/tmp/isFailedGetOutputMsg.tmp.gthaqhufxilpycbsswoh': No such file or directory'
 
 
failed = isFailedGetOutput(SK_'ls', output)
failed ! Check if any error has occurred.
F
if (.not. failed) call disp%show( output , deliml = SK_'''' )
'CMakeCache.txt
CMakeFiles
CMakeLists.txt
Makefile
build.sh
cmake_install.cmake
main.F90
main.exe
main.out.F90'
 
 
failed = isFailedGetOutput(SK_'ls -lhtr', output, errmsg) ! Gracefully handle runtime errors and capture the error message.
failed ! Check if any error has occurred.
F
if (failed) then; call disp%show( trim(errmsg) , deliml = SK_'''' ); else; call disp%show( output , deliml = SK_'''' ); end if
'total 68K
-rw-r--r-- 1 amir amir 3.1K Mar 14  2024 main.F90
-rw-r--r-- 1 amir amir 1.9K Oct 27 21:18 cmake_install.cmake
-rw-r--r-- 1 amir amir  13K Oct 27 21:18 CMakeCache.txt
-rwxr-xr-x 1 amir amir   76 Oct 27 22:30 build.sh
-rwxr-xr-x 1 amir amir 1.3K Oct 27 22:30 CMakeLists.txt
-rw-r--r-- 1 amir amir 6.1K Oct 27 22:43 Makefile
-rwxr-xr-x 1 amir amir  18K Oct 27 22:43 main.exe
drwxr-xr-x 7 amir amir 4.0K Oct 27 22:43 CMakeFiles
-rw-r--r-- 1 amir amir 1.6K Oct 27 22:43 main.out.F90'
 
 

Final Remarks ⛓

---

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
   
2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
   

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright

Computational Data Science Lab

Todo:

Low Priority: This generic interface should be extended to support character output of non-default kind once non-default characters is support by all relevant Fortran compilers.

Author:

Amir Shahmoradi, Tuesday March 7, 2017, 3:50 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas Austin

Definition at line 586 of file pm_sysShell.F90.

---

The documentation for this interface was generated from the following file:

• src/fortran/main/pm_sysShell.F90