netCDFPerl(1)

1netCDFPerl(1)                  UNIDATA UTILITIES                 netCDFPerl(1)
2
3
4

NAME

6       netCDFPerl - perl extension for netCDF dataset access
7

SYNOPSIS

9       use netCDF;
10
11       NetCDF::create("foo.nc", NetCDF::CLOBBER);
12       ...
13

DESCRIPTION

15       netCDFPerl  is a Perl 5 extension-module interface to the services pro‐
16       vided by the netCDF version 2 API, netcdf2(3).
17
18       The functions in the netCDF version 2 library can be accessed by a Perl
19       5 script by replacing the `nc' prefix of the regular netCDF version 2 C
20       function names with NetCDF::.  For example, the C  function  nccreate()
21       is available to a perl script as NetCDF::create.
22
23       Each perl function matches, as closely as possible and necessary, its C
24       counterpart:
25
26           * The number, order, and semantics of the arguments are  identical.
27             Note,  however, that it is not necessary to specify the number of
28             elements in an array because perl arrays carry that information.
29
30           * The behavior is the same in terms of the netCDF dataset.
31
32           * A value of -1 is returned to indicate an error.
33
34       Scalar argument types are mapped in an obvious way:
35
36
37             C      Perl 5
38
39           char *   string
40           char     integer
41           short    integer
42           int      integer
43           nclong   integer
44           long     integer
45           float    double
46           double   double
47
48       The individual elements of an array argument are similarly mapped.
49
50       Array arguments themselves are passed by reference for both  input  and
51       output.   For  example,  the  following Perl 5 code will write and then
52       read a hyperslab of values:
53
54           @start = (0, 0, 0);
55           @count = (1, 2, 3);
56           @out = (1, 2, 3, 4, 5, 6);
57           NetCDF::varput($ncid, $varid, @start, @count, @out);
58           NetCDF::varget($ncid, $varid, @start, @count, @in);
59
60       (The above assumes that $ncid and $varid have been appropriately  set.)
61       After this code is executed, the array @in will have the same values as
62       the array @out.  The previous contents, if any, of an  array  used  for
63       input are destroyed (e.g. @in in the above example).
64
65       To  define a scalar variable with NetCDF::vardef(), use an empty dimen‐
66       sion-ID array, e.g.
67
68           NetCDF::vardef($ncid, "scalar_variable", NetCDF::FLOAT, \());
69
70       The interface doesn't support null arguments.  One cannot  use  a  void
71       pointer  to  indicate that no value is requested for a particular argu‐
72       ment: all arguments must be present.
73
74       For technical reasons, output variables must be initialized, i.e.   any
75       variable  argument that is to have its value set by a function must al‐
76       ready have a value.  For example, if the first occurrence of the  vari‐
77       able $attval is in the following:
78
79           NetCDF::attget($ncid, NetCDF::GLOBAL, "history", \$attval);
80
81       then  a  core dump will probably result.  The solution is to initialize
82       the variable before using it:
83
84           $attval="";
85           NetCDF::attget($ncid, NetCDF::GLOBAL, "history", \$attval);
86
87
88       Two   additional   functions   are   provided   for   error   handling.
89       NetCDF::opts(i) determines the handling of errors by setting the ncopts
90       variable to i.  It returns the previous value.   NetCDF::err()  returns
91       the value of the error code variable, ncerr.
92
93       In addition to the above functions, most C macro constants that are de‐
94       fined in the netCDF header file netcdf.h are also available to  a  perl
95       script  by  dropping any `NC_' substring and using the NetCDF:: prefix,
96       e.g. NetCDF::LONG.
97

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO