NCGEN(1) UNIDATA UTILITIES NCGEN(1)NAMEncgen - From a CDL file generate a netCDF file, a C pro
gram, or a Fortran program
SYNOPSISncgen [-b] [-c] [-f] [-n] [-o netcdf_filename] input_file
DESCRIPTIONncgen generates either a netCDF file, or C or Fortran
source code to create a netCDF file. The input to ncgen
is a description of a netCDF file in a small language
known as CDL (network Common Data form Language), de
scribed below. If no options are specified in invoking
ncgen, it merely checks the syntax of the input CDL file,
producing error messages for any violations of CDL syntax.
Other options can be used to create the corresponding
netCDF file, to generate a C program that uses the netCDF
C interface to create the netCDF file, or to generate a
Fortran program that uses the netCDF Fortran interface to
create the same netCDF file.
ncgen may be used with the companion program ncdump to
perform some simple operations on netCDF files. For exam
ple, to rename a dimension in a netCDF file, use ncdump to
get a CDL version of the netCDF file, edit the CDL file to
change the name of the dimensions, and use ncgen to gener
ate the corresponding netCDF file from the edited CDL
file.
OPTIONS-b Create a (binary) netCDF file. If the -o option is
absent, a default file name will be constructed
from the netCDF name (specified after the netcdf
keyword in the input) by appending the `.nc' exten
sion. If a file already exists with the specified
name, it will be overwritten.
-c Generate C source code that will create a netCDF
file matching the netCDF specification. The C
source code is written to standard output.
-f Generate Fortran source code that will create a
netCDF file matching the netCDF specification. The
Fortran source code is written to standard output.
-o netcdf_file
Name for the binary netCDF file created. If this
option is specified, it implies the "-b" option.
(This option is necessary because netCDF files can
not be written directly to standard output, since
standard output is not seekable.)
-n Like -b option, except creates netCDF file with the
obsolete `.cdf' extension instead of the `.nc' ex
Printed: 101-10-25 $Date: 1996/10/08 18:57:20 $ 1
NCGEN(1) UNIDATA UTILITIES NCGEN(1)
tension, in the absence of an output filename spec
ified by the -o option. This option is only sup
ported for backward compatibility.
EXAMPLES
Check the syntax of the CDL file `foo.cdl':
ncgen foo.cdl
From the CDL file `foo.cdl', generate an equivalent binary
netCDF file named `x.nc':
ncgen-o x.nc foo.cdl
From the CDL file `foo.cdl', generate a C program contain
ing the netCDF function invocations necessary to create an
equivalent binary netCDF file named `x.nc':
ncgen-c -o x.nc foo.cdl
USAGE
CDL Syntax Summary
Below is an example of CDL syntax, describing a netCDF
file with several named dimensions (lat, lon, and time),
variables (Z, t, p, rh, lat, lon, time), variable at
tributes (units, long_name, valid_range, _FillValue), and
some data. CDL keywords are in boldface. (This example
is intended to illustrate the syntax; a real CDL file
would have a more complete set of attributes so that the
data would be more completely self-describing.)
netcdf foo { // an example netCDF specification in CDL
dimensions:
lat = 10, lon = 5, time = unlimited ;
variables:
long lat(lat), lon(lon), time(time);
float Z(time,lat,lon), t(time,lat,lon);
double p(time,lat,lon);
long rh(time,lat,lon);
// variable attributes
lat:long_name = "latitude";
lat:units = "degrees_north";
lon:long_name = "longitude";
lon:units = "degrees_east";
time:units = "seconds since 1992-1-1 00:00:00";
Z:units = "geopotential meters";
Z:valid_range = 0., 5000.;
p:_FillValue = -9999.;
rh:_FillValue = -1;
Printed: 101-10-25 $Date: 1996/10/08 18:57:20 $ 2
NCGEN(1) UNIDATA UTILITIES NCGEN(1)
data:
lat = 0, 10, 20, 30, 40, 50, 60, 70, 80, 90;
lon = -140, -118, -96, -84, -52;
}
All CDL statements are terminated by a semicolon. Spaces,
tabs, and newlines can be used freely for readability.
Comments may follow the characters `//' on any line.
A CDL description consists of three optional parts: dimen_
sions, variables, and data, beginning with the keyword di
mensions:, variables:, and data, respectively. The vari
able part may contain variable declarations and attribute
assignments.
A netCDF dimension is used to define the shape of one or
more of the multidimensional variables contained in the
netCDF file. A netCDF dimension has a name and a size.
At most one dimension in a netCDF file can have the unlim
ited size, which means a variable using this dimension can
grow to any length (like a record number in a file).
A variable represents a multidimensional array of values
of the same type. A variable has a name, a data type, and
a shape described by its list of dimensions. Each vari
able may also have associated attributes (see below) as
well as data values. The name, data type, and shape of a
variable are specified by its declaration in the variable
section of a CDL description. A variable may have the
same name as a dimension; by convention such a variable is
one-dimensional and contains coordinates of the dimension
it names. Dimensions need not have corresponding vari
ables.
A netCDF attribute contains information about a netCDF
variable or about the whole netCDF dataset. Attributes
are used to specify such properties as units, special val
ues, maximum and minimum valid values, scaling factors,
offsets, and parameters. Attribute information is repre
sented by single values or arrays of values. For example,
"units" is an attribute represented by a character array
such as "celsius". An attribute has an associated vari
able, a name, a data type, a length, and a value. In con
trast to variables that are intended for data, attributes
are intended for metadata (data about data).
In CDL, an attribute is designated by a variable and at
tribute name, separated by `:'. It is possible to assign
global attributes not associated with any variable to the
netCDF as a whole by using `:' before the attribute name.
The data type of an attribute in CDL is derived from the
type of the value assigned to it. The length of an at
tribute is the number of data values assigned to it, or
the number of characters in the character string assigned
Printed: 101-10-25 $Date: 1996/10/08 18:57:20 $ 3
NCGEN(1) UNIDATA UTILITIES NCGEN(1)
to it. Multiple values are assigned to non-character at
tributes by separating the values with commas. All values
assigned to an attribute must be of the same type.
The names for CDL dimensions, variables, and attributes
must begin with an alphabetic character or `_', and subse
quent characters may be alphanumeric or `_' or `-'.
The optional data section of a CDL specification is where
netCDF variables may be initialized. The syntax of an
initialization is simple: a variable name, an equals sign,
and a comma-delimited list of constants (possibly separat
ed by spaces, tabs and newlines) terminated with a semi
colon. For multi-dimensional arrays, the last dimension
varies fastest. Thus row-order rather than column order
is used for matrices. If fewer values are supplied than
are needed to fill a variable, it is extended with a type-
dependent `fill value', which can be overridden by supply
ing a value for a distinguished variable attribute named
`_FillValue'. The types of constants need not match the
type declared for a variable; coercions are done to con
vert integers to floating point, for example. The con
stant `_' can be used to designate the fill value for a
variable.
Primitive Data Types
char characters
byte 8-bit data
short 16-bit signed integers
long 32-bit signed integers
int (synonymous with long)
float IEEE single precision floating point (32 bits)
real (synonymous with float)
double IEEE double precision floating point (64 bits)
Except for the added data-type byte and the lack of un
signed, CDL supports the same primitive data types as C.
The names for the primitive data types are reserved words
in CDL, so the names of variables, dimensions, and at
tributes must not be type names. In declarations, type
names may be specified in either upper or lower case.
Bytes differ from characters in that they are intended to
hold a full eight bits of data, and the zero byte has no
special significance, as it does for character data. nc
gen converts byte declarations to char declarations in the
output C code and to the nonstandard BYTE declaration in
output Fortran code.
Shorts can hold values between -32768 and 32767. ncgen
converts short declarations to short declarations in the
output C code and to the nonstandard INTEGER*2 declaration
in output Fortran code.
Printed: 101-10-25 $Date: 1996/10/08 18:57:20 $ 4
NCGEN(1) UNIDATA UTILITIES NCGEN(1)
Longs can hold values between -2147483648 and 2147483647.
ncgen converts long declarations to long declarations in
the output C code and to INTEGER declarations in output
Fortran code. int and integer are accepted as synonyms
for long in CDL declarations. Now that there are plat
forms with 64-bit representations for C longs, it may be
better to use the int synonym to avoid confusion.
Floats can hold values between about -3.4+38 and 3.4+38.
Their external representation is as 32-bit IEEE normalized
single-precision floating point numbers. ncgen converts
float declarations to float declarations in the output C
code and to REAL declarations in output Fortran code. re
al is accepted as a synonym for float in CDL declarations.
Doubles can hold values between about -1.7+308 and
1.7+308. Their external representation is as 64-bit IEEE
standard normalized double-precision floating point num
bers. ncgen converts double declarations to double decla
rations in the output C code and to DOUBLE PRECISION dec
larations in output Fortran code.
CDL Constants
Constants assigned to attributes or variables may be of
any of the basic netCDF types. The syntax for constants
is similar to C syntax, except that type suffixes must be
appended to shorts and floats to distinguish them from
longs and doubles.
A byte constant is represented by a single character or
multiple character escape sequence enclosed in single
quotes. For example,
'a' // ASCII `a'
'\0' // a zero byte
'\n' // ASCII newline character
'\33' // ASCII escape character (33 octal)
'\x2b' // ASCII plus (2b hex)
'\377' // 377 octal = 255 decimal, non-ASCII
Character constants are enclosed in double quotes. A
character array may be represented as a string enclosed in
double quotes. The usual C string escape conventions are
honored. For example
"a" // ASCII `a'
"Two\nlines\n" // a 10-character string with two embedded newlines
"a bell:\007" // a string containing an ASCII bell
Note that the netCDF character array "a" would fit in a
one-element variable, since no terminating NULL character
is assumed. However, a zero byte in a character array is
interpreted as the end of the significant characters by
the ncdump program, following the C convention. There
fore, a NULL byte should not be embedded in a character
string unless at the end: use the byte data type instead
Printed: 101-10-25 $Date: 1996/10/08 18:57:20 $ 5
NCGEN(1) UNIDATA UTILITIES NCGEN(1)
for byte arrays that contain the zero byte. NetCDF and
CDL have no string type, but only fixed-length character
arrays, which may be multi-dimensional.
short integer constants are intended for representing
16-bit signed quantities. The form of a short constant is
an integer constant with an `s' or `S' appended. If a
short constant begins with `0', it is interpreted as oc
tal, except that if it begins with `0x', it is interpreted
as a hexadecimal constant. For example:
-2s // a short -2
0123s // octal
0x7ffs //hexadecimal
Long integer constants are intended for representing
32-bit signed quantities. The form of a long constant is
an ordinary integer constant, although it is acceptable to
append an optional `l' or `L'. If a long constant begins
with `0', it is interpreted as octal, except that if it
begins with `0x', it is interpreted as a hexadecimal con
stant. Examples of valid long constants include:
-2
1234567890L
0123 // octal
0x7ff // hexadecimal
Floating point constants of type float are appropriate for
representing floating point data with about seven signifi
cant digits of precision. The form of a float constant is
the same as a C floating point constant with an `f' or `F'
appended. For example the following are all acceptable
float constants:
-2.0f
3.14159265358979f // will be truncated to less precision
1.f
Floating point constants of type double are appropriate
for representing floating point data with about sixteen
significant digits of precision. The form of a double
constant is the same as a C floating point constant. An
optional `d' or `D' may be appended. For example the fol
lowing are all acceptable double constants:
-2.0
3.141592653589793
1.0e-20
1.d
BUGS
The programs generated by ncgen when using the -c or -f
use initialization statements to store data in variables,
and will fail to produce compilable programs if you try to
use them for large datasets, since the resulting state
ments may exceed the line length or number of continuation
Printed: 101-10-25 $Date: 1996/10/08 18:57:20 $ 6
NCGEN(1) UNIDATA UTILITIES NCGEN(1)
statements permitted by the compiler.
The CDL syntax makes it easy to assign what looks like an
array of variable-length strings to a netCDF variable, but
the strings will simply be concatenated into a single ar
ray of characters, since netCDF cannot represent an array
of variable-length strings in one netCDF variable.
NetCDF and CDL do not yet support a type corresponding to
a 64-bit integer.
Printed: 101-10-25 $Date: 1996/10/08 18:57:20 $ 7
