\input texinfo @c -*-texinfo-*-
@comment $Id: libcf.texi,v 1.1.1.1 2009/07/06 15:06:30 ed Exp $
@c %**start of header
@setfilename libcf.info
@settitle The CF Library Users Guide 
@setcontentsaftertitlepage
@c Combine the variable, concept, and function indices.
@synindex vr cp
@synindex fn cp
@c %**end of header

@c version.texi is automatically generated by automake and contains
@c defined variables VERSION, UPDATED, UPDATED-MONTH.
@include version.texi
@include defines.texi

@ifinfo
@dircategory netCDF CF Library
@direntry
* libcf: (libcf).         @value{libcf-man}
@end direntry
@end ifinfo

@titlepage
@title @value{libcf-man}
@subtitle Version @value{VERSION}
@subtitle @value{UPDATED-MONTH}
@author Ed Hartnett
@author Unidata Program Center
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@ifnottex
@node Top, Summary, (dir), (dir)
@top @value{libcf-man}

This guide describes libcf, the netCDF CF Library. This document
applies to libcf version @value{VERSION}, and was last updated on
@value{UPDATED}.

@end ifnottex

@menu
* Summary::                     
* Installation::                
* cfcheck::                     
* Files::                       
* Variables::                   
* Coordinates::                 
* Combined Index::              
@end menu

@node Summary, Installation, Top, Top
@unnumbered Summary
@cindex supported programming languages
@cindex API, C
@cindex API, Fortran
@cindex API, F90

The CF conventions for climate and forecast metadata are designed to
promote the processing and sharing of files created with the netCDF
API.

This library, libcf, makes it easier to create and work with data
files which conform to the CF conventions.

The functions of the CF library are intended to be interspersed with
netCDF library calls. That is, the programmer will open or create a
netCDF file with the netCDF API, and then add or read metadata with
libcf library functions, then continue to working with the netCDF API
to read and write data.

By using libcf, a data producer can produce files that conform to the
CF standards, without having to write netCDF code to create and decode
all the attributes that the CF convention uses to store meta-data. A
data consumer can use libcf to read any file which conforms to the CF
conventions; the file does not need to be created with libcf to be
read by libcf.

Fortran-77 wrapper functions provide a Fortran 77 API, just as is done
with netCDF itself. A Fortran 90 API is planned, but not yet begun.

For more information about the CF Conventions, see the CF Metadata
web site at @uref{@value{cf-url}}.

@node Installation, cfcheck, Summary, Top
@unnumbered Downloading and Installing libcf

Currently, and for some time to come, libcf is in alpha release. The
code is tested, but not extensively. The API may be extended, and
possibly changed, in each release.

You must have either netCDF-3 (or netCDF-4) installed. And reasonably
recent version of netCDF should work. libcf is tested with netCDF
3.6.2-beta4.

Get the latest version of the libcf tarball at the libcf ftp site:
@value{ftp-site}

Unpack the tarball, and run:

@example
./configure --with-netcdf=/my/netcdf --prefix=/my/libcf && make check install > output.txt
@end example

Where /my/netcdf is the root install directory of the netCDF library
you want to use, and /my/libcf is the root directory where you want
libcf installed. (They may be the same directory.) 

If you wish to use netCDF-4, you must also have HDF5 and libz, the
compression library, installed. In this case, configure libcf like
this:

@example
./configure --with-netcdf=/s/n4_new1/install --enable-netcdf-4 --with-hdf5=/home/ed/local/s && make check install > output.txt
@end example

If the build does not work for you, please email libcf support:
@value{libcf-support-email}. Please send the *complete* output of the
configure and build output, in ASCII (the output.txt file produced by
the above build commands), and the file config.log, which is generated
by the configure script.

@node cfcheck, Files, Installation, Top
@chapter The cfcheck Utility

The cfchck utility will chck a file to see if it contains valid CF
metadata. Messages about the file are printed to stdout.

@node Files, Variables, cfcheck, Top
@chapter Files

@menu
* nccf_def_convention::         
* nccf_inq_convention::         
* nccf_def_file::               
* nccf_inq_file::               
* nccf_add_history::            
@end menu

@node nccf_def_convention, nccf_inq_convention, Files, Files
@section Mark a File as Conforming to CF Conventions

Mark the file as following CF-1.0 conventions.

This functions is called automatically by nccf_def_file, so need not
be called by the user if nccf_def_file is being called.

@heading Usage 

@example
   int nccf_def_convention(int ncid);
@end example

@table @code

@item ncid
The ncid of the file.

@end table

@heading Return Codes

This function returns zero for success, or a netCDF error code for
failure.

@heading Example 

@example
@end example
 
@node nccf_inq_convention, nccf_def_file, nccf_def_convention, Files
@section Determine if a File Claims to Conform to CF Conventions

Determine if the file claims to follow CF-1.0 conventions. This
function only checks the global ``Conventions'' attribute. It does not
look at file metadata to ensure that this is a well-formed CF file. It
only tells whether the file claims to be a CF file.

@heading Usage 

@example
   int nccf_inq_convention(int ncid, int *cf_convention);
@end example

@table @code

@item ncid
The ncid of the file.

@item cf_conventions
If this pointer to an int is provided, a 1 is written there if this
file claims to follow CF 1.0 conventions, a 0 otherwise.

@end table

@heading Return Codes

This function returns zero for success, or a netCDF error code for
failure.

@heading Example 

@example
@end example
 
@node nccf_def_file, nccf_inq_file, nccf_inq_convention, Files
@section Add description to the data with nccf_def_file

Add some or all of the CF recommended text attributes to a file. Any
parameters which are set to NULL will be ignored.

@heading Usage 

@example
int nccf_def_file(int ncid, char *title, char *history, char *institution, 
                  char *source, char *comment, char *references);
@end example


@table @code

@item ncid
The ncid of the file.

@item title
If non-NULL, this text string will be written as the CF-recommended
``title'' attribute.

@item history
If non-NULL, this text string will be written as the CF-recommended
``history'' attribute.

@item institution
If non-NULL, this text string will be written as the CF-recommended
``institution'' attribute.

@item source
If non-NULL, this text string will be written as the CF-recommended
``source'' attribute.

@item comment
If non-NULL, this text string will be written as the CF-recommended
``comment'' attribute.

@item references
If non-NULL, this text string will be written as the CF-recommended
``references'' attribute.

@end table

@heading Return Codes

This function returns zero for success, or a netCDF error code for
failure.

@heading Example 

@example
@end example
 
@node nccf_inq_file, nccf_add_history, nccf_def_file, Files
@section Read the description of the data with nccf_inq_file

Read any existing CF recommended text attributes from the file.

Recall that in C, strlens do not include the null terminator. To get
the lengths before the strings (in order to allocated) pass NULL for
any or all strings and the lengths will be returned. Then call the
function again after allocating memory.

The CF version is guaranteed to be less than NC_MAX_NAME.

Any of these pointer arguments may be NULL, in which case it will be
ignored.

@heading Usage 

@example
int nccf_inq_file(int ncid, size_t *title_lenp, char *title, 
                  size_t *history_lenp, char *history, 
                  size_t *institution_lenp, char *institution, 
                  size_t *source_lenp, char *source, 
                  size_t *comment_lenp, char *comment,
                  size_t *references_lenp, char *references);
@end example


