NuSDaS Interface Reference Manual

$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).

Preparation

Versions of NuSDaS

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.

Operational Version

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 Version

'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.

Header Inclusion

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.

Common Notes

Note on Data Types

Terminology for Data Identifier

In NuSDaS, data is identified by following dimensions: data type, base time, member name, valid time, plane name, element name.

data type

Data type is 16-character string composed from type1, type2, and type3.

type1

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

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

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

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 name

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

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

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.

element name

Physical element name. Standard names are shown in table. Note that this field must have at least 6 characters.

Data Identifier in the Interface

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, ...)
symbolFortran typeC typedescription
type1CHARACTER(8)const char [8]data type, 1st component
type2CHARACTER(4)const char [4]data type, 2nd component
type3CHARACTER(4)const char [4]data type, 3rd component
btimeINTEGERN_SI4 *base time
membCHARACTER(4)const char [4]member name
vtime1INTEGERN_SI4 *valid time, start
vtime2INTEGERN_SI4 *valid time, end
plane1CHARACTER(6)const char [6]plane name, upper
plane2CHARACTER(6)const char [6]plane name, lower
elemCHARACTER(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.

Function/Subroutine Interface

NUSDAS_READ()

Reads a two-dimensional array from NuSDaS dataset.

SYNOPSIS
/* 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)
symbolFortranC
type1 ... elem(see table above)
udata(may be various type)void *
utype(should be constant in header)(should be macro in header)
iostatINTEGER, INTENT(OUT)(not used)
ARGUMENTS

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.

RETURN VALUE
> 0Succeeded. The value is number of array elements obtained.
0Warning: requested data is not written yet.
-1Warning: file containing requested data does not exists.
-2Warning: requested data is not registered yet.
-3Error: inconsistency between CNTL and DATA records.
-4Error: insufficient size of user array.
-5Error: conversion to specified data type is not supported.
-6Error: malformed run-length encoded data.
-7Error: malformed CNTL or INDX record.
-10 to -99(see error code table)
DESCRIPTION

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.

NUSDAS_WRITE()

Writes a two-dimensional array into NuSDaS dataset.

SYNOPSIS
/* 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)
symbolFortranC
type1 ... elem(see table above)
udata(may be various type) INTENT(OUT)void *
utype(should be constant in header)(should be macro in header)
iostatINTEGER, INTENT(OUT)(not used)
ARGUMENTS

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.

RETURN VALUE
> 0Succeeded. The value is number of array elements written.
-2Warning: requested data is not registered yet.
-3Error: size of user data array is too small.
-4Error: conversion to specified data type is not supported.
-5Error: data record size exceeds fixed record size.
-6Error: invalid missing value style.
-7Error: mask bit pattern undefined.
-8Error: overflow in packing.
-9Error: invalid compression scheme.
-10 to -99(see error code table)
DESCRIPTION

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.

NUSDAS_ESF_FLUSH()

flushes write buffer to ES files and close it.

SYNOPSIS
/* 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)
symbolFortranC
type1 ... vtime2(see table above)
iostatINTEGER, INTENT(OUT)(not used)
ARGUMENTS

From type1 to vtime2, see section 'Terminology for Data Identifier'.

iostat

see following section, RETURN VALUE.

RETURN VALUE

NUSDAS_ONEFILE_CLOSE()

closes a data file.

SYNOPSIS
/* 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)
symbolFortranC
type1 ... vtime2(see table above)
iostatINTEGER, INTENT(OUT)(not used)
ARGUMENTS

From type1 to vtime2, see section 'Terminology for Data Identifier'.

iostat

see following section, RETURN VALUE.

RETURN VALUE
1Specified file is not opened.
0Succeeded.
-2Warning: requested data is not registered yet.
-3Error: inconsistency between CNTL and DATA records.
-4Error: array size too large.
-5Error: array type mismatch.
-6Error: too large value in RLE compression.
-7Error: 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().

NUSDAS_ALLFILE_CLOSE()

SYNOPSIS
/* C */
    int
nusdas_allfile_close(closemode)

! Fortran
SUBROUTINE NUSDAS_ALLFILE_CLOSE(closemode, iostat)
symbolFortranC
closemode(should be symbol in header)(should be macro in header)
iostatINTEGER, INTENT(OUT)(not used)
ARGUMENTS
closemode

One of following symbols defined in header file:

N_FOPEN_READ

all files opened as read-only are closed.

N_FOPEN_WRITE

all files opened as writable are closed.

N_FOPEN_ALL

all files are closed.

iostat

see following section, RETURN VALUE.

RETURN VALUE
> 0Succeeded. The value is number of files successfully closed.
< 0Error: the absolute value is number of files that cause error.

NUSDAS_IOCNTL()

SYNOPSIS
/* C */
    int
nusdas_iocntl(param, value)

! Fortran
SUBROUTINE NUSDAS_IOCNTL(param, value, iostat)
symbolFortranC
param(should be symbol in header)(should be macro in header)
value(should be symbol in header)(should be macro in header)
iostatINTEGER, INTENT(OUT)(not used)
ARGUMENTS
param

Should be one of following symbols defined in header file.

N_IO_MARK_END

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.

N_IO_W_FCLOSE

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.

N_IO_R_FCLOSE

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.

N_IO_WARNING_OUT

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.

RETURN VALUE
0Succeeded.
-1Error: invalid argument.

NUSDAS_PARAMETER_CHANGE()

SYNOPSIS
/* C */
    int
nusdas_parameter_change(param, value)

! Fortran
SUBROUTINE NUSDAS_PARAMETER_CHANGE(param, value, iostat)
symbolFortranC
param(should be constant/macro in header)
value(see description of param)void *
iostatINTEGER, INTENT(OUT)(not used)
ARGUMENTS
param

specifies what parameter to change. It should be one of them:

N_PC_MISSING_UI1

missing value when user data array is char. value should be (pointer to) the same type. The default value is UCHAR_MAX.

N_PC_MISSING_SI2

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.

N_PC_MISSING_SI4

missing value when user data array is integer. value should be (pointer to) the same type. The default value is LONG_MIN.

N_PC_MISSING_R4

missing value when user data array is float. value should be (pointer to) the same type. The default value is FLT_MAX.

N_PC_MISSING_R8

missing value when user data array is double. The default value is DBL_MAX. value should be (pointer to) the same type.

N_PC_MASK_BIT

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.

N_PC_ID_SET

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.

N_PC_PACKING

packing scheme. See table Packing Type for acceptable values. N_OFF is the default.

N_PC_SIZEX

grid size in X direction. N_OFF is the default.

N_PC_SIZEY

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().

NUSDAS_MAKE_MASK()

creates data-presence bitmap from data array.

SYNOPSIS
/* C */
    int
nusdas_make_mask(udata, utype, usize, bitmap, bitmapsize)

! Fortran
SUBROUTINE NUSDAS_MAKE_MASK(udata, utype, usize, bitmap, bitmapsize, iostat)
symbolFortranC
udata(may be various type)void *
utype(should be constant/macro in header)
usizeINTEGERN_SI4 *
bitmapCHARACTER, DIMENSION(*), INTENT(OUT)char *
bitmapsizeINTEGERN_SI4 *
iostatINTEGER, INTENT(OUT)(not used)
ARGUMENTS
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.

RETURN VALUE
0Succeeded.
-1Error: bitmap size too little

NUSDAS_SUBC_PRESET1()

defines the default content of SUBC records for eta and sigma coordinates.

SYNOPSIS
/* 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)
symbolFortranC
subcgroupCHARACTER(4)char [4]
nlevINTEGERN_SI4 *
aREAL, DIMENSION(nlev)float *
bREAL, DIMENSION(nlev)float *
cREAL, DIMENSION(nlev)float *
iostatINTEGER, INTENT(OUT)(not used)
ARGUMENTS
subcgroup

must be "SIGM" or "ETA "

nlev

number of levels

a
b
c

vertical coordinate parameters

RETURN CODE
0Succeded
-1invalid subcgroup value
-2Too many SUBC records written.
-10 to -99(see error code table)

NUSDAS_SUBC_SIGM()

SYNOPSIS
/* 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)
symbolFortranC
nlevINTEGERN_SI4 *
aREAL, DIMENSION(nlev)float *
bREAL, DIMENSION(nlev)float *
cREAL, DIMENSION(nlev)float *
io(should be symbol/macro defined in header file)
iostatINTEGER, INTENT(OUT)(not used)
ARGUMENTS
nlev

number of levels

a
b
c

vertical coordinate parameters

io

one of following symbols

N_IO_PUT

writes SUBC record made from a, b, and c

N_IO_GET

reads SUBC record to a, b, and c

RETURN VALUE
0Succeeded.
-1Error: requested file not exist.
-2Error: requested record not exist.
-3Error: specified size is different to that of definition file.
-4Error: specified number of level is smaller than that in file.
-5Error: invalid argument.
-10 to -99(see error code table)

NUSDAS_SUBC_ETA()

SYNOPSIS
/* 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().

NUSDAS_SUBC_TDIF()

SYNOPSIS
/* 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)
symbolFortranC
dtimeINTEGERN_SI4 *
atimeINTEGERN_SI4 *
io(should be symbol/macro defined in header file)
iostatINTEGER, INTENT(OUT)(not used)
ARGUMENTS
dtime

difference of real valid time from nominal valid time in minutes.

atime

accumulation time in seconds.

io

one of following symbols

N_IO_PUT

writes SUBC record.

N_IO_GET

reads SUBC record.

RETURN VALUE
0Succeeded.
-1Error: requested file not exist.
-2Error: requested record not exist.
-3Error: specified size is different to that of definition file.
-10 to -99(see error code table)

NUSDAS_SUBC_SRF()

SYNOPSIS
/* 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)
symbolFortranC
subcgroupCHARACTER(4)char [4]
idataINTEGER, DIMENSION(*)N_SI4 *
io(should be symbol/macro defined in header file)
iostatINTEGER, INTENT(OUT)(not used)
ARGUMENTS
subcgroup

must be "RADR" or "ISPC"

io

one of following symbols

N_IO_PUT

writes SUBC record.

N_IO_GET

reads SUBC record.

RETURN VALUE
0Succeeded.
-1Error: requested file not exist.
-2Error: requested record not exist.
-3Error: specified size is different to that of definition file.
-4Error: invalid subc group name.
-5Error: invalid argument.
-10 to -99(see error code table)

NUSDAS_SUBC_INFO()

SYNOPSIS
/* 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)
symbolFortranC
infogroupCHARACTER(4)char [4]
idataCHARACTER, DIMENSION(isize)char *
isizeINTEGERN_SI4 *
io(should be symbol/macro defined in header file)
iostatINTEGER, INTENT(OUT)(not used)
ARGUMENTS
infogroup

four-letter string that identifies the INFO record in the data file.

io

one of following symbols

N_IO_PUT

writes SUBC record.

N_IO_GET

reads SUBC record.

RETURN VALUE
>= 0Succeeded. Value is size of INFO record retrieved.
-1Error: requested file not exist.
-2Error: requested file malformed.
-5Error: invalid argument.
-10 to -99(see error code table)

NUSDAS_GRID()

SYNOPSIS
/* 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)
symbolFortranC
projCHARACTER(4)char [4]
gridsizeINTEGER, DIMENSION(2)N_SI4 [2]
geometryREAL, DIMENSION(2, 7)float [7][2]
tattrCHARACTER(4)char [4]
io(should be symbol/macro defined in header file)
iostatINTEGER, INTENT(OUT)(not used)
ARGUMENTS
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

N_IO_PUT

writes SUBC record.

N_IO_GET

reads SUBC record.

RETURN VALUE
0Succeeded.
-1Error: requested file not exist.
-2Error: requested file malformed.
-5Error: invalid argument.
-10 to -99(see error code table)

NUSDAS_INQ_DEF()

SYNOPSIS
/* C */
    int
nusdas_inq_def(type1, type2, type3, param, value, vsize)

! Fortran
SUBROUTINE NUSDAS_INQ_DEF(type1, type2, type3, param, value, &
  vsize, iostat)
symbolFortranC
param(should be constant/macro defined in header file)
value(may be various type)void *
vsizeINTEGERN_SI4 *
iostatINTEGER, INTENT(OUT)(not used)
ARGUMENTS
param

one of following symbols:

N_MEMBER_NUM

number of members. value is assumed to be INTEGER.

N_MEMBER_LIST

list of members. that is assumed to be array of CHARACTER(4).

N_VALIDTIME_NUM

number of valid times. value is assumed to be INTEGER.

N_VALIDTIME_LIST

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.

N_VALIDTIME_UNIT

four-letter symbol of unit of time, which is used in interpreting N_VALIDTIME_LIST. value is assumed to be CHARACTER(4).

N_PLANE_NUM
N_PLANE_LIST
N_ELEMENT_NUM
N_ELEMENT_LIST
N_ELEMENT_MAP
N_PROJECTION
N_GRID_SIZE
N_GRID_DISTANCE
N_GRID_BASEPOINT
N_STAND_LATLON
N_SPARE_LATLON
value

array to which parameter will be stored.

vsize

number of elements (not byte size) of array value.

RETURN VALUE
>= 0Succeeded. Value is number of array elements retrieved.
-1Error: size of value array insufficient.
-2Error: value array not allocated (???)
-3Error: invalid argument.
-10 to -99(see error code table)

NUSDAS_INQ_CNTL()

SYNOPSIS
/* 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)
symbolFortranC
param(should be constant/macro defined in header file)
value(may be various type)void *
vsizeINTEGERN_SI4 *
iostatINTEGER, INTENT(OUT)(not used)
DESCRIPTION

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.

RETURN VALUE
>= 0Succeeded. Value is number of array elements retrieved.
-1Error: size of value array insufficient.
-2Error: value array not allocated (???)
-3Error: invalid argument.
-10 to -99(see error code table)

NUSDAS_INQ_NRDBTIME()

get list of basetime

SYNOPSIS
/* C */
    int
nusdas_inq_nrdbtime(type1, type2, type3, bdata, bsize, verbose)

! Fortran
SUBROUTINE NUSDAS_INQ_NRDBTIME(type1, type2, type3, &
  bdata, bsize, verbose, iostat)
bdataINTEGER, DIMENSION(bsize)N_SI4 *
bsizeINTEGERN_SI4 *
verbose(should be constant/macro defined in header file)
iostatINTEGER, INTENT(OUT)(not used)
ARGUMENTS
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:

N_ON

message is output while search is proceeding

N_OFF

message is suppressed

RETURN VALUE
>= 0Succeeded. Value is number of array elements retrieved.
-1Error: I/O error.
-2Error: data file without CNTL record found.
-3Error: record length error in seeking data file.
-4Error: cannot open file or directory.
-10 to -99(see error code table)
LIMITATION

Current implementation cannot handle dataset which has more base times than 999.

Operational version of this function does not work in some path styles.

NUSDAS_INQ_NRDVTIME()

get list of valid time

SYNOPSIS
/* C */
    int
nusdas_inq_nrdvtime(type1, type2, type3, bdata, bsize, verbose)

! Fortran
SUBROUTINE NUSDAS_INQ_NRDVTIME(type1, type2, type3, &
  bdata, bsize, verbose, iostat)
bdataINTEGER, DIMENSION(bsize)N_SI4 *
bsizeINTEGERN_SI4 *
verbose(should be constant/macro defined in header file)
iostatINTEGER, INTENT(OUT)(not used)
ARGUMENTS
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:

N_ON

message is output while search is proceeding

N_OFF

message is suppressed

RETURN VALUE

same as that of NUSDAS_INQ_NRDBTIME().

PORTABILITY

This function is available only for pnusdas version.

LIMITATION

Current implementation cannot handle dataset which has more valid times than 999.

Tables of Name and Constant

Data Identifier

model name
_GSMglobal spectral model
_RSMregional spectral model
_MSMmesoscale model
_TYMtyphoon model
_DCDdecoded observation bulletins
_SRFvery short-range precipitation forecast
_WFMweek-range ensemble model
_SF1month-range ensemble model
_SF4four-month-range ensemble model
_XXX(reserved for data from unspecified creation process)
horizontal grid name
namedescription
LLlatitude-longitude regular grid
LMLambert conformal projection
PSPolar Stereographic projection
GSGaussian grids
MRMercator projection
OLOblique-axis (rotated) lambert conformal projection
RDLocal Cartesian coordinate for radar
STStation data
YPMeridional vertical cross section using pressure coordinate
XPEast-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.

vertical grid name
namedescription
PPisobaric plane/layer
ETeta vertical coordinate plane/layer
SGsigma vertical coordinate plane/layer
HBhybrid vertical coordinate plane/layer
LAlatitude (for vertical cross section data)
LOlongitude (for vertical cross section data)
ZZplane/layer specified by height
THisentropic plane/layer
ZSz* vertical coordinate plane/layer
XX(reserved for data on unknown grids)
data attribute name
namedescription
FCforecast
EAearly analysis
AAcycle analysis
RAreanalysis
CCconstants
OBobservations
GSguess
XX(reserved for data of unknown nature)
time attribute name
namedescription
SVthe valid time has only one significant value
MVtime-average value for time span specified by valid1 and valid2
AVsummation value for time span specified by valid1 and valid2
DVstandard deviation value for region specified by valid1 and valid2
......
XX(reserved for data of unknown nature)

See also note on element name table.

plane name
namedescription
SURFsurface (*1)
ECTOPecho top of radar
(number)meaning dependent to vertical coordinate

notes:

  1. the sea level pressure is represented as element "PSEA " at plane "SURF ".
element name

See <URL:nuselem-en.html> for specific list.

User Data Array Type

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().

symboltype name
typemissing valueFortranC
N_I1N_MV_UI1(not recommended)N_SI1 (signed char)
N_I2N_MV_SI2INTEGER(2)N_SI2 (short in most cases)
N_I4N_MV_SI4INTEGERN_SI4 (int in most cases)
N_R4N_MV_R4REALfloat
N_R8N_MV_R8REAL(8) or DOUBLE PRECISIONdouble
N_NC---(binary representation as stored in data file)

Packing Type

These symbols are used for packing specification of NUSDAS_PARAMETER_CHANGE().

symboldeffiledescription
N_P_1PAC1PACpacking to signed 8bit integer
N_P_2PAC2PACpacking to signed 16bit integer
"2UPC"2UPCpacking to unsigned 16bit integer
N_P_4PAC4PACpacking to signed 32bit integer
N_P_I1I1signed 8bit integer
N_P_I2I2signed 16bit integer
N_P_N1I2N1I2packing to signed 16bit integer: factor is 10
N_P_I4I4signed 32bit integer
N_P_R4R4IEEE 32bit float
N_P_R8R8IEEE 64bit float
N_P_RLENRLENRun Length Encoding
N_P_GRIBGRIBGRIB version 2 (not implemented yet)

Error Code

codedescription
-10memory allocation failure
-11bad type1 or type2
-12invalid character in type1/type2/type3
-13non-existent type1/type2/type3
-19data type1/type2 completion table does not found
-20too many definition files are opened
-21definition file not found nor readable
-31too large dataset declared by definition file
-32memory allocation failure
-33lines in definition file are missing or not in correct order
-34malformed ELEMENTMAP specification
-40type1 undefined in definition file
-41type2 undefined in definition file
-42type3 undefined in definition file
-43number of valid times undefined in definition file
-44list of valid times undefined in definition file
-45number of planes undefined in definition file
-46list of planes undefined in definition file
-47number of elements undefined in definition file
-48list of elements undefined in definition file
-49size of grid undefined in definition file
-50invalid base time and valid time combination
-51data file directory not found or mkdir error
-52too many data files are opened
-53cannot create data file
-54NUSD record malformed or unreadable
-55CNTL record malformed or unreadable
-56INDX record malformed or unreadable
-57END record malformed or unreadable
-60I/O error (in datafile initialization)
-61memory allocation error (in datafile initialization)
-62specified data is not allowed by definition file (in datafile initialization)
-63record larger than fixed record size (in datafile initialization)
-64INFO source file specified but not readable
-65cannot write NUSD record (in closing of datafile)
-66cannot write INDX record (in closing of datafile)
-67cannot write END record (in closing of datafile)
-68write into read-only file
-69write into dataset with NRD number 50 or more
-70open error in ES routines
-71write error in ES routines
-72read error in ES routines
-73I/O error in ES routines
-76invalid unit number is used in ES routines
-77I/O error in ES routines
-78the file is not ES.
-79memory allocation failure in ES routines
-99I/O error

*1Using 32bit signed integer, it will overflow in year 5884, and it can be enough late even for climate change simulation