PDS_VERSION_ID          = PDS3
RECORD_TYPE             = STREAM
OBJECT                  = TEXT
  PUBLICATION_DATE        = 2003-02-27
  NOTE                    = "
    SOFTINFO.TXT describes the contents of this directory."
END_OBJECT              = TEXT
END

This directory contains files related to example software applicable to
the data on this volume.  All code and files are provided "as is"
without any warranty but with the hope that they will be useful in
understanding the data provided on this volume.  These supplemental
files are beyond PDS archiving requirements and may not meet PDS
standards.

[SOFTWARE]              This directory
   |
   |- KEY_BROWSE.JAR    Java JAR file containing an early-release
   |                    version of CORPWS, an application for viewing
   |                    and manipulating the key-parameters data.
   |
   |- KEY_BROWSE.TXT    Simple text database used by CORPWS application
   |                    to locate the data files on this volume.
   |
   |- LRF_INPUT.DAT     Example input file for testing LRF_LIST program.
   |
   |- LRF_LIST.C        Example code to list low-rate full-resolution data.
   |
   |- LRF_MAKEFILE.MAK  Makefile for building and testing LRF_LIST.
   |
   |- LRF_OUTPUT.TXT    Correct output produced by LRF_LIST using
   |                    LRF_INPUT.DAT as input.
   |
   |- SOFTINFO.TXT      Description of and instructions for software in
   |                    this directory.  (this file)
   |
   |- T*_WBRFR.DAT      Binary WBR input files for testing WBR_WFR_LIST.
   |
   |- T*_WBRFR.TXT      ASCII text output files for testing WBR_WFR_LIST.
   |
   |- T*_WFRFR.DAT      Binary WFR input files for testing WBR_WFR_LIST.
   |
   |- T*_WFRFR.TXT      ASCII text output files for testing WBR_WFR_LIST.
   |
   |- WBR_WFR_LIST.C    Example code to list high-rate full-resolution
   |                    data.
   |
   |- WBR_WFR_MAKEFILE.MAK Makefile for building and testing WBR_WFR_LIST.


CORPWS Java Application
=======================

  The Java JAR file KEY_BROWSE.JAR contains the application CORPWS which
  can be used on Java 1.4 or newer platforms to generate spectrograms
  from the Cassini RPWS Key Parameters data files on this volume.  The
  file KEY_BROWSE.TXT is a simple text database used by the application
  to locate the data files and may be edited to extend the use of the
  software beyond the contents of the current volume.

  The Java Runtime Environment (JRE) is freely available for common
  platforms from http://java.sun.com/.

  On most platforms the application can be started by opening a command
  console, changing directory to the EXTRAS/SOFTWARE directory on the
  volume, and issuing the command:

    java -jar KEY_BROWSE.JAR

  The Java virtual machine will load the application and display a
  two-panel spectrogram showing the first day of available data with
  electric field spectral density on the upper panel and magnetic field
  spectral density on the lower panel.  Two convenient text entry boxes
  are provided along the bottom of the plot for explicitly entering start
  and stop times, plus forward " >> " and back " << " buttons will step
  the current plot width in time.  A "Print" button provides high-quality
  PostScript output and a "Quit" button will exit the application.

  Almost any aspect of the display is configurable, and a number of
  convenient controls are accessible via mouse events on the display
  itself.  Any axis may be zoomed by left-dragging a range on the
  corresponding axis, time, frequency, or amplitude.  A subtle mouse
  "gesture," dragging a few pixels to the left (a left arrow will
  appear), may be used to undo the most recent zoom.  Another mouse
  gesture, dragging a few pixels down (a down arrow will appear) is used
  to zoom out.  Again, these mouse gestures are subtle and will not work
  if the mouse is dragged more than a few pixels.  If you move too far,
  the motion will be interpreted as a range to zoom instead of the "undo"
  or "zoom out" command.

  Right-clicking on a display element will bring up a menu that may be
  used to modify the default action of a mouse down event in the element,
  including for spectrograms tools such as a "Crosshair Digitizer,"
  "Vertical Slice," "Horizontal Slice," and "Vertical Averager."  These
  are very useful for obtaining line plots of slices in time or frequency
  from the data used to generate the spectrograms.  In addition, a
  "properties" item will allow modifications of almost any other aspect
  of the presentation, including plot titles, axis styles, color or gray
  scales, etc.

  The file KEY_BROWSE.TXT is expected to be in the same directory the
  application is launched from.  It provides a simple text database with
  two columns, date and file location.  An edited version of this file
  will allow access to data in other locations.

  This application is an early release version of a very flexible display
  and analysis package currently under development.  For more
  information and updates, see http://www-pw.physics.uiowa.edu/das2/.

  This application utilizes open source libraries from a number of
  sources, including:

    The Apache Software Foundation, http://www.apache.org/

    The Batik SVG Toolkit provided by the Apache XML Project,
    http://xml.apache.org/batik/

    The iText Java-PDF library, http://www.lowagie.com/iText/

  We gratefully acknowledge the efforts of the Java open source
  community.