@table @code

@item ncid
The ncid of the file.

@item title_lenp
Pointer to size_t which, if not NULL, will get the length of the title
attribute.

@item title
Pointer to char array which, if not NULL, will get the title
string. Memory must be allocated before this function is called. Call
this function with a NULL for this parameter to get the size first.

@item history_lenp
Pointer to size_t which, if not NULL, will get the length of the history
attribute.

@item history
Pointer to char array which, if not NULL, will get the history
string. Memory must be allocated before this function is called. Call
this function with a NULL for this parameter to get the size first.

@item institution_lenp
Pointer to size_t which, if not NULL, will get the length of the institution
attribute.

@item institution
Pointer to char array which, if not NULL, will get the institution
string. Memory must be allocated before this function is called. Call
this function with a NULL for this parameter to get the size first.

@item source_lenp
Pointer to size_t which, if not NULL, will get the length of the source
attribute.

@item source
Pointer to char array which, if not NULL, will get the source
string. Memory must be allocated before this function is called. Call
this function with a NULL for this parameter to get the size first.

@item comment_lenp
Pointer to size_t which, if not NULL, will get the length of the comment
attribute.

@item comment
Pointer to char array which, if not NULL, will get the comment
string. Memory must be allocated before this function is called. Call
this function with a NULL for this parameter to get the size first.

@item references_lenp
Pointer to size_t which, if not NULL, will get the length of the references
attribute.

@item references
Pointer to char array which, if not NULL, will get the references
string. Memory must be allocated before this function is called. Call
this function with a NULL for this parameter to get the size first.

@end table

@heading Return Codes

This function returns zero for success, or a netCDF error code for
failure.

@heading Example 

@example
@end example
 
@node nccf_add_history,  , nccf_inq_file, Files
@section Append to a History Attribute

This function appends a time-stamped history string to the history
attribute, creating the attribute if it doesn't already exist.

@heading Usage 

@example
int nccf_add_history(int ncid, const char *history);
@end example

@table @code

@item ncid
The ncid of the file.

@item history
The string to append to the history attribute. 

@end table

@heading Return Codes

This function returns zero for success, or a netCDF error code for
failure.

@heading Example 

@example
@end example
 
@node Variables, Coordinates, Files, Top
@chapter Variables

@menu
* nccf_def_var::                
* nccf_inq_var::                
* nccf_def_var_missing::        
* nccf_inq_var_missing::        
* nccf_def_notes::              
* nccf_inq_notes::              
* nccf_def_latitude::           
* nccf_inq_latitude::           
* nccf_def_longitude::          
* nccf_inq_longitude::          
* nccf_def_lvl::                
* nccf_inq_lvl::                
* nccf_def_lvl_vert::           
* nccf_inq_lvl_vert::           
* nccf_def_time::               
* nccf_inq_time::               
* nccf_def_ft_sigma::           
* nccf_inq_lvl_sigma::          
* nccf_def_ft_hybrid_sigma::    
* nccf_inq_lvl_hybrid_sigma::   
* nccf_def_ft_hybrid_height::   
* nccf_inq_lvl_hybrid_height::  
* nccf_def_ft_sleve::           
* nccf_inq_lvl_sleve::          
* nccf_def_ft_ocean_sigma::     
* nccf_inq_lvl_ocean_sigma::    
* nccf_def_ft_ocean_s::         
* nccf_inq_lvl_ocean_s::        
* nccf_def_ft_ocean_sigma_z::   
* nccf_inq_lvl_ocean_sigma_z::  
* nccf_def_ft_ocean_dbl_sigma::  
* nccf_inq_lvl_ocean_dbl_sigma::  
* nccf_get_vara::               
@end menu

@node nccf_def_var, nccf_inq_var, Variables, Variables
@section Add description to a variable with nccf_def_var

@heading Usage 

@example
int nccf_def_var(int ncid, int varid, const char *units, 
                    const char *long_name, const char *standard_name, 
                    int ncoord_vars, int *coord_varids);
@end example

@table @code

@item ncid
The ncid of the file.

@item varid
The varid of the netCDF variable being described.

@item units
If non-NULL, this text string will be written as the CF-recommended
``units'' attribute.

@item long_name
If non-NULL, this text string will be written as the CF-recommended
``long_name'' attribute.

@item standard_name
If non-NULL, this text string will be written as the CF-recommended
``standard_name'' attribute.

@item ncoord_vars
Number of coordinate variables for this variable.

@item coord_varids
The variable IDs of the coordinate variables for this variable.

@end table

@heading Return Codes

This function returns zero for success, or a netCDF error code for
failure.

@heading Example 

@example
@end example
 
@node nccf_inq_var, nccf_def_var_missing, nccf_def_var, Variables
@section Read variable description with nccf_inq_var

Read any existing CF recommended text attributes from a variable. 

@heading Usage 

@example
int nccf_inq_var(int ncid, int varid, size_t *units_lenp, char *units, 
                 size_t *long_name_lenp, char *long_name, 
                 size_t *standard_name_lenp, char *standard_name,
                 int *ncoord_vars, int *coord_varids);

@end example

@table @code

@item ncid
The ncid of the file.

@item varid
The varid of the netCDF variable.

@item units_lenp
Pointer to size_t which, if not NULL, will get the length of the units
attribute.

@item units
Pointer to char array which, if not NULL, will get the long_name
string. Memory must be allocated before this function is called. Call
this function with a NULL for this parameter to get the size first.

@item long_name_lenp
Pointer to size_t which, if not NULL, will get the length of the long_name
attribute.

@item long_name
Pointer to char array which, if not NULL, will get the long_name
string. Memory must be allocated before this function is called. Call
this function with a NULL for this parameter to get the size first.

@item standard_name_lenp
Pointer to size_t which, if not NULL, will get the length of the standard_name
attribute.

@item standard_name
Pointer to char array which, if not NULL, will get the standard_name
string. Memory must be allocated before this function is called. Call
this function with a NULL for this parameter to get the size first.

@item ncoord_vars
Pointer to an integer, which, if non-NULL, will get the number of
coordinate variables identified in the ``coordinates'' attribute.

@item coord_varids
Pointer to an array of integer, which, if non-NULL, will be filled
with the variable IDs of the variables listed int he ``coordinates''
attribute.

@end table

@heading Return Codes

This function returns zero for success, or a netCDF error code for
failure.

@heading Example 

@example
@end example
 
@node nccf_def_var_missing, nccf_inq_var_missing, nccf_inq_var, Variables
@section Define missing data values for a variable with nccf_def_var_missing
nccf_def_notes

This function sets the ``fill_value'', ``valid_min'', and
``valid_max'' attributes.

@heading Usage 

@example
int nccf_def_var_missing(int ncid, int varid, const void *fill_valuep, 
                            const void *valid_minp, const void *valid_maxp);
@end example

@table @code

@item ncid
The ncid of the file.

@item varid
The varid of the netCDF variable being described. 

@item fill_valuep
If non-NULL, this will point to a value of the same type as this
varid, which will be used as the fill_value for the data.

@item valid_minp
If non-NULL, this will point to a value of the same type as this
varid, which will be written as the ``valid_min'' attribute. If this
parameter is non-NULL, valid_max must also be provided.

@item valid_maxp
If non-NULL, this will point to a value of the same type as this
varid, which will be written as the ``valid_max'' attribute. If this
parameter is non-NULL, valid_min must also be provided.

