MAN page from openSUSE Tumbleweed netcdf-openmpi-


Updated: $Date: 2009/09/24 18:19:10 $


ncgen3 - From a CDL file generate a netCDF classic or 64 bit classicfile,a C program, or a Fortran program 


ncgen3[-b][-c][-f][-k kind_of_file][-x][-n][-o netcdf_filename]input_file


ncgen3 generates either a netCDF file, or C or Fortran source code tocreate a netCDF file. The input to ncgen3 is a description of a netCDFfile in a small language known as CDL (network Common Data form Language),described below.If no options are specified in invoking ncgen3, it merely checks thesyntax of the input CDL file, producing error messages forany violations of CDL syntax. Other options can be used to create thecorresponding netCDF file, to generate a C program that uses the netCDF Cinterface to create the netCDF file, or to generate a Fortran program thatuses the netCDF Fortran interface to create the same netCDF file.

ncgen3 may be used with the companion program ncdump to performsome simple operations on netCDF files. For example, to rename a dimensionin 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 ncgen3to generate the corresponding netCDF file from the edited CDL file. 


Create a (binary) netCDF file. If the -o option is absent, a defaultfile name will be constructed from the netCDF name (specified after thenetcdf keyword in the input) by appending the `.nc' extension. If afile already exists with the specified name, it will be overwritten.
GenerateCsource code that will create a netCDF filematching the netCDF specification. The C source code is written tostandard output.
GenerateFortransource code that will create a netCDF filematching the netCDF specification. The Fortran source code is writtento standard output.
-o netcdf_file
Name for the binary netCDF file created. If this option is specified, it impliesthe "-b" option. (This option is necessary because netCDF filescannot be written directly to standard output, since standard output is notseekable.)
-k kind_of_file
Using -k2 or -k "64-bit offset" specifies thatgenerated file (or program) should use version 2 of format thatemploys 64-bit file offsets. The default is to use version 1("classic") format with 32-bit file offsets, although this limits thesize of the netCDF file, variables, and records to the sizes supportedby the classic format. (NetCDF-4 will support additional kinds ofnetCDF files, "netCDF-4" and "netCDF-4 classic model".)Note: -v is also accepted to mean the same thing as-k for backward compatibility, but -k is preferred, to matchthe corresponding ncdump option.
Don't initialize data with fill values. This can speed up creation oflarge netCDF files greatly, but later attempts to read unwritten datafrom the generated file will not be easily detectable.


Check the syntax of the CDL file `foo.cdl':

ncgen3 foo.cdl

From the CDL file `foo.cdl', generate an equivalent binary netCDF filenamed `':

ncgen3 -o foo.cdl

From the CDL file `foo.cdl', generate a C program containing thenetCDF function invocations necessary to create an equivalent binary netCDFfile named `':

ncgen3 -c -o foo.cdl




CDL Syntax Summary

Below is an example of CDL syntax, describing a netCDF file with severalnamed dimensions (lat, lon, and time), variables (Z, t, p, rh, lat, lon,time), variable attributes (units, long_name, valid_range, _FillValue), andsome data. CDL keywords are in boldface. (This example is intended toillustrate the syntax; a real CDL file would have a more complete set ofattributes so that the data would be more completely self-describing.)

