Error Class

1. Description

2. Module Interface

3. Functions and Subroutines

4. Examples

Description

The Error class provides information about run-time errors. An instance of this class is an optional argument to several of the functions and subroutines in this library. An Error object contains information on the type of error that occured in the form of a code and a message, and the location in the source code where there was detected.

Module Interface

MODULE Error_Class

TYPE Error

INTERFACE isValid
INTERFACE initialize
INTERFACE finalize
INTERFACE get
INTERFACE set
INTERFACE print
INTERFACE clear
INTERFACE getCode
INTERFACE getFilename
INTERFACE getLine
INTERFACE getMessage
INTERFACE isSet

END MODULE Error_Class

Functions and Subroutines

FUNCTION isValid(this) RESULT(result)
    LOGICAL :: result
    TYPE(Error), INTENT(in) :: this

This function checks whether the parameter this contains a valid Error object. It may be applied to any Error object at any time.

SUBROUTINE initialize(this,code,filename,line,message)
    TYPE(Error),      INTENT(inout)        :: this
    INTEGER,          INTENT(in), OPTIONAL :: code
    CHARACTER(len=*), INTENT(in), OPTIONAL :: filename
    INTEGER,          INTENT(in), OPTIONAL :: line
    CHARACTER(len=*), INTENT(in), OPTIONAL :: message

This subroutine initializes an (invalid) Error object so that it can be used. This subroutine should be invoked on an object before any other function or subroutine applied to it (except isValid of course). After initialization, the parameter this contains a valid Error object. The four optional arguments are used to initialize the object with user specified data. When the parameter code has a non-zero value, the Error object is set, which means that it contains information on a run-time error.

SUBROUTINE finalize(this)
    TYPE(Error), INTENT(inout) :: this

This subroutine finalizes the (valid) Error object, this. This object should have been initialized earlier in the program. After finalization, the object is invalid and should not be used anymore.

SUBROUTINE get(this,code,filename,line,message)
    TYPE(Error),      INTENT(in)            :: this
    INTEGER,          INTENT(out), OPTIONAL :: code
    CHARACTER(len=*), INTENT(out), OPTIONAL :: filename
    INTEGER,          INTENT(out), OPTIONAL :: line
    CHARACTER(len=*), INTENT(out), OPTIONAL :: message

This subroutine retrieves information from the Error object, this. The object is not modified. The four optional arguments determine which information will be retrieved. This subroutine can be invoked without the optional arguments. This acts as a no-op and, therefore, is not very useful.

SUBROUTINE set(this,code,filename,line,message)
    TYPE(Error),      INTENT(inout)        :: this
    INTEGER,          INTENT(in), OPTIONAL :: code
    CHARACTER(len=*), INTENT(in), OPTIONAL :: filename
    INTEGER,          INTENT(in), OPTIONAL :: line
    CHARACTER(len=*), INTENT(in), OPTIONAL :: message

This subroutine changes the information stored in the Error object, this.  The four optional arguments determine which information will be changed. This subroutine can be invoked without the optional arguments. This acts as a no-op and is not very useful.

SUBROUTINE print(this)
    TYPE(Error), INTENT(in) :: this

This subroutine is the equivalent of the Fortran PRINT statement. It prints the Error object, this, to the standard output unit in standardized format. The object is not modified.

SUBROUTINE clear(this)
    TYPE(Error), INTENT(inout) :: this

This subroutine clears the error condition of the Error object, this, unless it was not set. In that case, the object is unaffected

FUNCTION getCode(this) RESULT(result)
    INTEGER :: result
    TYPE(Error), INTENT(in) :: this

This function retrieves the error code of the object, this. The object it self is not modified. Note that when the return value is zero the Error object is not set. This means that the other information contained in the object is not related to a run-time error.

FUNCTION getFilename(this) RESULT(result)
    CHARACTER(len=*) :: result
    TYPE(Error), INTENT(in) :: this

This function retrieves the name of the source code file in which the error occured from the Error object, this. Note that this filename is only meaningful when an error condition is set on this object.

FUNCTION getLine(this) RESULT(result)
    INTEGER :: result
    TYPE(Error), INTENT(in) :: this

This function retrieves the source code line near which the error occured from the Error object, this. Note that this information only meaningful when an error condition is set on this object.

FUNCTION getMessage(this) RESULT(result)
    CHARACTER(len=*) :: result
    TYPE(Error), INTENT(in) :: this

This function retrieves a message describin the error from the Error object, this. Note that this message may not always be set.

FUNCTION isSet(this) RESULT(result)
    LOGICAL :: result
    TYPE(Error), INTENT(in) :: this

This function checks whether an error condition is set on the Error object, this, and returns the result.

Examples

Here is a simple example program that shows how the Error class is typically used:

PROGRAM Error_Class_Example
  USE Error_Class
  USE DataFile_Class
  IMPLICIT NONE

  TYPE(DataFile) :: file
  TYPE(Error)    :: err

  CALL initialize(err)
  CALL initialize(input,name="data.nc",type=NetCDFFile,err=err)
  IF (isSet(err)) THEN
     CALL print(err)
     STOP 'initialize'
  END IF

  CALL finalize(input,err=err)
  IF (isSet(err)) THEN
     CALL print(err)
     STOP 'finalize'
  END IF

  CALL finalize(err)
END PROGRAM Error_Class_Example

The program opens and closes a file using a DataFile object, file. Note that the Error object, err, is initialized before it is used to capture any error that may occur while initializing the DataFile object.