gtool_history.f90.rd

# 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