dc_error.f90

Go to the documentation of this file.

!-----------------------------------------------------------------------
! Copyright (c) 2000-2026 Gtool Development Group. All rights reserved.
!-----------------------------------------------------------------------
!>
!> @author    Youhei SASAKI, Eizi TOYODA, Yasuhiro MORIKAWA
!> @copyright Copyright (C) GFD Dennou Club, 2000-2026. All rights reserved. <br/>
!>            License is BSD-2-Clause. see [COPYRIGHT](@ref COPYRIGHT) in detail
!> @en
!> @brief Error handling module
!> @details
!> Error handling about parts of programs should be regulated definitely.
!> Error means that input to the part of program is invalid, or
!> expected operation can not be done, etc.
!>
!> Procedures (procedures is generic name of subroutines and functions)
!> provided to users by gtool5 library almost report error to invoker
!> in the following two manner.
!>
!> - When error occurs, the program display appropriate messages and
!>   aborts.
!> - If logical optional argument `err` is given, the argument `err` become
!>   `.true.` when error occurs. If `err` is abbreviated,
!>   the operation is same as above.
!>
!> `StoreError` subroutine in `dc_error` module handle above all operations.
!> See `StoreError` about the interface of it.
!>
!> @enden
!>
!> @ja
!> @brief エラー処理用モジュール
!> @details
!> プログラムの部品は必ずエラーの取り扱いを明確に規定すべきものです。
!> エラーとは当該部品への入力が不適切であるとか、
!> 期待される動作をすることができないといった事態を指します。
!>
!> gtool5 ライブラリがユーザに提供する手続
!> (手続とはサブルーチンまたは関数の総称) はほとんどの場合、
!> 以下の 2 つの方式のいずれかで呼び出し元にエラーを報告します。
!>
!> - エラーが発生すると適切なメッセージを表示してプログラム終了
!> - 論理型の省略できる引数 `err` が与えられた場合は、
!>   エラー時にはそれを `.true.` にします。
!>   err が省略された場合は上に同じ。
!>
!> これらの処理はすべて `dc_error` モジュールの `StoreError`
!> サブルーチンで行っています。引用仕様などに関しては `StoreError`
!> を参照してください。
!>
!> @endja
!>
!> @section error_code_list Error Code List / エラーコード一覧
!>
!> @en
!> Programmers who add codes to gtool5 library must call
!> `StoreError` with appropriate error code.
!> And so values of error code and corresponding messages are listed
!> as follows to figure out if a new error code is needed to declared.
!> To use error codes mnemonic,
!> require "netcdf_f77" module or include "netcdf.inc" (deprecated)
!> about error codes with prefix `NF_E`, or
!> require "dc_error" module
!> about error codes with prefix `GT_E` and
!> `DC_E` and `HST_E`.
!> Error codes smaller than `USR_ERRNO` are saved
!> as user-defined error codes.
!>
!> Non error code that indicates normal (error-free) situation is
!> `DC_NOERR`.
!>
!> List of numerical values of error codes
!> issues a guideline about declaration of new error codes.
!> Give not numerical value but mnemonic of error code to source code.
!> @enden
!>
!> @ja
!> gtool5 ライブラリにコードを追加するプログラマは適切な
!> エラーコードで `StoreError` を呼び出すようにしなければなりません。
!> そこで、 新しいエラーコードを定義する必要があるかどうかを
!> 判定するために、 エラーコードの値と対応するメッセージを
!> 以下に一覧します。
!> エラーコードニーモニックを使用するためには、
!> `NF_E` で始まる名前については netcdf_f77
!> モジュールを引用するか include 'netcdf.inc' を行い（後者は推奨しません）、
!> `GT_E`, `DC_E`, `HST_E`
!> で始まる名前については dc_error モジュールを引用してください。
!> また `USR_ERRNO` 番より小さい値は、
!> 各々のユーザが適宜エラーコードを
!> 定義して利用するために空けてあります。
!>
!> エラーではない状態を表す非エラーコードは `DC_NOERR` です。
!>
!> エラーコードの数値の欄を設けたのは、新たなエラーコードを
!> 割り当てる際の指針を示すためです。
!> ソースコードにはエラーコードをニーモニックで与えるべきであり、
!> 数値をハードコードすることは厳に慎んで下さい。
!> @endja
!>
!> @subsection unused_codes Unused codes / 利用しないコード
!>
!> @en
!> Positive integer is not used as error codes.
!>
!> NetCDF library might return "libc" error code "error".
!> Numerical value of "errno" is no portable, so positive integer
!> should be reserved for "errno".
!> @enden
!>
!> @ja
!> 正の整数値はエラーコードとして使用しません。
!>
!> NetCDF ライブラリは libc のエラーコード errno を返す可能性があり、
!> errno の数値には移植性がないため、全ての正の整数値は errno
!> の仕様のために予約されているべきだからです。
!> @endja
!>
!> @subsection non_error_code Non error code / 非エラーコード
!>
!> @en
!> Use following non error code by referring this "dc_error" module.
!>
!> | Number | Mnemonic     |
!> |--------|--------------|
!> | 0      | `DC_NOERR`   |
!> @enden
!>
!> @ja
!> 以下の非エラーコードに関しては dc_error モジュールを引用することで
!> 利用してください。
!>
!> | 数値 | ニーモニック |
!> |------|--------------|
!> | 0    | `DC_NOERR`   |
!> @endja
!>
!> @subsection netcdf_error_codes Error codes for netCDF / netCDF に関するエラーコード
!>
!> @en
!> Use following error codes by referring this "netcdf_f77" module.
!>
!> | Number | Mnemonic          | Error message                                              |
!> |--------|-------------------|------------------------------------------------------------|
!> | 0      | `NF_NOERR`        | No Error (non error code)                                  |
!> | -33    | `NF_EBADID`       | Not a netCDF id                                            |
!> | -34    | `NF_ENFILE`       | Too many netCDF files open                                 |
!> | -35    | `NF_EEXIST`       | netCDF file exists && NC_NOCLOBBER                         |
!> | -36    | `NF_EINVAL`       | Invalid argument                                           |
!> | -37    | `NF_EPERM`        | Write to read only                                         |
!> | -38    | `NF_ENOTINDEFINE` | Operation not allowed in data mode                         |
!> | -39    | `NF_EINDEFINE`    | Operation not allowed in define mode                       |
!> | -40    | `NF_EINVALCOORDS` | Index exceeds dimension bound                              |
!> | -41    | `NF_EMAXDIMS`     | NF_MAX_DIMS exceeded                                       |
!> | -42    | `NF_ENAMEINUSE`   | String match to name in use                                |
!> | -43    | `NF_ENOTATT`      | Attribute not found                                        |
!> | -44    | `NF_EMAXATTS`     | NC_MAX_ATTRS exceeded                                      |
!> | -45    | `NF_EBADTYPE`     | Not a netCDF data type or _FillValue type mismatch         |
!> | -46    | `NF_EBADDIM`      | Invalid dimension id or name                               |
!> | -47    | `NF_EUNLIMPOS`    | NC_UNLIMITED in the wrong index                            |
!> | -48    | `NF_EMAXVARS`     | NF_MAX_VARS exceeded                                       |
!> | -49    | `NF_ENOTVAR`      | Variable not found                                         |
!> | -50    | `NF_EGLOBAL`      | Action prohibited on NC_GLOBAL varid                       |
!> | -51    | `NF_ENOTNC`       | Not a netCDF file                                          |
!> | -52    | `NF_ESTS`         | In Fortran, string too short                               |
!> | -53    | `NF_EMAXNAME`     | NC_MAX_NAME exceeded                                       |
!> | -54    | `NF_EUNLIMIT`     | NC_UNLIMITED size already in use                           |
!> | -55    | `NF_ENORECVARS`   | NC_rec op when there are no record vars                    |
!> | -56    | `NF_ECHAR`        | Attempt to convert between text & numbers                  |
!> | -57    | `NF_EEDGE`        | Edge+start exceeds dimension bound                         |
!> | -58    | `NF_ESTRIDE`      | Illegal stride                                             |
!> | -59    | `NF_EBADNAME`     | Attribute or variable name contains illegal characters     |
!> | -60    | `NF_ERANGE`       | Numeric conversion not representable                       |
!> | -61    | `NF_ENOMEM`       | Memory allocation (malloc) failure                         |
!> | -62    | `NF_EVARSIZE`     | One or more variable sizes violate format constraints      |
!> | -63    | `NF_EDIMSIZE`     | Invalid dimension size                                     |
!> | -64    | `NF_ETRUNC`       | File likely truncated or possibly corrupted                |
!> | -62 to -99 |              | Reserved area for future extensions of netCDF              |
!> @enden
!>
!> @ja
!> 以下のエラーコードに関しては netcdf_f77 モジュールを引用することで
!> 利用してください。
!>
!> | 数値   | ニーモニック      | エラーメッセージ                                           |
!> |--------|-------------------|------------------------------------------------------------|
!> | 0      | `NF_NOERR`        | No Error (非エラーコードです)                              |
!> | -33    | `NF_EBADID`       | Not a netCDF id                                            |
!> | -34    | `NF_ENFILE`       | Too many netCDF files open                                 |
!> | -35    | `NF_EEXIST`       | netCDF file exists && NC_NOCLOBBER                         |
!> | -36    | `NF_EINVAL`       | Invalid argument                                           |
!> | -37    | `NF_EPERM`        | Write to read only                                         |
!> | -38    | `NF_ENOTINDEFINE` | Operation not allowed in data mode                         |
!> | -39    | `NF_EINDEFINE`    | Operation not allowed in define mode                       |
!> | -40    | `NF_EINVALCOORDS` | Index exceeds dimension bound                              |
!> | -41    | `NF_EMAXDIMS`     | NF_MAX_DIMS exceeded                                       |
!> | -42    | `NF_ENAMEINUSE`   | String match to name in use                                |
!> | -43    | `NF_ENOTATT`      | Attribute not found                                        |
!> | -44    | `NF_EMAXATTS`     | NC_MAX_ATTRS exceeded                                      |
!> | -45    | `NF_EBADTYPE`     | Not a netCDF data type or _FillValue type mismatch         |
!> | -46    | `NF_EBADDIM`      | Invalid dimension id or name                               |
!> | -47    | `NF_EUNLIMPOS`    | NC_UNLIMITED in the wrong index                            |
!> | -48    | `NF_EMAXVARS`     | NF_MAX_VARS exceeded                                       |
!> | -49    | `NF_ENOTVAR`      | Variable not found                                         |
!> | -50    | `NF_EGLOBAL`      | Action prohibited on NC_GLOBAL varid                       |
!> | -51    | `NF_ENOTNC`       | Not a netCDF file                                          |
!> | -52    | `NF_ESTS`         | In Fortran, string too short                               |
!> | -53    | `NF_EMAXNAME`     | NC_MAX_NAME exceeded                                       |
!> | -54    | `NF_EUNLIMIT`     | NC_UNLIMITED size already in use                           |
!> | -55    | `NF_ENORECVARS`   | NC_rec op when there are no record vars                    |
!> | -56    | `NF_ECHAR`        | Attempt to convert between text & numbers                  |
!> | -57    | `NF_EEDGE`        | Edge+start exceeds dimension bound                         |
!> | -58    | `NF_ESTRIDE`      | Illegal stride                                             |
!> | -59    | `NF_EBADNAME`     | Attribute or variable name contains illegal characters     |
!> | -60    | `NF_ERANGE`       | Numeric conversion not representable                       |
!> | -61    | `NF_ENOMEM`       | Memory allocation (malloc) failure                         |
!> | -62    | `NF_EVARSIZE`     | One or more variable sizes violate format constraints      |
!> | -63    | `NF_EDIMSIZE`     | Invalid dimension size                                     |
!> | -64    | `NF_ETRUNC`       | File likely truncated or possibly corrupted                |
!> | -62〜-99 |                 | 将来の netCDF の拡張のための gtool5 の予約領域             |
!> @endja
!>
!> @subsection gtdata_error_codes Error codes for gtdata / gtool5 のデータ構造 (gtdata) に関するエラーコード
!>
!> @en
!> Use following error codes by referring this "dc_error" module.
!>
!> | Number | Mnemonic               | Error message                                              |
!> |--------|------------------------|------------------------------------------------------------|
!> | -100   | `GT_EFAKE`             | function not implemented                                   |
!> | -101   | `GT_ENOMOREDIMS`       | dimension number %d is out of range                        |
!> | -102   | `GT_EDIMNODIM`         | dimension variable has no dimension                        |
!> | -103   | `GT_EDIMMULTIDIM`      | dimension variable has many dimensions                     |
!> | -104   | `GT_EDIMOTHERDIM`      | dimension variable has another dimension                   |
!> | -105   | `GT_EBADDIMNAME`       | cause_c: unknown dimension name                            |
!> | -106   | `GT_ENOTVAR`           | variable not opened                                        |
!> | -107   | `GT_ENOMEM`            | allocate/deallocate error                                  |
!> | -108   | `GT_EOTHERFILE`        | specified dimensional variable not on the same file        |
!> | -109   | `GT_EARGSIZEMISMATCH`  | arguments (cause_c) array size mismatch                    |
!> | -110   | `GT_ENOMATCHDIM`       | dimension matching failed                                  |
!> | -111   | `GT_ELIMITED`          | variable already limited                                   |
!> | -112   | `GT_EBADVAR`           | variable type not supported                                |
!> | -113   | `GT_ECHARSHORT`        | character length not enough                                |
!> | -114   | `GT_ENOUNLIMITDIM`     | NC_UNLIMITED dimension is not found                        |
!> | -115   | `GT_EBADATTRNAME`      | invalid attribute name                                     |
!> | -116   | `GT_EBADHISTORY`       | invalid GT_HISTORY variable                                |
!> | -117   | `GT_EBADALLOCATESIZE`  | invalid allocated size                                     |
!> | -118   | `GT_ERANKMISMATCH`     | rank of data and argument is mismatch (cause_c)            |
!> | -119   | `GT_ENOTURL`           | URL (cause_c) is not found                                 |
!> | -120   | `GT_EBADGT4COMMAGRAPHY`| (cause_c) is not gtool4 comma-graphy                       |
!> | to -299|                        | Reserved area for future extensions of gtdata layer        |
!> @enden
!>
!> @ja
!> 以下のエラーコードに関しては dc_error モジュールを引用することで
!> 利用してください。
!>
!> | 数値   | ニーモニック           | エラーメッセージ                                           |
!> |--------|------------------------|------------------------------------------------------------|
!> | -100   | `GT_EFAKE`             | function not implemented                                   |
!> | -101   | `GT_ENOMOREDIMS`       | dimension number %d is out of range                        |
!> | -102   | `GT_EDIMNODIM`         | dimension variable has no dimension                        |
!> | -103   | `GT_EDIMMULTIDIM`      | dimension variable has many dimensions                     |
!> | -104   | `GT_EDIMOTHERDIM`      | dimension variable has another dimension                   |
!> | -105   | `GT_EBADDIMNAME`       | cause_c: unknown dimension name                            |
!> | -106   | `GT_ENOTVAR`           | variable not opened                                        |
!> | -107   | `GT_ENOMEM`            | allocate/deallocate error                                  |
!> | -108   | `GT_EOTHERFILE`        | specified dimensional variable not on the same file        |
!> | -109   | `GT_EARGSIZEMISMATCH`  | arguments (cause_c) array size mismatch                    |
!> | -110   | `GT_ENOMATCHDIM`       | dimension matching failed                                  |
!> | -111   | `GT_ELIMITED`          | variable already limited                                   |
!> | -112   | `GT_EBADVAR`           | variable type not supported                                |
!> | -113   | `GT_ECHARSHORT`        | character length not enough                                |
!> | -114   | `GT_ENOUNLIMITDIM`     | NC_UNLIMITED dimension is not found                        |
!> | -115   | `GT_EBADATTRNAME`      | invalid attribute name                                     |
!> | -116   | `GT_EBADHISTORY`       | invalid GT_HISTORY variable                                |
!> | -117   | `GT_EBADALLOCATESIZE`  | invalid allocated size                                     |
!> | -118   | `GT_ERANKMISMATCH`     | rank of data and argument is mismatch (cause_c)            |
!> | -119   | `GT_ENOTURL`           | URL (cause_c) is not found                                 |
!> | -120   | `GT_EBADGT4COMMAGRAPHY`| (cause_c) is not gtool4 comma-graphy                       |
!> | 〜-299 |                        | 将来の gtdata 層の拡張のための予約                         |
!> @endja
!>
!> @subsection grads_error_codes Error codes for GrADS data I/O / GrADS データ入出力に関するエラーコード
!>
!> @en
!> Use following error codes by referring this "dc_error" module.
!>
!> | Number | Mnemonic     | Error message      |
!> |--------|--------------|--------------------|
!> | -300   | `GR_ENOTGR`  | invalid GrADS file |
!> | to -399|              | Reserved area for future extensions of GrADS data I/O layer |
!> @enden
!>
!> @ja
!> 以下のエラーコードに関しては dc_error モジュールを引用することで
!> 利用してください。
!>
!> | 数値   | ニーモニック | エラーメッセージ   |
!> |--------|--------------|--------------------|
!> | -300   | `GR_ENOTGR`  | invalid GrADS file |
!> | 〜-399 |              | 将来の GrADS data 入出力層の拡張のための予約 |
!> @endja
!>
!> @subsection dc_error_codes Error codes for DC utilities / DC ユーティリティ用エラーコード
!>
!> @en
!> Use following error codes by referring this "dc_error" module.
!>
!> | Number | Mnemonic             | Error message                                              |
!> |--------|----------------------|------------------------------------------------------------|
!> | -400   | `DC_ENOTINIT`        | object (cause_c) is not initialized                        |
!> | -401   | `DC_EALREADYINIT`    | object (cause_c) is already initialized                    |
!> | -402   | `DC_EBADUNIT`        | unit (cause_c) is invalid                                  |
!> | -403   | `DC_EBADCALTYPE`     | calendar type (cause_i) is invalid                         |
!> | -404   | `DC_EBADTIMEZONE`    | time zone (cause_c) is invalid                             |
!> | -405   | `DC_EFILENAMEEMPTY`  | filename is empty                                          |
!> | -406   | `DC_EBADFILEOPMODE`  | file open mode (cause_c) is invalid                        |
!> | -407   | `DC_ENOUNITNUM`      | available unit number is not found within (cause_c)        |
!> | -408   | `DC_ENOFILEEXIST`    | file (cause_c) is not found                                |
!> | -409   | `DC_ENOFILEREAD`     | file (cause_c) is not readable                             |
!> | -410   | `DC_ENOFILEWRITE`    | file (cause_c) is not writable                             |
!> | -411   | `DC_ENEGATIVE`       | negative value is invalid for (cause_c)                    |
!> | -412   | `DC_EARGLACK`        | lack of arguments (cause_c)                                |
!> | -413   | `DC_ENOASSOC`        | argument (cause_c) is not associated                       |
!> | -414   | `DC_ENOENTRY`        | entry of (cause_c) is not found                            |
!> | -415   | `DC_ENODIMTIME`      | dimensional time can not be converted into nondimensional time |
!> | -416   | `DC_EDIMTIME`        | nondimensional time can not be converted into dimensional time |
!> | -417   | `DC_ETOOLARGETIME`   | number is too large for time                               |
!> | -418   | `DC_EBADDATE`        | invalid expression of date                                 |
!> | -419   | `DC_EINCONSISTCALDATE`| calendar and date are inconsistent                        |
!> | -420 to -499 |                | Reserved area for future extensions of DC utilities        |
!> @enden
!>
!> @ja
!> 以下のエラーコードに関しては dc_error モジュールを引用することで
!> 利用してください。
!>
!> | 数値   | ニーモニック         | エラーメッセージ                                           |
!> |--------|----------------------|------------------------------------------------------------|
!> | -400   | `DC_ENOTINIT`        | object (cause_c) is not initialized                        |
!> | -401   | `DC_EALREADYINIT`    | object (cause_c) is already initialized                    |
!> | -402   | `DC_EBADUNIT`        | unit (cause_c) is invalid                                  |
!> | -403   | `DC_EBADCALTYPE`     | calendar type (cause_i) is invalid                         |
!> | -404   | `DC_EBADTIMEZONE`    | time zone (cause_c) is invalid                             |
!> | -405   | `DC_EFILENAMEEMPTY`  | filename is empty                                          |
!> | -406   | `DC_EBADFILEOPMODE`  | file open mode (cause_c) is invalid                        |
!> | -407   | `DC_ENOUNITNUM`      | available unit number is not found within (cause_c)        |
!> | -408   | `DC_ENOFILEEXIST`    | file (cause_c) is not found                                |
!> | -409   | `DC_ENOFILEREAD`     | file (cause_c) is not readable                             |
!> | -410   | `DC_ENOFILEWRITE`    | file (cause_c) is not writable                             |
!> | -411   | `DC_ENEGATIVE`       | negative value is invalid for (cause_c)                    |
!> | -412   | `DC_EARGLACK`        | lack of arguments (cause_c)                                |
!> | -413   | `DC_ENOASSOC`        | argument (cause_c) is not associated                       |
!> | -414   | `DC_ENOENTRY`        | entry of (cause_c) is not found                            |
!> | -415   | `DC_ENODIMTIME`      | dimensional time can not be converted into nondimensional time |
!> | -416   | `DC_EDIMTIME`        | nondimensional time can not be converted into dimensional time |
!> | -417   | `DC_ETOOLARGETIME`   | number is too large for time                               |
!> | -418   | `DC_EBADDATE`        | invalid expression of date                                 |
!> | -419   | `DC_EINCONSISTCALDATE`| calendar and date are inconsistent                        |
!> | -420〜-499 |                  | 将来の DC ユーティリティの拡張のための予約                 |
!> @endja
!>
!> @subsection history_error_codes Error codes for data I/O layer / データ入出力層エラーコード
!>
!> @en
!> Use following error codes by referring this "dc_error" module.
!>
!> | Number | Mnemonic                | Error message                                              |
!> |--------|-------------------------|------------------------------------------------------------|
!> | -500   | `HST_ENOTINDEFINE`      | operation (cause_c) not allowed in data mode               |
!> | -501   | `HST_EINDEFINE`         | operation (cause_c) not allowed in define mode             |
!> | -502   | `HST_EINTFILE`          | different intervals are applied to a file (cause_c)        |
!> | -503   | `HST_EBADNAME`          | name (cause_c) is invalid                                  |
!> | -504   | `HST_ENOTTERMGTHIST`    | GT_HISTORY correspond to (cause_c) is not terminated       |
!> | -505   | `HST_ENODEPENDTIME`     | (cause_c) does not depend on time                          |
!> | -506   | `HST_EBADVARNAME`       | variable name (cause_c) is invalid                         |
!> | -507   | `HST_ENOTIMEDIM`        | time dimension is not found                                |
!> | -508   | `HST_ENOAXISNAME`       | axis or weight (cause_c) is not found                      |
!> | -509   | `HST_EVARINUSE`         | variable name (cause_c) is already used                    |
!> | -510   | `HST_EALREADYREGVARFIX` | already register of variables is fixed by (cause_c)        |
!> | -511   | `HST_EBADSLICE`         | slice options are invalid (cause_c)                        |
!> | -512   | `HST_EBADNEWFILEINT`    | invalid newfile interval (cause_c)                         |
!> | -513   | `HST_EMAXDIMSDEPENDED`  | variable (cause_c) depends on (cause_i) dimensions         |
!> | -514   | `HST_EINDIVISIBLE`      | (cause_c) can not be divided                               |
!> | -515   | `HST_EBADTERMINUS`      | terminus options are invalid (cause_c)                     |
!> | -516   | `HST_EBADORIGIN`        | origin options are invalid (cause_c)                       |
!> | -517   | `HST_EMPINOAXISDATA`    | data of axis (cause_c) for MPI is lack                     |
!> @enden
!>
!> @ja
!> 以下のエラーコードに関しては dc_error モジュールを引用することで
!> 利用してください。
!>
!> | 数値   | ニーモニック            | エラーメッセージ                                           |
!> |--------|-------------------------|------------------------------------------------------------|
!> | -500   | `HST_ENOTINDEFINE`      | operation (cause_c) not allowed in data mode               |
!> | -501   | `HST_EINDEFINE`         | operation (cause_c) not allowed in define mode             |
!> | -502   | `HST_EINTFILE`          | different intervals are applied to a file (cause_c)        |
!> | -503   | `HST_EBADNAME`          | name (cause_c) is invalid                                  |
!> | -504   | `HST_ENOTTERMGTHIST`    | GT_HISTORY correspond to (cause_c) is not terminated       |
!> | -505   | `HST_ENODEPENDTIME`     | (cause_c) does not depend on time                          |
!> | -506   | `HST_EBADVARNAME`       | variable name (cause_c) is invalid                         |
!> | -507   | `HST_ENOTIMEDIM`        | time dimension is not found                                |
!> | -508   | `HST_ENOAXISNAME`       | axis or weight (cause_c) is not found                      |
!> | -509   | `HST_EVARINUSE`         | variable name (cause_c) is already used                    |
!> | -510   | `HST_EALREADYREGVARFIX` | already register of variables is fixed by (cause_c)        |
!> | -511   | `HST_EBADSLICE`         | slice options are invalid (cause_c)                        |
!> | -512   | `HST_EBADNEWFILEINT`    | invalid newfile interval (cause_c)                         |
!> | -513   | `HST_EMAXDIMSDEPENDED`  | variable (cause_c) depends on (cause_i) dimensions         |
!> | -514   | `HST_EINDIVISIBLE`      | (cause_c) can not be divided                               |
!> | -515   | `HST_EBADTERMINUS`      | terminus options are invalid (cause_c)                     |
!> | -516   | `HST_EBADORIGIN`        | origin options are invalid (cause_c)                       |
!> | -517   | `HST_EMPINOAXISDATA`    | data of axis (cause_c) for MPI is lack                     |
!> @endja
!>
!> @subsection reserved_error_codes Reserved error codes / gtool5 の将来の拡張のために予約してあるエラーコード
!>
!> @en
!> Following error codes are reserved for future extensions.
!>
!> | Number      | Description                                        |
!> |-------------|----------------------------------------------------|
!> | -600 to -999| Reserved area for future extensions of gtool5      |
!> @enden
!>
!> @ja
!> 以下のエラーコードは今後の拡張も考えて予約してある部分です。
!>
!> | 数値        | 説明                                               |
!> |-------------|----------------------------------------------------|
!> | -600〜-999  | 将来の gtool5 の拡張のための予約                   |
!> @endja
!>
!> @subsection user_error_codes User-defined error codes / ユーザ定義用エラーコード
!>
!> @en
!> Error codes smaller than -1000 are saved for as user-defined error codes
!> used by upper programs.
!>
!> | Number   | Mnemonic     | Error message          |
!> |----------|--------------|------------------------|
!> | -1000 to | `USR_ERRNO`  | cause_c (cause_i)      |
!> @enden
!>
!> @ja
!> -1000 よりも小さいエラーコードは、
!> gtool5 の上位のプログラムが利用するエラーコードとして空けてあります。
!>
!> | 数値     | ニーモニック | エラーメッセージ       |
!> |----------|--------------|------------------------|
!> | -1000〜  | `USR_ERRNO`  | cause_c (cause_i)      |
!> @endja
!>
 