netcdf foo {  // an example netCDF specification in CDLdimensions:        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;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: dimensions,variables, and data, beginning with the keyworddimensions:,variables:,anddata,respectively.The variable part may contain variabledeclarations and attribute assignments.

A netCDF dimension is used to define the shape of one or more of themultidimensional variables contained in the netCDF file. A netCDFdimension has a name and a size. At most one dimension in a netCDF filecan have the unlimited size, which means a variable using thisdimension can grow to any length (like a record number in a file).

A variable represents a multidimensional array of values of thesame type. A variable has a name, a data type, and a shape describedby its list of dimensions. Each variable may also have associatedattributes (see below) as well as data values. The name, datatype, and shape of a variable are specified by its declaration in thevariable section of a CDL description. A variable may have the samename as a dimension; by convention such a variable is one-dimensionaland contains coordinates of the dimension it names. Dimensions neednot have corresponding variables.

A netCDF attribute contains information about a netCDF variable orabout the whole netCDF dataset. Attributes are usedto specify such properties as units, special values, maximum andminimum valid values, scaling factors, offsets, and parameters. Attributeinformation is represented by single values or arrays of values. Forexample, "units" is an attribute represented by a character array suchas "celsius". An attribute has an associated variable, a name,a data type, a length, and a value. In contrast to variables that areintended for data, attributes are intended for metadata (data aboutdata).

In CDL, an attribute is designated by a variable and attribute name,separated by `:'. It is possible to assign global attributesnot associated with any variable to the netCDF as a whole by using`:' before the attribute name. The data type of an attribute in CDLis derived from the type of the value assigned to it. The length ofan attribute is the number of data values assigned to it, or thenumber of characters in the character string assigned to it. Multiplevalues are assigned to non-character attributes by separating thevalues with commas. All values assigned to an attribute must be ofthe same type.

The names for CDL dimensions, variables, and attributes must begin with analphabetic character or `_', and subsequent characters may be alphanumericor `_' or `-'.

The optional data section of a CDL specification is wherenetCDF variables may be initialized. The syntax of an initializationis simple: a variable name, an equals sign, and acomma-delimited list of constants (possibly separated by spaces, tabsand newlines) terminated with a semicolon. For multi-dimensionalarrays, the last dimension varies fastest. Thus row-order rather thancolumn order is used for matrices. If fewer values are supplied thanare needed to fill a variable, it is extended with a type-dependent`fill value', which can be overridden by supplying a value for adistinguished variable attribute named `_FillValue'. Thetypes of constants need not match the type declared for a variable;coercions are done to convert integers to floating point, for example.The constant `_' can be used to designate the fill value for a variable. 

Primitive Data Types

char    charactersbyte    8-bit datashort   16-bit signed integerslong    32-bit signed integersint     (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 ofunsigned,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 attributes must not betype names. In declarations, type names may be specifiedin either upper or lower case.

Bytes differ from characters in that they are intended to hold a full eightbits of data, and the zero byte has no special significance, as itdoes for character data.ncgen3 converts byte declarations to chardeclarations in the output C code and to the nonstandard BYTEdeclaration in output Fortran code.

Shorts can hold values between -32768 and 32767.ncgen3 converts short declarations to shortdeclarations in the output C code and to the nonstandard INTEGER*2declaration in output Fortran code.

Longs can hold values between -2147483648 and 2147483647.ncgen3 converts long declarations to longdeclarations in the output C code and to INTEGERdeclarations in output Fortran code. int and integer areaccepted as synonyms for long in CDL declarations.Now that there are platforms with 64-bit representations for C longs, it maybe better to use the int synonym to avoid confusion.

Floats can hold values between about -3.4+38 and 3.4+38. Theirexternal representation is as 32-bit IEEE normalized single-precisionfloating point numbers. ncgen3 converts floatdeclarations to float declarations in the output C code and toREAL declarations in output Fortran code. real is acceptedas a synonym for float in CDL declarations.

Doubles can hold values between about -1.7+308 and 1.7+308. Theirexternal representation is as 64-bit IEEE standard normalizeddouble-precision floating point numbers. ncgen3 convertsdouble declarations to double declarations in the output Ccode and to DOUBLE PRECISION declarations in output Fortrancode.


CDL Constants

Constants assigned to attributes or variables may be of any of thebasic netCDF types. The syntax for constants is similar to C syntax,except that type suffixes must be appended to shorts and floats todistinguish them from longs and doubles.

A byte constant is represented by a single character or multiplecharacter 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 arraymay be represented as a string enclosed in double quotes. The usual Cstring 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-elementvariable, since no terminating NULL character is assumed. However, a zerobyte in a character array is interpreted as the end of the significantcharacters by the ncdump program, following the C convention.Therefore, a NULL byte should not be embedded in a character string unlessat the end: use the byte data type instead for byte arrays thatcontain the zero byte. NetCDF and CDL have no string type, but onlyfixed-length character arrays, which may be multi-dimensional.

short integer constants are intended for representing 16-bitsigned quantities. The form of a short constant is an integerconstant with an `s' or `S' appended. If a short constantbegins with `0', it is interpreted as octal, except that if it begins with`0x', it is interpreted as a hexadecimal constant. For example:

-2s     // a short -20123s   // octal0x7ffs  //hexadecimal

Long integer constants are intended for representing 32-bit signedquantities. The form of a long constant is an ordinary integerconstant, although it is acceptable to append an optional `l' or`L'. If a long constant begins with `0', it is interpreted asoctal, except that if it begins with `0x', it is interpreted as a hexadecimalconstant. Examples of valid long constants include:

-21234567890L0123            // octal0x7ff           // hexadecimal

Floating point constants of type float are appropriate for representingfloating point data with about seven significant digits of precision. The form of a float constant is the same as a C floating pointconstant with an `f' or `F' appended. For example the followingare all acceptable float constants:

-2.0f3.14159265358979f       // will be truncated to less precision1.f

Floating point constants of type double are appropriate forrepresenting floating point data with about sixteen significant digitsof precision. The form of a double constant is the same as a Cfloating point constant. An optional `d' or `D' may be appended.For example the following are all acceptable double constants:




The programs generated by ncgen3 when using the -c or -fuse initialization statements to store data in variables, and will fail toproduce compilable programs if you try to use them for large datasets, sincethe resulting statements may exceed the line length or number ofcontinuation statements permitted by the compiler.

The CDL syntax makes it easy to assign what looks like an array ofvariable-length strings to a netCDF variable, but the strings will simply beconcatenated into a single array of characters, since netCDF cannotrepresent 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.



CDL Syntax Summary
Primitive Data Types
CDL Constants

This document was created byman2html,using the manual pages.