Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
NCMPIGEN(1)			   UTILITIES			   NCMPIGEN(1)

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  gen-
       erate  a	Fortran	program	that uses the netCDF Fortran interface to cre-
       ate 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 di-
       mension 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	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.)

       -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	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.  ncmpigen  converts	byte  declarations  to
       char declarations in the	output C code and to the nonstandard BYTE dec-
       laration	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	exter-
       nal representation is as	32-bit IEEE normalized single-precision	float-
       ing  point numbers.  ncmpigen converts float declarations to float dec-
       larations in the	output C code and to REAL declarations in output  For-
       tran  code.   real  is  accepted	as a synonym for float in CDL declara-
       tions.

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

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 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: 2020-01-29		  2013-11-17			   NCMPIGEN(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | USAGE | DATE | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ncmpigen&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help