\input ../doc/texinfo   @c -*-texinfo-*-

@c %**start of header
@setfilename nc.info
@settitle NetCDF Prototype C++ Interface
@setchapternewpage odd
@c %**end of header

@ifinfo
This file documents the prototype experimental Unidata C++ netCDF
interface.

Copyright (C) 1993 University Corporation for Atmospheric Research.
Permission is granted to make and distribute verbatim copies of
this file provided the copyright notice and this permission notice
are preserved on all copies.
@end ifinfo

@titlepage
@title NetCDF C++ Interface
@subtitle Class Documentation
@subtitle Prototype Release (Version 0), March 1993
@author Russ Rew and Mitch Baltuch
@author Unidata Program Center
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1993 University Corporation for Atmospheric Research

Permission is granted to make and distribute verbatim copies of this
manual provided that the copyright notice and these paragraphs are
preserved on all copies.  The software and any accompanying written 
materials are provided ``as is'' without warranty of any kind.  UCAR 
expressly disclaims all warranties of any kind, either expressed or 
implied, including but not limited to the implied warranties of 
merchantability and fitness for a particular purpose.  

The Unidata Program Center is managed by the University 
Corporation for Atmospheric Research and sponsored by the National 
Science Foundation.  Any opinions, findings, conclusions, or 
recommendations expressed in this publication are those of the 
author(s) and do not necessarily reflect the views of the National 
Science Foundation.

Mention of any commercial company or product in this document 
does not constitute an endorsement by the Unidata Program Center.  
Unidata does not authorize any use of information from this 
publication for advertising or publicity purposes.
@end titlepage

@node Top, Introduction, (dir), (dir)
@ifinfo
@top NetCDF C++ Interface
This manual is preliminary documentation for the prototype, experimental C++
interface for netCDF (version 0).

@menu
* Introduction::                
* File Classes::                
* NetCDF Components::           
* Auxiliary Classes::           
* Function Index::              

 --- The Detailed Node Listing ---

Introduction

* Class Hierarchy::             
* Auxiliary Types and Constants::  

File Classes

* Class NcFile::                
* Class NcNewFile::             
* Class NcOldFile::             

Dimensions, Variables, and Attributes

* Class NcDim::                 
* Class NcTypedComponent::      
* Class NcVar::                 
* Class NcAtt::                 

Auxiliary Classes

* Class NcValues::              
* Class NcError::               
@end menu
@end ifinfo

@c Combine the variable and function indices.
@synindex vr fn

@iftex
@finalout
@end iftex

@node Introduction, File Classes, Top, Top
@unnumbered Introduction

This is an early release for a prototype implementation of a C++ interface
for the netCDF data access library.

The main requirements for the design of the C++ interface are:

@itemize @bullet
@item
to provide the functionality of the C interface;
@item
to keep the C++ interface state consistent with the C interface state;
@item
to provide type safety by eliminating all use of @code{void*} pointers; and
@item
to provide an interface that is simpler to use than the C interface.
@end itemize

Some of the features of the C++ interface are:

@itemize @bullet
@item
No IDs needed for netCDF's variables, dimensions, or attributes.
@item
No explicit open or close calls needed for netCDF files; a constructor
opens and a destructor closes a file.
@item
No need to specify types for creating attributes; they will have the
type of the value provided.
@item
No use of @code{void*}: values are type-checked.
@item
Less indirection is needed for dimensions & dimension sizes than with
the C interface.  Dimensions can be given as arguments in variable
definitions.
@item
Code for data types is isolated, which should make the addition of new
types easier.
@item
No explicit @code{ncredef} or @code{ncendef} calls are needed for
switching between define and data modes.  Whenever a mode switch is
required, it happens implicitly.  Note: this may change; there appear to
be advantages to not allowing @code{ncredef} functionality in the C++
interface, but supporting copy semantics and a @code{schema} object
instead.
@end itemize

The header file @file{netcdf.hh} must be included in source code files
using this interface.

This early release provides the functionality of netCDF version 2.02,
but does not yet include member functions corresponding to the netCDF
2.3 generalized hyperslab access interfaces (@code{ncvarputg},
@code{ncvargetg}) or the record I/O interfaces (@code{ncrecinq},
@code{ncrecput}, @code{ncrecget}) in netCDF version 2.3.

