
===================================
README  -  CF Checker version 2.0.6
===================================

To run the CF file conformance checker you must have the following 
installed on your system:

     - Python 2.5
     - UDUNITS2
     - CDMS (part of CDAT-5.x)


Notes on CDMS install
---------------------

The CDMS module is part of the CDAT distribution available from the
PCMDI software portal (http://www2-pcmdi.llnl.gov/cdat/).

You can either install the entire CDAT distribution or alternatively 
use the CDAT-lite_ package.

.. _CDAT-lite: http://pypi.python.org/pypi/cdat-lite


Notes on UDUNITS-2 install
--------------------------
The UDUNITS-2 package can be obtained from the unidata website
(http://www.unidata.ucar.edu/software/udunits)


To run the CF checker
---------------------

Once you have both UDUNITS-2 and CDMS installed you need to complete the 
following steps in order to run the CF Checker.

1. Make sure that the location of the cdms library is in your PYTHONPATH

   E.g. export PYTHONPATH=/home/rsh/software/CDAT-5.2-cdms/lib/python2.5/site-packages

2. Make sure that the path to the udunits libraries are in the system 
   library path or alternatively set the environment variable LD_LIBRARY_PATH

   E.g. export LD_LIBRARY_PATH=$PREFIX/lib    

   where $PREFIX is the --prefix option you passed to the configure script 
   when installing udunits.

3. Depending on the platform you are installing on, you may need to edit
   the name of the udunits2 library in the cfchecks.py script.  If the name
   of the library is anything other than libudunits2.so then you will need to
   modify, as appropriate, the line

   udunits=CDLL("libudunits2.so")

4. You may also need to modify the path to the python interpreter at the top 
   of the cfchecks.py script.

5. Run the checker by typing:
      cfchecks.py <netCDF_file.nc>

Environment Variables
---------------------

The following parameters can be set on the command-line or through environment variables:

 1. UDUNITS : The path to udunits2.xml.  Usually $UDUNITS_HOME/share/udunits/udunits2.xml
 2. CF_STANDARD_NAMES : The path or URL to the CF standard names table
 3. CF_AREA_TYPES : The path or URL to the CF area types tables


If you have any problems or comments please contact Rosalyn Hatcher
(r.s.hatcher@reading.ac.uk)

Wrapper script
--------------

A wrapper to cfchecks, called "cf-checker", is provided in the src/
directory, which will maintain local copies of the standard names
table and the area types table, and will refresh these local copies
only if the age of the file (based on its modification time) is more
than a specified maximum, defaulting to 1 day.  This allows for
running the checker repeatedly without refetching the tables on each
invocation, while still keeping them reasonably up to date.

For a usage message, type "cf-checker -h"

Note that the wrapper defaults to storing the downloaded files in
/var/spool/cf-checker, so if the script is used unmodified then this
directory should be created or else an alternative value should be
passed as a command line option ("-d").  Ensure either that all users
have write permission to the directory used, or else that a user that
does have write permission runs a cron job to refresh the tables.  For
the latter purpose, it is permissible to run the wrapper without
specifying any data files to check, in which it will do no more than
update the tables; this is still conditional on age, so for this
purpose it is recommended to run the wrapper with a maximum age of
zero ("-t 0"), and to run the cron job at intervals not exceeding the
default maximum age.

The wrapper is maintained by CEDA and not by NCAS CMS.