module dc_error
 
  use netcdf, only: nf90_enotvar, nf90_einval
  use dc_types, only: string
  implicit none
  private
  public :: nf90_enotvar, nf90_einval
 
  !> @en Error storage variables @enden
  !> @ja エラー等を保持 @endja
 
  !> @var DC_NOERR
  !> @en Non-error code (no error) @enden
  !> @ja 非エラーコード (エラーなし) @endja
  integer, public, parameter   :: dc_noerr  = 0
  integer, private, save       :: errno     = dc_noerr
                              !< @en Current error number @enden
                              !< @ja 現在のエラー番号 @endja
  integer, private, save       :: cause_int = dc_noerr
                              !< @en Integer cause value @enden
                              !< @ja 整数型原因値 @endja
  logical, private, save       :: cause_int_valid = .false.
                              !< @en Flag for integer cause validity @enden
                              !< @ja 整数型原因値の有効性フラグ @endja
  character(STRING), private, save :: cause_string = ""
                              !< @en String cause value @enden
                              !< @ja 文字列型原因値 @endja
  character(STRING), private, save :: cause_location = ""
                              !< @en Error location @enden
                              !< @ja エラー発生箇所 @endja
 
  !> @en
  !> Positive error numbers are reserved for libc system error messages.
  !> Due to high system dependency and very large values used,
  !> it is difficult to reserve empty space.
  !>
  !> Negative error numbers are used by netCDF. Allowing for some
  !> extensions, values up to -99 are not used.
  !> @enden
  !>
  !> @ja
  !> 正のエラー番号は libc システムエラーメッセージのために
  !> あけてある。システム依存性が大きく、非常に大きな数値も
  !> 用いられるので空き領域を確保するのは困難である。
  !>
  !> 負のエラー番号は netCDF が使っている。少々の拡張も見込んで、
  !> -99 までは使わないで置く。
  !> @endja
 
  integer, parameter, public:: gt_efake = -100
 
  !> @en -101 or less: Data structure errors @enden
  !> @ja -101 以下: データ構造のエラー @endja
  integer, parameter, public:: gt_enomoredims        = -101
  integer, parameter, public:: gt_edimnodim          = -102
  integer, parameter, public:: gt_edimmultidim       = -103
  integer, parameter, public:: gt_edimotherdim       = -104
  integer, parameter, public:: gt_ebaddimname        = -105
  integer, parameter, public:: gt_enotvar            = -106
  integer, parameter, public:: gt_enomem             = -107
  integer, parameter, public:: gt_eotherfile         = -108
  integer, parameter, public:: gt_eargsizemismatch   = -109
  integer, parameter, public:: gt_enomatchdim        = -110
  integer, parameter, public:: gt_elimited           = -111
  integer, parameter, public:: gt_ebadvar            = -112
  integer, parameter, public:: gt_echarshort         = -113
  integer, parameter, public:: gt_enounlimitdim      = -114
  integer, parameter, public:: gt_ebadattrname       = -115
  integer, parameter, public:: gt_ebadhistory        = -116
  integer, parameter, public:: gt_ebadallocatesize   = -117
  integer, parameter, public:: gt_erankmismatch      = -118
  integer, parameter, public:: gt_enoturl            = -119
  integer, parameter, public:: gt_ebadgt4commagraphy = -120
 
  !> @en -300 or less: GrADS I/O errors @enden
  !> @ja -300 以下: GrADS 入出力のエラー @endja
  integer, parameter, public:: gr_enotgr = -300
 
  !> @en -400 or less: DC utilities errors @enden
  !> @ja -400 以下: dc ユーティリティのエラー @endja
  integer, parameter, public:: dc_enotinit       = -400
  integer, parameter, public:: dc_ealreadyinit   = -401
  integer, parameter, public:: dc_ebadunit       = -402
  integer, parameter, public:: dc_ebadcaltype    = -403
  integer, parameter, public:: dc_ebadtimezone   = -404
  integer, parameter, public:: dc_efilenameempty = -405
  integer, parameter, public:: dc_ebadfileopmode = -406
  integer, parameter, public:: dc_enounitnum     = -407
  integer, parameter, public:: dc_enofileexist   = -408
  integer, parameter, public:: dc_enofileread    = -409
  integer, parameter, public:: dc_enofilewrite   = -410
  integer, parameter, public:: dc_enegative      = -411
  integer, parameter, public:: dc_earglack       = -412
  integer, parameter, public:: dc_enoassoc       = -413
  integer, parameter, public:: dc_enoentry       = -414
  integer, parameter, public:: dc_enodimtime     = -415
  integer, parameter, public:: dc_edimtime       = -416
  integer, parameter, public:: dc_etoolargetime  = -417
  integer, parameter, public:: dc_ebaddate       = -418
  integer, parameter, public:: dc_einconsistcaldate = -419
 
  !> @en -500 or less: Data I/O layer errors @enden
  !> @ja -500 以下: データ入出力層のエラー @endja
  integer, parameter, public:: hst_enotindefine      = -500
  integer, parameter, public:: hst_eindefine         = -501
  integer, parameter, public:: hst_eintfile          = -502
  integer, parameter, public:: hst_ebadname          = -503
  integer, parameter, public:: hst_enottermgthist    = -504
  integer, parameter, public:: hst_enodependtime     = -505
  integer, parameter, public:: hst_ebadvarname       = -506
  integer, parameter, public:: hst_enotimedim        = -507
  integer, parameter, public:: hst_enoaxisname       = -508
  integer, parameter, public:: hst_evarinuse         = -509
  integer, parameter, public:: hst_ealreadyregvarfix = -510
  integer, parameter, public:: hst_ebadslice         = -511
  integer, parameter, public:: hst_ebadnewfileint    = -512
  integer, parameter, public:: hst_emaxdimsdepended  = -513
  integer, parameter, public:: hst_eindivisible      = -514
  integer, parameter, public:: hst_ebadterminus      = -515
  integer, parameter, public:: hst_ebadorigin        = -516
  integer, parameter, public:: hst_empinoaxisdata    = -517
 
 
  !> @en -1000 or less: User-defined errors @enden
  !> @ja -1000 以下: ユーザー定義 @endja
  integer, parameter, public:: usr_errno = -1000
 
  public:: storeerror, dumperror, geterrormessage, errorcode
 
  !> @en
  !> Procedure reference specification.
  !> Made as an external function to be replaceable in the future.
  !> @enden
  !> @ja
  !> 手続引用仕様.
  !> いずれ差し替えられるように外部関数にしておく。
  !> @endja
  interface
    subroutine dumperror()
    end subroutine dumperror
  end interface
 