This manual assumes familiarity with Chapters 1 through 4 of the netCDF
User's Guide, where the concepts of netCDF dimensions, variables, and
attributes are discussed.

@menu
* Class Hierarchy::             
* Auxiliary Types and Constants::  
@end menu

@page
@node Class Hierarchy, Auxiliary Types and Constants,  , Introduction
@unnumberedsec Class Hierarchy

@display
@group
@code{NcFile}                   abstract base class for files
        @code{NcNewFile}        new netCDF files
        @code{NcOldFile}        existing netCDF files

@code{NcDim}                    dimension

@code{NcTypedComponent}         abstract base class
        @code{NcVar}            variable
        @code{NcAtt}            attribute

@code{NcValues}                 abstract base class for arrays
        @code{NcValues_ncbyte}  array of bytes
        @code{NcValues_char}    array of characters
        @code{NcValues_short}   array of shorts
        @code{NcValues_int}     array of ints
        @code{NcValues_long}    array of longs
        @code{NcValues_float}   array of floats
        @code{NcValues_double}  array of doubles

@code{NcError}                    for error handling
@end group
@end display

@page
@node Auxiliary Types and Constants,  , Class Hierarchy, Introduction
@unnumberedsec Auxiliary Types and Constants

The netCDF classes use several auxiliary types for arguments and return
types from member functions: @code{NcToken}, @code{NcType}, @code{ncbyte},
and @code{NcBool}.

@table @code
@vindex NcToken
@item NcToken
Used for names for netCDF objects, in particular variable names, dimension
names, and attribute names.  Currently this is just a typedef for
@code{const char*}.
@vindex NcType
@item NcType
Used for specifying netCDF value types.  Currently this is an enumerated
type with the following legitimate values:  @code{ncByte},
@code{ncChar}, @code{ncShort}, @code{ncLong}, @code{ncFloat},
@code{ncDouble}, and @code{ncInt}.  The latter is a synonym for @code{ncLong}.
@vindex ncbyte
@item ncbyte
Used to declare values of type @code{ncByte}, analogously to using
the built-in type @code{float} to declare values of type @code{ncFloat}.
This is currently just a typedef for @code{unsigned char}.
@vindex NcBool
@item NcBool
Used for the return type of some member functions.  If the member
function fails, 0 is returned, otherwise some non-zero value.  Currently
this is just a typedef for @code{unsigned int}.
@end table

@page
@node File Classes, NetCDF Components, Introduction, Top
@unnumbered     File Classes

There are three netCDF file classes: @code{NcFile}, @code{NcOldFile},
and @code{NcNewFile}.  The latter two are derived from the
@code{NcFile} abstract base class, which defines all the member
functions except the constructors.

@menu
* Class NcFile::                
* Class NcNewFile::             
* Class NcOldFile::             
@end menu

@vindex NcFile
@node Class NcFile, Class NcNewFile,  , File Classes
@unnumberedsec	Class NcFile

@code{NcFile} is the abstract base class for netCDF file objects.  It
provides all common methods for file operations.  There are no
constructors for @code{NcFile}.  @code{NcOldFile} or @code{NcNewFile}
classes must be used to create @code{NcFile} objects.

Some member functions return pointers to dimensions (@code{NcDim}) or
variables (@code{NcVar}).  These objects are owned by the @code{NcFile}
they are associated with, and will be deleted automatically by the
@code{NcFile} destructor (or by the @code{close} member function, if
this is called earlier than the destructor), so users should not delete
these.  Member functions that return pointers to attributes
(@code{NcAtt}) currently pass ownership to the calling function; users
should delete attributes when they are finished with them.  Note: it
appears that it will be desirable to change the ownership of
@code{NcAtt} objects in the future so that they are owned by their
variables, at which time their destructor will be called when the
associated variable destructor is invoked.

All member functions that return a value of type @code{NcBool} return
@code{TRUE} on success and @code{FALSE} on failure.  All member
functions that return a pointer value return the @code{NULL} pointer on
failure.

This class interface hides the distinction in the C and Fortran
interfaces between @dfn{define mode} (when dimensions, variables, or
attributes are being defined or renamed), and @dfn{data mode} (when data
values are being accessed), by automatically switching between the modes
when necessary.  Users should be aware that switching from accessing
data to adding or renaming dimensions, variables and attributes can be
expensive, since it may entail a copy of the data.

