cimis-download README    
Carlos A. Rueda
CSTARS - Center for Spatial Technologies and Remote Sensing
University of California, Davis

Contents
	What is cimis-download?
	Limitations
	Changes in version 0.8
	Prerequisite
	Running cimis-download
	Your CIMIS user/password
	Source code
	Copyright
	
	
What is cimis-download?
-----------------------

This is a Java based, command line program that allows you to download
daily and hourly data from the CIMIS website http://wwwcimis.water.ca.gov
in an automated way.

This program has been developed and tested under a Linux system, but
it should run on any machine with a Java Runtime Environment. More
details are given below.

Limitations
-----------

This tool is dependent on the interface used to interact with the
following CIMIS website scripts:

  http://wwwcimis.water.ca.gov/cimis/logon.do
  http://wwwcimis.water.ca.gov/cimis/dailyReport.do
  http://wwwcimis.water.ca.gov/cimis/hourlyReport.do

This interface (field names, formats, protocols) has not been changed
for quite some time, but any unexpected modification may alter the
results or even make the tool useless.


Changes in version 0.8
----------------------

- Able to download daily and hourly data; use --report to specify
  which report is desired.
- Option --append to append data to an existing file.
- Options --from and --to to specify a period of days.
- Option --hours to specify the desired hours in an hourly report.


Prerequisite
------------

A Java Runtime Environment (JRE) is the only prerequisite to be able
to run the program. You can get a JRE for your operating system from 
http://java.sun.com


Running cimis-download
----------------------

A description of general usage is obtained by entering the following
command in a terminal window: 
  java -jar cimis-download.jar --help

Examples:

  java -jar cimis-download.jar --user=myuser --pass=mypassword 
       --report=daily --sensor=DAY_AIR_TMP_AVG --from=2005-06-21
	   --to=2005-06-25 --output=mydaily
  Gets the daily report for average air temperature for the period
  from June 21 to June 25, 2005.  Report is written out to 'mydaily.csv'.

  java -jar cimis-download.jar --user=myuser --pass=mypassword 
       --report=hourly --sensor=HLY_NET_RAD --date=2004-04-21 
	   --hours=1200,1300,1400  --output=myhourly
  Gets the hourly report for net radiation, April 21, 2004 at hours 1200,
  1300, and 1400.  Report is written out to 'myhourly.csv'.

NOTE:
  Output file is always recreated unless --append is specified.
  An extension suffix is given according to method (methods NON
  and CSV give extension '.csv' and method WEB gives extension '.html'

  NO ERROR CHECKING IS DONE on the obtained report from the CIMIS
  website! So, you should check the contents of the output file for
  possible errors, which may occur due to imposed limits on result
  size or unexpected changes in protocol communication from the data
  provider.


Your CIMIS user/password
------------------------

Please notice that you need to be registered in the CIMIS website to
be able to download data. So you need to specify the --user and --pass
options accordingly.


Source code
-----------

Point your browser to:
 http://cvs.casil.ucdavis.edu/cgi-bin/cvsweb.cgi/src/CIMIS/?cvsroot=goes

 src/edu/ucdavis/edu/cimis/Downloader.java
	Defines the Java class that performs the download.
	
 classes/com/sonalb*   (including subdirectories)
 	Java library for cookie handling. (http://jcookie.sf.net/)
 	Not actually source files but compiled classes. 
	The jCookie library code is © Sonal Bansal, 2001-2002
	and released under the GNU LGPL v2.1.
 	
 classes/gnu/getopt/*
 	Java port of the GNU getopt functions
	(http://www.urbanophile.com/arenn/hacking/download.html)
 	Source files and compiled classes.
	Distribution terms: GNU Library GPL.
	
 build.xml
 	Build file to be used with the Apache Ant tool. See below.
	
Compiling the tool: 
	Once you have the files above in place and assuming you have 
	installed the Apache Ant tool, http://ant.apache.org/, just type: 
		ant
	the executable JAR file will be created.
	

Copyright
---------

Below is the copyright agreement for the usage of this tool.

Copyright (c) 2004-2005 The Regents of the University of California.
All rights reserved.

Permission is hereby granted, without written agreement and without
license or royalty fees, to use, copy, modify, and distribute this
software and its documentation for any purpose, provided that the above
copyright notice and the following two paragraphs appear in all copies
of this software.

IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
ENHANCEMENTS, OR MODIFICATIONS.

----------------------------------------------------------------------
$Id: README.txt,v 1.15 2005/06/30 19:05:36 crueda Exp $