contains
 
  !> @en
  !> @brief Return an error code specified currently.
  !> @return Integer error code currently set
  !> @enden
  !> @ja
  !> @brief 現在設定されているエラーコードを返します。
  !> @return 現在設定されている整数型エラーコード
  !> @endja
  integer function errorcode() result(result)
    result = errno
  end function errorcode
 
  !> @en
  !> @brief Return messages corresponding to an error code specified currently.
  !> @param[out] msg Error message string corresponding to the current error code
  !> @enden
  !> @ja
  !> @brief 現在設定されているエラーコードから対応するメッセージを返します。
  !> @param[out] msg 現在のエラーコードに対応するエラーメッセージ文字列
  !> @endja
  subroutine geterrormessage(msg)
    use netcdf, only: nf90_strerror
    character(len = *), intent(out):: msg
    character(len = STRING):: message
    character(len = 20):: errno_c
    character(len = 20):: cause_int_c
  continue
    select case(errno)
    case(gt_efake)
      msg = ' function not implemented'
      !
      ! -101 以下: データ構造のエラー
      ! -101 or less: Error of data structure
      !
    case(gt_enomoredims)
      write(message, "(': dimension number', i4, ' is out of range')") cause_int
      msg = trim(message)
    case(gt_ebaddimname)
      msg = '(' // trim(cause_string) // '): unknown dimension name'
    case(gt_enotvar)
      msg = ' variable not opened'
    case(gt_enomem)
      msg = ' allocate/deallocate error'
    case(gt_edimnodim)
      msg = ' dimension variable has no dimension'
    case(gt_edimmultidim)
      msg = ' dimension variable has many dimensions'
    case(gt_edimotherdim)
      msg = ' dimension variable has another dimension'
    case(gt_eotherfile)
      msg = ' specified dimensional variable not on the same file'
    case(gt_eargsizemismatch)
      msg = ' arguments (' // trim(cause_string) //') array size mismatch'
    case(gt_enomatchdim)
      msg = ' dimension matching failed'
    case(gt_elimited)
      msg = ' variable already limited'
    case(gt_ebadvar)
      msg = ' variable type not supported'
    case(gt_echarshort)
      msg = ' character length not enough'
    case(gt_enounlimitdim)
      msg = ' NC_UNLIMITED dimension is not found'
    case(gt_ebadattrname)
      msg = ' invalid attribute name'
    case(gt_ebadallocatesize)
      msg = ' invalid allocated size'
    case(gt_erankmismatch)
      msg = ' rank of data and argument are mismatch (' // trim(cause_string) // ')'
    case(gt_enoturl)
      msg = ' URL (' // trim(cause_string) // ') is not found'
    case(gt_ebadgt4commagraphy)
      msg = ' (' // trim(cause_string) // ') is not gtool4 comma-graphy (ex. "time=100.0,x=10:20,y=^1:^5")'
      !
      ! -300 以下: GrADS 入出力のエラー
      ! -300 or less: Error of GrADS I/O
      !
    case(gr_enotgr)
      msg = ' invalid GrADS file'
      !
      ! -400 以下: DC ユーティリティのエラー
      ! -400 or less: Error of DC utilities
      !
    case(dc_enotinit)
      msg = ' object (' // trim(cause_string) // ') is not initialized'
    case(dc_ealreadyinit)
      msg = ' object (' // trim(cause_string) // ') is already initialized'
    case(dc_ebadunit)
      msg = ' unit (' // trim(cause_string) // ') is invalid'
    case(dc_ebadcaltype)
      write(message, '(" calendar type (", i4, ") is invalid")') cause_int
      msg = trim(message)
    case(dc_ebadtimezone)
      msg = ' time zone (' // trim(cause_string) // ') is invalid'
    case(dc_efilenameempty)
      msg = ' filename is empty'
    case(dc_ebadfileopmode)
      msg = ' file open mode (' // trim(cause_string) // ') is invalid'
    case(dc_enounitnum)
      msg = ' available unit number is not found within (' // trim(cause_string) // ')'
    case(dc_enofileexist)
      msg = ' file (' // trim(cause_string) // ') is not found'
    case(dc_enofileread)
      msg = ' file (' // trim(cause_string) // ') is not readable'
    case(dc_enofilewrite)
      msg = ' file (' // trim(cause_string) // ') is not writable'
    case(dc_enegative)
      msg = ' negative value is invalid for (' // trim(cause_string) // ')'
    case(dc_earglack)
      msg = ' lack of arguments (' // trim(cause_string) // ')'
    case(dc_enoassoc)
      msg = ' argument (' // trim(cause_string) // ') is not associated'
    case(dc_enoentry)
      msg = ' entry of (' // trim(cause_string) // ') is not found'
    case(dc_enodimtime)
      msg = ' dimensional time can not be converted into nondimensional time'
    case(dc_edimtime)
      msg = ' nondimensional time can not be converted into dimensional time'
    case(dc_etoolargetime)
      msg = ' number is too large for time'
    case(dc_ebaddate)
      msg = ' invalid expression of date'
    case(dc_einconsistcaldate)
      msg = ' calendar and date are inconsistent'
      !
      ! -500 以下: データ入出力層のエラー
      ! -500 or less: Error of data I/O layer
      !
    case(hst_enotindefine)
      msg = ' operation (' // trim(cause_string) // ') not allowed in data mode'
    case(hst_eindefine)
      msg = ' operation (' // trim(cause_string) // ') not allowed in define mode'
    case(hst_eintfile)
      msg = ' different intervals are applied to a file (' // trim(cause_string) // ')'
    case(hst_ebadname)
      msg = ' name (' // trim(cause_string) // ') is invalid'
    case(hst_enottermgthist)
      msg = ' GT_HISTORY correspond to (' // trim(cause_string) // ') is not terminated'
    case(hst_enodependtime)
      msg = ' (' // trim(cause_string) // ') does not depend on time'
    case(hst_ebadvarname)
      msg = ' variable name (' // trim(cause_string) // ') is invalid'
    case(hst_enotimedim)
      msg = ' time dimension is not found'
    case(hst_enoaxisname)
      msg = ' axis or weight (' // trim(cause_string) // ') is not found'
    case(hst_evarinuse)
      msg = ' variable name (' // trim(cause_string) // ') is already used'
    case(hst_ealreadyregvarfix)
      msg = ' already register of variables is fixed by (' // trim(cause_string) // ')'
    case(hst_ebadslice)
      msg = ' slice options are invalid (' // trim(cause_string) // ')'
    case(hst_ebadnewfileint)
      msg = ' invalid newfile interval (' // trim(cause_string) // ')'
    case(hst_emaxdimsdepended)
      write(message, '("(", i4, ")")') cause_int
      msg = trim(message)
      msg = ' variable (' // trim(cause_string) // ') depends on ' // trim(message) // ' dimensions'
    case(hst_eindivisible)
      msg = ' (' // trim(cause_string) // ') can not be divided'
    case(hst_ebadterminus)
      msg = ' terminus options are invalid (' // trim(cause_string) // ')'
    case(hst_ebadorigin)
      msg = ' origin options are invalid (' // trim(cause_string) // ')'
    case(hst_empinoaxisdata)
      msg = ' data of axis (' // trim(cause_string) // ') for MPI is lack'
 
      !
      !
      ! -1000 以下: ユーザー定義
      ! -1000 or less: User-defined error
      !
    case(:usr_errno)
      if (len(trim(adjustl(cause_string))) < 1) then
        cause_string = 'Unknown error'
      end if
      if (cause_int_valid) then
        write(cause_int_c, "(i8)") cause_int
        msg = trim(cause_string) // ' (' // trim(adjustl(cause_int_c)) // ')'
      else
        msg = trim(cause_string)
      end if
    case default
      goto 999
    end select
    write(errno_c, "(i8)") errno
    msg =  '*** ERROR (Code ' // trim(adjustl(errno_c))  // &
      & ') [' // trim(cause_location) // '] ***  ' // &
      & trim(msg)
    return
 