@unnumberedsubsec Public Member Functions

@table @code
@findex ~NcFile
@item ~NcFile( void )
Destructor.  The file is closed and all resources associated with it are
released, including the associated @code{NcVar} and @code{NcDim}
objects.  If you wish to close the file earlier, you may explicitly call
the @code{close} member function; a subsequent destructor call will work
properly.

@findex close
@item NcBool close( void )
Close netCDF file.

@findex is_valid
@item NcBool is_valid( void ) const
Returns @code{TRUE} if valid netCDF file, @code{FALSE} otherwise (e.g.
if constructor could not open file).

@findex num_dims
@item int num_dims( void ) const
Returns the number of dimensions in the netCDF file.

@findex num_vars
@item int num_vars( void ) const
Returns the number of variables in the netCDF file.

@findex num_atts
@item int num_atts( void ) const
Returns the number of global attributes in the netCDF file.

@findex get_dim
@item NcDim* get_dim(NcToken name) const
Get a dimension by name.

@findex get_var
@item NcVar* get_var(NcToken name) const
Get a variable by name.

@findex get_att
@item NcAtt* get_att(NcToken name) const
Get a global attribute by name.

@findex get_dim
@item NcDim* get_dim(int i) const
Get the ith dimension (beginning with the 0th).

@findex get_var
@item NcVar* get_var(int i) const
Get the ith variable (beginning with the 0th).

@findex get_att
@item NcAtt* get_att(int i) const
Get the ith global attribute (beginning with the 0th).

@findex rec_dim
@item NcDim* rec_dim( void ) const
Get the unlimited dimension, if any.

@findex add_dim
@item NcDim* add_dim(NcToken dimname)
Add an unlimited dimension named @code{dimname} to the netCDF file.

@findex add_dim
@item NcDim* add_dim(NcToken dimname, long dimsize)
Add a dimension named @code{dimname} of size @code{dimsize}.

@findex add_var
@item NcVar* add_var(NcToken varname, NcType type, const NcDim* dim0, @dots{} , const NcDim* dim4=0)
Add a variable named @code{varname} of between 1 and 5 dimensions of the
specified type.  Dimension arguments default to 0.  Supply as many
dimensions as needed.  If more than 5 dimensions are required, use the
n-dimensional version of this member function. 

@findex add_var
@item NcVar* add_var(NcToken varname, NcType type, int ndims, const NcDim* dims)
Add a variable named @code{varname} of @code{ndims} dimensions and of
the specified type.  Use this method when dealing with variables of more
than 5 dimensions.

@findex add_att
@item NcBool add_att(NcToken name, char val)
@findex add_att
@itemx NcBool add_att(NcToken name, short val)
@findex add_att
@itemx NcBool add_att(NcToken name, int val)
@findex add_att
@itemx NcBool add_att(NcToken name, long val)
@findex add_att
@itemx NcBool add_att(NcToken name, float val)
@findex add_att
@itemx NcBool add_att(NcToken name, double val)
@findex add_att
@itemx NcBool add_att(NcToken name, const char* val)
Add global scalar attributes of the specified name and with the
supplied value.

@findex add_att
@item  NcBool add_att(NcToken name, int n, const char* val)
@findex add_att
@itemx NcBool add_att(NcToken name, int n, const short* val)
@findex add_att
@itemx NcBool add_att(NcToken name, int n, const int* val)
@findex add_att
@itemx NcBool add_att(NcToken name, int n, const long* val)
@findex add_att
@itemx NcBool add_att(NcToken name, int n, const float* val)
@findex add_att
@itemx NcBool add_att(NcToken name, int n, const double* val)
Add global vector attributes with the specified name and vector value.

@findex set_fill
@item NcBool set_fill( FillMode mode = Fill)
Sets fill-mode to either @code{NcFile::Fill} or @code{NcFile::NoFill}.
Default is @code{Fill}, in which case unwritten values are prewritten
with appropriate type-specific or variable-specific fill values.

@findex get_fill
@item enum NcFile::FillMode get_fill( void ) const
Returns fill mode of the file.

@findex sync
@item NcBool sync( void )
Synchronizes file to disk.

@findex abort
@item NcBool abort( void )
Either just closes file (if recently it has been in data mode as the
result of accessing data), or backs out of the most recent sequence of
changes to the file schema (dimensions, variables, and attributes).
@end table

