Re: 960522: NetCDF C++ interface question

>From: Greg Kogut <address@hidden>
>Subject: NetCDF C++ interface question
>Keywords: 199605221948.AA26658

Hi Greg,

> Is there any example code for the using the 'put_rec' function 
> of the C++ NetCDF interface?  I don't understand its use.  The
> equivelent function in the C interface took an array of pointers to void
> as a parameter.  The C++ interface takes pointers to specific types.  
> 
> How is 'put_rec' used to pass record data?

Good question.

There is currently no example code in the netCDF distribution for using the
put_rec member function, and the description of the new record variable
member functions in the C++ netCDF class documentation is fairly minimal.

The intention of these functions is to permit easily writing or reading one
record's worth of data for a single variable, and not to duplicate the
functionality of the C interface record functions that deal with data for
multiple record variables, possibly of differing types.  We were not able
to come up with a good C++ abstraction for an equivalent to the C interface
without introducing "record" as a new class.  Introducing a new record
class seemed to complicate the interface and implementation without much
benefit.

One of the goals of the C++ interface was to eliminate the use of void* and
void** arguments to functions, because these are not type-safe, so the user
can easily make errors that cannot be caught by the compiler.  We have not
been able to come up with a type-safe interface for the C record functions,
and since they are just a convenience rather than a necessity, we
substituted the somewhat less convenient but type-safe record variable
member functions such as put_rec.  I'd be interested in knowing about any
approach to an equivalent interface to the C record functions that supports
type-safety.

The NcVar member functions

    // Put a record's worth of data in current record
    NcBool put_rec( const ncbyte* vals );
    NcBool put_rec( const char* vals );
    NcBool put_rec( const short* vals );
    NcBool put_rec( const nclong* vals );
    NcBool put_rec( const float* vals );
    NcBool put_rec( const double* vals );

put an entire record's worth of data into the open netCDF file at the
"current record", which can be set with the "set_rec" member function,
supposedly easier to use than the "set_cur" member function because it
only requires a record number.  Each variable has its own current record,
stored in a private "the_cur" array of longs.

There is a similar set of member functions that include an explicit record
number argument as well:

    // Put a record's worth of data in specified record
    NcBool put_rec( const ncbyte* vals, long rec );
    NcBool put_rec( const char* vals, long rec );
    NcBool put_rec( const short* vals, long rec );
    NcBool put_rec( const nclong* vals, long rec );
    NcBool put_rec( const float* vals, long rec );
    NcBool put_rec( const double* vals, long rec );

In looking at the interface now, it appears that the "set_rec" member
function is not really enough; there should be a member function to access
the current record number and to increment the record number.  Such
omissions are a symptom that we should have constructed and provided
examples for using these functions before adding them to the interface.

Anyway, thanks for pointing out the lack of documentation for these.  We'll
try to fix it for the next version.  And please let me know if you find
problems in using them, since the current C++ "test" doesn't test these
functions.

--Russ

______________________________________________________________________________

Russ Rew                                           UCAR Unidata Program
address@hidden                              http://www.unidata.ucar.edu