@end table

@heading Return Codes

This function returns zero for success, or an error code for
failure.

@heading Example 

@example
@end example
 
@node nccf_inq_var_missing, nccf_def_notes, nccf_def_var_missing, Variables
@section Learn about missing data settings with nccf_inq_var_missing

Get attributes which define missing data information. If the
attributes are not there, then provide the valid data anyway, based on
netCDF defaults.

@heading Usage 

@example
int nccf_inq_var_missing(int ncid, int varid, void *fill_valuep, 
                            void *valid_minp, void *valid_maxp);
@end example

@table @code

@item ncid
The ncid of the file.

@item varid
The varid of the netCDF variable.

@item fill_valuep
If this is not NULL, the fill value of the variable will be written at
this address by nccf_inq_var_missing. If the fill value was not
defined for the variable, the netCDF default value will be used.

@item valid_minp
If this is not NULL, the valid_min value of the variable will be
written at this address by nccf_inq_var_missing. If the valid_min was
not defined for the variable, the netCDF default value will be used.

@item valid_maxp
If this is not NULL, the valid_max value of the variable will be
written at this address by nccf_inq_var_missing. If the valid_max
value was not defined for the variable, the netCDF default value will
be used.

@end table

@heading Return Codes

This function returns zero for success, or an error code for failure.

@heading Example 

@example
@end example
 
@node nccf_def_notes, nccf_inq_notes, nccf_inq_var_missing, Variables
@section Add CF-Recommended Metadata to a File or Variable with
nccf_def_notes

This functions writes up to four text attributes for either a
variable, or an entire file. These text attributes, ``institution,''
``source,'' ``comment,'' and ``references'' are recommended by the CF
Metadata Convention.

@heading Usage 

@example
int nccf_def_notes(int ncid, int varid, char *units, char *long_name, 
                   char *standard_name, char *institution, 
                   char *source, char *comment, char *references);
@end example

@table @code

@item ncid
The ncid of the file.

@item varid
The varid of the netCDF variable being described. Use NC_GLOBAL if you
wish these attributes to apply to the entire file.

@item institution
If non-NULL, this text string will be written as the CF-recommended
``institution'' attribute.

@item source
If non-NULL, this text string will be written as the CF-recommended
``source'' attribute.

@item comment
If non-NULL, this text string will be written as the CF-recommended
``comment'' attribute.

@item references
If non-NULL, this text string will be written as the CF-recommended
``references'' attribute.

@end table

@heading Return Codes

This function returns zero for success, or a netCDF error code for
failure.

@heading Example 

@example
@end example
 
@node nccf_inq_notes, nccf_def_latitude, nccf_def_notes, Variables
@section Read variable description with nccf_inq_notes

Read any existing CF recommended text attributes from a variable. 

@heading Usage 

@example
int nccf_inq_notes(int ncid, int varid, 
                   size_t *institution_lenp, char *institution, 
                   size_t *source_lenp, char *source, 
                   size_t *comment_lenp, char *comment, 
                   size_t *references_lenp, char *references);
@end example

@table @code

@item ncid
The ncid of the file.

@item varid
The varid of the netCDF variable.

@item institution_lenp
Pointer to size_t which, if not NULL, will get the length of the institution
attribute.

@item institution
Pointer to char array which, if not NULL, will get the institution
string. Memory must be allocated before this function is called. Call
this function with a NULL for this parameter to get the size first.

@item source_lenp
Pointer to size_t which, if not NULL, will get the length of the source
attribute.

@item source
Pointer to char array which, if not NULL, will get the source
string. Memory must be allocated before this function is called. Call
this function with a NULL for this parameter to get the size first.

@item comment_lenp
Pointer to size_t which, if not NULL, will get the length of the comment
attribute.

@item comment
Pointer to char array which, if not NULL, will get the comment
string. Memory must be allocated before this function is called. Call
this function with a NULL for this parameter to get the size first.

@item references_lenp
Pointer to size_t which, if not NULL, will get the length of the references
attribute.

@item references
Pointer to char array which, if not NULL, will get the references
string. Memory must be allocated before this function is called. Call
this function with a NULL for this parameter to get the size first.

@end table

@heading Return Codes

This function returns zero for success, or a netCDF error code for
failure.

@heading Example 

@example
@end example
 
@node nccf_def_latitude, nccf_inq_latitude, nccf_inq_notes, Variables
@section Define a coordinate variable and dimension for latitude with nccf_def_latitude

Define a coordinate variable and dimension with all the CF
recommended attribute accessories for latitude.

@heading Usage 

@example
int nccf_def_latitude(int ncid, size_t len, nc_type xtype, 
                         const char *formula_terms, int *lat_dimidp, 
                         int *lat_varidp);
@end example

@table @code

@item ncid
The ncid of the file.

@item len
The length of this coordinate dimension.

@item xtype
The type of this coordinate variable.

@item formula_terms
If non-NULL, a string which will be written as the ``formula_terms''
attribute on the coordinate variable.

@item lat_dimidp
If non-NULL, nccf_def_latitude will write the dimension ID of the
netCDF dimension for the latitude here.

@item lat_varidp
If non-NULL, nccf_def_latitude will write the variable ID of the
netCDF coordinate variable for the latitude here.

@end table

@heading Return Codes

This function returns zero for success, or an error code for
failure.

@heading Example 

@example
@end example
 
@node nccf_inq_latitude, nccf_def_longitude, nccf_def_latitude, Variables
@section Learn about a latitude coordinate variable and dimension with
nccf_inq_latitude

Inquire about a latitude dimension and coordinate variable. 

@heading Usage 

@example
int nccf_inq_latitude(int ncid, size_t *lenp, nc_type *xtypep, 
                         size_t *ft_lenp, char *formula_terms, 
                         int *lat_dimidp, int *lat_varidp);
@end example

@table @code

@item ncid
The ncid of the file.

@item lenp
If non-NULL, the length of the latitude dimension will be written
here by nccf_inq_latitude.

@item xtypep
If non-NULL, the type of the coordinate variable will be written here.

@item ft_lenp
If non-NULL, the length of the value of the ``formula_terms''
attribute will be written here by ft_lenp. If there is no
``formula_terms'' attribute, zero will be written.

@item lat_dimidp
If non-NULL, the dimid of the latitude dimension will be written here.

@item lat_varidp
If non-NULL, the varid of the latitude coordinate variable will be
written here.

@end table

@heading Return Codes

This function returns zero for success, or an error code for failure.

@heading Example 

@example
@end example
 
@node nccf_def_longitude, nccf_inq_longitude, nccf_inq_latitude, Variables
@section Define a coordinate variable and dimension for longitude with nccf_def_longitude

Define a coordinate variable and dimension with all the CF
recommended attribute accessories for longitude.

@heading Usage 

@example
int nccf_def_longitude(int ncid, size_t len, nc_type xtype, 
                         const char *formula_terms, int *lon_dimidp, 
                         int *lon_varidp);
@end example

@table @code

@item ncid
The ncid of the file.

@item len
The length of this coordinate dimension.

@item xtype
The type of this coordinate variable.

@item formula_terms
If non-NULL, a string which will be written as the ``formula_terms''
attribute on the coordinate variable.