@page
@vindex NcNewFile
@node Class NcNewFile, Class NcOldFile, Class NcFile, File Classes
@unnumberedsec	Class NcNewFile

This class is derived from the abstract base class @code{NcFile}, and it
is used to create new netCDF files.

@unnumberedsubsec Public Member Functions

@table @code
@findex NcNewFile
@item NcNewFile( const char * path, CreateMode = NoClobber )
The constructor creates a new netCDF file.  If called with a single path
name argument or @code{NcNewFile::NoClobber} for its second argument, it
creates the file only if it does not already exist.  The constructor
will not fail in case of a bad path name or if the file already exists,
but no netCDF file will be created, and the fact that the creation
failed may be checked with the @code{is_valid()} member function.

If called with @code{NcNewFile::Clobber} for its second argument, a
new netCDF file will be created even if the file already exists,
clobbering the old netCDF file.

@findex ~NcNewFile
@item ~NcNewFile( void )
The destructor will close the file, if it has not already been closed
with an explicit call to the @code{close()} member function.

@end table

@page
@vindex NcOldFile
@node Class NcOldFile,  , Class NcNewFile, File Classes
@unnumberedsec	Class NcOldFile

This class is derived from the abstract base class @code{NcFile}, and it
is used to open existing netCDF files, either for read-only access (the
default), or for read-write access.

@unnumberedsubsec Public Member Functions

@table @code
@findex NcOldFile
@item NcOldFile( const char * path, OpenMode = ReadOnly )
The constructor opens an existing netCDF file.  The constructor
will not fail in case of a bad path name or the proper permissions on
the file but no netCDF file will be opened, and the fact that the open
failed may be checked with the @code{is_valid()} member function.

If called with a single path name argument or @code{NcOldFile::ReadOnly}
for its second argument, the file is opened for read-only access.  If
called with @code{NcOldFile::Write} for its second argument, the file
will be opened with read-write access.

@findex ~NcNewFile
@item ~NcNewFile( void )
The destructor will close the file, if it has not already been closed
with an explicit call to the @code{close()} member function.
@end table

@page
@node NetCDF Components, Auxiliary Classes, File Classes, Top
@unnumbered     Dimensions, Variables, and Attributes

The components of a netCDF file are dimensions, variables, and
attributes.  There is a class for each of these kinds of objects;
@code{NcDim}, @code{NcVar}, and @code{NcAtt}.  Variables and attributes
share some common characteristics that are factored out in the
abstract base class @code{NcTypedComponent}.  Users will never declare
@code{NcTypedComponent} instances, but must know about the public member
functions of this class for use with variables and attributes.

@menu
* Class NcDim::                 
* Class NcTypedComponent::      
* Class NcVar::                 
* Class NcAtt::                 
@end menu

@page
@vindex NcDim
@node Class NcDim, Class NcTypedComponent,  , NetCDF Components
@unnumberedsec	Class NcDim

A netCDF dimension has a name and a size.  These are only created and
destroyed by NcFile member functions, because they cannot exist
independently of an open netCDF file.  Hence there are no public
constructors or destructors.

@unnumberedsubsec Public Member Functions

@table @code
@findex name
@item NcToken name( void ) const

Returns the name of the dimension if it exists, 0 otherwise.

@findex size
@item long size( void ) const

Returns the dimension size.

@findex is_valid
@item NcBool is_valid( void ) const

Returns @code{TRUE} if file and dimension are both valid, @code{FALSE}
otherwise.

@findex is_unlimited
@item NcBool is_unlimited( void ) const

Returns @code{TRUE} if the dimension is the unlimited dimension,
@code{FALSE} if either not a valid netCDF file, or if the dimension is
not the unlimited dimension.

@findex rename
@item NcBool rename( NcToken newname )

Renames the dimension to @code{newname}.

@findex id
@item int id( void ) const

Returns the id number of the dimension.  This should almost never be
needed in the C++ interface.

@end table

@page
@vindex NcTypedComponent
@node Class NcTypedComponent, Class NcVar, Class NcDim, NetCDF Components
@unnumberedsec	Class NcTypedComponent

@code{NcTypedComponent} is an abstract base class for @code{NcVar} and
@code{NcAtt} that captures the similarities between netCDF variables and
attributes.

