
$Id: README,v 1.10 2005/05/13 20:55:16 jimg Exp $

Updated for version 3.5.1 beta of the DAP netCDF Client Library.

For information about building the DAP netCDF 3 Client Library, see the
INSTALL file.

----------------------------------------------------------------------------

This file contains information about the OPeNDAP netCDF Client Library
software. For information about building the software, see the file INSTALL.
For the latest news about this software, see NEWS.

Using this library, virtually any program which uses netCDF 3.x to read data
can read from hundreds of DAP-enabled data sources located all over the
Internet. In most cases using the library is as simple a relinking your
program. 

For more information about OPeNDAP, see http://www.opendap.org/

The libnc-dap library included in this distribution is a client-server
implementation of the Unidata netCDF API, which uses the DAP2 protocol to
communicate with suitable data servers. libnc-dap contains a new
implementation of the netCDF library which can be linked with programs which
currently are built with the standard implementation of the API.

The libnc-dap library mirrors the standard implementation of the netCDF API
very closely. Many software packages have been developed for netCDF data
display and analysis; rebuilding these packages with the nc-dap library
instead of the original netCDF library makes them capable of accessing data
over the network through the provided server software. The user can refer to
the entire remote dataset using a URL instead of the local file name.
Furthermore, if the user wants to work only with a small part of the data
set, a constraint expression can be supplied along with the URL to save on
network data transmission time.

The current libnc-dap client library software supports the C programming
interface and the Fortran Jacket of the netCDF 3.4 for UNIX platform. We have
also built a win32 version of an earlier release of this software and will
probably update that to match this software.

You can obtain a copy of the latest version of the libnc-dap software from
http://www.opendap.org/download/nc-dods.html. 

Included in this distribution are: 

 - The netCDF client library,
 - The Fortran jackets for the library,
 - dncdump: A DAP-enabled client built by relinking the standard ncdump
   utility with the library.
 - test programs, and documentation.

REPORTING PROBLEMS

If you encounter problems using this software, please report them to
dods-tech@unidata.ucar.edu. This list requires a subscription; see 
http://www.opendap.org/mailLists/index.html for more information. 

RELINKING USER SOFTWARE

If you're going to recompile your software as part of the re-linking process
(recommended) then use 'ncdap-config --cflags' to get options which should be
passed to a c/c++ compiler. Currently this passes the correct header
directory so that your compilation will use libnc-dap's version of the header
file in place of the stock netCDF header. (The headers are installed in
$prefix/include/libnc-dap). If you're compiling a Fortran program, use
--fflags in place of --cflags.

To re-link an existing C or CPP program with libnc-dap, you do just that.
Find the directory that contains the source code and modify the Makefile for
the program so that in place of the netCDF library the OPeNDAP library is
used. Because OPeNDAP software is implemented as a core set of classes that
are then specialized for each re-implemented API, the re-linking of a program
involves several libraries. These libraries are:

	libdap++.a:	 The core software and its dependents
	libnc-dap.a:	 The software special to the netCDF implementation

Once built and installed, these libraries will be in /usr/local/lib/ by
default. Use the script ncdap-config to find the files, check the version, et
cetera. Use the --help option to see on-line help. Relinking with libnc-dap
can seem daunting at first because libdap++ uses many other libraries, either
directly of indirectly. However, the ncdap-config script has options which
tell exactly which libraries, and in what order, your program should link
with for your specific binary build of libdap++ and linbnc-dap. Use the
--libs option of ncdap-config to get that information.

To relink a Fortran program, use the ncdap-config script to determine which
Fortran compiler (ncdap-config --fc) and the libraries needed. For the latter
you will need to use the  --flibs option. 

Note that our support for Fortran is essentially limited to the GNU
compilers. If you use other compilers, we'll try to help, but cannot make any
guarantees...

Once re-linked, the program will work exactly as before when run using local
files. However, users can also give URLs to specify data files. In this case
the machine name part of the URL must reference a machine which has data
accessible via a DAP data server (see www.opendap.org for information about
servers, both getting and installing them as well as finding existing ones).
Suppose that a friend has told you about a data file named `fnoc3.nc' in a
directory called `data' on a machine named test.opendap.org. To look at this
data invoke ncdump using the URL for this data in place of a simple filename.
E.G.:

       dncdump http://test.opendap.org/opendap/nph-dods/data/fnoc3.nc

       ^^^^^^        ^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^ ^^^^ ^^^^^^^^ 
       Program	     Machine name     Server         Dir  File     
	      
And to look at the first 10 elements of an array variable named `u' in this
data file, you can use a constraint as a URL parameter. E.G.:

       dncdump http://test.opendap.org/odap-3.4/nph-dods/data/fnoc3.nc?u[0:9]

       ^^^^^^        ^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^ ^^^^ ^^^^^^^^ ^^^^^^
       Program	     Machine name     Server         Dir  File     Constraint
	      
The User's Guide and Quick Start Guide at www.opendap.org/support/ contain
many more examples and an explanation of the Constraint Expressions which can
be used when requesting data.


