Intel® Fortran Compiler Classic and Intel® Fortran Compiler Developer Guide and Reference

ID 767251
Date 3/22/2024
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

Methods of Handling Errors

Whenever possible, the Intel® Fortran RTL does certain error handling, such as generating appropriate messages and taking necessary action to recover from errors. You can explicitly supplement or override default actions by using the following methods:

  • To transfer control to error-handling code within the program, use the END, EOR, and ERR branch specifiers in I/O statements. See Use the END EOR and ERR Branch Specifiers.

  • To identify Fortran-specific I/O errors based on the value of Intel® Fortran RTL error codes, use the I/O status specifier (IOSTAT) in I/O statements (or call the ERRSNS subroutine). To capture an explanatory message about an error condition, use the IOMSG specifier. For more information, see Use the IOSTAT and IOMSG Specifiers, and Fortran Exit Codes.

  • To continue execution after an error condition is detected in some intrinsic subroutines, including the collectives, atomics, MOVE_ALLOC and image control, and the ALLOCATE and DEALLOCATE statements, specify the optional STAT argument or specifier.

    Further information about the error can be captured using an optional ERRMSG argument or specifier, if available, for the intrinsic or statement. For more information, see USE the STAT or STATUS argument, or STAT and ERRMSG Specifiers.

  • Obtain system-level error codes by using the appropriate library routines.

  • For certain error conditions, use the signal handling facility to change the default action to be taken.

Use the END, EOR, and ERR Branch Specifiers

When a severe error occurs during Intel® Fortran program execution, the default action is to display an error message and terminate the program. To override this default action, there are three branch specifiers you can use in I/O statements to transfer control to a specified point in the program:

  • The END branch specifier handles an end-of-file condition.

  • The EOR branch specifier handles an end-of-record condition for non-advancing reads.

  • The ERR branch specifier handles all error conditions.

If you use the END, EOR, or ERR branch specifiers, no error message is displayed and execution continues at the designated statement, usually error-handling code.

You might encounter an unexpected error that the error-handling routine cannot handle. In this case, do one of the following:

  • Modify the error-handling routine to display the error message number.

  • Remove the END, EOR, or ERR branch specifiers from the I/O statement that causes the error.

After you modify the source code, compile, link, and run the program to display the error message. For example:

    READ (8,50,ERR=400)

If any severe error occurs during execution of this statement, the Intel® Fortran RTL transfers control to the statement at label 400. Similarly, you can use the END specifier to handle an end-of-file condition that might otherwise be treated as an error. For example:

    READ (12,70,END=550)

When using non-advancing I/O, use the EOR specifier to handle the end-of-record condition. For example:

150 FORMAT (F10.2, F10.2, I6)
    READ (UNIT=20, FMT=150, SIZE=X, ADVANCE='NO', EOR=700) A, F, I

You can also use ERR as a specifier in an OPEN, CLOSE, or INQUIRE statement. For example:

    OPEN (UNIT=10, FILE='FILNAME', STATUS='OLD', ERR=999)

If an error is detected during execution of this OPEN statement, control transfers to the statement at label 999.

Use the IOSTAT and IOMSG Specifiers, and Fortran Exit Codes

The IOSTAT specifier can be used to continue program execution after an I/O error, or an end-of-file or end-of-record condition occurs, and to return information about the status of I/O operations. Certain error conditions are not returned in IOSTAT.

The IOSTAT specifier can supplement or replace the use of the END=, EOR=, and ERR= branch specifiers.

Use of an IOSTAT= specifier in an I/O statement prevents initiation of error termination if an error occurs during the execution of the I/O statement. The integer variable specified in the IOSTAT= specifier becomes defined during the execution of the I/O statement with the following values:

  • Zero for normal completion of the I/O statement (no error, end-of-file, or end-of-record condition occurs).

  • The value of the (negative) default integer scalar constant IOSTAT_EOR defined in the intrinsic module ISO_FORTRAN_ENV if no error condition or end-of-file condition occurs, but an end-of-record condition does occur during the execution of an input statement.

  • The value of the (negative) default integer scalar constant IOSTAT_END defined in ISO_FORTRAN_ENV if no error condition occurs, but an end-of-file condition does occur during the execution of an input statement.

  • For an INQUIRE statement, the value of the default integer constant IOSTAT_INQUIRE_INTERNAL_UNIT defined in ISO_FORTRAN_ENV if a file-unit-number identifies an internal unit in the execution of the statement.

  • A positive integer value if an error condition occurs. (This value is one of the Fortran-specific IOSTAT numbers listed in the runtime error message. See List of Runtime Error Messages, which lists many of the messages.)

