| 1 |
$Header$ |
| 2 |
|
| 3 |
Purpose: Document libnco_c++ |
| 4 |
|
| 5 |
libnco_c++ is a C++ interface to the netCDF 3.x library. |
| 6 |
It is in its own directory in the NCO repository on Sourceforge. |
| 7 |
The software is completely independent of NCO, however, and only |
| 8 |
requires the current netCDF C library to build. |
| 9 |
libnco_c++ is mostly complete and it needs alpha testers, |
| 10 |
comments, and contributions by developers (not end users yet). |
| 11 |
I'm very interested in comments, critcisms, and contributions to |
| 12 |
the basic design and API. You can download the latest version from |
| 13 |
the NCO CVS repository on Sourceforge |
| 14 |
|
| 15 |
cvs -d:pserver:[email protected]:/cvsroot/nco login |
| 16 |
cvs -z3 -d:pserver:[email protected]:/cvsroot/nco co -kk nco |
| 17 |
|
| 18 |
All code is in the nco/src/nco_c++ directory, including the |
| 19 |
all important TODO and ChangeLog files. If you want to contribute |
| 20 |
patches or comments the appropriate venue is the developer's forum |
| 21 |
|
| 22 |
http://sf.net/forum/forum.php?forum_id=9831 |
| 23 |
|
| 24 |
Those with good patches to contribute will get CVS write access. |
| 25 |
What follows is a description of the software design and status. |
| 26 |
I hope you like it! |
| 27 |
|
| 28 |
Charlie Zender |
| 29 |
|
| 30 |
Short description: |
| 31 |
libnco_c++ does NOT use an object-based approach, like libnetcdf_c++.a. |
| 32 |
We use a pure overload-based approach. |
| 33 |
The design emulates the Fortran90 interface with some C++-specific extensions. |
| 34 |
Explicit reference to intrinsic types is determined by the library. |
| 35 |
External types take advantage of the netCDF 3.X built-in conversion rules. |
| 36 |
|
| 37 |
Status of the library: |
| 38 |
More than half of libnetcdf.a functionality is implemented. |
| 39 |
I have not overloaded the [get/put]_vara_ or [get/put]_varm_ |
| 40 |
or [get/put]_vars_ functions yet. |
| 41 |
This is because my C++ applications do not yet require them. |
| 42 |
There are no hooks yet for native short, char, and byte types. |
| 43 |
Most other calls are implemented (for float, double, long and int). |
| 44 |
The subset that is implemented is completely self-contained. |
| 45 |
It is highly portable and has been used for two years on production code. |
| 46 |
This code references only nco_ calls, no references to nc_ calls. |
| 47 |
The only requirement to build the nco_c++ library is a C++ compiler |
| 48 |
and libnetcdf.a version 3.X. |
| 49 |
I am currently interested in receiving feedback and testing |
| 50 |
on the library design. |
| 51 |
There is a short TODO list appended below. |
| 52 |
|
| 53 |
Design: |
| 54 |
I faced many design choices, and my decision was to emphasize, |
| 55 |
in no particular order, |
| 56 |
(0) Easy Migration from C interface |
| 57 |
(1) Error Handling |
| 58 |
(2) Flexibility |
| 59 |
(3) Maintainability. |
| 60 |
(4) Taking advantage of C++ constructs |
| 61 |
(5) Testing |
| 62 |
|
| 63 |
(0) Easy Migration from C interface |
| 64 |
All calls have identical names to netCDF 3.X calls with but |
| 65 |
with prefix nco_ instead of nc_. Type names are deleted |
| 66 |
so nc_put_var_float() becomes nco_put_var(). Order of arguments |
| 67 |
is maintained where possible, with optional arguments (e.g., |
| 68 |
start and count vectors) moved to end of function parameter list, and |
| 69 |
some new optional arguments (allowed non-fatal return codes). |
| 70 |
|
| 71 |
(1) Error Handling |
| 72 |
Let |
| 73 |
rcd = Return code from netCDF 3.X layer |
| 74 |
rcd_opt = Optional, user-specified non-fatal return code |
| 75 |
By default, all rcd != NC_NOERR errors are fatal for all |
| 76 |
functions. Inquire functions, and some others, however, allow |
| 77 |
specification of allowed, non-fatal, return codes. |
| 78 |
rcd=nco_enddef(nc_out,NC_ENOTINDEFINE) |
| 79 |
|
| 80 |
(2) Flexibility |
| 81 |
Functions that return information may be called with returned |
| 82 |
values in parameter list, or values returned as function return |
| 83 |
values. This allows returned information to be used to initialize |
| 84 |
variables that are const, i.e., |
| 85 |
|
| 86 |
rcd=nco_inq_foo(nc_id,foo); -> or |
| 87 |
foo=nco_inq_foo(nc_id); -> which allows this construct |
| 88 |
const int foo(nco_inq_foo(nc_id)); |
| 89 |
|
| 90 |
(3) Maintainability |
| 91 |
There is only one nco_foo() function which calls the corresponding |
| 92 |
nc_foo() function. All other overloads of nco_foo() do preprocessing |
| 93 |
of the argument list and then call the primary nco_foo() function. |
| 94 |
The primary nco_foo() function is the one whose arguments look most |
| 95 |
like the corresponding nc_foo() function. In practice this means |
| 96 |
that nco_put_var(nc_id,var_nm,var_val) calls |
| 97 |
nco_put_var(nc_id,var_id,var_val) which calls |
| 98 |
nc_put_var_[float,long,etc]() as appropriate. |
| 99 |
Thus there are as few interfaces to the underlying libnetcdf.a as |
| 100 |
possible. |
| 101 |
|
| 102 |
(4) Taking advantage of C++ constructs |
| 103 |
(4)(i) Everything is passed by reference so that the calling routines |
| 104 |
never need to pass pointers, and the function overhead is as limited |
| 105 |
as possible. All input variable are declared const. |
| 106 |
C++ strings are allowed anywhere an variable/dimension/attribute ID |
| 107 |
would normally be required. |
| 108 |
Thus variables can always be passed by name rather than ID. |
| 109 |
This means the calling program never has to keep track of IDs |
| 110 |
(except the file ID, which, in my opinion, should have its |
| 111 |
own ID->name call implemented in the netCDF library). |
| 112 |
|
| 113 |
(4)(ii) There is no standard way in C++, unlike Fortran, for an array |
| 114 |
to know its rank and dimensionality. However, the C++ STL |
| 115 |
provides valarrays and vectors which do know this information. |
| 116 |
A valarray interface to a couple of the functions |
| 117 |
demonstrate how this could be supported more generally. |
| 118 |
|
| 119 |
(4)(iii) Functions are templated where possible. |
| 120 |
|
| 121 |
(5) Testing |
| 122 |
There is a short, standalone sample program, tst.cc, which tests some |
| 123 |
of the libnco_c++. In particular, it demonstrates reading and writing. |
| 124 |
tst.cc should eventually contain tests for the entire API. |
| 125 |
|
| 126 |
Description of files: |
| 127 |
Only files matching *nco_* are part of the libnco_c++ library, other |
| 128 |
files can be safely ignored (but may contain sample code which utilizes |
| 129 |
libnco_c++). The full API of the libnco_c++.a library are completely |
| 130 |
self-contained in the libnco_c++.hh header: |
| 131 |
|
| 132 |
#include <nco_att.hh> // C++ interface to netCDF attribute routines |
| 133 |
#include <nco_dmn.hh> // C++ interface to netCDF dimension routines |
| 134 |
#include <nco_fl.hh> // C++ interface to netCDF file-level routines |
| 135 |
#include <nco_hgh.hh> // High-level NCO utilities |
| 136 |
#include <nco_utl.hh> // C++ interface utilities for netCDF routines |
| 137 |
#include <nco_var.hh> // C++ interface to netCDF variable routines |
| 138 |
|
| 139 |
Each .hh file contains the prototypes defined in a corresponding |
| 140 |
.cc file. The contents of all the individual files should be |
| 141 |
apparent from their names with the exception of nco_hgh. |
| 142 |
nco_hgh contains a program-specific high-level interface which should |
| 143 |
not be part of a generic netCDF C++ interface library. |
| 144 |
It can be safely ignored. The file tst.cc uses the libnco_c++.a API. |
| 145 |
tst.cc shows how libnco_c++ is intended to be used in a real |
| 146 |
environment. |
| 147 |
|
| 148 |
Build libnco_c++ with the Makefile generated by configure. |
| 149 |
If this fails, try using the handwritten Makefile.old---type |
| 150 |
'make -f Makefile.old' using GNU make. |
| 151 |
Makefile.old requires GNU make and Perl to be in your executable path. |