999 continue
    if (len(cause_string) > 0) then
      message = nf90_strerror(errno)
      write(errno_c, "(i8)") errno
      msg =  '*** ERROR (Code ' // trim(adjustl(errno_c)) // &
        & ') [' // trim(cause_location)             // &
        & '('   // trim(cause_string) // ')] ***  ' // &
        & trim(message)
    else if (cause_int_valid) then
      message = nf90_strerror(errno)
      write(errno_c, "(i8)") errno
      write(cause_int_c, "(i8)") cause_int
      msg =  '*** ERROR (Code ' // trim(adjustl(errno_c)) // &
        & ') [' // trim(cause_location)             // &
        & '('   // trim(adjustl(cause_int_c)) // ')] ***  ' // &
        & trim(message)
    else
      message = nf90_strerror(errno)
      write(errno_c, "(i8)") errno
      msg =  '*** ERROR (Code ' // trim(adjustl(errno_c))  // &
        & ') [' // trim(cause_location) // '] ***  ' // &
        & trim(message)
    endif
  end subroutine geterrormessage
 
  !> @en
  !> @brief Error handling subroutine for typical procedures of library
  !> @details
  !> Number of necessary arguments is two. Give integer error code
  !> to first argument `number`, and procedure name where the error
  !> occurs to second argument `where`. By default, like a following
  !> string is displayed to standard output, and the program aborts.
  !> Error message is determined by error code automatically.
  !> See error code list.
  !>
  !>     *** ERROR (Code number) [where] ***  error_message
  !>
  !>     *** ERROR (Code number) [where(cause_c)] ***  error_message
  !>
  !> In addition, for usage that users call StoreError as an error
  !> handling tool from the outside of gtool5 library,
  !> error codes smaller than `USR_ERRNO` is saved.
  !> When error codes smaller than `USR_ERRNO` is given,
  !> StoreError displays like a following string to standard output,
  !> and stops the program.
  !> `dc_message` module is prepared too. This module can be used
  !> more easily for message output and rise of error.
  !>
  !>     *** ERROR (Code number) [where] ***  cause_c
  !>
  !>     *** ERROR (Code number) [where] ***  cause_c (cause_i)
  !>
  !> @param[in] number Error code
  !> @param[in] where Place where error occurs
  !> @param[out] err Exception handling flag. By default, when error code
  !>                 (excluding non error code) is given to `number`,
  !>                 the program display error message and aborts.
  !>                 If this `err` argument is given, `.true.` is substituted
  !>                 to `err` and the program does not abort.
  !> @param[in] cause_c Character message
  !> @param[in] cause_i Integer message
  !> @enden
  !>
  !> @ja
  !> @brief 典型的ライブラリ手続のために作られたエラー処理サブルーチン
  !> @details
  !> 必要な引数は2つであり、第1引数 `number` には整数型のエラーコード、
  !> 第2引数 `where` には文字型でエラーの発生した手続名を与えます。
  !> デフォルトでは以下の形式の文字列が標準出力に表示されてプログラム
  !> は終了します。 エラーメッセージ error_message
  !> はエラーコードから自動的に決まります。
  !> 対応表がエラーコード一覧にあるので参照してください。
  !>
  !>     *** ERROR (Code number) [where] ***  error_message
  !>
  !>     *** ERROR (Code number) [where(cause_c)] ***  error_message
  !>
  !> なお、gtool5 のライブラリ外からユーザがエラー処理用ツール
  !> として StoreError を用いることを想定し、`USR_ERRNO`
  !> 番より小さいエラーコードは空けてあります。`USR_ERRNO`
  !> より小さい値をエラーコードに与えると,
  !> StoreError は以下の形式の文字列を標準出力に出力してプログラムを
  !> 終了させます。より安易に使えるメッセージ出力およびエラー発生の
  !> ためのモジュールとして `dc_message` も用意してあるので
  !> そちらも参照してください。
  !>
  !>     *** ERROR (Code number) [where] ***  cause_c
  !>
  !>     *** ERROR (Code number) [where] ***  cause_c (cause_i)
  !>
  !> @param[in] number エラーコード
  !> @param[in] where エラー発生個所
  !> @param[out] err 例外処理用フラグ。デフォルトでは、`number` に非エラーコード
  !>                 以外の値が与えられた場合、エラーメッセージを
  !>                 表示してプログラムは強制終了します。
  !>                 引数 `err` が与えられる場合、
  !>                 プログラムは強制終了せず、代わりに
  !>                 `err` に `.true.` が代入されます。
  !> @param[in] cause_c 文字型メッセージ
  !> @param[in] cause_i 整数型メッセージ
  !> @endja
  subroutine storeerror(number, where, err, cause_c, cause_i)
    integer,            intent(in)            :: number
    character(len = *), intent(in)            :: where
    logical,            intent(out), optional :: err
    character(len = *), intent(in),  optional :: cause_c
    integer,            intent(in),  optional :: cause_i
  continue
    if (present(err)) then
      err = (number /= dc_noerr)
      return
    endif
    if (number == dc_noerr) return
    errno = number
    cause_location = where
    if (present(cause_c)) then
      cause_string = trim(cause_c)
    else
      cause_string = ""
    endif
    if (present(cause_i)) then
      cause_int = cause_i
      cause_int_valid = .true.
    else
      cause_int_valid = .false.
    end if
    call dumperror
  end subroutine storeerror
 
  !> @namespace dc_error
end module dc_error
 
!> @en
!> @brief Get error messages from "GetErrorMessage", and put the messages
!>        to sysdep#AbortProgram, and stop the program.
!> @enden
!> @ja
!> @brief GetErrorMessage からエラーメッセージを取得後、
!>        それを sysdep#AbortProgram に渡してプログラムを終了させます。
!> @endja
subroutine dumperror()
  use dc_types, only: string
  use dc_error, only: geterrormessage
  use sysdep, only: abortprogram
  character(len = STRING):: message
continue
  call geterrormessage(message)
  call abortprogram(message)
end subroutine dumperror