
This is the ACE level 1, browse, and ancillary software package. The routines
in this package are intended to help you access ACE level 1 and browse data
from C programs. The version number of this package changes in step with the
version of the ACE level 1 datasets. That sometimes means that the contents
of this package will not change when the version number changes.

****** See the Changelog below for details of changes in this package. ******

The package will unzip into a directory called "acetest".  acetest contains a
number of subdirectories, whose contents are described briefly below.  Other
README files within the subdirs may give more details.

These routines are "bare-bones". You are expected to be able to read the C
header files which describe each of the data structures, and modify the code
so that it does what you want. Makefiles in each of the subdirectories will
need to be modified before compiling the code.

More documentation is available from the ASC web site,
http://www.srl.caltech.edu/ASC/ACE.

To get help, send email to asc@srl.caltech.edu.

This package should always be available by ftp, from
mussel.srl.caltech.edu, in pub/ace/software.

Description of directories below "acetest".
-------------------------------------------

anciltest   routines to access ACE ancillary data HDF file,
            ACE_ANCIL.HDF

avgbrtst    routines to access ACE_BROWSE.HDF, which contains ACE
            5minute, 1hour and daily browse parameters.

	    ACE_ANCIL.HDF and ACE_BROWSE.HDF can be obtained from
	    the ASC web site or anon ftp site.

rawbrtst    routines to access raw browse parameter files. Raw browse
            parameters are generated during level 1 processing, and
	    the time periods are tied to the instrument cycle times.
	    There is one raw browse parameter file for each day of the
	    mission. ACE_BROWSE.HDF is created from the raw browse
	    parameter files.

hdfsubs     hdf subroutines used to access ACE data structures

include     C header files

edbtest     routines to read Expt Data Records (EDBs) from level 1
            data files. SWICS and SWIMS data is stored in EDBs.

striptest   routines to strip a data subset from one HDF file and write
            it out to another HDF file.

schktest    routines to access ACE spacecraft housekeeping data

cristest    routines to access CRIS level 1 data structures
epamtest    routines to access EPAM level 1 data structures
magtest     routines to access MAG  level 1 data structures
sepicatest  routines to access SEPICA level 1 data structures
sistest     routines to access SIS  level 1 data structures
swetest     routines to access SWEPAM Electron level 1 data structures
switest     routines to access SWEPAM Ion level 1 data structures
swicstest   routines to access SWICS level 1 housekeeping
            SWICS level 1 data is contained in the EDBs
swimstest   routines to access SWIMS level 1 housekeeping
            SWIMS level 1 data is contained in the EDBs
uleistest   routines to access ULEIS level 1 data structures

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

CHANGELOG
---------

2.1-->2.2	1998/04/17
---------
hdfgen.pl - now warns if more than one variable declaration is made per line,
   in the input header file
hdfgen.pl - when reporting RCS file headers, leaves off trailing "$" so as not
   to interfere with subsequent check ins of RCS (or CVS). Change suggested by
   Eduardo Santiago <esm@lanl.gov>.

Several variables have been added to the MAG browse data structure,
in magframe_out_br.h
	 
2.1-->2.2	1998/03/12
---------
Some reorganization occurred:
   1. browsetest directory was renamed to rawbrtst. This directory contains
      routines to access raw browse parameters
   2. avgbrtst directory was added. This directory contains routines to
      access 5min, 1hr and daily browse data from ACE_BROWSE.HDF

Added new routine, ACE_aosr(), to ancil_subs.c. This routine allows one to
retreive a complete attitude/orbit data structure (interpolated), for a given
spacecraft clock. For usage, see example routine get_aosr_struct.c, in
anciltest directory,

2.0-->2.1	1998/02/18
---------
This version of the ACE level 1 software package contains a change in one of
the HDF access routines which makes it incompatible with components of
earlier versions (2.0 and before) of the software package. The change does
not affect the ACE level 1 HDF data files themselves, just the method of
reading them from any of the example test routines in this package.

If you use this package, you will need to make a few changes to any code you
have written based on the example routines in earlier versions of this
package.

Description of change:
----------------------

In previous versions, access to an HDF file from all our example test
routines was initialized with the following calls 
(this example from magtest/mag_vec_rd.c) 

  if ((hdf_fp=Hopen(argv[1], DFACC_ALL, 0))==FAIL) {
      fprintf(stderr, "Hopen: could not open hdf file\n");
      exit(-1);
    }
  Vstart(hdf_fp);

  if ((sd_id=SDstart(argv[1], DFACC_WRITE))==FAIL) {
          fprintf(stderr, "SDstart: could not open hdf file\n");
          exit(-1);
        }

  if( init_rd_mag_vec(hdf_fp, sd_id) == 0) {
    fprintf(stderr,"No mag vector data\n");
    exit(-1);
    }


Above, the HDF file is being accessed with read-write permissions,
even though all the test examples in teh software package require only
read permission. This is unnecessary, and results in silly things like
files being created if you supply a wrong input filename, etc.

The new procedure inmplemented in this package is as follows:

  if ((hdf_fp=Hopen(argv[1], DFACC_RDONLY, 0))==FAIL) {
      fprintf(stderr, "Hopen: could not open hdf file\n");
      exit(-1);
    }
  Vstart(hdf_fp);

  if ((sd_id=SDstart(argv[1], DFACC_RDONLY))==FAIL) {
          fprintf(stderr, "SDstart: could not open hdf file\n");
          exit(-1);
        }

  if( init_rd_mag_vec(hdf_fp, sd_id,"r") == 0) {
    fprintf(stderr,"No mag vector data\n");
    exit(-1);
    }

The Hopen and SDstart functions use read-only flags, and init_rd_mag_vec has
an extra parmeter: "r", or "w", depending on the file permission desired.

The function init_rd_mag_vec is defined in the hdfsubs directory of the
package, as are all the analogous functions for the other ACE level 1
data structures. All the source files in the hdfsubs directory have changed
to implement the extra parameter in the init_rd_xxxx routines.

