--- name: "ncgen-hdf" section: "1" platform: "linux" package: "hdf4-tools" version: "4.3.0-1+b1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/ncgen-hdf" --- # ncgen-hdf(1) From a CDL file generate a netCDF file, a C program, or a Fortran program ## NAME ncgen-hdf - From a CDL file generate a netCDF file, a C program, or a Fortran program ## SYNOPSIS ncgen-hdf \[-b\] \[-c\] \[-f\] \[-n\] \[-o *output\_file*\] *input\_file* ## DESCRIPTION **ncgen-hdf** *generates either a netCDF file, or C or Fortran source code to* *create a netCDF file. The input to* **ncgen-hdf** *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* **ncgen-hdf***, 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-hdf** *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* **ncgen-hdf** *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** outputfile *Name for the 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.* ## EXAMPLES *Check the syntax of the CDL file \`***foo.cdl***':* *ncgen-hdf foo.cdl* *From the CDL file \`***foo.cdl***', generate an equivalent binary netCDF file* *named \`***x.nc***':* *ncgen-hdf -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***':* *ncgen-hdf -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.* ### 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.* **ncgen-hdf** *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-hdf** *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.* **ncgen-hdf** *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.* **ncgen-hdf** *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.* **ncgen-hdf** *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* **ncdump** *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 .1f ``` *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 ``` ## BUGS *The programs generated by* **ncgen-hdf** *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.*