@item lon_dimidp
If non-NULL, nccf_def_longitude will write the dimension ID of the
netCDF dimension for the longitude here.

@item lon_varidp
If non-NULL, nccf_def_longitude will write the variable ID of the
netCDF coordinate variable for the longitude here.

@end table

@heading Return Codes

This function returns zero for success, or an error code for
failure.

@heading Example 

@example
@end example
 
@node nccf_inq_longitude, nccf_def_lvl, nccf_def_longitude, Variables
@section Learn about a longitude coordinate variable and dimension with
nccf_inq_longitude

Inquire about a longitude dimension and coordinate variable. 

@heading Usage 

@example
int nccf_inq_longitude(int ncid, size_t *lenp, nc_type *xtypep, 
                         size_t *ft_lenp, char *formula_terms, 
                         int *lon_dimidp, int *lon_varidp);
@end example

@table @code

@item ncid
The ncid of the file.

@item lenp
If non-NULL, the length of the longitude dimension will be written
here by nccf_inq_longitude.

@item xtypep
If non-NULL, the type of the coordinate variable will be written here.

@item ft_lenp
If non-NULL, the length of the value of the ``formula_terms''
attribute will be written here by ft_lenp. If there is no
``formula_terms'' attribute, zero will be written.

@item lon_dimidp
If non-NULL, the dimid of the longitude dimension will be written here.

@item lon_varidp
If non-NULL, the varid of the longitude coordinate variable will be
written here.

@end table

@heading Return Codes

This function returns zero for success, or an error code for failure.

@heading Example 

@example
@end example
 
@node nccf_def_lvl, nccf_inq_lvl, nccf_inq_longitude, Variables
@section Define a coordinate variable and dimension for level with nccf_def_lvl

Define a coordinate variable and dimension with all the CF
recommended attribute accessories for a vertical level.

@heading Usage 

@example
int nccf_def_lvl(int ncid, const char *name, size_t len, nc_type xtype, 
                 const char *units, int positive_up, const char *standard_name, 
                 const char *long_name, const char *formula_terms, 
                 int *lvl_dimidp, int *lvl_varidp);
@end example

@table @code

@item ncid
The ncid of the file.

@item name
The name of the coordinate dimension and variable.

@item len
The length of this coordinate dimension and variable.

@item xtype
The type of this coordinate variable.

@item units
If non-NULL, a string which will be written as the ``units''
attribute on the coordinate variable.

@item positive_up
Set to 0 and the attribute ``positive'' to ``down''. Set to any other
value to get ``up''.

@item standard_name
If non-NULL, a string which will be written as the ``standard_name''
attribute on the coordinate variable.

@item long_name
If non-NULL, a string which will be written as the ``long_name''
attribute on the coordinate variable.

@item lon_dimidp
If non-NULL, nccf_def_lvl will write the dimension ID of the
netCDF dimension for the level here.

@item lon_varidp
If non-NULL, nccf_def_lvl will write the variable ID of the
netCDF coordinate variable for the level here.

@end table

@heading Return Codes

This function returns zero for success, or an error code for
failure.

@heading Example 

@example
@end example
 
@node nccf_inq_lvl, nccf_def_lvl_vert, nccf_def_lvl, Variables
@section Learn about a level coordinate variable and dimension with
nccf_inq_lvl

Inquire about a level dimension and coordinate variable. 

@heading Usage 

@example
int nccf_inq_lvl(int ncid, char *name, size_t *lenp, nc_type *xtypep, 
                 size_t *ft_lenp, char *formula_terms, int *positive_upp, 
                 int *lvl_dimidp, int *lvl_varidp);
@end example

@table @code

@item ncid
The ncid of the file.

@item name
If non-NULL, the name of this vertical level dimension (and variable)
will be written here.

@item lenp
If non-NULL, the length of the level dimension will be written
here by nccf_inq_lvl.

@item xtypep
If non-NULL, the type of the coordinate variable will be written here.

@item ft_lenp
If non-NULL, the length of the value of the ``formula_terms''
attribute will be written here by ft_lenp. If there is no
``formula_terms'' attribute, zero will be written.

@item positive_upp
If non-NULL, a one will be written here if the ``positive'' attribute
of this coordinate variable is ``up'', a zero will be written if it is
``down''.

@item lvl_dimidp
If non-NULL, the dimid of the level dimension will be written here.

@item lvl_varidp
If non-NULL, the varid of the level coordinate variable will be
written here.

@end table

@heading Return Codes

This function returns zero for success, or an error code for failure.

@heading Example 

@example
@end example
 
@node nccf_def_lvl_vert, nccf_inq_lvl_vert, nccf_inq_lvl, Variables
@section Define a coordinate variable and dimension for level with nccf_def_lvl

Define a unitless vertical coordinate variable and dimension from
Apendix D of the CF Convention, with all the CF recommended attribute
accessories for a vertical level.

@heading Usage 

@example
int nccf_def_lvl_vert(int ncid, int lvl_type, const char *name, nc_type xtype, 
                      size_t len, int *lvl_dimidp, int *lvl_varidp);
@end example

@table @code

@item ncid
The ncid of the file.

@item lvl_type
One of: CF_VERT_ATM_LN, CF_VERT_SIGMA, CF_VERT_HYBRID_SIGMA,
CF_VERT_HYBRID_HEIGHT, CF_VERT_SLEVE, CF_VERT_OCEAN_SIGMA,
CF_VERT_OCEAN_S, CF_VERT_OCEAN_SIGMA_Z, CF_VERT_OCEAN_DBL_SIGMA.

@item name
The name of the coordinate dimension and variable.

@item xtype
The type of this coordinate variable.

@item len
The length of this coordinate dimension and variable.

@item lvl_dimidp
If non-NULL, the function will write the dimension ID of the
netCDF dimension for the level here.

@item llvl_varidp
If non-NULL, the function will write the variable ID of the
netCDF coordinate variable for the level here.

@end table

@heading Return Codes

This function returns zero for success, or an error code for
failure.

@heading Example 

@example
@end example
 
@node nccf_inq_lvl_vert, nccf_def_time, nccf_def_lvl_vert, Variables
@section Learn about a level coordinate variable and dimension with
nccf_inq_lvl

Inquire about a level dimension and coordinate variable. 

@heading Usage 

@example
int nccf_inq_lvl_vert(int ncid, char *name, nc_type *xtypep, size_t *lenp, 
                      int *lvl_typep, int *lvl_dimidp, int *lvl_varidp);
@end example

@table @code

@item ncid
The ncid of the file.

@item name
If non-NULL, the name of this vertical level dimension (and variable)
will be written here.

@item xtypep
If non-NULL, the type of the coordinate variable will be written here.

@item lenp
If non-NULL, the length of the level dimension will be written
here.

@item lvl_typep
If non-NULL, the type of vertical dimension will be written here, one
of CF_VERT_ATM_LN, CF_VERT_SIGMA, CF_VERT_HYBRID_SIGMA,
CF_VERT_HYBRID_HEIGHT, CF_VERT_SLEVE, CF_VERT_OCEAN_SIGMA,
CF_VERT_OCEAN_S, CF_VERT_OCEAN_SIGMA_Z, CF_VERT_OCEAN_DBL_SIGMA.

@item lvl_dimidp
If non-NULL, the dimid of the level dimension will be written here.

