xenial (1) ncmpigen.1.gz

Provided by: pnetcdf-bin_1.7.0~pre1-1_amd64 bug

NAME

       ncmpigen - From a CDL file generate a netCDF file, a C program, or a Fortran program

SYNOPSIS

       ncmpigen [-b] [-c] [-f] [-n] [-o netcdf_filename] [-v file_format] input_file

DESCRIPTION

       ncmpigen  generates either a netCDF file, or C or Fortran source code to create a netCDF file.  The input
       to ncmpigen is a description of a netCDF file in a small language known as CDL (network Common Data  form
       Language),  described  below.   If  no  options  are specified in invoking ncmpigen, 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.

       ncmpigen  may  be  used  with the companion program ncmpidump to perform some simple operations on netCDF
       files.  For example, to rename a dimension in a netCDF file, use ncmpidump to get a CDL  version  of  the
       netCDF  file,  edit  the  CDL file to change the name of the dimensions, and use ncmpigen 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 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 cannot 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'
              extension,  in  the absence of an output filename specified by the -o option.  This option is only
              supported for backward compatibility.

       -v file_format
              File format of the output netCDF file. The value of file_format can be: 1  or  classic  for  CDF-1
              format.   2  or  64-bit-offset  is  CDF-2.   5 or 64-bit-variable for CDF-5.  The default (if this
              option is not given) is CDF-1, the classic format.

EXAMPLES

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

              ncmpigen foo.cdl

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

              ncmpigen -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':

              ncmpigen -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  attributes  (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;

              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
       keyword  dimensions:,  variables:,  and  data,  respectively.   The  variable  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 unlimited 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 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 coordinates of the dimension it
       names.  Dimensions need not have corresponding 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, attributes 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 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 attribute is the number of  data  values  assigned  to  it,  or  the  number  of
       characters  in  the  character  string  assigned  to  it.   Multiple values are assigned to non-character
       attributes 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 subsequent 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 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 `_FillValue'.  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 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 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.  ncmpigen 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.   ncmpigen  converts  short declarations to short
       declarations in the output C code and to the nonstandard INTEGER*2 declaration in output Fortran code.

       Longs can hold values between -2147483648 and 2147483647.  ncmpigen 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  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 external representation is as 32-bit IEEE
       normalized single-precision floating point  numbers.   ncmpigen  converts  float  declarations  to  float
       declarations 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 external representation is  as  64-bit
       IEEE  standard normalized double-precision floating point numbers.  ncmpigen converts double declarations
       to double declarations in the output C code and to DOUBLE PRECISION declarations 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 ncmpidump program, following the C  convention.   Therefore,  a  NULL  byte
       should  not  be embedded in a character string unless 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
       interpreted  as  octal,  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 constant.  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 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 following are all acceptable double
       constants:
              -2.0
              3.141592653589793
              1.0e-20
              1.d

DATE

       $Date: 2014-04-16 13:38:34 -0500 (Wed, 16 Apr 2014) $

BUGS

       The programs generated by ncmpigen 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 statements may exceed the line length or number of continuation 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 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 integer.