@unnumberedsubsec Public Member Functions

@table @code
@findex name
@item NcToken name( void ) const

Returns the name of the variable or attribute.

@findex type
@item NcType type( void ) const

Returns the type of the variable or attribute.  The type will be one of
@code{ncByte}, @code{ncChar}, @code{ncShort}, @code{ncLong},
@code{ncFloat}, or @code{ncDouble}.

@findex is_valid
@item NcBool is_valid( void ) const

Returns @code{TRUE} if the component is valid, @code{FALSE} otherwise.

@findex num_vals
@item long num_vals( void ) const

Returns the number of values for an attribute or variable.  For an
attribute, this is just 1 for a scalar attribute, the number of values
for a vector-valued attribute, and the number of characters for a
string-valued attribute.  For a variable, this is the product of the
dimension sizes for all the variable's dimensions.

@findex rename
@item NcBool rename( NcToken newname )

Renames the variable or attribute.

@findex values
@item NcValues* values( void )

Returns a pointer to the block of all values for the variable or
attribute.  This will be deleted when the variable or attribute is
destroyed.  Note that this is not a good way to read selected values of
a variable; use the @code{get} member function instead, to get single
values or selected cross-sections of values.

@findex as_ncbyte
@item ncbyte as_ncbyte( int n ) const
@findex as_char
@itemx char as_char( int n ) const
@findex as_short
@itemx short as_short( int n ) const
@findex as_long
@itemx long as_long( int n ) const
@findex as_float
@itemx float as_float( int n ) const
@findex as_double
@itemx double as_double( int n ) const
@findex as_string
@itemx char* as_string( int n ) const

Get the n-th value of the attribute or variable.  These member functions
provide conversions from the value type of the variable or attribute to
the specified type.  If the value is out-of-range, the default
fill-value of the appropriate type should be returned (not yet
implemented).
@end table


@page
@vindex NcVar
@node Class NcVar, Class NcAtt, Class NcTypedComponent, NetCDF Components
@unnumberedsec	Class NcVar

@code{NcVar} is derived from NcTypedComponent, and represents a netCDF
variable.  A netCDF variable has a name, a type, a shape, zero or more
attributes, and a block of values associated with it.  Because variables
are only associated with open netCDF files, there are no public
constructors for this class.  Use member functions of @code{NcFile} to
get netCDF variables.

@unnumberedsubsec Public Member Functions

@table @code
@findex ~NcVar
@item ~NcVar( void )
Destructor.

@findex num_dims
@item int num_dims( void ) const
Returns number of dimensions for this variable.

@findex get_dim
@item NcDim* get_dim( int ) const
Returns a pointer to the n-th dimension (starting at 0).  Returns a
NULL-pointer if an invalid dimension is requested.

@findex edges
@item const long* edges( void ) const
Returns the shape of the variable, in the form of a vector containing
the sizes of the dimensions of the variable.

@findex num_atts
@item int num_atts( void ) const
Returns the number of attributes attached to the variable.

@findex get_att
@item NcAtt* get_att( NcToken ) const
Returns an attribute by name of the variable.  If no such attribute has
been attached to the variable, zero is returned.  Currently, attributes
returned in this way must be deleted by the caller.

@findex get_att
@item NcAtt* get_att( int ) const
Returns the n-th (starting at 0) attribute of the variable.  If no such
attribute has been attached to the variable, zero is returned.
Currently, attributes returned in this way must be deleted by the
caller.

@findex put
@item NcBool put( const char* vals, long c0, long c1, long c2, long c3, long c4 )
@findex put
@itemx NcBool put( const short* vals, long c0, long c1, long c2, long c3, long c4 )
@findex put
@itemx NcBool put( const long* vals, long c0, long c1, long c2, long c3, long c4 )
@findex put
@itemx NcBool put( const int* vals, long c0, long c1, long c2, long c3, long c4 )
@findex put
@itemx NcBool put( const float* vals, long c0, long c1, long c2, long c3, long c4 )
@findex put
@itemx NcBool put( const double* vals, long c0, long c1, long c2, long c3, long c4 )
Write scalar or 1 to 5-dimensional arrays by providing enough arguments.
Arguments are edge lengths, and their number must not exceed variable's
dimensionality.  Start corner is @code{[0,0,..., 0]} by default, but may
be reset using the @code{set_cur()} member function.  @code{FALSE} is
returned if type of values does not match type for variable.  For more
than 5 dimensions, use the overloaded n-dimensional form of the
@code{put} member function.