@item lvl_varidp
If non-NULL, the varid of the level coordinate variable will be
written here.

@end table

@heading Return Codes

This function returns zero for success, or an error code for failure.

@heading Example 

@example
@end example
 
@node nccf_def_time, nccf_inq_time, nccf_inq_lvl_vert, Variables
@section Define a coordinate variable and dimension for time with nccf_def_time

Define a coordinate variable and dimension with all the CF
recommended attribute accessories for time.

@heading Usage 

@example
int nccf_def_time(int ncid, const char *name, size_t len, nc_type xtype, 
                     const char *units, const char *standard_name, const char *long_name, 
                     const char *formula_terms, int *time_dimidp, int *time_varidp);
@end example

@table @code

@item ncid
The ncid of the file.

@item len
The length of this coordinate dimension.

@item xtype
The type of this coordinate variable.

@item formula_terms
If non-NULL, a string which will be written as the ``formula_terms''
attribute on the coordinate variable.

@item lon_dimidp
If non-NULL, nccf_def_time will write the dimension ID of the
netCDF dimension for the time here.

@item lon_varidp
If non-NULL, nccf_def_time will write the variable ID of the
netCDF coordinate variable for the time here.

@end table

@heading Return Codes

This function returns zero for success, or an error code for
failure.

@heading Example 

@example
@end example
 
@node nccf_inq_time, nccf_def_ft_sigma, nccf_def_time, Variables
@section Learn about a time coordinate variable and dimension with
nccf_inq_time

Inquire about a time dimension and coordinate variable. 

@heading Usage 

@example
int nccf_inq_time(int ncid, size_t *lenp, nc_type *xtypep, size_t *ft_lenp, 
                     char *formula_terms, int *time_dimidp, int *time_varidp);
@end example

@table @code

@item ncid
The ncid of the file.

@item lenp
If non-NULL, the length of the time dimension will be written
here by nccf_inq_time.

@item xtypep
If non-NULL, the type of the coordinate variable will be written here.

@item ft_lenp
If non-NULL, the length of the value of the ``formula_terms''
attribute will be written here by ft_lenp. If there is no
``formula_terms'' attribute, zero will be written.

@item formula_terms
If non-NULL the value of the ``formula_terms'' attribute, if any, will
be copied here.

@item time_dimidp
If non-NULL, the dimid of the time dimension will be written here.

@item time_varidp
If non-NULL, the varid of the time coordinate variable will be
written here.

@end table

@heading Return Codes

This function returns zero for success, or an error code for failure.

@heading Example 

@example
@end example
 
@node nccf_def_ft_sigma, nccf_inq_lvl_sigma, nccf_inq_time, Variables
@section Define atmosphere sigma coordinate.

Define formula terms attribute for atmosphere sigma coordinate variable.

@heading Usage 

@example
int nccf_def_ft_sigma(int ncid, int varid, int ps_varid, int ptop_varid);

@end example

@table @code

@item ncid
The ncid of the file.

@item varid 
The varid of the vertical coordinate variable.

@item ps_varid
The variable ID of the ps variable.

@item ptop_varid
The variable ID of the ptop variable.

@end table

@heading Return Codes

This function returns zero for success, or an error code for
failure.

@heading Example 

@example
@end example
 
@node nccf_inq_lvl_sigma, nccf_def_ft_hybrid_sigma, nccf_def_ft_sigma, Variables
@section Inquire about atmosphere sigma coordinate.
nccf_inq_time

Inquire about atmosphere sigma coordinate.

@heading Usage 

@example
int nccf_inq_lvl_sigma(int ncid, char *name, nc_type *xtypep, size_t *lenp, 
                       int *ps_varidp, int *ptop_varidp, int *lvl_dimidp, 
                       int *lvl_varidp);
@end example

@table @code

@item ncid
The ncid of the file.

@item name
If non-NULL, this pointer gets the name of the coordinate variable and
dimension.     

@item xtypep
If non-NULL, the type of the coordinate variable will be written here.

@item lenp
If non-NULL, the length of the coordinate dimension will be written
here.

@item ps_varidp
If non-NULL, the variable ID of the ps variable will be written
here.

@item ptop_varidp
If non-NULL, the variable ID of the ptop variable will be written
here.

@item lvl_dimidp
If non-NULL, the dimid of the coordinate dimension will be written here.

@item lvl_varidp
If non-NULL, the varid of the coordinate variable will be written
here.

@end table

@heading Return Codes

This function returns zero for success, or an error code for failure.

@heading Example 

@example
@end example
 
@node nccf_def_ft_hybrid_sigma, nccf_inq_lvl_hybrid_sigma, nccf_inq_lvl_sigma, Variables
@section Define atmosphere sigma coordinate.

Define formula terms attribute for atmosphere hybrid sigma coordinate
variable.

@heading Usage 

@example
int nccf_def_ft_hybrid_sigma(int ncid, int varid, int a_varid, int b_varid, 
                             int ps_varid, int p0_varid);
@end example

@table @code

@item ncid
The ncid of the file.

@item varid 
The varid of the vertical coordinate variable.

@item a_varid
The variable ID of the a variable.

@item b_varid
The variable ID of the b variable.

@item ps_varid
The variable ID of the ps variable.

@item ptop_varid
The variable ID of the ptop variable.

@end table

@heading Return Codes

This function returns zero for success, or an error code for
failure.

@heading Example 

@example
@end example
 
@node nccf_inq_lvl_hybrid_sigma, nccf_def_ft_hybrid_height, nccf_def_ft_hybrid_sigma, Variables
@section Inquire about atmosphere sigma coordinate.

Inquire about atmosphere hybrid sigma coordinate.

@heading Usage 

@example
int nccf_inq_lvl_hybrid_sigma(int ncid, char *name, nc_type *xtypep, 
                              size_t *lenp, int *a_varidp, int *b_varidp, 
                              int *ps_varidp, int *p0_varidp, int *lvl_dimidp, 
                              int *lvl_varidp);
@end example

@table @code

@item ncid
The ncid of the file.

@item name
If non-NULL, this pointer gets the name of the coordinate variable and
dimension.     

@item xtypep
If non-NULL, the type of the coordinate variable will be written here.

@item lenp
If non-NULL, the length of the coordinate dimension will be written
here.

@item a_varidp
If non-NULL, the variable ID of the a variable will be written
here.

@item b_varidp
If non-NULL, the variable ID of the b variable will be written
here.

@item ps_varidp
If non-NULL, the variable ID of the ps variable will be written
here.

@item ptop_varidp
If non-NULL, the variable ID of the ptop variable will be written
here.

@item lvl_dimidp
If non-NULL, the dimid of the coordinate dimension will be written here.

@item lvl_varidp
If non-NULL, the varid of the coordinate variable will be written
here.

@end table

@heading Return Codes

This function returns zero for success, or an error code for failure.

@heading Example 

@example
@end example
 
@node nccf_def_ft_hybrid_height, nccf_inq_lvl_hybrid_height, nccf_inq_lvl_hybrid_sigma, Variables
@section The formula_terms attribute for atmosphere hybrid height

Define formula terms attribute for atmosphere hybrid height
coordinate variable

@heading Usage 

@example
int nccf_def_ft_hybrid_height(int ncid, int varid, int a_varid, int b_varid, 
                              int orog_varid);
@end example

@table @code

