manpagez: man pages & more
man ncgen3(1)
Home | html | info | man
ncgen3(1)                      UNIDATA UTILITIES                     ncgen3(1)




NAME

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


SYNOPSIS

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


DESCRIPTION

       ncgen3  generates  either a netCDF file, or C or Fortran source code to
       create a netCDF file.  The input to ncgen3 is a description of a netCDF
       file  in  a  small language known as CDL (network Common Data form Lan-
       guage), described below.  If no options are specified in  invoking  nc-
       gen3,  it merely checks the syntax of the input CDL file, producing er-
       ror 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  gen-
       erate  a Fortran program that uses the netCDF Fortran interface to cre-
       ate the same netCDF file.

       ncgen3 may be used with the companion program ncdump  to  perform  some
       simple  operations on netCDF files.  For example, 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 ncgen3
       to generate 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'  extension.  If a file already exists with the speci-
              fied 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 stan-
              dard 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 neces-
              sary because netCDF files cannot be written directly to standard
              output, since standard output is not seekable.)

       -k kind_of_file
              Using  -k2  or  -k "64-bit offset" specifies that generated file
              (or program) should use version 2 of format that employs  64-bit
              file  offsets.  The default is to use version 1 ("classic") for-
              mat with 32-bit file offsets, although this limits the  size  of
              the  netCDF  file, variables, and records to the sizes supported
              by the classic format.  (NetCDF-4 will support additional  kinds
              of  netCDF  files,  "netCDF-4"  and  "netCDF-4  classic model".)
              Note: -v is also accepted to mean the same thing as -k for back-
              ward  compatibility,  but  -k  is preferred, to match the corre-
              sponding ncdump option.

       -x     Don't initialize data with fill values.  This can speed up  cre-
              ation  of large netCDF files greatly, but later attempts to read
              unwritten data from the generated file will not  be  easily  de-
              tectable.


EXAMPLES

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

              ncgen3 foo.cdl

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

              ncgen3 -o x.nc foo.cdl

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

              ncgen3 -c -o x.nc foo.cdl



USAGE

   CDL Syntax Summary
       Below is an example of CDL syntax, describing a netCDF file with sever-
       al  named dimensions (lat, lon, and time), variables (Z, t, p, rh, lat,
       lon, time), variable attributes (units, long_name, valid_range,  _Fill-
       Value), 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;

              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,  vari-
       ables,  and  data,  beginning with the keyword dimensions:, variables:,
       and data, respectively.  The variable part may contain variable  decla-
       rations 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  di-
       mension  has a name and a size.  At most one dimension in a netCDF file
       can have the unlimited size, which means a variable using  this  dimen-
       sion 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 variable 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 coordi-
       nates of the dimension it names.  Dimensions need not have  correspond-
       ing variables.

       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 values, maximum and minimum valid values,
       scaling factors, offsets, and  parameters.   Attribute  information  is
       represented 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 variable, a name, a data type, a length,
       and a value.  In contrast to variables that are intended for data,  at-
       tributes are intended for metadata (data about data).

       In  CDL,  an  attribute is designated by a variable and attribute name,
       separated by `:'.  It is possible to assign global attributes not asso-
       ciated  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 attribute
       is the number of data values assigned to it, or the number  of  charac-
       ters  in  the character string assigned to it.  Multiple values are as-
       signed to non-character attributes by separating the values  with  com-
       mas.  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 subsequent characters  may  be  al-
       phanumeric or `_' or `-'.

       The  optional data section of a CDL specification is where netCDF vari-
       ables may be initialized.  The syntax of an initialization is simple: a
       variable  name, an equals sign, and a comma-delimited list of constants
       (possibly separated by spaces, tabs and  newlines)  terminated  with  a
       semicolon.   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
       supplying  a value for a distinguished variable attribute named `_Fill-
       Value'.  The types 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 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 unsigned, CDL sup-
       ports the same primitive data types as C.  The names for the  primitive
       data types are reserved words in CDL, so the names of variables, dimen-
       sions, and attributes 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.  ncgen3 converts byte declarations to char
       declarations in the output C code and to the nonstandard BYTE  declara-
       tion in output Fortran code.

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

       Longs  can hold values between -2147483648 and 2147483647.  ncgen3 con-
       verts 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
       platforms  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  exter-
       nal representation is as 32-bit IEEE normalized single-precision float-
       ing point numbers.  ncgen3 converts float declarations to float  decla-
       rations in the output C code and to REAL declarations in output Fortran
       code.  real is accepted as a synonym for float in CDL declarations.

       Doubles can hold values between about -1.7+308 and 1.7+308.  Their  ex-
       ternal representation is as 64-bit IEEE standard normalized double-pre-
       cision floating point numbers.  ncgen3 converts double declarations  to
       double declarations in the output C code and to DOUBLE PRECISION decla-
       rations in output Fortran code.


   CDL Constants
       Constants assigned to attributes or variables may be of any of the  ba-
       sic netCDF types.  The syntax for constants is similar to C syntax, ex-
       cept that type suffixes must be appended to shorts and floats  to  dis-
       tinguish them from longs and doubles.

       A  byte constant is represented by a single character or multiple char-
       acter 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 signif-
       icant  characters  by  the  ncdump program, following the C convention.
       Therefore, a NULL byte should not be embedded in a character string un-
       less  at  the  end: use the byte data type instead 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 in-
       terpreted as octal, except that if it begins with `0x',  it  is  inter-
       preted 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  con-
       stant,  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 significant 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 accept-
       able float constants:
              -2.0f
              3.14159265358979f   // will be truncated to less precision
              1.f


       Floating point constants of type double are appropriate for  represent-
       ing floating point data with about sixteen significant digits of preci-
       sion.  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
       following are all acceptable double constants:
              -2.0
              3.141592653589793
              1.0e-20
              1.d



BUGS

       The programs generated by ncgen3 when using the -c or -f  use  initial-
       ization 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  statements may exceed the line length or number of con-
       tinuation 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 sim-
       ply be concatenated into a single array  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  in-
       teger.



Printed: 115-3-5         $Date: 2009/09/24 18:19:10 $                ncgen3(1)

netcdf 4.3.3.1 - Generated Thu Mar 5 07:57:38 CST 2015
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.