LRF_LIST.C example C code
=========================
  The file LRF_LIST.C contains example C code for a complete program to
  read and list data from Cassini RPWS low-rate full-resolution archive
  files.

  In order to compile and test the example code, you will need to copy
  all of the files in the EXTRAS/SOFTWARE (this) directory to a writable
  directory.  For UNIX-like development environments, a makefile is
  provided to automate the creation and verification of an executable
  program.  To use the makefile (in the writable directory):

  % make -f LRF_MAKEFILE.MAK

  If there are no compilation errors, then

  % make -f LRF_MAKEFILE.MAK test

  The last line printed should indicate whether the executable was
  verified to be working correctly or not.

  Compile and Test Details
  ------------------------
  In case the makefile cannot be used, the details of compilation and
  testing are as follows:

  In order to compile this code on UNIX systems, it may be necessary to
  rename the file and remove the CR character from the CRLF line
  termination:

  % tr -d \\r < LRF_LIST.C > lrf_list.c

  Then, the compile may be as simple as

  % gcc -O -o lrf_list lrf_list.c -lm

  The executable should be used to generate an output file from the
  provided input data file:

  % lrf_list LRF_INPUT.DAT > LRF_OUTPUT.out

  Again, it may be necessary to remove the extra CR from the CRLF line
  terminations on the provided output file:

  % tr -d \\r LRF_OUTPUT.TXT > LRF_OUTPUT.orig

  Finally the newly created output file should be compared against the
  provided output file:

  % diff LRF_OUTPUT.orig LRF_OUTPUT.out

  If there are no differences, then your compiled example should be
  working correctly.


WBR_WFR_LIST.C example C code
=============================
  The file WBR_WFR_LIST.C contains example C code for a complete program
  to read, calibrate, and list data from Cassini RPWS wideband or
  waveform archive files.  Quick-start help for using these data and this
  example code is given in EXTRAS/WFRWBR.TXT (one directory up from
  here).

  In order to compile and test the example code, you will need to copy
  all of the files in the EXTRAS/SOFTWARE (this) directory to a writable
  directory.  For UNIX-like development environments, a makefile is
  provided to automate the creation and verification of an executable
  program.  To use the makefile (in the writable directory):

  % make -f WBR_WFR_MAKEFILE.MAK

  If there are no compilation errors, then

  % make -f WBR_WFR_MAKEFILE.MAK test

  The last line printed should indicate whether the executable was
  verified to be working correctly or not.

  Compile and Test Details
  ------------------------
  In case the makefile cannot be used, the details of compilation and
  testing are as follows:

  In order to compile this code on UNIX systems, it may be necessary to
  rename the file and remove the CR character from the CRLF line
  termination:

  % tr -d \\r < WBR_WFR_LIST.C > wbr_wfr_list.c

  Then, the compile may be as simple as

  % gcc -O -o wbr_wfr_list wbr_wfr_list.c -lm

  The executable should be used to generate output files from each of the
  provided input data files:

  % wbr_wfr_list -aercls T1999229_21_10KHZD_WBRFR.DAT > \
  T1999229_21_10KHZD_WBRFR.out
  % wbr_wfr_list -aercls T1999230_03_10KHZ1_WBRFR.DAT > \
  T1999230_03_10KHZ1_WBRFR.out
  % wbr_wfr_list -aercls T1999230_2_5KHZ2_WFRFR.DAT > \
  T1999230_2_5KHZ2_WFRFR.out
  % wbr_wfr_list -aercls T1999255_25HZ4_WFRFR.DAT > \
  T1999255_25HZ4_WFRFR.out

  Again, it may be necessary to remove the extra CR from the CRLF line
  terminations on each of the provided output files:

  % tr -d \\r < T1999229_21_10KHZD_WBRFR.TXT > \
  T1999229_21_10KHZD_WBRFR.orig
  % tr -d \\r < T1999230_03_10KHZ1_WBRFR.TXT > \
  T1999230_03_10KHZ1_WBRFR.orig
  % tr -d \\r < T1999230_2_5KHZ2_WFRFR.TXT > T1999230_2_5KHZ2_WFRFR.orig
  % tr -d \\r < T1999255_25HZ4_WFRFR.TXT > T1999255_25HZ4_WFRFR.orig

  Finally the newly created output files should be compared against the
  provided output files:

  % diff T1999229_21_10KHZD_WBRFR.orig T1999229_21_10KHZD_WBRFR.out
  % diff T1999230_03_10KHZ1_WBRFR.orig T1999230_03_10KHZ1_WBRFR.out
  % diff T1999230_2_5KHZ2_WFRFR.orig T1999230_2_5KHZ2_WFRFR.out
  % diff T1999255_25HZ4_WFRFR.orig T1999255_25HZ4_WFRFR.out

  If there are no differences, then your compiled example should be
  working correctly.  If the lowest-order digit of some floating
  point values differ by one, then platform-dependent differences
  in rounding may be the cause.  These differences can be ignored.

=======================================================================