Note that the value assigned to the IOSTAT variable is the same value that would be returned as an exit code if error termination was initiated.

In addition, many I/O statements support an optional IOMSG= specifier. If an error, end of file, or end of record error occurs during the execution of the statement containing the specifier, the default character scalar variable specified in the IOMSG= specifier becomes defined with an explanatory message, truncated or padded as in intrinsic character assignment. If none of these conditions occur, the value of the IOMSG variable is unchanged.

Following the execution of the I/O statement and assignment of an IOSTAT and IOMSG value, control transfers to the END=, EOR=, or ERR= statement label, if any. If there is no control transfer, normal execution continues.

The non-standard include file FOR_ISODEF.FOR and the non-standard module FORISODEF contain symbolic constants for the values returned through an IOSTAT= specifier.

The following example uses the IOSTAT and IOMSG specifier and the module FORIOSDEF to handle an OPEN statement error (in the FILE specifier):


     USE foriosdef
     IMPLICIT NONE
     CHARACTER(LEN=40) :: FILNM
     CHARACTER(LEN=128) :: MSG
     INTEGER IERR
     PRINT *, 'Type file name:'
     READ (*,*) FILNM
     OPEN (UNIT=1, FILE=FILNM, STATUS='OLD', IOSTAT=IERR, ERR=100, IOMSG=MSG)
     PRINT *, 'Opening file: ', FILNM
     ! process the input file
     ...
     CLOSE (UNIT=1)
     STOP
 100 IF(IERR . EQ. FOR$IOS_FILNOTFOU) THEN
        PRINT *, 'File: ', FILNM, ' does not exist '
     ELSE 
        PRINT *, 'Unrecoverable error, code =', IERR
        PRINT *, 'Error description =', MSG
     END IF
     END PROGRAM

Another way to obtain information about an error is by using the ERRSNS subroutine, which allows you to obtain the last I/O system error code associated with an Intel® Fortran RTL error.

Use the STAT or STATUS argument, or STAT and ERRMSG Specifiers

ALLOCATE, DEALLOCATE, and image control statements have optional STAT= and ERRMSG= specifiers. Several intrinsic subroutines have optional STAT or STATUS arguments, and some of these also have an optional ERRMSG argument.

Use STAT specifiers, or STAT and STATUS arguments, to prevent initiation of error termination if an error condition occurs during the execution of the statement or procedure that specifies this specifier or argument.

If an error occurs, the integer status variable is assigned a non-zero value; if no error occurs, it is assigned a value of 0. The status variable can be tested to determine if an error occurred, and the program can contain error handling code if an error did occur. Several intrinsic subroutines and statement descriptions include the meaning of the error code value; for example, IERRNO and CHDIR.

If a statement has an ERRMSG specifier, or an intrinsic subroutine has an ERRMSG argument, the variable associated with it is a default character scalar variable that becomes defined with an explanatory message about the type of error that occurred. The message is truncated or blank padded, according to the rules for intrinsic assignment. If no error occurs, the value of ERRMSG is unchanged.

The following example shows how the use of the STAT= and ERRMSG= can be used on an ALLOCATE statement to handle allocation errors:

     IMPLICIT NONE
     REAL,ALLOCATABLE(:, :, :)  :: A, B
     CHARACTER(LEN=128)         :: MSG
     INTEGER                    :: STATUS
     INTEGER                    :: I, J, K
     PRINT *, 'Enter the 3 extents of the arrays A and B:'
     READ (*,*) I, J, K
     ALLOCATE (A(I, J, K), B(I, J, K), STAT=STATUS, ERRMSG=MSG)
     IF(STATUS .NE.1) THEN
        PRINT *, 'Unrecoverable allocation error', STATUS 
        PRINT *, 'Error description =', MSG
        ERROR STOP STATUS
     END IF
     END PROGRAM

See Also