@findex put
@item  NcBool put( const char* vals, const long* counts )
@findex put
@itemx NcBool put( const short* vals, const long* counts )
@findex put
@itemx NcBool put( const long* vals, const long* counts )
@findex put
@itemx NcBool put( const int* vals, const long* counts )
@findex put
@itemx NcBool put( const float* vals, const long* counts )
@findex put
@itemx NcBool put( const double* vals, const long* counts )
Write n-dimensional arrays, starting at @code{[0, 0, ..., 0]} by
default, may be reset with @code{set_cur()}.  @code{FALSE} is returned
if type of values does not match type for variable.

@findex get
@item  NcBool get( char* vals, long c0, long c1, long c2, long c3, long c4 ) const
@findex get
@itemx NcBool get( short* vals, long c0, long c1, long c2, long c3, long c4 ) const
@findex get
@itemx NcBool get( long* vals, long c0, long c1, long c2, long c3, long c4 ) const
@findex get
@itemx NcBool get( int* vals, long c0, long c1, long c2, long c3, long c4 ) const
@findex get
@itemx NcBool get( float* vals, long c0, long c1, long c2, long c3, long c4 ) const
@findex get
@itemx NcBool get( double* vals, long c0, long c1, long c2, long c3, long c4 ) const
Get scalar or 1 to 5 dimensional arrays by providing enough
arguments.  Arguments are edge lengths, and their number must not
exceed variable's dimensionality.  Start corner is @code{[0,0,..., 0]} by
default, but may be reset using the @code{set_cur()} member function.

@findex get
@item  NcBool get( char* vals, const long* counts ) const
@findex get
@itemx NcBool get( short* vals, const long* counts ) const
@findex get
@itemx NcBool get( long* vals, const long* counts ) const
@findex get
@itemx NcBool get( int* vals, const long* counts ) const
@findex get
@itemx NcBool get( float* vals, const long* counts ) const
@findex get
@itemx NcBool get( double* vals, const long* counts ) const
Get n-dimensional arrays, starting at @code{[0, 0, ..., 0]} by default,
may be reset with @code{set_cur()} member function.

@findex set_cur
@item NcBool set_cur(long c0=-1, long c1=-1, long c2=-1, long c3=-1, long c4=-1)

@findex set_cur
@item NcBool set_cur(long* cur)
Resets the starting corner to the values supplied.  The first form works
for a variable of dimensionality from scalar to 5 dimensions.  For more
than five dimensions, use the second form.  The method returns FALSE if
any argument is greater than the size of the corresponding dimension.

@findex add_att
@item  NcBool add_att( NcToken, char )
@findex add_att
@itemx NcBool add_att( NcToken, short )
@findex add_att
@itemx NcBool add_att( NcToken, int )
@findex add_att
@itemx NcBool add_att( NcToken, long )
@findex add_att
@itemx NcBool add_att( NcToken, float )
@findex add_att
@itemx NcBool add_att( NcToken, double )
@findex add_att
@itemx NcBool add_att( NcToken, const char* )
@findex add_att
@itemx NcBool add_att( NcToken, int, const char* )
@findex add_att
@itemx NcBool add_att( NcToken, int, const short* )
@findex add_att
@itemx NcBool add_att( NcToken, int, const int* )
@findex add_att
@itemx NcBool add_att( NcToken, int, const long* )
@findex add_att
@itemx NcBool add_att( NcToken, int, const float* )
@findex add_att
@itemx NcBool add_att( NcToken, int, const double* )
Add scalar or vector attribute of any type to a variable, given the
name, number of values, and the vector of values.

@findex rename
@item NcBool rename( NcToken newname )
Rename a variable.

@findex id
@item int id( void ) const
Return the variable number.  This is not needed in the C++ interface,
but might be needed in calling a C-function that requires that a variable
be identified by number instead of name.
@end table

@page
@vindex NcAtt
@node Class NcAtt,  , Class NcVar, NetCDF Components
@unnumberedsec	Class NcAtt

