netCDFPerl - Man Page

perl extension for netCDF dataset access

Synopsis

use netCDF;

NetCDF::create("foo.nc", NetCDF::CLOBBER);
...

Description

netCDFPerl is a Perl 5 extension-module interface to the services provided by the netCDF version 2 API, netcdf2(3).

The functions in the netCDF version 2 library can be accessed by a Perl 5 script by replacing the `nc' prefix of the regular netCDF version 2 C function names with NetCDF::. For example, the C function nccreate() is available to a perl script as  NetCDF::create.

Each perl function matches, as closely as possible and necessary, its C counterpart:

Scalar argument types are mapped in an obvious way:

!.3rmk "3rt0"
!.3rlns "d"
.
.
!.3rvpt ""
C Perl 5
!.3rlns "m"
.
.
!.3rvpt "1"
!.3rmk "3rt1"
!.3rlns "d"
.
.
!.3rvpt ""
char * string
!.3rlns "m"
.
.
!.3rvpt "1"
!.3rmk "3rt2"
!.3rlns "d"
.
.
!.3rvpt ""
char integer
!.3rlns "m"
.
.
!.3rvpt "1"
!.3rmk "3rt3"
!.3rlns "d"
.
.
!.3rvpt ""
short integer
!.3rlns "m"
.
.
!.3rvpt "1"
!.3rmk "3rt4"
!.3rlns "d"
.
.
!.3rvpt ""
int integer
!.3rlns "m"
.
.
!.3rvpt "1"
!.3rmk "3rt5"
!.3rlns "d"
.
.
!.3rvpt ""
nclong integer
!.3rlns "m"
.
.
!.3rvpt "1"
!.3rmk "3rt6"
!.3rlns "d"
.
.
!.3rvpt ""
long integer
!.3rlns "m"
.
.
!.3rvpt "1"
!.3rmk "3rt7"
!.3rlns "d"
.
.
!.3rvpt ""
float double
!.3rlns "m"
.
.
!.3rvpt "1"
!.3rmk "3rt8"
!.3rlns "d"
.
.
!.3rvpt ""
double double
!.3rlns "m"
.
.
!.3rvpt "1"
!.3rvpt ""
!.3rlnx "s"
.
.
.
.
!.3rlnx "r"
.
.
.
.
!.3rvpt "1"
.

The individual elements of an array argument are similarly mapped.

Array arguments themselves are passed by reference for both input and output. For example, the following Perl 5 code will write and then read a hyperslab of values:

@start = (0, 0, 0);
@count = (1, 2, 3);
@out = (1, 2, 3, 4, 5, 6);
NetCDF::varput($ncid, $varid, @start, @count, @out);
NetCDF::varget($ncid, $varid, @start, @count, @in);

(The above assumes that $ncid and $varid have been appropriately set.) After this code is executed, the array @in will have the same values as the array @out. The previous contents, if any, of an array used for input are destroyed (e.g. @in in the above example).

To define a scalar variable with NetCDF::vardef(), use an empty dimension-ID array, e.g.

NetCDF::vardef($ncid, "scalar_variable", NetCDF::FLOAT, \());

The interface doesn't support null arguments. One cannot use a void pointer to indicate that no value is requested for a particular argument: all arguments must be present.

For technical reasons, output variables must be initialized, i.e. any variable argument that is to have its value set by a function must already have a value. For example, if the first occurrence of the variable $attval is in the following:

NetCDF::attget($ncid, NetCDF::GLOBAL, "history", \$attval);

then a core dump will probably result. The solution is to initialize the variable before using it:

$attval="";
NetCDF::attget($ncid, NetCDF::GLOBAL, "history", \$attval);

Two additional functions are provided for error handling. NetCDF::opts(i) determines the handling of errors by setting the ncopts variable to i.   It returns the previous value. NetCDF::err() returns the value of the error code variable, ncerr.

In addition to the above functions, most C macro constants that are defined in the netCDF header file netcdf.h are also available to a perl script by dropping any `NC_' substring and using the  NetCDF:: prefix, e.g. NetCDF::LONG.

See Also

perl(1), netcdf2(3)

Info

Printed: 120-0-0 UNIDATA UTILITIES