@item ncid
The ncid of the file.

@item varid 
The varid of the vertical coordinate variable.

@item a_varid
The variable ID of the a variable.

@item b_varid
The variable ID of the b variable.

@item orog_varid
The variable ID of the orog variable.

@end table

@heading Return Codes

This function returns zero for success, or an error code for
failure.

@heading Example 

@example
@end example
 
@node nccf_inq_lvl_hybrid_height, nccf_def_ft_sleve, nccf_def_ft_hybrid_height, Variables
@section Inquire about hybrid height coordinate.

Inquire about the hybrid height coordinate.

@heading Usage 

@example
int nccf_inq_lvl_hybrid_height(int ncid, char *name, nc_type *xtypep, size_t *lenp,
                               int *a_varidp, int *b_varidp, int *orog_varidp,
                               int *lvl_dimidp, int *lvl_varidp);
@end example

@table @code

@item ncid
The ncid of the file.

@item name
If non-NULL, this pointer gets the name of the coordinate variable and
dimension.     

@item xtypep
If non-NULL, the type of the coordinate variable will be written here.

@item lenp
If non-NULL, the length of the coordinate dimension will be written
here.

@item a_varidp
If non-NULL, the variable ID of the a variable will be written
here.

@item b_varidp
If non-NULL, the variable ID of the b variable will be written
here.

@item orog_varidp
If non-NULL, the variable ID of the orog variable will be written
here.

@item lvl_dimidp
If non-NULL, the dimid of the coordinate dimension will be written here.

@item lvl_varidp
If non-NULL, the varid of the coordinate variable will be written
here.

@end table

@heading Return Codes

This function returns zero for success, or an error code for failure.

@heading Example 

@example
@end example
 
@node nccf_def_ft_sleve, nccf_inq_lvl_sleve, nccf_inq_lvl_hybrid_height, Variables
@section Define atmosphere sleve coordinate.

Define formula terms attribute for the atmosphere sleve coordinate
variable.

@heading Usage 

@example
int nccf_def_ft_sleve(int ncid, int varid, int a_varid, int b1_varid, 
                      int b2_varid, int ztop_varid, int zsurf1_varid, 
                      int zsurf2_varid);
@end example

@table @code

@item ncid
The ncid of the file.

@item varid 
The varid of the vertical coordinate variable.

@item a_varid
The variable ID of the a variable.

@item b1_varid
The variable ID of the b1 variable.

@item b2_varid
The variable ID of the b2 variable.

@item ztop_varid
The variable ID of the ztop variable.

@item zsurf1_varid
The variable ID of the zsurf1 variable.

@item zsurf2_varid
The variable ID of the zsurf2 variable.

@end table

@heading Return Codes

This function returns zero for success, or an error code for
failure.

@heading Example 

@example
@end example
 
@node nccf_inq_lvl_sleve, nccf_def_ft_ocean_sigma, nccf_def_ft_sleve, Variables
@section Inquire About Sleve Coordinate.

Inquire about the sleve coordinate.

@heading Usage 

@example
int nccf_inq_lvl_sleve(int ncid, char *name, nc_type *xtypep, size_t *lenp,
                       int *a_varidp, int *b1_varidp, int *b2_varidp, int *ztop_varidp,
                       int *zsurf1_varidp, int *zsurf2_varidp, int *lvl_dimidp,
                       int *lvl_varidp);
@end example

@table @code

@item ncid
The ncid of the file.

@item name
If non-NULL, this pointer gets the name of the coordinate variable and
dimension.     

@item xtypep
If non-NULL, the type of the coordinate variable will be written here.

@item lenp
If non-NULL, the length of the coordinate dimension will be written
here.

@item a_varidp
If non-NULL, the variable ID of the a variable will be written
here.

@item b1_varidp
If non-NULL, the variable ID of the b1 variable will be written
here.

@item b2_varidp
If non-NULL, the variable ID of the b2 variable will be written
here.

@item ztop_varidp
If non-NULL, the variable ID of the ztop variable will be written
here.

@item zsurf1_varidp
If non-NULL, the variable ID of the zsurf1 variable will be written
here.

@item zsurf2_varidp
If non-NULL, the variable ID of the zsurf2 variable will be written
here.

@item lvl_dimidp
If non-NULL, the dimid of the coordinate dimension will be written here.

@item lvl_varidp
If non-NULL, the varid of the coordinate variable will be written
here.

@end table

@heading Return Codes

This function returns zero for success, or an error code for failure.

@heading Example 

@example
@end example
 
@node nccf_def_ft_ocean_sigma, nccf_inq_lvl_ocean_sigma, nccf_inq_lvl_sleve, Variables
@section Define Ocean Sigma Coordinate.

Define the formula terms attribute for the ocean sigma coordinate variable.

@heading Usage 

@example
int nccf_def_ft_ocean_sigma(int ncid, int varid, int eta_varid, int depth_varid);
@end example

@table @code

@item ncid
The ncid of the file.

@item varid 
The varid of the vertical coordinate variable.

@item eta_varid
The variable ID of the eta variable.

@item depth_varid
The variable ID of the depth variable.

@end table

@heading Return Codes

This function returns zero for success, or an error code for
failure.

@heading Example 

@example
@end example
 
@node nccf_inq_lvl_ocean_sigma, nccf_def_ft_ocean_s, nccf_def_ft_ocean_sigma, Variables
@section Inquire About Ocean Sigma Coordinate.

Inquire about the ocean sigma coordinate.

@heading Usage 

@example
int nccf_inq_lvl_ocean_sigma(int ncid, char *name, nc_type *xtypep, size_t *lenp,
                             int *eta_varidp, int *depth_varidp, int *lvl_dimidp,
                             int *lvl_varidp);
@end example

@table @code

@item ncid
The ncid of the file.

@item name
If non-NULL, this pointer gets the name of the coordinate variable and
dimension.     

@item xtypep
If non-NULL, the type of the coordinate variable will be written here.

@item lenp
If non-NULL, the length of the coordinate dimension will be written
here.

@item eta_varidp
If non-NULL, the variable ID of the eta variable will be written
here.

@item lvl_dimidp
If non-NULL, the dimid of the coordinate dimension will be written here.

@item lvl_varidp
If non-NULL, the varid of the coordinate variable will be written
here.

@end table

@heading Return Codes

This function returns zero for success, or an error code for failure.

@heading Example 

@example
@end example
 
@node nccf_def_ft_ocean_s, nccf_inq_lvl_ocean_s, nccf_inq_lvl_ocean_sigma, Variables
@section Define Ocean S Coordinate.

Define ocean s coordinate.

@heading Usage 

@example
int nccf_def_ft_ocean_s(int ncid, const char *name, nc_type xtype, size_t len,
                         int eta_varid, int depth_varid, int a_varid, int b_varid,
                         int depth_c_varid, int *lvl_dimidp, int *lvl_varidp);
@end example

@table @code

@item ncid
The ncid of the file.

@item varid 
The varid of the vertical coordinate variable.

@item xtype
The type of this coordinate variable.

@item len
The length of this coordinate dimension.

@item eta_varid
The variable ID of the eta variable.

@item depth_varid
The variable ID of the depth variable.

@item a_varid
The variable ID of the a variable.

@item b_varid
The variable ID of the b variable.

@item depth_c_varid
The variable ID of the depth_c variable.

