$Date: 2003/03/07 07:07:23 $
TOYODA Eizi <URL:mailto:toyoda@npd.kishou.go.jp> Numerical Prediction Division, Japan Meteorological Agency
This document describes the C and Fortran interfaces of the NuSDaS (Numerical Prediction Standard Dataset System).
Within JMA, NuSDaS interface is available in two versions: operational and pnusdas ones. Although the former is official and mandatory in the operational suites, the latter version may be useful in some cases.
This version is not supported outside of NAPS/JMA.
Source code is located in /grpK/nwp/Open/Tools/Nusdas
or
equivalent directories.
Makefiles of models are designed to refer these files if necessary.
Users refer the source code directly when building applications.
'Pnusdas' is portable version of NuSDaS.
The source code is slightly different from the operational one,
mainly for portability to little-endian computers.
The source code is provided in a package pnusdas.tar
.
Users have to untar it, configure, and make like many UNIX tools:
tar xvf pnusdas.tar cd pnusdas sh configure make
and you will have libnusdas.a
.
File INSTALL or configure's message may be helpful.
Programs/functions/subroutines calling NuSDaS interface should include header file like following:
/* C */ #include "nusdas.h" ! Fortran INCLUDE 'nusdas_fort.h'
Note that INCLUDE in Fortran should be written in all subroutine/functions calling NuSDaS, not once per file like C.
typedef
-ed name
in "nusdas.h"
.
It means 32bit signed integer type, and is equivalent to
int
in most environments.CHARACTER(
n)
must have at least n characters length.const char *
must have at least the same size to
corresponding Fortran interface.
Character array have not to be terminated with NUL ('\0') character.In NuSDaS, data is identified by following dimensions: data type, base time, member name, valid time, plane name, element name.
Data type is 16-character string composed from type1, type2, and type3.
Type1 is 8-character string. The first 4 characters are model name. Following 2 characters are horizontal grid name. The last 2 characters are vertical grid name. (See tables for predefined name).
Type2 is 4-character string. The first 2 characters are data attribute name. The last 2 characters are time attribute name. (See tables for predefined name).
Type3 is 4-character string.
You can use arbitrary name for this field;
it does not affect behavior of library nor conventional meaning.
Name "STD1"
is used for the most typical operational dataset.
Base time is also known as reference time. The initial time is used for forecast data. It is expressed as a number of minutes counted from 00:00GMT January 1, 1801 *1. Typically, return value of NWP_GETTIME() is used.
Member is 4-character string representing member of ensemble forecast.
Name " "
(four spaces) is used for non-ensemble data.
Note that this field must have at least 4 characters,
and space character should be filled if conventional name is shorter.
For example, the control run of ensemble is called '00' in JMA,
and it is represented as "00 "
(double digit zero, followed by two spaces)
in NuSDaS.
Do not use "00"
(double digit zero, followed by NUL terminator)
even in C interface.
Valid time is a time or period to which the requested data
is most closely related.
It is expressed as a pair of integers, interpreted as
beginning and ending of the period.
If the requested data corresponds to one time moment,
the end of time span is expressed as special value -1
.
Note that the value is in absolute date,
not relative time from base time or any other date.
Plane name identifies plane/layer to which the requested data belongs. In most cases, it is vertical height. Plane name is a pair of six-character string. They are upper and lower boundary of layer and two plane names. Data for a plane is identified by a pair of two same plane names. For example, "SURF " represents surface, and "500 " denotes 500hPa level. Meaning of numbers is dependent to the vertical coordinate of the dataset shown in type1. Note that these fields must have at least 6 characters.
Physical element name. Standard names are shown in table. Note that this field must have at least 6 characters.
In NuSDaS interface functions/subroutines, they are specified with the first 3-10 arguments. They looks like
/* C */ int nusdas_xxx(type1, type2, type3, btime, memb, vtime1, plane1, elem, ...) int nusdas_xxx2(type1, type2, type3, btime, memb, vtime1, vtime2, plane1, plane2, elem, ...) ! Fortran SUBROUTINE NUSDAS_XXX(type1, type2, type3, btime, memb, vtime1, plane1, elem, ...) SUBROUTINE NUSDAS_XXX2(type1, type2, type3, btime, memb, vtime1, vtime2, plane1, plane2, elem, ...)
symbol | Fortran type | C type | description |
type1 | CHARACTER(8) | const char [8] | data type, 1st component |
type2 | CHARACTER(4) | const char [4] | data type, 2nd component |
type3 | CHARACTER(4) | const char [4] | data type, 3rd component |
btime | INTEGER | N_SI4 * | base time |
memb | CHARACTER(4) | const char [4] | member name |
vtime1 | INTEGER | N_SI4 * | valid time, start |
vtime2 | INTEGER | N_SI4 * | valid time, end |
plane1 | CHARACTER(6) | const char [6] | plane name, upper |
plane2 | CHARACTER(6) | const char [6] | plane name, lower |
elem | CHARACTER(6) | const char [6] | element name |
Some subroutines/functions have two forms: name of one ends with '2',
and the other without '2'.
In such a case, the with-2-form is the essential interface.
Calling the latter, the no-2-form, is equivalent to
that of the with-2-form with vtime2 and plane2 set to
-1
and plane1 respectively.
Reads a two-dimensional array from NuSDaS dataset.
/* C */ int nusdas_read(type1, type2, type3, btime, memb, vtime1, plane1, elem, udata, utype, usize) int nusdas_read2(type1, type2, type3, btime, memb, vtime1, vtime2, plane1, plane2, elem, udata, utype, usize) ! Fortran SUBROUTINE NUSDAS_READ(type1, type2, type3, btime, memb, vtime1, & plane1, elem, udata, utype, usize, iostat) SUBROUTINE NUSDAS_READ2(type1, type2, type3, btime, memb, vtime1, vtime2, & plane1, plane2, elem, udata, utype, usize, iostat)
symbol | Fortran | C |
type1 ... elem | (see table above) | |
udata | (may be various type) | void * |
utype | (should be constant in header) | (should be macro in header) |
iostat | INTEGER, INTENT(OUT) | (not used) |
From type1 to elem, see section 'Terminology for Data Identifier'.
udata
user data array, to which the requested data will be copied.
utype
see table of User Data Array Type.
usize
number of array elements allocated user data. It must equal to or be larger than that of dataset.
iostat
same meaning as return value in C interface.
> 0 | Succeeded. The value is number of array elements obtained. |
0 | Warning: requested data is not written yet. |
-1 | Warning: file containing requested data does not exists. |
-2 | Warning: requested data is not registered yet. |
-3 | Error: inconsistency between CNTL and DATA records. |
-4 | Error: insufficient size of user array. |
-5 | Error: conversion to specified data type is not supported. |
-6 | Error: malformed run-length encoded data. |
-7 | Error: malformed CNTL or INDX record. |
-10 to -99 | (see error code table) |
NUSDAS_READ and NUSDAS_READ2 reads a data record to user data array udata. If you are going to read data in a layer or timespan, use NUSDAS_READ2.
Writes a two-dimensional array into NuSDaS dataset.
/* C */ int nusdas_write(type1, type2, type3, btime, memb, vtime1, plane1, elem, udata, utype, usize) int nusdas_write2(type1, type2, type3, btime, memb, vtime1, vtime2, plane1, plane2, elem, udata, utype, usize) ! Fortran SUBROUTINE NUSDAS_WRITE(type1, type2, type3, btime, memb, vtime1, & plane1, elem, udata, utype, usize, iostat) SUBROUTINE NUSDAS_WRITE2(type1, type2, type3, btime, memb, vtime1, vtime2, & plane1, plane2, elem, udata, utype, usize, iostat)
symbol | Fortran | C |
type1 ... elem | (see table above) | |
udata | (may be various type) INTENT(OUT) | void * |
utype | (should be constant in header) | (should be macro in header) |
iostat | INTEGER, INTENT(OUT) | (not used) |
From type1 to elem, see section 'Terminology for Data Identifier'.
udata
user data array, from which the requested data will be copied.
utype
see table of User Data Array Type.
usize
number of array elements allocated user data. It must equal to than that of dataset.
iostat
see following section, RETURN VALUE.
> 0 | Succeeded. The value is number of array elements written. |
-2 | Warning: requested data is not registered yet. |
-3 | Error: size of user data array is too small. |
-4 | Error: conversion to specified data type is not supported. |
-5 | Error: data record size exceeds fixed record size. |
-6 | Error: invalid missing value style. |
-7 | Error: mask bit pattern undefined. |
-8 | Error: overflow in packing. |
-9 | Error: invalid compression scheme. |
-10 to -99 | (see error code table) |
NUSDAS_WRITE and NUSDAS_WRITE2 writes a data record from user data array udata. If you are going to write data in a layer or timespan, use NUSDAS_WRITE2.
flushes write buffer to ES files and close it.
/* C */ int nusdas_esf_flush(type1, type2, type3, btime, memb, vtime1); int nusdas_esf_flush2(type1, type2, type3, btime, memb, vtime1, vtime2); ! Fortran SUBROUTINE NUSDAS_ESF_FLUSH(type1, type2, type3, btime, memb, vtime1, iostat) SUBROUTINE NUSDAS_ESF_FLUSH2(type1, type2, type3, btime, memb, vtime1, vtime2, iostat)
symbol | Fortran | C |
type1 ... vtime2 | (see table above) | |
iostat | INTEGER, INTENT(OUT) | (not used) |
From type1 to vtime2, see section 'Terminology for Data Identifier'.
iostat
see following section, RETURN VALUE.
closes a data file.
/* C */ int nusdas_onefile_close(type1, type2, type3, btime, memb, vtime1) int nusdas_onefile_close2(type1, type2, type3, btime, memb, vtime1, vtime2) ! Fortran SUBROUTINE NUSDAS_ONEFILE_CLOSE(type1, type2, type3, btime, memb, vtime1, & iostat) SUBROUTINE NUSDAS_ONEFILE_CLOSE2(type1, type2, type3, btime, memb, vtime1, & vtime2, iostat)
symbol | Fortran | C |
type1 ... vtime2 | (see table above) | |
iostat | INTEGER, INTENT(OUT) | (not used) |
From type1 to vtime2, see section 'Terminology for Data Identifier'.
iostat
see following section, RETURN VALUE.
1 | Specified file is not opened. |
0 | Succeeded. |
-2 | Warning: requested data is not registered yet. |
-3 | Error: inconsistency between CNTL and DATA records. |
-4 | Error: array size too large. |
-5 | Error: array type mismatch. |
-6 | Error: too large value in RLE compression. |
-7 | Error: malformed CNTL or INDX record. |
-10 to -99 | (see error code table) |
NUSDAS_ONEFILE_CLOSE closes one data file specified
with type1 ... valid2.
It should be called before the end of the calling program
which have called NUSDAS_WRITE() series
and have cleared N_IO_W_FCLOSE
flag using NUSDAS_IOCNTL().
/* C */ int nusdas_allfile_close(closemode) ! Fortran SUBROUTINE NUSDAS_ALLFILE_CLOSE(closemode, iostat)
symbol | Fortran | C |
closemode | (should be symbol in header) | (should be macro in header) |
iostat | INTEGER, INTENT(OUT) | (not used) |
closemode
One of following symbols defined in header file:
all files opened as read-only are closed.
all files opened as writable are closed.
all files are closed.
iostat
see following section, RETURN VALUE.
> 0 | Succeeded. The value is number of files successfully closed. |
< 0 | Error: the absolute value is number of files that cause error. |
/* C */ int nusdas_iocntl(param, value) ! Fortran SUBROUTINE NUSDAS_IOCNTL(param, value, iostat)
symbol | Fortran | C |
param | (should be symbol in header) | (should be macro in header) |
value | (should be symbol in header) | (should be macro in header) |
iostat | INTEGER, INTENT(OUT) | (not used) |
param
Should be one of following symbols defined in header file.
If value is N_ON
, the END record is written to data file
for each call of NUSDAS_WRITE() functions.
That is the default; it is safer, but slower.
If value is N_OFF
, the END record is written
only when the data file is closed.
Though it makes NUSDAS_WRITE() faster, files may be corrupt and
unreadable if writing program exits without closing the file.
Note that N_ON
is assumed when parameter N_IO_W_FCLOSE()
is set to N_ON
.
If value is N_ON
, data file opened for write is closed
for each call of NUSDAS_WRITE() functions.
That is the default; it is safer, but slower.
If value is N_OFF
, such data files will be closed
only when either NUSDAS_ONEFILE_CLOSE() or
NUSDAS_ALLFILE_CLOSE() is called explicitly.
Though it makes NUSDAS_WRITE() faster, files may be corrupt and
unreadable if writing program exits without closing the file.
And you will also have to care about shortage of file handle resource:
if too many files are opened simultaneously, further open may fail.
If value is N_ON
, data file opened for read is closed
for each call of NUSDAS_WRITE() functions.
That is the default; it is safer, but slower.
If value is N_OFF
, such data files will be closed
only when either NUSDAS_ONEFILE_CLOSE() or
NUSDAS_ALLFILE_CLOSE() is called explicitly.
You will have to care about shortage of file handle resource.
If value is N_ON
, subroutines in the NuSDaS interface
output messages on waring/error to the standard error handle.
That is the default.
If value is N_OFF
, such messages are suppressed.
value
Should be N_ON
or N_OFF
defined in header file.
iostat
see following section, RETURN VALUE.
0 | Succeeded. |
-1 | Error: invalid argument. |
/* C */ int nusdas_parameter_change(param, value) ! Fortran SUBROUTINE NUSDAS_PARAMETER_CHANGE(param, value, iostat)
symbol | Fortran | C |
param | (should be constant/macro in header) | |
value | (see description of param) | void * |
iostat | INTEGER, INTENT(OUT) | (not used) |
param
specifies what parameter to change. It should be one of them:
missing value when user data array is char
.
value should be (pointer to) the same type.
The default value is UCHAR_MAX.
missing value when user data array is short integer (INTEGER*2). value should be (pointer to) the same type. The default value is SHRT_MIN.
missing value when user data array is integer. value should be (pointer to) the same type. The default value is LONG_MIN.
missing value when user data array is float. value should be (pointer to) the same type. The default value is FLT_MAX.
missing value when user data array is double. The default value is DBL_MAX. value should be (pointer to) the same type.
bitmap for missing grid points. value should be created as bitmap of NUSDAS_MAKE_MASK(). Default value for the parameter is meaningless, since writing without initializing bitmap fails (if bitmap required), or otherwise simply ignored.
NRD number to/from which further access is done. This is useful in switching among many NRD's providing same data type. N_OFF is the default.
packing scheme. See table Packing Type for acceptable values. N_OFF is the default.
grid size in X direction. N_OFF is the default.
grid size in Y direction. N_OFF is the default.
Note that all parameters have global effect:
once some parameter is changed,
the effect remains until the end of calling process,
even when different data type is accessed.
Take care of yourself, especially on changing
N_PC_PACKING
, N_PC_SIZEX
, and N_PC_SIZEY
.
value
Value to be set as parameter.
If NULL
is given,
it is equivalent to the default value.
If you are using Fortran interface, be careful to tricky
implementation of NULL
in nusdas_fort.h
due to
consideration to only-Fortran-90 compilers.
It will conflict with built-in function NULL()
of Fortran 95
standard; subroutines using NuSDaS interface is unable to
use NULL()
.
creates data-presence bitmap from data array.
/* C */ int nusdas_make_mask(udata, utype, usize, bitmap, bitmapsize) ! Fortran SUBROUTINE NUSDAS_MAKE_MASK(udata, utype, usize, bitmap, bitmapsize, iostat)
symbol | Fortran | C |
udata | (may be various type) | void * |
utype | (should be constant/macro in header) | |
usize | INTEGER | N_SI4 * |
bitmap | CHARACTER, DIMENSION(*), INTENT(OUT) | char * |
bitmapsize | INTEGER | N_SI4 * |
iostat | INTEGER, INTENT(OUT) | (not used) |
udata
user data array from which the bitmap is created.
Array elements where data is missing should be set to
the missing value for the User Data Array Type.
For example, elements equivalent to N_MV_R4
are regarded as
missing if udata is REAL/float array.
utype
see table of User Data Array Type.
usize
number of array elements allocated user data.
bitmap
character array to which the bitmap will be stored.
bitmapsize
size of bitmap in bytes.
iostat
same meaning as return value in C interface.
0 | Succeeded. |
-1 | Error: bitmap size too little |
defines the default content of SUBC records for eta and sigma coordinates.
/* C */ int nusdas_subc_preset1(type1, type2, type3, subcgroup, nlev, a, b, c) ! Fortran SUBROUTINE NUSDAS_SUBC_PRESET1(type1, type2, type3, subcgroup, nlev, & a, b, c, iostat)
symbol | Fortran | C |
subcgroup | CHARACTER(4) | char [4] |
nlev | INTEGER | N_SI4 * |
a | REAL, DIMENSION(nlev) | float * |
b | REAL, DIMENSION(nlev) | float * |
c | REAL, DIMENSION(nlev) | float * |
iostat | INTEGER, INTENT(OUT) | (not used) |
subcgroup
must be "SIGM" or "ETA "
nlev
number of levels
a
b
c
vertical coordinate parameters
0 | Succeded |
-1 | invalid subcgroup value |
-2 | Too many SUBC records written. |
-10 to -99 | (see error code table) |
/* C */ int nusdas_subc_sigm(type1, type2, type3, btime, memb, vtime1, nlev, a, b, c, io) int nusdas_subc_sigm2(type1, type2, type3, btime, memb, vtime1, vtime2, nlev, a, b, c, io) ! Fortran SUBROUTINE NUSDAS_SUBC_SIGM(type1, type2, type3, btime, memb, vtime1, & nlev, a, b, c, io, iostat) SUBROUTINE NUSDAS_SUBC_SIGM2(type1, type2, type3, btime, memb, vtime1, & vtime2, nlev, a, b, c, io, iostat)
symbol | Fortran | C |
nlev | INTEGER | N_SI4 * |
a | REAL, DIMENSION(nlev) | float * |
b | REAL, DIMENSION(nlev) | float * |
c | REAL, DIMENSION(nlev) | float * |
io | (should be symbol/macro defined in header file) | |
iostat | INTEGER, INTENT(OUT) | (not used) |
nlev
number of levels
a
b
c
vertical coordinate parameters
io
one of following symbols
writes SUBC record made from a, b, and c
reads SUBC record to a, b, and c
0 | Succeeded. |
-1 | Error: requested file not exist. |
-2 | Error: requested record not exist. |
-3 | Error: specified size is different to that of definition file. |
-4 | Error: specified number of level is smaller than that in file. |
-5 | Error: invalid argument. |
-10 to -99 | (see error code table) |
/* C */ int nusdas_subc_eta(type1, type2, type3, btime, memb, vtime1, nlev, a, b, c, io) int nusdas_subc_eta2(type1, type2, type3, btime, memb, vtime1, vtime2, nlev, a, b, c, io) ! Fortran SUBROUTINE NUSDAS_SUBC_ETA(type1, type2, type3, btime, memb, vtime1, & nlev, a, b, c, io, iostat) SUBROUTINE NUSDAS_SUBC_ETA2(type1, type2, type3, btime, memb, vtime1, & vtime2, nlev, a, b, c, io, iostat)
argument types, argument meanings, and return values are same as NUSDAS_SUBC_SIGM().
/* C */ int nusdas_subc_tdif(type1, type2, type3, btime, memb, vtime1, dtime, atime, io) int nusdas_subc_tdif2(type1, type2, type3, btime, memb, vtime1, vtime2, dtime, atime, io) ! Fortran SUBROUTINE NUSDAS_SUBC_TDIF(type1, type2, type3, btime, memb, vtime1, & dtime, atime, iostat) SUBROUTINE NUSDAS_SUBC_TDIF2(type1, type2, type3, btime, memb, vtime1, & vtime2, dtime, atime, iostat)
symbol | Fortran | C |
dtime | INTEGER | N_SI4 * |
atime | INTEGER | N_SI4 * |
io | (should be symbol/macro defined in header file) | |
iostat | INTEGER, INTENT(OUT) | (not used) |
dtime
difference of real valid time from nominal valid time in minutes.
atime
accumulation time in seconds.
io
one of following symbols
writes SUBC record.
reads SUBC record.
0 | Succeeded. |
-1 | Error: requested file not exist. |
-2 | Error: requested record not exist. |
-3 | Error: specified size is different to that of definition file. |
-10 to -99 | (see error code table) |
/* C */ int nusdas_subc_srf(type1, type2, type3, btime, memb, vtime1, plane1, elem, subcgroup, idata, io) int nusdas_subc_srf2(type1, type2, type3, btime, memb, vtime1, vtime2, plane1, plane2, elem, subcgroup, idata, io) ! Fortran SUBROUTINE NUSDAS_SUBC_SRF(type1, type2, type3, btime, memb, vtime1, & plane1, elem, subcgroup, idata, io, iostat) SUBROUTINE NUSDAS_SUBC_SRF2(type1, type2, type3, btime, memb, vtime1, & vtime2, plane1, plane2, elem, subcgroup, idata, io, iostat)
symbol | Fortran | C |
subcgroup | CHARACTER(4) | char [4] |
idata | INTEGER, DIMENSION(*) | N_SI4 * |
io | (should be symbol/macro defined in header file) | |
iostat | INTEGER, INTENT(OUT) | (not used) |
subcgroup
must be "RADR" or "ISPC"
io
one of following symbols
writes SUBC record.
reads SUBC record.
0 | Succeeded. |
-1 | Error: requested file not exist. |
-2 | Error: requested record not exist. |
-3 | Error: specified size is different to that of definition file. |
-4 | Error: invalid subc group name. |
-5 | Error: invalid argument. |
-10 to -99 | (see error code table) |
/* C */ int nusdas_subc_info(type1, type2, type3, btime, memb, vtime1, infogroup, idata, isize, io) int nusdas_subc_info2(type1, type2, type3, btime, memb, vtime1, vtime2, infogroup, idata, isize, io) ! Fortran SUBROUTINE NUSDAS_SUBC_INFO(type1, type2, type3, btime, memb, vtime1, & infogroup, idata, isize, io, iostat) SUBROUTINE NUSDAS_SUBC_SRF2(type1, type2, type3, btime, memb, vtime1, & vtime2, infogroup, idata, isize, io, iostat)
symbol | Fortran | C |
infogroup | CHARACTER(4) | char [4] |
idata | CHARACTER, DIMENSION(isize) | char * |
isize | INTEGER | N_SI4 * |
io | (should be symbol/macro defined in header file) | |
iostat | INTEGER, INTENT(OUT) | (not used) |
infogroup
four-letter string that identifies the INFO record in the data file.
io
one of following symbols
writes SUBC record.
reads SUBC record.
>= 0 | Succeeded. Value is size of INFO record retrieved. |
-1 | Error: requested file not exist. |
-2 | Error: requested file malformed. |
-5 | Error: invalid argument. |
-10 to -99 | (see error code table) |
/* C */ int nusdas_grid(type1, type2, type3, btime, memb, vtime1, proj, gridsize, geometry, tattr, io) int nusdas_grid2(type1, type2, type3, btime, memb, vtime1, vtime2, proj, gridsize, geometry, tattr, io) SUBROUTINE NUSDAS_GRID(type1, type2, type3, btime, memb, vtime1, & proj, gridsize, geometry, tattr, io, iostat) int SUBROUTINE NUSDAS_GRID2(type1, type2, type3, btime, memb, vtime1, & vtime2, proj, gridsize, geometry, tattr, io, iostat)
symbol | Fortran | C |
proj | CHARACTER(4) | char [4] |
gridsize | INTEGER, DIMENSION(2) | N_SI4 [2] |
geometry | REAL, DIMENSION(2, 7) | float [7][2] |
tattr | CHARACTER(4) | char [4] |
io | (should be symbol/macro defined in header file) | |
iostat | INTEGER, INTENT(OUT) | (not used) |
proj
four-character symbol of projection type. The name is different from that in type1 string.
gridsize
grid size.
geometry
byte offset 80--135 in CNTL record
tattr
four-character symbol of time attribute. The name is different from that in type2 string.
io
one of following symbols
writes SUBC record.
reads SUBC record.
0 | Succeeded. |
-1 | Error: requested file not exist. |
-2 | Error: requested file malformed. |
-5 | Error: invalid argument. |
-10 to -99 | (see error code table) |
/* C */ int nusdas_inq_def(type1, type2, type3, param, value, vsize) ! Fortran SUBROUTINE NUSDAS_INQ_DEF(type1, type2, type3, param, value, & vsize, iostat)
symbol | Fortran | C |
param | (should be constant/macro defined in header file) | |
value | (may be various type) | void * |
vsize | INTEGER | N_SI4 * |
iostat | INTEGER, INTENT(OUT) | (not used) |
param
one of following symbols:
number of members. value is assumed to be INTEGER.
list of members. that is assumed to be array of CHARACTER(4).
number of valid times. value is assumed to be INTEGER.
list of forecast time (offset of valid time from base time). value is assumed to be array of INTEGER. Note that the value is NOT ALWAYS IN MINUTES.
four-letter symbol of unit of time,
which is used in interpreting N_VALIDTIME_LIST
.
value is assumed to be CHARACTER(4).
value
array to which parameter will be stored.
vsize
number of elements (not byte size) of array value.
>= 0 | Succeeded. Value is number of array elements retrieved. |
-1 | Error: size of value array insufficient. |
-2 | Error: value array not allocated (???) |
-3 | Error: invalid argument. |
-10 to -99 | (see error code table) |
/* C */ int nusdas_inq_cntl(type1, type2, type3, btime, memb, vtime1, param, value, vsize) int nusdas_inq_cntl2(type1, type2, type3, btime, memb, vtime1, vtime2, param, value, vsize) ! Fortran SUBROUTINE NUSDAS_INQ_CNTL(type1, type2, type3, btime, memb, vtime1, & param, value, vsize, iostat) SUBROUTINE NUSDAS_INQ_CNTL2(type1, type2, type3, btime, memb, & vtime1, vtime2, param, value, vsize, iostat)
symbol | Fortran | C |
param | (should be constant/macro defined in header file) | |
value | (may be various type) | void * |
vsize | INTEGER | N_SI4 * |
iostat | INTEGER, INTENT(OUT) | (not used) |
Meaning of arguments is same to that of NUSDAS_INQ_DEF().
However, only following parameter symbols are acceptable:
N_MEMBER_NUM
,
N_MEMBER_LIST
,
N_VALIDTIME_NUM
,
N_VALIDTIME_LIST
,
N_PLANE_NUM
,
N_PLANE_LIST
,
N_ELEMENT_NUM
,
and
N_ELEMENT_LIST
.
See also NUSDAS_GRID() to get grid information from CNTL record.
>= 0 | Succeeded. Value is number of array elements retrieved. |
-1 | Error: size of value array insufficient. |
-2 | Error: value array not allocated (???) |
-3 | Error: invalid argument. |
-10 to -99 | (see error code table) |
get list of basetime
/* C */ int nusdas_inq_nrdbtime(type1, type2, type3, bdata, bsize, verbose) ! Fortran SUBROUTINE NUSDAS_INQ_NRDBTIME(type1, type2, type3, & bdata, bsize, verbose, iostat)
bdata | INTEGER, DIMENSION(bsize) | N_SI4 * |
bsize | INTEGER | N_SI4 * |
verbose | (should be constant/macro defined in header file) | |
iostat | INTEGER, INTENT(OUT) | (not used) |
bdata
array to which the list of base time will be stored.
bsize
element number (not byte size) of array bdata
verbose
one of following symbols:
message is output while search is proceeding
message is suppressed
>= 0 | Succeeded. Value is number of array elements retrieved. |
-1 | Error: I/O error. |
-2 | Error: data file without CNTL record found. |
-3 | Error: record length error in seeking data file. |
-4 | Error: cannot open file or directory. |
-10 to -99 | (see error code table) |
Current implementation cannot handle dataset which has more base times than 999.
Operational version of this function does not work in some path styles.
get list of valid time
/* C */ int nusdas_inq_nrdvtime(type1, type2, type3, bdata, bsize, verbose) ! Fortran SUBROUTINE NUSDAS_INQ_NRDVTIME(type1, type2, type3, & bdata, bsize, verbose, iostat)
bdata | INTEGER, DIMENSION(bsize) | N_SI4 * |
bsize | INTEGER | N_SI4 * |
verbose | (should be constant/macro defined in header file) | |
iostat | INTEGER, INTENT(OUT) | (not used) |
bdata
array to which the list of valid time will be stored.
bsize
element number (not byte size) of array bdata
verbose
one of following symbols:
message is output while search is proceeding
message is suppressed
same as that of NUSDAS_INQ_NRDBTIME().
This function is available only for pnusdas version.
Current implementation cannot handle dataset which has more valid times than 999.
_GSM | global spectral model |
_RSM | regional spectral model |
_MSM | mesoscale model |
_TYM | typhoon model |
_DCD | decoded observation bulletins |
_SRF | very short-range precipitation forecast |
_WFM | week-range ensemble model |
_SF1 | month-range ensemble model |
_SF4 | four-month-range ensemble model |
_XXX | (reserved for data from unspecified creation process) |
name | description |
LL | latitude-longitude regular grid |
LM | Lambert conformal projection |
PS | Polar Stereographic projection |
GS | Gaussian grids |
MR | Mercator projection |
OL | Oblique-axis (rotated) lambert conformal projection |
RD | Local Cartesian coordinate for radar |
ST | Station data |
YP | Meridional vertical cross section using pressure coordinate |
XP | East-west vertical cross section using pressure coordinate |
XX | (reserved for data on unknown grids) |
See Users Guide for how to describe projection parameters in the definition file.
name | description |
PP | isobaric plane/layer |
ET | eta vertical coordinate plane/layer |
SG | sigma vertical coordinate plane/layer |
HB | hybrid vertical coordinate plane/layer |
LA | latitude (for vertical cross section data) |
LO | longitude (for vertical cross section data) |
ZZ | plane/layer specified by height |
TH | isentropic plane/layer |
ZS | z* vertical coordinate plane/layer |
XX | (reserved for data on unknown grids) |
name | description |
FC | forecast |
EA | early analysis |
AA | cycle analysis |
RA | reanalysis |
CC | constants |
OB | observations |
GS | guess |
XX | (reserved for data of unknown nature) |
name | description |
SV | the valid time has only one significant value |
MV | time-average value for time span specified by valid1 and valid2 |
AV | summation value for time span specified by valid1 and valid2 |
DV | standard deviation value for region specified by valid1 and valid2 |
... | ... |
XX | (reserved for data of unknown nature) |
See also note on element name table.
name | description |
SURF | surface (*1) |
ECTOP | echo top of radar |
(number) | meaning dependent to vertical coordinate |
notes:
See <URL:nuselem-en.html> for specific list.
Type symbols are used for argument utype for NUSDAS_READ() and NUSDAS_WRITE() subroutines. Missing value symbols are used as udata value for NUSDAS_MAKE_MASK().
symbol | type name | ||
type | missing value | Fortran | C |
N_I1 | N_MV_UI1 | (not recommended) | N_SI1 (signed char) |
N_I2 | N_MV_SI2 | INTEGER(2) | N_SI2 (short in most cases) |
N_I4 | N_MV_SI4 | INTEGER | N_SI4 (int in most cases) |
N_R4 | N_MV_R4 | REAL | float |
N_R8 | N_MV_R8 | REAL(8) or DOUBLE PRECISION | double |
N_NC | --- | (binary representation as stored in data file) |
These symbols are used for packing specification of NUSDAS_PARAMETER_CHANGE().
symbol | deffile | description |
N_P_1PAC | 1PAC | packing to signed 8bit integer |
N_P_2PAC | 2PAC | packing to signed 16bit integer |
"2UPC" | 2UPC | packing to unsigned 16bit integer |
N_P_4PAC | 4PAC | packing to signed 32bit integer |
N_P_I1 | I1 | signed 8bit integer |
N_P_I2 | I2 | signed 16bit integer |
N_P_N1I2 | N1I2 | packing to signed 16bit integer: factor is 10 |
N_P_I4 | I4 | signed 32bit integer |
N_P_R4 | R4 | IEEE 32bit float |
N_P_R8 | R8 | IEEE 64bit float |
N_P_RLEN | RLEN | Run Length Encoding |
N_P_GRIB | GRIB | GRIB version 2 (not implemented yet) |
code | description |
-10 | memory allocation failure |
-11 | bad type1 or type2 |
-12 | invalid character in type1/type2/type3 |
-13 | non-existent type1/type2/type3 |
-19 | data type1/type2 completion table does not found |
-20 | too many definition files are opened |
-21 | definition file not found nor readable |
-31 | too large dataset declared by definition file |
-32 | memory allocation failure |
-33 | lines in definition file are missing or not in correct order |
-34 | malformed ELEMENTMAP specification |
-40 | type1 undefined in definition file |
-41 | type2 undefined in definition file |
-42 | type3 undefined in definition file |
-43 | number of valid times undefined in definition file |
-44 | list of valid times undefined in definition file |
-45 | number of planes undefined in definition file |
-46 | list of planes undefined in definition file |
-47 | number of elements undefined in definition file |
-48 | list of elements undefined in definition file |
-49 | size of grid undefined in definition file |
-50 | invalid base time and valid time combination |
-51 | data file directory not found or mkdir error |
-52 | too many data files are opened |
-53 | cannot create data file |
-54 | NUSD record malformed or unreadable |
-55 | CNTL record malformed or unreadable |
-56 | INDX record malformed or unreadable |
-57 | END record malformed or unreadable |
-60 | I/O error (in datafile initialization) |
-61 | memory allocation error (in datafile initialization) |
-62 | specified data is not allowed by definition file (in datafile initialization) |
-63 | record larger than fixed record size (in datafile initialization) |
-64 | INFO source file specified but not readable |
-65 | cannot write NUSD record (in closing of datafile) |
-66 | cannot write INDX record (in closing of datafile) |
-67 | cannot write END record (in closing of datafile) |
-68 | write into read-only file |
-69 | write into dataset with NRD number 50 or more |
-70 | open error in ES routines |
-71 | write error in ES routines |
-72 | read error in ES routines |
-73 | I/O error in ES routines |
-76 | invalid unit number is used in ES routines |
-77 | I/O error in ES routines |
-78 | the file is not ES. |
-79 | memory allocation failure in ES routines |
-99 | I/O error |
*1Using 32bit signed integer,
it will overflow in year 5884, and it can be enough late
even for climate change simulation