@code{NcAtt} is derived from @code{NcTypedComponent}, and represents a netCDF
attribute.  A netCDF attribute has a name and a type, and may be either
a scalar attribute or a vector attribute.  Scalar attributes have one
value and vector attributes have multiple values.  In addition, each
attribute is attached to a specific netCDF variable or is global to an
entire netCDF file.  Because attributes are only associated with open
netCDF files, there are no public constructors for this class.  Use
member functions of @code{NcFile} and @code{NcVar} to get netCDF
attributes.  Most of the useful member functions for @code{NcAtt} are
inherited from class @code{NcTypedComponent}.

@unnumberedsubsec Public Member Functions

@table @code
@findex ~NcAtt
@item ~NcAtt( void )
Destructor.

@findex remove
@item NcBool remove( void )
Deletes the attribute from the file and detaches it from the variable.
Does not call the destructor.  Subsequent calls to @code{is_valid()} will
return @code{FALSE}.
@end table

@page
@node Auxiliary Classes, Function Index, NetCDF Components, Top
@unnumbered  Auxiliary Classes

Auxiliary classes include the abstract base class @code{NcValues}, its
type-specific derived subclasses, and the error-handling class
@code{NcError}.

@menu
* Class NcValues::              
* Class NcError::               
@end menu

@page
@vindex NcValues
@node Class NcValues, Class NcError,  , Auxiliary Classes
@unnumberedsec	Class NcValues

@vindex NcValues_ncbyte
@vindex NcValues_char
@vindex NcValues_short
@vindex NcValues_long
@vindex NcValues_int
@vindex NcValues_float
@vindex NcValues_double
Class @code{NcValues} is an abstract base class for a block of typed
values.  The derived classes are @code{NcValues_ncbyte},
@code{NcValues_char}, @code{NcValues_short}, @code{NcValues_long},
@code{NcValues_int}, @code{NcValues_float}, @code{NcValues_double}.
These classes are used as the return type of the
@code{NcTypedComponent::values()} member function, for typed-value
blocks values associated with variables and attributes.

@unnumberedsubsec Public Member Functions

@table @code
@findex NcValues
@item NcValues( void )
Default constructor.

@findex NcValues
@item NcValues(NcType, long)
Constructor for a value block of the specified type and length.

@findex ~NcValues
@item ~NcValues( void )
Destructor.

@findex num
@item long num( void )
Returns the number of values in the value block.

@findex print
@item ostream& print(ostream&) const
Used to print the comma-delimited sequence of values of the value block.

@findex base
@item void* base( void ) const
Returns a bland pointer to the beginning of the value block.

@findex bytes_for_one
@item int bytes_for_one( void ) const
Returns the number of bytes required for one value.

@findex as_ncbyte
@item ncbyte as_ncbyte( int n ) const
@findex as_char
@itemx char as_char( int n ) const
@findex as_short
@itemx short as_short( int n ) const
@findex as_long
@itemx long as_long( int n ) const
@findex as_float
@itemx float as_float( int n ) const
@findex as_double
@itemx double as_double( int n ) const
@findex as_string
@itemx char* as_string( int n ) const
Provide conversions for the nth value from the value type to a desired
basic type.  If the value is out of range, the default "fill-value" for
the appropriate type is returned.
@end table

@page
@vindex NcError
@node Class NcError,  , Class NcValues, Auxiliary Classes
@unnumberedsec	Class NcError

This class provides control for netCDF error handling.  Declaring an
@code{NcError} object temporarily changes the error-handling behavior
for all netCDF classes until the @code{NcError} object is destroyed
(typically by going out of scope), at which time the previous
error-handling behavior is restored.

@unnumberedsubsec Public Member Functions

@table @code
@findex NcError
@item NcError( Behavior b = verbose_fatal )
The constructor saves the previous error state for restoration when the
destructor is invoked, and sets a new specified state.  Valid error
states are @code{NcError::silent_nonfatal},
@code{NcError::verbose_nonfatal}, @code{NcError::silent_fatal}, or
@code{NcError::verbose_fatal}, to control whether error messages are
output from the underlying library and whether such messages are fatal
or nonfatal.

@findex ~NcError
@item ~NcError( void )
Destructor, restores previous error state.

@findex get_err
@item int get_err( void )
Returns most recent error, as enumerated in @file{netcdf.h}.
@end table

@page
@node Function Index,  , Auxiliary Classes, Top
@unnumbered Class and Member Function Index

@printindex fn

@contents

@c That's all
@bye