@item lvl_dimidp
If non-NULL, the dimension ID of the netCDF coordinate dimension will
be written here.

@item lvl_varidp
If non-NULL, the variable ID of the netCDF coordinate variable will be
written here.

@end table

@heading Return Codes

This function returns zero for success, or an error code for
failure.

@heading Example 

@example
@end example
 
@node nccf_inq_lvl_ocean_s, nccf_def_ft_ocean_sigma_z, nccf_def_ft_ocean_s, Variables
@section Inquire About Ocean S Coordinate.
nccf_inq_time

Inquire about the ocean s coordinate.

@heading Usage 

@example
int nccf_inq_lvl_ocean_s(int ncid, char *name, nc_type *xtypep, size_t *lenp,
                         int *eta_varidp, int *depth_varidp, int *a_varidp, int *b_varidp,
                         int *depth_c_varidp, int *lvl_dimidp, int *lvl_varidp);
@end example

@table @code

@item ncid
The ncid of the file.

@item name
If non-NULL, this pointer gets the name of the coordinate variable and
dimension.     

@item xtypep
If non-NULL, the type of the coordinate variable will be written here.

@item lenp
If non-NULL, the length of the coordinate dimension will be written
here.

@item eta_varidp
If non-NULL, the variable ID of the eta variable will be written
here.

@item depth_varidp
If non-NULL, the variable ID of the depth variable will be written
here.

@item a_varidp
If non-NULL, the variable ID of the a variable will be written
here.

@item b_varidp
If non-NULL, the variable ID of the b variable will be written
here.

@item depth_c_varidp
If non-NULL, the variable ID of the depth_c variable will be written
here.

@item lvl_dimidp
If non-NULL, the dimid of the coordinate dimension will be written here.

@item lvl_varidp
If non-NULL, the varid of the coordinate variable will be written
here.

@end table

@heading Return Codes

This function returns zero for success, or an error code for failure.

@heading Example 

@example
@end example
 
@node nccf_def_ft_ocean_sigma_z, nccf_inq_lvl_ocean_sigma_z, nccf_inq_lvl_ocean_s, Variables
@section Define Ocean Sigma Z Coordinate.

Define ocean sigma z coordinate.

@heading Usage 

@example
int nccf_def_ft_ocean_sigma_z(int ncid, const char *name, nc_type xtype,
                               size_t len, int eta_varid, int depth_varid,
                               int depth_c_varid, int nsigma_varid,
                               int zlev_varid, int *lvl_dimidp, int *lvl_varidp);
@end example

@table @code

@item ncid
The ncid of the file.

@item varid 
The varid of the vertical coordinate variable.

@item xtype
The type of this coordinate variable.

@item len
The length of this coordinate dimension.

@item eta_varid
The variable ID of the eta variable.

@item depth_varid
The variable ID of the depth variable.

@item depth_c_varid
The variable ID of the depth_c variable.

@item nsigma_varid
The variable ID of the nsigma variable.

@item zlev_varid
The variable ID of the zlev variable.

@item lvl_dimidp
If non-NULL, the dimension ID of the netCDF coordinate dimension will
be written here.

@item lvl_varidp
If non-NULL, the variable ID of the netCDF coordinate variable will be
written here.

@end table

@heading Return Codes

This function returns zero for success, or an error code for
failure.

@heading Example 

@example
@end example
 
@node nccf_inq_lvl_ocean_sigma_z, nccf_def_ft_ocean_dbl_sigma, nccf_def_ft_ocean_sigma_z, Variables
@section Inquire About Ocean Sigma Z Coordinate.

Inquire about the ocean sigma z coordinate.

@heading Usage 

@example
int nccf_inq_lvl_ocean_sigma_z(int ncid, char *name, nc_type *xtypep, size_t *lenp,
                               int *eta_varidp, int *depth_varidp, int *depth_c_varidp,
                               int *nsigma_varidp, int *zlev_varidp, int *lvl_dimidp,
                               int *lvl_varidp);
@end example

@table @code

@item ncid
The ncid of the file.

@item name
If non-NULL, this pointer gets the name of the coordinate variable and
dimension.     

@item xtypep
If non-NULL, the type of the coordinate variable will be written here.

@item lenp
If non-NULL, the length of the coordinate dimension will be written
here.

@item eta_varidp
If non-NULL, the variable ID of the eta variable will be written
here.

@item depth_varidp
If non-NULL, the variable ID of the depth variable will be written
here.

@item depth_c_varidp
If non-NULL, the variable ID of the depth_c variable will be written
here.

@item nsigma_varidp
If non-NULL, the variable ID of the nsigma variable will be written
here.

@item zlev_varidp
If non-NULL, the variable ID of the zlev variable will be written
here.

@item lvl_dimidp
If non-NULL, the dimid of the coordinate dimension will be written here.

@item lvl_varidp
If non-NULL, the varid of the coordinate variable will be written
here.

@end table

@heading Return Codes

This function returns zero for success, or an error code for failure.

@heading Example 

@example
@end example
 
@node nccf_def_ft_ocean_dbl_sigma, nccf_inq_lvl_ocean_dbl_sigma, nccf_inq_lvl_ocean_sigma_z, Variables
@section Define Ocean Double Sigma Coordinate.

Define ocean double sigma coordinate.

@heading Usage 

@example
int nccf_def_ft_ocean_dbl_sigma(int ncid, const char *name, nc_type xtype, size_t len,
                                 int depth_varid, int z1_varid, int z2_varid, int a_varid,
                                 int href_varid, int k_c_varid, int *lvl_dimidp,
                                 int *lvl_varidp);
@end example

@table @code

@item ncid
The ncid of the file.

@item varid 
The varid of the vertical coordinate variable.

@item xtype
The type of this coordinate variable.

@item len
The length of this coordinate dimension.

@item depth_varid
The variable ID of the depth variable.

@item z1_varid
The variable ID of the z1 variable.

@item z2_varid
The variable ID of the z2 variable.

@item a_varid
The variable ID of the a variable.

@item href_varid
The variable ID of the href variable.

@item k_c_varid
The variable ID of the k_c variable.

@item lvl_dimidp
If non-NULL, the dimension ID of the netCDF coordinate dimension will
be written here.

@item lvl_varidp
If non-NULL, the variable ID of the netCDF coordinate variable will be
written here.

@end table

@heading Return Codes

This function returns zero for success, or an error code for
failure.

@heading Example 

@example
@end example
 
@node nccf_inq_lvl_ocean_dbl_sigma, nccf_get_vara, nccf_def_ft_ocean_dbl_sigma, Variables
@section Inquire About Ocean Double Sigma Coordinate.

Inquire about the ocean double sigma coordinate.

@heading Usage 

@example
int nccf_inq_lvl_ocean_dbl_sigma(int ncid, char *name, nc_type *xtypep, size_t *lenp,
                                 int *depth_varidp, int *z1_varidp, int *z2_varidp,
                                 int *a_varidp, int *href_varidp, int *k_c_varidp,
                                 int *lvl_dimidp, int *lvl_varidp);
@end example

@table @code

@item ncid
The ncid of the file.

@item name
If non-NULL, this pointer gets the name of the coordinate variable and
dimension.     

@item xtypep
If non-NULL, the type of the coordinate variable will be written here.

@item lenp
If non-NULL, the length of the coordinate dimension will be written
here.

