module gtool_history

a sequential output interface for gtool4 netCDF dataset.

Description

This module is designed for output to gtool4 netCDF dataset sequentially along an axis (hereafter it will be called 'time'). The name indicates that the module is originally intended to serve as the 'history' of atmospheric forecast models.

Dependency

• module gtdata_types for internal data access
• module dc_types for constants STRING and TOKEN
• module dc_trace for error trace function

Derived Types

type GT_HISTORY

Data entity of this type represents a netCDF dataset controlled by gtool4 library. It must be initialized by HistoryOpen, then used in many subroutines, and must be finalized by HistoryClose. Note that the resultant file is undefined if you forget to finalize it.

Users are recommended to retain the object of this type returned by HistoryOpen, to use it as the last argument (called history) for all following subroutine calls. However, it is not mandatory. When you are going to write ONLY one dataset, argument history of all subroutine calls can be omitted, and the history entity will be internally managed within this module.

type GT_HISTORY_AXIS

This type may be used as a argument axes of HistoryCreate to define features of axes of a history dataset. Typically, a constant array of this type will be used for fixed specification.

type GT_HISTORY_AXIS
    character(len = token):: name
    integer:: length
    character(len = string):: longname, units
    character(len = token):: xtype
end type

type GT_HISTORY_VARINFO

This type may be used as a argument varinfo of HistoryAddVariable to define features of variable of a history dataset.

Procedure Interface

HistoryCreate subroutines

Two specific subroutines shares common part:

call HistoryCreate(file, title, source, institution, ..., origin, interval, [history])

Both two ones initializes a dataset file. The result of type GT_HISTORY will be returned by history or managed internally if omitted. Mandatory global attributes are defined by arguments title, source, and institution; they are all declared as character(len = *). Spatial axis definitions have two different forms: a primitive one uses several arrays of various types: dims, dimsizes, longnames, units, and xtypes. Another sophisticated one has only array of type GT_HISTORY_AXIS, axes. Temporal definition is done without origin, interval.

subroutine HistoryCreate2(file, title, source, institution, &
    & axes, origin, interval, history)
implicit none
    character(len=*), intent(in):: file
    character(len=*), intent(in):: title, source, institution
    type(GT_HISTORY_AXIS), intent(in):: axes(:)
    real, intent(in):: origin, interval
    type(GT_HISTORY), intent(out), optional:: history

subroutine HistoryCreate1(file, title, source, institution, &
    & dims, dimsizes, longnames, units, origin, interval, &
    & xtypes, history)
    use gtdata_generic
    use dc_url
    use dc_error
    use dc_string
    use dc_types, only: string, token
implicit none
    character(len=*), intent(in):: file
    character(len=*), intent(in):: title, source, institution
    character(len=*), intent(in):: dims(:)
    integer, intent(in):: dimsizes(:)
    character(len=*), intent(in):: longnames(:)
    character(len=*), intent(in):: units(:)
    real, intent(in):: origin, interval
    character(len=*), intent(in), optional:: xtypes(:)
    type(GT_HISTORY), intent(out), optional, target:: history