@item depth_varidp
If non-NULL, the variable ID of the depth variable will be written
here.

@item z1_varidp
If non-NULL, the variable ID of the z1 variable will be written
here.

@item z2_varidp
If non-NULL, the variable ID of the z2 variable will be written
here.

@item a_varidp
If non-NULL, the variable ID of the a variable will be written
here.

@item href_varidp
If non-NULL, the variable ID of the href variable will be written
here.

@item k_c_varidp
If non-NULL, the variable ID of the k_c variable will be written
here.

@item lvl_dimidp
If non-NULL, the dimid of the coordinate dimension will be written here.

@item lvl_varidp
If non-NULL, the varid of the coordinate variable will be written
here.

@end table

@heading Return Codes

This function returns zero for success, or an error code for failure.

@heading Example 

@example
@end example
 
@node nccf_get_vara,  , nccf_inq_lvl_ocean_dbl_sigma, Variables
@section Get a geographic subset of the data.

Get a geographic subset of the data.

@heading Usage 

@example
   int nccf_get_vara(int ncid, int varid, float *lat_bounds, int *nlat, float *lon_bounds, 
		     int *nlon, int *lvl_index, int *nlvl, int rec, void *data);
@end example

@table @code

@item ncid
The ncid of the file.

@item varid
The varid of the data variable from which the subset will be taken.

@item lat_bounds
A length two array, this holds the latitude start and stop values for
the range of interest.

@item nlat
A pointer to an integer which will get the number of latitude values
which fall within the range.

@item lon_bounds
A length two array, this holds the longitude start and stop values for
the range of interest. (Wrapping around the dateline is not allowed!)

@item nlon
A pointer to an integer which will get the number of longitude values
which fall within the range.

@item lvl_index
A zero-based index number for the verticle level of interest to the
subsetter. (Ignored if data has no vertical axis).

@item timestep
A zero-based index number for the timestep of interest to the
subsetter. (Ignored if data has no time axis).

@item data
A pointer to which the data subset will be written. Memory must be
allocated (and deallocated) by the user.

@end table

@heading Return Codes

This function returns zero for success, or an error code for failure.

@heading Example 

@example
@end example
 
@node Coordinates, Combined Index, Variables, Top
@chapter Coordinate Systems

@menu
* nccf-def-axis-type::          
* nccf-inq-axis-type::          
* nccf-def-coord-system::       
* nccf-inq-coord-system::       
* nccf-assign-coord-system::    
* nccf-def-transform::          
* nccf-inq-transform::          
* nccf-assign-transform::       
@end menu

@node nccf-def-axis-type, nccf-inq-axis-type, Coordinates, Coordinates
@section Label the axis type of a coordinate var with nccf_def_axis_type

@heading Usage 

@example
int
nccf_def_axis_type(int ncid, int varid, int axis_type);
@end example

@table @code

@item ncid
The ncid of the file.

@end table

@heading Return Codes

This function returns zero for success, or a netCDF error code for
failure.

@heading Example 

@example
@end example
 
@node nccf-inq-axis-type, nccf-def-coord-system, nccf-def-axis-type, Coordinates
@section Find out the axis type of a coordinate var with nccf_inq_axis_type

@heading Usage 

@example
int
nccf_inq_axis_type(int ncid, int varid, int *axis_type);
@end example


@table @code

@item ncid
The ncid of the file.

@end table

@heading Return Codes

This function returns zero for success, or a netCDF error code for
failure.

@heading Example 

@example
@end example
 
@node nccf-def-coord-system, nccf-inq-coord-system, nccf-inq-axis-type, Coordinates
@section Define a coordinate system with nccf_def_coord_system

@heading Usage 

@example
int
nccf_def_coord_system(int ncid, const char *name, int naxes, int *axis_varids, 
                    int *system_varid);
@end example

Define a coordinate system consisting of naxes axes, each axis
represented by a coordinate varid in the axis_varids array. This
create a new (scalar, NC_CHAR) var, whose varid is returned in
system_varid.


@table @code

@item ncid
The ncid of the file.

@end table

@heading Return Codes

This function returns zero for success, or a netCDF error code for
failure.

@heading Example 

@example
@end example
 
@node nccf-inq-coord-system, nccf-assign-coord-system, nccf-def-coord-system, Coordinates
@section Find out about a coordinate system with nccf_inq_coord_system

@heading Usage 

@example
int
nccf_inq_coord_system(int ncid, int system_varid, char *name, 
                    int *naxes, int *axis_varids);
@end example

Find out about a coordinate system, it's name, number of axes, and the
varid of each axis coordinate var.


@table @code

@item ncid
The ncid of the file.

@end table

@heading Return Codes

This function returns zero for success, or a netCDF error code for
failure.

@heading Example 

@example
@end example
 
@node nccf-assign-coord-system, nccf-def-transform, nccf-inq-coord-system, Coordinates
@section Assign a coordinate system to a var with nccf_assign_coord_system

@heading Usage 

@example
int
nccf_assign_coord_system(int ncid, int varid, int system_varid);
@end example

Assign a coordinate system to a var. This adds an attribute to the
var.


@table @code

@item ncid
The ncid of the file.

@end table

@heading Return Codes

This function returns zero for success, or a netCDF error code for
failure.

@heading Example 

@example
@end example
 
@node nccf-def-transform, nccf-inq-transform, nccf-assign-coord-system, Coordinates
@section Define a coordinate transform with nccf_def_transform

@heading Usage 

@example
int
nccf_def_transform(int ncid, const char *name, const char *transform_type, 
                 const char *transform_name, int *transform_varid);
@end example

Define a coordinate transform. This adds a (scalar, NC_CHAR) var,
which contains some attributes. The varid of this new variable is
returned in transform_varid.


@table @code

@item ncid
The ncid of the file.

@end table

@heading Return Codes

This function returns zero for success, or a netCDF error code for
failure.

@heading Example 

@example
@end example
 
@node nccf-inq-transform, nccf-assign-transform, nccf-def-transform, Coordinates
@section Find out about a coordinate transform with nccf_inq_transform

@heading Usage 

@example
int
nccf_inq_transform(int ncid, int transform_varid, char *name, size_t *type_len, 
                 char *transform_type, size_t *name_len, char *transform_name);
@end example

Find out about a coordinate transform, it's name, and the contents
of the transform_type and transform_name attributes. Pass NULL for
any that you're not interested in. Pass NULL for transform_type and
transform_name to get their lengths with type_len and name_len.


@table @code

@item ncid
The ncid of the file.

@end table

@heading Return Codes

This function returns zero for success, or a netCDF error code for
failure.

@heading Example 

@example
@end example
 
@node nccf-assign-transform,  , nccf-inq-transform, Coordinates
@section Assign a coordinate transform to a coordinate system with nccf_assign_transform

@heading Usage 

@example
int
nccf_assign_transform(int ncid, int system_varid, int transform_varid);
@end example

Assign a coordinate transform to a coordinate system. This adds an
attribute to the variable that holds the coordinate system
attributes.


@table @code

@item ncid
The ncid of the file.

@end table

@heading Return Codes

This function returns zero for success, or a netCDF error code for
failure.

@heading Example 

@example
@end example
 
@node Combined Index,  , Coordinates, Top
@unnumbered Index

@printindex cp

@bye
End:
