Extended IDL Help

This page was created by the PaPCo routine papco_make_html_help. For more information on this routine, refer to the IDL Online Help Navigator or type: 

     doc_library, 'papco_make_html_help'

at the IDL command line prompt.

Last modified: Wed May 9 12:56:19 2007.

List of Routines

Routine Descriptions

: papco_panel_label

 [Next Routine] [List of Routines] 
 File: papco_panel_label

 A collection of routines to place labels around papco panels in
such a way that they scale to fit into the space available for a panel.

 Aug 2002 - added routine to put labels into panel window,
            e.g. colored labels for each line in panel, like energy channels

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_panel_label.pro:9)

anytim2cal

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     : SOHO - CDS     
                   
 Name        : ANYTIM2CAL()
               
 Purpose     : Converts (almost) any time format to calendar format.
               
 Explanation : Tests the type of input and tries to use the appropriate
               conversion routine to create the date/time in a user
               selectable calendar format for, for example, printing in
               documents, tables etc.
               
 Use         : IDL>  utc = anytim2cal(any_format, form=xx)
    
 Inputs      : any_format - date/time in any of the acceptable CDS 
                            time formats -- for acceptable formats see file 
                            aaareadme.txt.
               
 Opt. Inputs : None
               
 Outputs     : Function returns string array in format requested.
               
 Opt. Outputs: None
               
 Keywords    : 
      FORM  = n   where... 
			    n		  output format
			    0		dd/mmm/yy hh:mm:ss  [default]
			    1		dd-mmm-yy hh:mm:ss
			    2		dd/mm/yy  hh:mm:ss
			    3		dd-mm-yy hh:mm:ss
			    4		mm/dd/yy hh:mm:ss
			    5		mm-dd-yy hh:mm:ss
			    6		yy/mm/dd hh:mm:ss
			    7		yy-mm-dd hh:mm:ss
			    8		yyyymmddhhmmss
                           9           dd-mmm-yyyy hh:mm:ss.sss (VMS-like)
                          10           dd-mmm-yyyy hh:mm:ss.ss (!stime-like)
                          11           yyyy/mm/dd hh:mm:ss.sss (cpt use)
			    etc TBD
      DATE   - Output only the date in format above.
      TIME   - Output only the time in format above.
      MSEC   -	Include milliseconds in the "ss" fields above (="ss.sss").
      ERRMSG - If defined and passed, then any error messages will be returned
               to the user in this parameter rather than being printed to
               the screen.  If no errors are encountered, then a null string 
               is returned.  In order to use this feature, the string ERRMSG
               must be defined first, e.g.,

                   ERRMSG = ''
                   ANYTIM2CAL, DT, ERRMSG=ERRMSG, ...
                   IF ERRMSG NE '' THEN ...

 Calls       : ANYTIM2UTC, CHECK_EXT_TIME

 Common      : None
               
 Restrictions: None
               
 Side effects: If no parameters are passed, ERRMSG is returned as a string
               array.  If any other error occurs and ERRMSG is set, ERRMSG
		is returned as a string of '-1'.
               
 Category    : Util, time
               
 Prev. Hist. : None

 Written     : C D Pike, RAL, 24-May-94
               
 Modified    :	Version 1, C.D. Pike, RAL, 24 May 1994
		Version 2, Donald G. Luttermoser, GSFC/ARC, 20 December 1994
			Added the keyword ERRMSG.  Added forms 4 and 5.
               Version 3, CDP, make work with vector input and
                               added formats 6 & 7.   5-Jan-95
               Version 4, CDP, fix round off giving 60 in seconds field.
                               23-Jan-95
		Version 5, William Thompson, GSFC, 25 January 1995
			Changed to call intrinsic ROUND instead of NINT.  The
			version of NINT in the Astronomy User's Library doesn't
			automatically select between short and long integers as
			the CDS version does.
		Version 6, Donald G. Luttermoser, GSFC/ARC, 30 January 1995
			Added ERRMSG keyword to internally called procedures.
		Version 7, Donald G. Luttermoser, GSFC/ARC, 8 February 1995
			Added form 8.  Allowed for input to be either scalar
			or vector.
		Version 8, Donald G. Luttermoser, GSFC/ARC, 13 February 1995
			Added the /MSEC keyword.  Streamlined code to get
			rid of redundancies.
		Version 9, William Thompson, GSFC/ARC, 16 February 1995
			Rewrote to call CHECK_EXT_TIME.  This is used instead
			of the logic introduced in version 4 for checking the
			validity of the time returned.
               Version 10 Fixed array input bug in /msec code.  CDP, 20-Feb-95
               Version 11 Add VMS and !stime-like formats 9/10. CDP, 15/3/95
               Version 12 Add type 11 format.  CDP, 15-DEc-95


 Version     :	Version 12, 15-Dec-95

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/anytim2cal.pro:100)

anytim2utc

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     : SOHO - CDS     
                   
 Name        : ANYTIM2UTC()
               
 Purpose     : Converts (almost) any time format to CDS UTC format.
               
 Explanation : Tests the type of input and tries to use the appropriate
               conversion routine to create the date/time in CDS UTC
               format (either internal (default), external or string)
               CDS time format.
               
 Use         : IDL>  utc = anytim2utc(any_format)
    
 Inputs      : any_format - date/time in any of the acceptable CDS 
                            time formats -- for acceptable formats see file 
                            aaareadme.txt.
               
 Opt. Inputs : None
               
 Outputs     : Function returns CDS UTC time structure.
               
 Opt. Outputs: None
               
 Keywords    : EXTERNAL  = Create output in external format
               CCSDS     = Create string output in CCSDS format
               ECS       = Create string output in ECS format
		VMS	  = Create string output in VMS format
		STIME	  = Create string output in STIME format

		Only one of the above keywords can be set.  If none of them are
		set, then the output is in internal format.  The following
		keywords are only valid if a string format was selected.

		TRUNCATE  = If set, then the time will be truncated to 1 second
			    accuracy.  Note that this is not the same thing as
			    rounding off to the nearest second, but is a
			    rounding down.

		DATE_ONLY = If set, then only the date part of the string is
			    returned.

		TIME_ONLY = If set, then only the time part of the string is
			    returned.

		UPPERCASE = If set, then the month field in either the VMS or
			    STIME format is returned as uppercase.

		The following keyword is always valid.

               ERRMSG    = If defined and passed, then any error messages 
                           will be returned to the user in this parameter 
                           rather than being printed to the screen.  If no
                           errors are encountered, then a null string is
                           returned.  In order to use this feature, the 
                           string ERRMSG must be defined first, e.g.,

                                ERRMSG = ''
                                UTC = ANYTIM2UTC ( DT, ERRMSG=ERRMSG, ...)
                                IF ERRMSG NE '' THEN ...

 Calls       : DATATYPE, INT2UTC, STR2UTC

 Common      : None
               
 Restrictions: None
               
 Side effects: None
               
 Category    : Util, time
               
 Prev. Hist. : None

 Written     : C D Pike, RAL, 16-May-94
               
 Modified    :	Version 1, C D Pike, RAL, 16-May-94
		Version 2, William Thompson, GSFC, 14 November 1994
			Changed .DAY to .MJD
		Version 3, Donald G. Luttermoser, GSFC/ARC, 20 December 1994
			Added the keyword ERRMSG.  Included ON_ERROR flag.
		Version 4, Donald G. Luttermoser, GSFC/ARC, 30 January 1995
			Added ERRMSG keyword to internally called procedures.
			Made error handling routine more robust.
		Version 5, Donald G. Luttermoser, GSFC/ARC, 8 February 1995
			Allowed for input to be either scalar or vector.
		Version 6, William Thompson, GSFC, 14 March 1995
			Added keywords VDS, STIME, TRUNCATE, DATE_ONLY,
			TIME_ONLY, UPPERCASE
		Version 7, William Thompson, GSFC, 5 May 1995
			Fixed bug with use of ERRMSG keyword.
			Made so that TAI times are supported.
		Version 8, William Thompson, GSFC, 8 May 1995
			Fixed bug introduced in version 7
               Version 9 C D Pike, RAL, 17-May-95
                       Handle time only (no date) string input.
		Version 10, William Thompson, GSFC, 20 December 1995
			Fixed bug with use of ERRMSG keyword when string
			contained no "-" characters.

 Version     : Version 10, 20 December 1995

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/anytim2utc.pro:101)

a_papco_module

 [Previous Routine] [Next Routine] [List of Routines] 
 CALL (a_papco_module):

 PROCEDURE:   a_papco_module

 DESCRIPTION: Routine for data access to a PAPCO module's data
              For use inside the PAPCO environment 
              (papco is compiled, required modules are loaded)

 INPUT:       none - use keywords

 OUTPUT:      none (places data into papco's data cache)
              if keyword DATA is set it returns the contents of the cache

 KEYWORDS:    VERBOSE  -  enables print comments, save/restore
                           comments
              MODULE   -  name of the module to access
              SUBTYPE  -  module suptype
              T1       -  start date/time in any PAPCO format, string
              T2       -  end date/time in any PAPCO format, string
              MJDT     -  1: T1, T2 in mjdt
                           >1 get time from current COMMON mjdt
              INFO     -  prints out all the control structure info
                           for this module, then returns.
                           1: print to screen
                           2: print info to file, current directory
              READONLY -  just do a "r_module" instead of "draw_module"
                           1: return all data in files
                           2: restrict to actual times set
              DATA     -  set to variable to return data in 
              ERR_NO   -  set to variable containing error number -
                           anything other than zero indicates a data
                           access error
              ERR_MSG  -  set to variable containing error message
              DEBUG    -  turns of error catching
              "extra"  -  any of the control structure tags can be
                           set by using a keyword of the same name. 
         
 Enter a time in one of these formats: date time, date
 where time is in one of those formats: h:m:s, h:m
 and date is in one of those formats: m/d/y, doy/y, d.m.y, m/d/y, yyyymmdd
 where d is day and doy is day of year, h:m:s is the time
 (year > 1990 if you use T90 format)
 e.g: 1/90 14:11, 1/1990 1:1:1, 350/1991 01:00:03
      15.1.90 14:11, 1/15/1990 15:3:1              

 Example call to access one day of POLAR IES data, Spin Averaged:

 a_papco_module, T1='19980503', T2='19980503', PRODUCT=1, SECTORS=16, $ 
                 SPINS=16, CAL=1, PL_TYPE=6, MODULE = 'polar_ceppad'

 DATE:        June 2006

 AUTHOR:      R. Friedel

 CHANGES:     

 - end of header tag, used by papco_routine_info

(See /home/jbf/ct/papco/working/papco/papco_lib/a_papco_module.pro:59)

break_path

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     : SOHO - CDS

 Name        : BREAK_PATH()

 Purpose     : Breaks up a path string into its component directories.

 Explanation :

 Use         : Result = BREAK_PATH( PATHS )

 Inputs      : PATHS	= A string containing one or more directory paths.  The
			  individual paths are separated by commas, although in
			  UNIX, colons can also be used.  In other words, PATHS
			  has the same format as !PATH, except that commas can
			  be used as a separator regardless of operating
			  system.

		     	  A leading $ can be used in any path to signal that
			  what follows is an environmental variable, but the $
			  is not necessary.  (In VMS the $ can either be part
			  of the path, or can signal logical names for
			  compatibility with Unix.)  Environmental variables
			  can themselves contain multiple paths.

 Opt. Inputs : None.

 Outputs     : The result of the function is a string array of directories.
		Unless the NOCURRENT keyword is set, the first element of the
		array is always the null string, representing the current
		directory.  All the other directories will end in the correct
		separator character for the current operating system.

 Opt. Outputs: None.

 Keywords    : NOCURRENT = If set, then the current directory (represented by
			    the null string) will not automatically be
			    prepended to the output.

 Calls       : STR_SEP

 Common      : None.

 Restrictions: None.

 Side effects: None.

 Category    : Utilities, Operating_system

 Prev. Hist. : None, but influenced by TEST_OPENR by William Thompson, and
		CONCAT_DIR by M. Morrison.

 Written     : William Thompson, GSFC, 3 May 1993.

 Modified    : Version 1, William Thompson, GSFC, 6 May 1993.
			Added IDL for Windows compatibility.
		Version 2, William Thompson, GSFC, 16 May 1995
			Added keyword NOCURRENT
		Version 3, William Thompson, GSFC, 29 August 1995
			Modified to use OS_FAMILY

 Version     : Version 3, 29 August 1995

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/system/break_path.pro:64)

calculateHeight

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      calculateHeight, ymin, ymax

 DESCRIPTION:
      This function calculates the height of the plot-array.
  The height of this array is the resolution, in which the data on the
      y-axis are plotted. When the databins have different sizes, one can't
      just choose the number of bins to be the resolution but has to make
  sure, that the resolution is big enough for all bins to be visible.
  So, the bin-sizes are added in units of the smallest bin, and this
  sum is made the y-resolution of the plot-array.

 READ THIS !
      When you experience PROBLEMS IN THE RESOLUTION on the y-axis, this
  routine is probably the bad guy. Just increase the returned value to
  increase your resolution. (Be careful: when printing, the size of the
      created Postscript-files is almost proportional to this function's
      return-value.

 INPUTS:
      ymin, ymax  : arrays containing the bounds of the data-bins

 OUTPUT:
      an Integer

 CALLING SEQUENCE:
      yDim=calculateHeight(YMINArr, YMAXArr)

 MODIFICATION HISTORY:
      august 1995, written by A.Keese

(See /home/jbf/ct/papco/working/papco/papco_lib/color_plot/plot_clr.pro:74)

cat_struct

 [Previous Routine] [Next Routine] [List of Routines] 
 function cat_struct, a, b
 
 PURPOSE:
       Catenate structures which may have redundant fields.
       This is only needed for IDL V5, earlier versions can 
       just use create_struct to cat redundant structures.
       DOES NOT WORK WITH ARRAYS OF STRUCTURES
       Note that if both a and b contain the same tag, the returned
       structure c, will have c.tag = a.tag

 INPUTS:
       a, b  structures.

 OUTPUT:
       Structure containing the fields of a and b.

 HISTORY:
       created 12/3/97 by jason franz at cornell university
        as a quick fix for PAPCO

(See /home/jbf/ct/papco/working/papco/papco_lib/cat_struct.pro:22)

cds2jd

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     : SOHO - CDS     
                   
 Name        : CDS2JD()
               
 Purpose     : Converts any CDS time format to full Julian day.
               
 Explanation : Converts any CDS time format to the equivalent Julian
               day value.  Returns result in a structure with the
               tags int (long) and frac (double).
               
 Use         : IDL>  jd = cds2jd(any_format)
    
 Inputs      : any_format - date/time in any of the acceptable CDS 
                            time formats -- for acceptable formats see file 
                            aaareadme.txt.
               
 Opt. Inputs : None
               
 Outputs     : Function returns JD in a structure {int:0L,frac:0.0d0}.
               
 Opt. Outputs: None
               
 Keywords    : ERRMSG  =  If defined and passed, then any error messages will
                          be returned to the user in this parameter rather 
                          than being printed to the screen.  If no errors are
                          encountered, then a null string is returned.  In 
                          order to use this feature, the string ERRMSG must 
                          be defined first, e.g.,

                             ERRMSG = ''
                             JD = CDS2JD ( DT, ERRMSG=ERRMSG, ...)
                             IF ERRMSG NE '' THEN ...

 Calls       : ANYTIM2UTC, INT2UTC, JULDAY

 Common      : None
               
 Restrictions: None
               
 Side effects: None
               
 Category    : Util, time
               
 Prev. Hist. : None

 Written     : C D Pike, RAL, 16-May-94
               
 Modified    :	Version 1, C D Pike, RAL, 16-May-94
		Version 2, William Thompson, GSFC, 14 November 1994
			Changed .DAY to .MJD
		Version 3, Donald G. Luttermoser, GSFC/ARC, 20 December 1994
			Added the keyword ERRMSG.  Included ON_ERROR flag.
		Version 4, Donald G. Luttermoser, GSFC/ARC, 30 January 1995
			Added ERRMSG keyword to internally called procedured.
			Made error handling routine more robust.
		Version 5, Donald G. Luttermoser, GSFC/ARC, 13 February 1995
			Allowed for input to be either scalar or vector.

 Version     :	Version 5, 13 Februaryy 1995

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/cds2jd.pro:61)

check_ext_time

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     :	SOHO - CDS

 Name        :	CHECK_EXT_TIME

 Purpose     :	Checks CDS external time values for logical consistency.

 Explanation :	This procedure checks time values in CDS external format to
		ensure that the date-time values have valid values.  If a 
		value is found inaccurate, then these values are repaired
		with CHECK_INT_TIME.

		This procedure should be called whenever the external time is
		modified.

 Use         :	CHECK_EXT_TIME, EXT

 Inputs      :	EXT	= The UTC date/time as a data structure with the
			  elements:

				YEAR		= Integer year (1995).
				MONTH		= Integer month (1-12).
				DAY		= Integer day (1-31).
				HOUR		= Integer hour (0-23).
				MINUTE		= Integer minute (0-59).
				SECOND		= Integer second (0-59).
				MILLISECOND	= Integer millisec (0-999).

 Opt. Inputs :	None.

 Outputs     :	The input array will be repaired to reflect the correct values.

 Opt. Outputs:	None.

 Keywords    :	ERRMSG	= If defined and passed, then any error messages 
			  will be returned to the user in this parameter 
			  rather than using IDL's MESSAGE utility.  If no
			  errors are encountered, then a null string is
			  returned.  In order to use this feature, the 
			  string ERRMSG must be defined first, e.g.,

				ERRMSG = ''
				CHECK_EXT_TIME, EXT, ERRMSG=ERRMSG
				IF ERRMSG NE '' THEN ...

 Calls       :	DATATYPE, UTC2INT, INT2UTC, CHECK_INT_TIME

 Common      :	None.

 Restrictions:	Not valid for dates before 1 January 1972.

 Side effects:	None.

 Category    :	Utilities, Time.

 Prev. Hist. :	None, but uses CHECK_INT_TIME by W. Thompson, NASA/GSFC/ARC
		to check and make the fix.

 Written     :	Donald G. Luttermoser, NASA/GSFC/ARC, 15 February 1995.

 Modified    :	Version 1, Donald G. Luttermoser, GSFC/ARC, 15 February 1995.

 Version     :	Version 1, 15 February 1995.

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/check_ext_time.pro:65)

check_int_time

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     :	SOHO - CDS

 Name        :	CHECK_INT_TIME

 Purpose     :	Checks CDS internal time values for logical consistency.

 Explanation :	This procedure checks time values in CDS internal format to
		ensure that the milliseconds of day is neither negative nor
		larger than the number of milliseconds in the day in question.
		If either is true, then the day and time is repaired.  Leap
		seconds are taken into account.

		This procedure should be called whenever the internal time is
		modified.

 Use         :	CHECK_INT_TIME, INT

 Inputs      :	INT	= The UTC date/time as a data structure with the
			  elements:

				MJD	= The Modified Julian Day number
				TIME	= The time of day, in milliseconds
					  since the start of the day.

			  Both are long integers.

 Opt. Inputs :	None.

 Outputs     :	The input array will be repaired to reflect the correct number
		of milliseconds in the day.

 Opt. Outputs:	None.

 Keywords    :	ERRMSG    =  If defined and passed, then any error messages 
                            will be returned to the user in this parameter 
                            rather than using IDL's MESSAGE utility.  If no
                            errors are encountered, then a null string is
                            returned.  In order to use this feature, the 
                            string ERRMSG must be defined first, e.g.,

                                ERRMSG = ''
                                CHECK_INT_TIME, INT, ERRMSG=ERRMSG
                                IF ERRMSG NE '' THEN ...

 Calls       :	DATATYPE, GET_LEAP_SEC

 Common      :	None.

 Restrictions:	Not valid for dates before 1 January 1972.

		This procedure requires a file containing the dates of all leap
		second insertions starting with 31 December 1971.  This file
		must have the name 'leap_seconds.dat', and must be in the
		directory given by the environment variable TIME_CONV.  It must
		be properly updated as new leap seconds are announced.

 Side effects:	None.

 Category    :	Utilities, Time.

 Prev. Hist. :	Based on CHECK_TIME by M. Morrison, LPARL.

 Written     :	William Thompson, GSFC, 29 September 1993.

 Modified    :	Version 1, William Thompson, GSFC, 29 September 1993.
		Version 2, Donald G. Luttermoser, GSFC/ARC, 20 December 1994
			Added the keyword ERRMSG.  Added a check for the 
			STRUCTURE-TAG names.
		Version 3, Donald G. Luttermoser, GSFC/ARC, 30 January 1995
			Added ERRMSG keyword to internally called procedures.
			Made the error handling routine more robust.  Note
			that this procedure can handle both vectors and 
			scalars.

 Version     :	Version 3, 30 January 1995.

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/check_int_time.pro:78)

comments[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 FILE:	 
    comments.pro
 
 DESCRIPTION:  
    This is a utility for gaining informations on a tree of IDL-files.
    All IDL-Programs (*.pro) that are contained in a certain path AND 
    anywhere in its subtree are analyzed. 
    The functions, procedures and structures found in theses IDL-programs 
    are accumulated in some reference-files.    
    
    If you start this program by
       .run comments
       commentsFor, '~/myPrograms', '~/protocol'
    those files are written:
       ~/protocol.files       - lists all procedures, functions, structures
                                by the file they're contained in
       ~/protocol.proc_ref    - is a reference: all procedure/functions or
				  structure-names are listed alphabetically
				  and the files, they're defined in are listed
       ~/protocol.definitions - similar to .proc_ref but not only the names
				  of those object are listed but their 
				  definitions, too
	 ~/protocol.def_warn	- warns you, if a procedure or function is
				  declared in multiple files
	 ~/protocol.file_warn	- lists duplicate file-names

 USAGE :
    Start this utility by typing
       commentsFor, dirName, protocolName
    e.g.: 
       commentsFor, '~/myPro', '~/protocol'

    Before starting you have to compile those files:
       .run string_functions
	 .run comments

 MODIFICATION HISTORY:       
     september 1995, written by A.Keese

(See /home/jbf/ct/papco/working/papco/papco_lib/comments.pro:40)

comments[2]

 [Previous Routine] [Next Routine] [List of Routines] 
 this is the main-procedure.

(See /home/jbf/ct/papco/working/papco/papco_lib/comments.pro:81)

comments[3]

 [Previous Routine] [Next Routine] [List of Routines] 
 write all references listed by their file-name

(See /home/jbf/ct/papco/working/papco/papco_lib/comments.pro:243)

comments[4]

 [Previous Routine] [Next Routine] [List of Routines] 
 parse a function-definition for its name
 the function-definition is expected to contain no '$' or ';'
 enclosed in a string (I think, something like that can't appear in a
 valid function-definition

 totalLine is an array of on IDL-Statement. 
           e.g.: totalLine = ['pro a, $', 'b']

(See /home/jbf/ct/papco/working/papco/papco_lib/comments.pro:328)

comments[5]

 [Previous Routine] [Next Routine] [List of Routines] 
 parse a structure-definition for the structure's name

 totalLine is an array of on IDL-Statement. 
           e.g.: totalLine = ['tmp={str, $', 'a:1}']

(See /home/jbf/ct/papco/working/papco/papco_lib/comments.pro:364)

comments[6]

 [Previous Routine] [Next Routine] [List of Routines] 
 process one file - all interestings statements are searched and 
 stored in the common-block COMMENTS

 fName : the name of a file in the current directory

(See /home/jbf/ct/papco/working/papco/papco_lib/comments.pro:456)

comments[7]

 [Previous Routine] [Next Routine] [List of Routines] 
 read an IDL-statement, parse it, return data in the parameters.
 INPUT:
   r_unit    : logical file-unit to read from

 OUTPUT :
 totalLine   : returns an array with all file-lines of that IDL-statement
 inBrackets1 : depth in '(' ... ')' (should be zero before and after each 
               read statement - may be used for expansions.
 inBrackets2 : depth in '[' ... ']' (should be zero before and after each 
               read statement - may be used for expansions.
 inBrackets3 : depth in '{' ... '}' (should be zero before and after each 
               read statement - may be used for expansions.
 inBlocks    : this integer is increased or decreased to contain the depth
               of IDL-blocks (as BEGIN...END or FUNCTION...END...)
 foundFunction: set to one, if 'totalLine' contains a function-definition or
               a procedure definition
 foundEndBlock: set to one, if the statement is the end of a block like
               'END', 'ENDFOR', ...
 foundStartBlock: set to one, if the statement is a BEGIN-statement
 foundStructure: set to one, if the statement contains a structure definition

(See /home/jbf/ct/papco/working/papco/papco_lib/comments.pro:545)

convert_dateToDay

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: convert_dateToDay    

 CALLING SEQUENCE:  convert_dateToDay, dateString
 
 DESCRIPTION:  
      convert a verbose date-description to the format day_ofYear, year

 INPUTS:       
      dateString, string, a string containing the date
			   date=doy"/"y | dom"."mon"."y
			   doy=aNumber, dom=aNumber, y=aNumber, 
			   mon=aNumber | aString
			   (doy:day of year,dom:day of month,mon:month,y:year)

 OUTPUT:	 
     struct, structure is returned  err={error:1, day:0, year:0}
     with fields:
        error, boolean,
	       if EQ 1, the date-string was not valid
	       if EQ 0, the date-string was valid and day,year contain the date
        day, int, the day of year of the time-string
        year, int, the year of the converted date

 CALLING SEQUENCE:
      a=convert_dateToDay(aString)
	if a.err then $
	   print, 'ERROR !' $
	else $ 
	   print, 'day:', a.day, ' year:', a.year

 MODIFICATION HISTORY:       
      september 1995, written by A.Keese

(See /home/jbf/ct/papco/working/papco/papco_lib/convert_time.pro:817)

convert_t90_to_Date

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE: convert_t90_to_Date
 
 DESCRIPTION:  
      Convert a T90-time to the time's date to its time of day
 
 INPUTS:       
      time, long, the time that you wish to convert, in t90 units. (The number of seconds since midnight, Jan 1, 1990.)
 
 KEYWORDS:
      MJDT, keyw, input time in the MJDT format instead

 OUTPUTS:
      year, int, (1990,...2001,...)     the year of the input time 
	day_oy, int, (1,2,3,...,356)        its day of year

	hour, int, (0,...,23)         \   these three 
	minute, int, (0,...,59)          >  variables return
	second, int, (0,...,59)         /   the time of day

      month, int, (1,...,12)             the month
	cmonth	  a string (e.g. 'Jan' for January) for the month 
      day_om, int, (1,...,31)	            the day of month

 CALLING SEQUENCE:
      convert_t90_to_Date, convert_timeToSeconds('5.5.1990 11:12:13',/t90), $
			     y, doy, h, m, s, m, cm, dom
      this assigns y=1990, doy=125, h=11, m=12, s=13, m=5, cm='May', dom=5

 MODIFICATION HISTORY:       
      September 1995, written by A.Keese
      January 1997, by R. Friedel, keyword MJDT added

(See /home/jbf/ct/papco/working/papco/papco_lib/convert_time.pro:242)

convert_time[3]

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     
      FUNCTION convert_TZERO_TO_T90, seconds, day, theYear
 
 DESCRIPTION:  
      Convert a TZERO-time to a T90-time or MJDT time
 
 INPUTS:       
      seconds    a number 
      day, int, - the day of year
      theYear, int, - the year

 KEYWORDS:
      MJDT       if set, return time in  the MJDT format instead

 OUTPUT:	 
      T90-format: a long integer. -1 if outside T90 range OR
      time={MJDT, MJD:0l, T:0.0 }: a structure  in MJDT-format
                                   if keyword MJDT is set

 CALLING SEQUENCE:
      sec=convert_t90_to_tzero(t90_val_orig, sec, doy)
      t90_val=convert_tzero_to_t90(sec, doy, year)
      if t90_val NE t90_val_orig then print, 'error !'

 MODIFICATION HISTORY:       
      september 1995, written by A.Keese 
      january 1997, by R. Friedel, keyword MJDT added

(See /home/jbf/ct/papco/working/papco/papco_lib/convert_time.pro:101)

convert_time[4]

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     
      FUNCTION convert_T90_TO_TZERO, seconds, day, $
                       theYear, DAY=ForDay, YEAR=ForYear
 
 DESCRIPTION:  
      This is the inverse function from convert_tzero_to_t90.
      A T90-value is converted to TZERO-format or MJD format
      if keyword MJDT is set

 INPUTS:       
      seconds  a long number - a T90-value
 
 KEYWORDS:
      MJDT          if set, contains input time in the MJDT format 
                    then other inputs seconds,day are don't cares.

 OUTPUT:	 
      return-value  The return-value is the seconds since midnight
      day           the day of year
      theYear       the year

 KEYWORDS:
      DAY, YEAR     set these if you want to force the tzero-value to have
                    those values as day or year. The returned value of this
                    function will calculated, so that the TZERO and the T90-
                    time are the same.
                    These keywords were necessary, because some CRRES-orbits
                    start on one day and end on the next day. In this case,
                    the seconds the orbit's start and end refer to midnight
                    of the first day.
		      When converting from T90 to TZERO, you can force this 
		      by specifying the DAY and YEAR-keywords.
		      e.g.: let startTime90, endTime90 be in the T90-format.
		            to convert them to TZERO, use this sequence:
			    xut1=convert_t90_to_tzero(startTime90, day, year)
			    xut2=convert_t90_to_tzero(endTime90, $
			                              DAY=day, YEAR=year)

 CALLING SEQUENCE:
      see one paragraph higher...

 MODIFICATION HISTORY:       
      september 1995, written by A.Keese 
      january 1997, by R. Friedel, keyword MJDT added

(See /home/jbf/ct/papco/working/papco/papco_lib/convert_time.pro:179)

convert_time[5]

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     
      FUNCTION convert_date_to_t90, day=day, month=month, doy=doy, $
                              year=year, hour=hour, minutes=minutes, $
                              seconds=seconds, MJDT=MJDT
 
 DESCRIPTION:  
      Convert a time of a given date to the T90-format or MJDT
 
 INPUTS:       
      none
 
 KEYWORDS:
      You don't have to specify any keyword...

      DAY, int,       if set, this is the day of month. 
                                 if omitted, it is assumed to be 1
      MONTH, int, or string
                this is the month. You may specify a name as well (either)
                in german or in english. Only the first three characters are
                significant
                If omitted, it is assumed to be 1
      DOY, int,       the day of year. If set, DAY and  MONTH are 
                                 ignored. If omitted, it is assumed to be 1
      YEAR, int,       if YEAR LT 1000, 1900 is added
                                 If omitted, it is assumed to be 1990
      HOUR, int,       If omitted, it is assumed to be 0
      MINUTES, int,       If omitted, it is assumed to be 0
      SECONDS, int,       If omitted, it is assumed to be 0
      MJDT      if set, output time in the MJDT format instead

 OUTPUT:	 
      the seconds since midnight of 1st January 1990 are returned
      if keyword MJDT is set, time in MJDT format is returned
      (modified Julian Date + seconds since midnight that date

 CALLING SEQUENCE:
      sec=convert_Date_to_T90(day=1, year=1991, hour=12)
      sec=convert_Date_to_T90(doy=1, year=1991, hour=12)

 MODIFICATION HISTORY:       
      september 1995, written by A.Keese 
      january 1997, by R. Friedel, keyword MJDT added

(See /home/jbf/ct/papco/working/papco/papco_lib/convert_time.pro:320)

convert_time[6]

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     
      FUNCTION convert_secondsToTime, seconds, T90=T90, MJDT=MJDT
 
 DESCRIPTION:  
      Convert a time to a verbose description. 
	If the time is in T90-format, the verbose description will consist
	of the date followed by the time of day.
	If the time is not in T90-format (i.e., it's seconds since midnight), 
	the verbose description will consist of the time of day. In this case, 
	the time of day will be preceded by an 'N' if seconds GT 24L*3600L  
	(i.e. the time is the time of the next day)

 INPUTS:       
      seconds	     a long number
		     a time in the T90 or TZERO-format
 
 KEYWORDS:
      T90	     if specified, 'seconds' are interpreted as T90-time.
		     Else, 'seconds' are interpreted as TZERO
      MJDT         if set, input time in the MJDT format instead
      COUNTRY      sets output format to US (1) or EUROPE (0) time style

 OUTPUT:	 
      a string     the string contains the verbose description

 CALLING SEQUENCE:
      ; TZERO - time:
	timeString=convert_secondsToTime(seconds)
	s1=convert_timeToSeconds(timeString)	
      if s1.value NE seconds then print, "this shouldn't happen"
	
	; T90-time
	timeString=convert_secondsToTime(sec, /T90)
	s1=convert_timeToSeconds(timeString)	
      if s1.value NE seconds then print, "this shouldn't happen"
	
 MODIFICATION HISTORY:       
      september 1995, written by A.Keese 
      january 1997, by R. Friedel, keyword MJDT added
      february 1997, by R. Friedel, keyword COUNTRY added

(See /home/jbf/ct/papco/working/papco/papco_lib/convert_time.pro:438)

convert_time[7]

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     
      FUNCTION convert_timeToSeconds, aTimeString, T90=T90, MJDT=MJDT
 
 DESCRIPTION:  
      Convert a verbose time-description to the time in seconds or MJDT.
 
 INPUTS:       
      aTimeString	a String
			It contains the verbose time in this formats:
			If the T90-Keyword is set :
			   timeString=date [time
			   date=doy"/"y | dom"."mon"."y | mon"/"dom"/"y
			   doy=aNumber, dom=aNumber, y=aNumber=mon=aNumber
			   (doy:day of year,dom:day of month,mon:month,y:year)
			   time=hour":"minutes[":"seconds]
			   hour=aNumber, minutes=aNumber, seconds=aNumber
			 
			   valid examples: 
			     aTimeString="1/91 11:12"
			     aTimeString="12/30/1990 11:12:31"
			     aTimeString="30.12.1990 11:12:"
			     aTimeString="1/91"
			     aTimeString="1.1.1990 55:12" ; hour may be GT 24 !

			   invalid examples:
			     aTimeString="30/12/1990 11:12:31"
			     aTimeString="12.30.1990 11:12:31"
			     aTimeString="11:12:31"

			   
			If the T90-Keyword is not set:
			   timeString=["N"]time
			   time=hour":"minutes[":"seconds]
			   hour=aNumber, minutes=aNumber, seconds=aNumber

			   if N precedes the time, 24 hours will be added to 
			   the result - i.e. this is the time of the next day

			   valid examples: 
			     aTimeString="11:12"
			     aTimeString="11:12:31"
			     aTimeString="N11:12:31"
			     aTimeString="N33:12:31" ; hour may be GT 24 !

			   invalid examples: 
			     aTimeString="12/30/1990 11:12:31"
 KEYWORDS:
      T90		   if set, the timeString is expected to contain
			   date and time. If not set, timeString is expected
			   to contain the time only.
      MJDT       if set, input time in the MJDT format instead

 OUTPUT:	 
      a structure
      return, {err:-1, $
	           value:LONG(0), $
                 errtext:['text1', 'text2', ...]}
      The fields of the returned structure are :
	err	   a Boolean (-1 or 0)
		   if err EQ -1, timeString did not contain a valid time.
			         in this case, 'errtext' contains an 
				 explanation of the syntax-error
                 if err EQ 0,  timeString was valid. In this case, value 
			         contains the time in seconds
	value	   a long
		   the timeString converted to seconds
                 or a MJDT structure if the keyword MJDT is set

      errtext	   a string-array
		   contains a description of valid formats.

 CALLING SEQUENCE:
	result=convert_timeToSeconds(aString, /T90)
	if result.err then begin
	   dummy=messagebox(result.errtext, ['Cancel'], title='syntax-error')
	   return
	endif
	print, '-> time-format of your string:', result.value

 MODIFICATION HISTORY:       
      september 1995, written by A.Keese 
      january 1997, by R. Friedel, keyword MJDT added

(See /home/jbf/ct/papco/working/papco/papco_lib/convert_time.pro:565)

convert_time[8]

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     
      FUNCTION convert_dayToDate, dayNumber, year
 
 DESCRIPTION:  
      convert a given date (in the format 'dayofyear/year') to a 
      verbose description

 INPUTS:       
      dayNumber	integer - day of year
      year		integer	- year
			this is the date to be converted

 OUTPUT:	 
      a string containing a verbose description of this date in the 
	format 'day.month.year'

 CALLING SEQUENCE:
      print, convert_dayToDate(100, 1990)

 MODIFICATION HISTORY:       
      september 1995, written by A.Keese

(See /home/jbf/ct/papco/working/papco/papco_lib/convert_time.pro:772)

convert_time[9]

 [Previous Routine] [Next Routine] [List of Routines] 
  return the sum of a time plus an offset, or the offset of two times.
  parameters:
     time1, time2: { PAPCO_TIME, mjd:0L, t:float(0), t90:0L }
  keywords:
     /add  add the two times together.  The fields are added, then carry is performed.
     /subtract  subtract the times and borrow is performed.
  returns:
     { PAPCO_TIME }.

(See /home/jbf/ct/papco/working/papco/papco_lib/convert_time.pro:862)

crosspn

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
   CROSSPN

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov

 PURPOSE:
   A version of CROSSP for efficient vector cross products

 CALLING SEQUENCE:
   C = CROSSPN(A, B)

 DESCRIPTION: 

   The function CROSSPN computes the vector cross product (outer
   product).  The difference between CROSSPN and the IDL library
   function CROSSP, is that CROSSPN allows more than one cross
   product to be computed at one time (i.e., it is vectorized).

   Thus, in the expression "C = CROSSPN(A, B)" the vector cross
   product is computed as C = A x B.  Because CROSSPN is vectorized,
   any of the following combinations are valid:

       * A is a 3-vector, B is a 3-vector
            ==> C is the vector cross product C = A x B

       * A is a 3xN array, B is a 3-vector
            ==> C(*,I) = A(*,I) x B    (each A is crossed with B)

       * A is a 3-vector, B is a 3xN array
            ==> C(*,I) = A x B(*,I)  (A is crossed with each B)

       * A is a 3xN array, B is a 3xN array
            ==> C(*,I) = A(*,I) x B(*,I)   (component-by-component)

   If both A and B are arrays then they must have the same
   dimensions.

 INPUTS:

   A - a 3-vector or 3xN array.

   B - a 3-vector or 3xN array.


 RETURNS:

   The vector cross product A x B, either a 3-vector or a 3xN array
   depending on A and B.

 SEE ALSO:

   CROSSP

 MODIFICATION HISTORY:
   Written, CM, 10 Mar 2002
   Documented, CM, 22 Mar 2002

  $Id: papco_math.pro,v 1.14 2007/05/09 17:04:06 jbfaden Exp $

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_math.pro:996)

Cursor_Reset

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO Cursor_Reset

 DESCRIPTION:
	This resets the mouse-selection:
	If a zoom-rectangle or a vertical slicing-line was displayed, it is
	erased.
	If the keyword 'FULLY' is specified, the slice-window and the zoom-
	window are closed.

 INPUTS:
	none

 KEYWORDS:
 	FULLY	if set, the selection-windows are closed

 CALLING SEQUENCE:
	papco_cursor_Reset, /FULLY

 MODIFICATION HISTORY:
     written august and september 1995, Andreas Keese
     march 1996, Haje Korth

(See /home/jbf/ct/papco/working/papco/papco/papco_cursor.pro:1611)

cw_filesel

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
 CW_FILESEL

 PURPOSE:
       This is a compound widget for file selection.

 CATEGORY:
       Input/Output

 CALLING SEQUENCE:
       Result = PAPCO_CW_FILESEL(Parent)

 INPUTS:
       Parent - The widget ID of the parent.

 OPTIONAL KEYWORDS:

        FILENAME
        Set this keyword to have the initial filename filled in the filename text area.

        FILTER - Set this keyword to an array of strings determining the
                 filter types.  If not set, the default is "All Files".  All
                 files containing the chosen filter string will be displayed
                 as possible selections.  "All Files" is a special filter
                 which returns all files in the current directory.  A single
         filter "field" may have several filters separated by a comma.

                 Example:  FILTER=['All Files', '.txt', '.jpg,.jpeg']

        FIX_FILTER - If set, the user can not change the file filter.

        FRAME - If set, a frame is drawn around the widget.

        IMAGE_FILTER - If set, the filter "Image Files" will be added to the
                 list of filters.  If set, and FILTER is not set,
                 "Image Files" will be the only filter displayed.  Valid
                 image files are determined from QUERY_IMAGE.

        MULTIPLE - If set, the file selection list will allow multiple
                 filenames to be selected.  The filename text area will not
                 be editable in this case.  MULTIPLE and SAVE are exclusive
                 keywords.

        PATH - Set this keyword to the initial path the widget is to start
                 in.  The default is the current directory.

        SAVE - If set, the dialog will change to a file saving interface.
               The "Open" button changes to "Save" and the "Filter" dialog
               is named "Save as:".  SAVE and MULTIPLE are exclusive keywords.

        UVALUE - The "user value" to be assigned to the widget.

        UNAME - The "user name" to be assigned to the widget.

        WARN_EXIST - If set, the user is warned if a filename is chosen
               that matches an already existing file. This is useful in
               routines that save to a file.

 OUTPUTS:
 This function returns its Widget ID.

 EXAMPLE:

       fileSel = PAPCO_CW_FILESEL(myBase)

   Using PAPCO_CW_FILESEL
     The widget has a string value that is the currently-selected filename:
       WIDGET_CONTROL, fileSel, GET_VALUE=filename
     To set the filename, use the command:
       WIDGET_CONTROL, fileSel, SET_VALUE=string

 MODIFICATION HISTORY:
   Written by: Scott Lasica, July, 1998
   CT, RSI, July 2000: Minor rewrite. Change dir sorting on Windows.
               Added WARN_EXIST.

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_cw_filesel.pro:81)

cw_papco_props_editor

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: cw_papco_props_editor
 DESCRIPTION:  creates a compound widget for editing the properties set.
 INPUTS:   
   PARENT, type, description
   PROPS_STRUCT, type, description
 KEYWORDS:
   _EXTRA, extra keywords are passed to the root base.
   RETURN_EVENTS, keyw, fire off return events on text fields
   ALL_EVENTS, keyw, fire off all events on text fields
   DOC_LABEL, long, the widget id of a label or text widget.
 RETURNS: 
   type, description
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.13 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_props_editor.pro:491)

datatype

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     : SOHO - CDS

 Name        : 
	DATATYPE()
 Purpose     : 
	Returns the data type of a variable.
 Explanation : 
	This routine returns the data type of a variable in a format specified
	by the optional flag parameter.
 Use         : 
	Result = DATATYPE( VAR  [, FLAG ] )
 Inputs      : 
	VAR	= Variable to examine.
 Opt. Inputs : 
	FLAG	= Output format flag as explained below.  The default is 0.
 Outputs     : 
	The result of the function is the either a string or integer giving the
	data type of VAR.  Depending on the value of FLAG, the result will be
	one of the values from the following table:

		FLAG = 0       FLAG = 1           FLAG = 2       FLAG = 3

		UND            Undefined          0              UND
		BYT            Byte               1              BYT
		INT            Integer            2              INT
		LON            Long               3              LON
		FLO            Float              4              FLT
		DOU            Double             5              DBL
		COM            Complex            6              COMPLEX
		STR            String             7              STR
		STC            Structure          8              STC
		DCO            DComplex           9              DCOMPLEX
		PTR            Pointer           10              POINTER
		OBJ            Object            11              OBJECT

 Opt. Outputs: 
	None.
 Keywords    : 
	HELP	= If set, then a short explanation is printed out.
 Calls       : 
	None.
 Common      : 
	None.
 Restrictions: 
	FLAG, if passed, must be an integer between 0 and 3.
 Side effects: 
	None.
 Category    : 
	Utilities, Arrays.
 Prev. Hist. : 
	Written by R. Sterner, 24 Oct, 1985.
	RES 29 June, 1988 --- added spelled out TYPE.
	R. Sterner, 13 Dec 1990 --- Added strings and structures.
	R. Sterner, 19 Jun, 1991 --- Added format 3.
	Johns Hopkins University Applied Physics Laboratory.

 Copyright (C) 1985, Johns Hopkins University/Applied Physics Laboratory
 This software may be used, copied, or redistributed as long as it is not
 sold and this copyright notice is reproduced on each copy made.  This
 routine is provided as is without any express or implied warranties
 whatsoever.  Other limitations apply as described in the file disclaimer.txt.

 Written     : 
	R. Sterner, JHU/APL, 24 October 1985.
 Modified    : 
	Version 1, William Thompson, GSFC, 23 April 1993.
		Incorporated into CDS library.
	Version 2, William Thompson, GSFC, 16 August 1995
		Incorporated following changes.

       R. Sterner, 18 Mar, 1993 --- Added /DESCRIPTOR.
       R. Sterner, 1995 Jul 24 --- Added DCOMPLEX for data type 9.
       D. Zarro,   1997 Jul 19 --- Added PTR and OBJ for data type 10 and 11.
       D. Zarro,   1999 Jun 15 --- Added MESSAGE statement in case of invalid input

 Version     : 
	Version 3

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/util/datatype.pro:79)

date2mjd

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     :	SOHO - CDS

 Name        :	DATE2MJD()

 Purpose     :	Convert calendar dates to Modified Julian Days.

 Explanation :	This procedure calculates the Modified Julian Day number from
		the year, month and day, or from the year, day-of-year.

 Use         :	Result = DATE2MJD(YEAR, MONTH, DAY)
		Result = DATE2MJD(YEAR, DOY)

 Inputs      :	YEAR	= Calendar year, e.g. 1989.  All four digits are
			  required.

 Opt. Inputs :	MONTH	= Calendar month, from 1-12.
		DAY	= Calendar day, from 1-31, depending on the month.

				or

		DOY	= Day-of-year, from 1-365 or 1-366, depending on the
			  year.

		Either MONTH and DAY, or DOY must be passed.

 Outputs     :	The result of the function is the Modified Julian Day number
		for the date in question.  It is an integral number--fractional
		days are not considered.

 Opt. Outputs:	None.

 Keywords    :	ERRMSG  =  If defined and passed, then any error messages 
                          will be returned to the user in this parameter 
                          rather than being handled by the IDL MESSAGE 
                          utility.  If no errors are encountered, then a null
                          string is returned.  In order to use this feature,
                          the string ERRMSG must be defined first, e.g.,

                            ERRMSG = ''
                            MJD = DATE2MJD ( YEAR, MONTH, DAY, ERRMSG=ERRMSG )
                            IF ERRMSG NE '' THEN ...

 Calls       :	DATATYPE

 Common      :	None.

 Restrictions:	None.

 Side effects:	If number of parameters sent is invalid, ERRMSG is returned as
               a string array of 2 elements if the keyword ERRMSG is set.
		Also, the result returned has a value of -1.

 Category    :	Utilities, Time.

 Prev. Hist. :	None.  However, part of the logic of this routine is based on
		JDCNV by B. Pfarr, GSFC.

 Written     :	William Thompson, GSFC, 13 September 1993.

 Modified    :	Version 1, William Thompson, GSFC, 13 September 1993.
		Version 2, Donald G. Luttermoser, GSFC/ARC, 20 December 1994.
			Added the keyword ERRMSG.  Added test for month to 
			make sure a string is not passed.  Note that there are
			no internal procedures called that use the ERRMSG
			keyword.
		Version 3, Donald G. Luttermoser, GSFC/ARC, 30 January 1995.
			Made the error handling routine more robust.  Note 
			this routine can handle both vector and scalar input.

 Version     :	Version 3, 30 January 1995.

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/date2mjd.pro:73)

date_code()

 [Previous Routine] [Next Routine] [List of Routines] 
 PROJECT:
       SOHO - SUMER

 NAME:	
       DATE_CODE()

 PURPOSE:
       Convert any date/time value into YYYYMMDD format.

 EXPLANATION:
       
 CALLING SEQUENCE: 
       Result = DATE_CODE(time)

 INPUTS:
       TIME - The date/time in any of the standard CDS time formats

 OPTIONAL INPUTS: 
       None.

 OUTPUTS:
       Result - A string with 'YYYYMMDD' format. If error occurs, a null
                string is returned.

 OPTIONAL OUTPUTS:
       None.

 KEYWORD PARAMETERS: 
       None.

 CALLS:
       ANYTIM2UTC

 COMMON BLOCKS:
       None.

 RESTRICTIONS: 
       None.

 SIDE EFFECTS:
       None.

 CATEGORY:
       
 PREVIOUS HISTORY:
       Written April 24, 1995, Liyun Wang, GSFC/ARC

 MODIFICATION HISTORY:
       Version 1, Liyun Wang, GSFC/ARC, April 24, 1995
       Version 2, August 21, 1995, Liyun Wang, GSFC/ARC
          Added ERROR keyword

 VERSION:
       Version 2, August 21, 1995

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/date_code.pro:64)

dealloc_lun

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:    dealloc_lun
 
 DESCRIPTION:  deallocate all lun's assigned with get_lun that are closed but
               have not been deallocated. Used primarily after save/restore,
               which uses get_lun internally but does not seem to free the
               units. Using a global close,/all is no good since we
               only want to make get_lun luns available,
               but don't want to indiscriminantly close all open files!

 INPUTS:       none

 OUTPUT:       none

 KEYWORDS:     
     QUIET, keyw, inhibits verbose output

 CALL:	 dealloc_lun

 HISTORY:      written September 1997, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/dealloc_lun.pro:21)

dmy2ymd()

 [Previous Routine] [Next Routine] [List of Routines] 
 PROJECT:
       SOHO - CDS

 NAME:	
       DMY2YMD()

 PURPOSE:
       To convert date string DD-MM-YY format to YY/MM/DD format.
 EXPLANATION:
       
 CALLING SEQUENCE: 
       Result = DMY2YMD(date)

 INPUTS:
       DATE -- A string scalar in DD-MM-YY or DD/MM/YY format.

 OPTIONAL INPUTS: 
       None.

 OUTPUTS:
       Result -- A string scalar in 19YY/MM/DD format.

 OPTIONAL OUTPUTS:
       None.

 KEYWORD PARAMETERS: 
       None.

 CALLS:
       None.

 COMMON BLOCKS:
       None.

 RESTRICTIONS: 
       None.

 SIDE EFFECTS:
       None.

 CATEGORY:
       
 PREVIOUS HISTORY:
       Written September 26, 1994, by Liyun Wang, GSFC/ARC

 MODIFICATION HISTORY:
       
 VERSION:
       Version 1, September 26, 1994

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/dmy2ymd.pro:59)

download_status

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      FUNCTION download_status

 DESCRIPTION:
      Displays the download status by analyzing the wget logfile.

 INPUTS:
      c_tmp_dir          where to put the files
      c_log_file         name of log file
      c_command          string with full wget command

 OUTPUT:
      function returns number of saved files

 KEYWORDS:
  none

 MODIFICATION HISTORY:
     written July 1997, Haje Korth
     modified september 1997 Torsten Heise
         diveded routine in four functions:
             download_status,
             download_status_get_FileName,
             download_status_get_FileLength and
             download_status_get_BytesRead
         this was necessary to get more than one file at the
         same time ( e.g. with the wget command: wget hydra.mpae.gwdg.de/*.*)

(See /home/jbf/ct/papco/working/papco/papco/papco_get_remote_data.pro:474)

download_status_get_BytesRead

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      FUNCTION download_status_get_BytesRead

 DESCRIPTION:
      Get the number of read bytes of the file currently transfered
      by analyzing the wget logfile.

 INPUTS:
      log_file            name of log file
      line_offset         start at this line with analyzing the wget logfile.
      new_line_offset     set bye this function
      FileRead            set bye this function
 OUTPUT:
      new_line_offset     inspected the wget logfile until this
                          position
      FileRead            1 if the file read completly
      function returns the name of the currently transfered file

 KEYWORDS:
  none

 MODIFICATION HISTORY:
     written july 1997, Haje Korth
     rewritten september 1997, Torsten Heise

(See /home/jbf/ct/papco/working/papco/papco/papco_get_remote_data.pro:343)

download_status_get_FileLength

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      FUNCTION download_status_get_FileLength

 DESCRIPTION:
      Get the length of the file currently transfered by analyzing
      the wget logfile.

 INPUTS:
      log_file            name of log file
      line_offset         start at this line with analyzing the wget logfile.
      new_line_offset     inspected the wget logfile until this

 OUTPUT:
      new_line_offset
      function returns the length of the currently transfered file

 KEYWORDS:
  none

 MODIFICATION HISTORY:
     written July 1997, Haje Korth
     rewritten september 1997, Torsten Heise

(See /home/jbf/ct/papco/working/papco/papco/papco_get_remote_data.pro:252)

download_status_get_FileName

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      FUNCTION download_status_get_FileName

 DESCRIPTION:
      Get the name of the file currently transfered by analyzing the
      wget logfile.

 INPUTS:
      log_file            name of log file
      line_offset         start at this line with analyzing the wget logfile.
      new_line_offset     inspected the wget logfile until this
                          position, set bye this function
 OUTPUT:
      new_line_offset
      function returns the name of the currently transfered file

 KEYWORDS:
  none

 MODIFICATION HISTORY:
     written july 1997,Haje Korth
     rewritten september 1997, Torsten Heise

(See /home/jbf/ct/papco/working/papco/papco/papco_get_remote_data.pro:170)

doy2utc

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     : SOHO - CDS     
                   
 Name        : DOY2UTC()
               
 Purpose     : Converts day of year to internal CDS time format.
               
 Explanation : Takes day-of-year value and year (default=current) and
               converts to the internal CDS UTC time structure.
               
 Use         : IDL> utc = doy2utc(doy [,year])
    
 Inputs      : doy - integer day-of-year value (can be an array)
               
 Opt. Inputs : year - the applicable year (default is current year)
                      If this is an array it must have the same dimensions
                      as doy.
               
 Outputs     : Function returns a CDS UTC structure.
               
 Opt. Outputs: None
               
 Keywords    :	ERRMSG       =	If defined and passed, then any error messages 
				will be returned to the user in this parameter 
				rather than being handled by the IDL MESSAGE 
				utility.  If no errors are encountered, then a 
				null string is returned.  In order to use this 
				feature, the string ERRMSG must be defined 
				first, e.g.,

					ERRMSG = ''
					RESULT = DOY2UTC( DOY, ERRMSG=ERRMSG )
					IF ERRMSG NE '' THEN ...

 Calls       :	None

 Common      : None
               
 Restrictions: None
               
 Side effects: If an error is encountered and the ERRMSG keyword has been 
		set, the result returned is an integer -1.  If ERRMSG has
		not been set and an error occurs, DOY2UTC returns with a
		null result.
               
 Category    : Util, time
               
 Prev. Hist. : None

 Written     : C D Pike, RAL, 5-Jan-95
               
 Modified    :	Version 1, C.D. Pike, RAL, 5 January 1995
		Version 2, C.D. Pike, RAL, 9 January 1995
			Fix bug if input is single value array.
		Version 3, Donald G. Luttermoser, GSFC/ARC, 1 February 1995
			Added the keyword ERRMSG.  Set ONERROR flag to 2.
			Corrected bug in YEAR calculation.  Note that this
			routine can handle both scalar and vector input.
               Version 4, Changed handling of input year array, as 
                          suggested by S Paswaters.  CDP, 10-Mar-95

 Version     : Version 4, 10-Mar-95

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/doy2utc.pro:63)

draw_error_panel

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: draw_error_panel
 DESCRIPTION: draw a panel containing the message. 
 INPUTS:   
   MESSAGE, string|strarr, message to display, one element per line.
 KEYWORDS:
 SIDE EFFECTS: affects plot device, affects coordinateSystems common block
 EXCEPTIONS:
 EXAMPLES: 
   draw_error_panel, [ 'Hello', 'There!' ]
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.4 $
 CURATOR: Jeremy Faden
 HISTORY:  
   02-Dec-2004, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/draw_error_panel.pro:19)

dsp_strarr

 [Previous Routine] [Next Routine] [List of Routines] 
 PROJECT:
      SOHO - CDS

 NAME:
      DSP_STRARR

 PURPOSE: 
      To display a string array in a text widget.

 EXPLANATION:
      
 CALLING SEQUENCE: 
      DSP_STRARR, string_array [, font = font, title=title]

 INPUTS:
      strings -- The string array to be displayed. 
 OPTIONAL INPUTS: 
      None.

 OUTPUTS:
      None.

 OPTIONAL OUTPUTS:
      None.

 KEYWORD PARAMETERS: 
      FONT   -- Font to be used for the text widget. Default: fixed
      TITLE  -- Title of the widget window. Default: 'Info Window'
      ONE_COPY -- Set this keyword to let xmanager know that only one copy of
                  this widget is allowed to run at one time.
 CALLS:
      None.

 COMMON BLOCKS:
      None.

 RESTRICTIONS: 
      None.

 SIDE EFFECTS:
      None.

 CATEGORY:
      Utilities, widgets

 PREVIOUS HISTORY:
      
 MODIFICATION HISTORY:
      Written September 2, 1994, by Liyun Wang, GSFC/ARC
      
 VERSION:

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/cdsxtra/dsp_strarr.pro:61)

e: papco_math.pro

 [Previous Routine] [Next Routine] [List of Routines] 
  file:   papco_math.pro

  description: this file contains math procedures and functions that are regularly
               used by the papco modules.
           Each procedure's name starts with the prefix 'papco_', to
               distinguish it from other programs.
  
  MODIFICATIONS: 
           Separated the math functions from papco_util, Feb. 2006, A. Aasnes at LANL

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_math.pro:11)

entrybox[3]

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:     
      entryBox_event
 
 DESCRIPTION:  
      this is the event-handler. It is called by XMANAGER only
 
 INPUTS:       
      event 	: the event to be handled
 
 OUTPUT:	 
      none

 CALLING SEQUENCE:
      this procedure is to be called by XMANAGER only

 MODIFICATION HISTORY:       
      january 1997, written by R, Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/entrybox.pro:46)

entrybox[4]

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     
       FUNCTION entryBox, strArray, buttons, CENTER=center
 
 DESCRIPTION:  
      A window containing a entry field and buttons is displayed modally.
      The index of the pressed button is returned

 INPUTS:       
	strArray:   An array containing the text to be displayed
	buttons :   a string-array containing the buttonlabels

 KEYWORDS:
	CENTER  :   If set, the displayed text is horizontally centered           
      TITLE   :   The title of the entry-box
      DefVal  :   A default value for the entry field

 OUTPUT:	 
      -1	:   if no button was selected
      Integer :   if a button was selected, its index is returned 
		    the first button has index 0

 CALLING EXAMPLE:
      IF EntryBox(['Exit','Program'], ['Yes', 'No'],$
                      TITLE='Exit Entry', /CENTER) EQ 0 $
         THEN EXIT

 MODIFICATION HISTORY:

(See /home/jbf/ct/papco/working/papco/papco_lib/entrybox.pro:100)

fast logical routines

 [Previous Routine] [Next Routine] [List of Routines] 
 name: fast logical routines

 Logical operations useful for various kinds of problems. Very speedy
 routines as we use histogram function. Note the use of [a] and [b]
 to avoid problems when a or b are not arrays.

 They are the functions:
   papco_aandb: retrieve union of two integer arrays both A and B
   papco_aorb: A or B or both A and B
   papco_anotb: A and NOT B
   papco_aXORb: Only A or Only B

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_math.pro:1151)

file functions.pro

 [Previous Routine] [Next Routine] [List of Routines] 
 file: papco_lib/fit/functions.pro
 A collection of mathematical functions, useful for f.ex. curvefit

(See /home/jbf/ct/papco/working/papco/papco_lib/fit/functions.pro:4)

file papco.pro

 [Previous Routine] [Next Routine] [List of Routines] 
 FILE:
    papco_XX.X/papco/papco.pro

 DESCRIPTION:
    This file contains the main widget of PAPCO, the Panelplot-Composer.
    contained are :      - the widget-construction-routines
                          - the event-handlers.

    The Panelplot-composer is a window in which you can compose plots
    from various modules. You can add new plots, resize the plots, edit or
    delete the plots, zoom into the plots, save list of plots, load them,
    print them to various devices.

 FILES BELONGING TO THE MAIN-WINDOW:

      papco.pro
         - initialize papco state

      papco_plotedit.pro
         - adding and editing plotinfos
         - deleting plotinfos
         - routine for obtaining verbose description of plotinfos

      papco_files.pro
         - procedures for saving and loading plotinfos
         - procedures for writing and reading default-settings
         - batch-mode

      papco_settime.pro
         - procedures for selecting an orbit and time-range
         - procedure for displaying time-range when using time-slider

      papco_draw.pro
         - routines for outputting plots.

      papco_draw_window.pro
         - routines for handling the graphics output window

      papco_cursor.pro
         - routines for handling the mouse-cursor
         - routines for zooming into plots
         - routines for doing slices of plots
         - routines for doing level zero access

      papco_edit_type.pro
         - changing the plot-type of a plotinfo

      papco_opsys.pro
         - implements architecture independence for some routines

 COMMON-BLOCKS:
    COMMON PLOT_COMPOSER, widgetdata

 STRUCTURES:
    The structures defined in this file are:

        papco_PLOTINFO     -> a structure to hold the description of
                              one plot-panel

        PLOT_COMPOSER      -> a structure to hold the global variables
                              of the papco main-window.

        PLOT_DRAWN         -> when a plot is drawn to the screen,
                              variables of this type are used
                              for storing info about this plot

    They are described in the file
    papco_XX/papco_doc/papco_variables.text

    Those procedures are contained here:
       PRO papco_error_handler
       FUNCTION papco_getPlotInfoStruct
       FUNCTION papco_DescriptionFor, plotInfo, totalHeight
       PRO papco_EditPlotType, plotNumber
       PRO papco_DeletePlot, plotNumber
       PRO papco_PrintMenu_event, event
       FUNCTION papco_SetOrbit, anOrbitNr
       PRO papco_setTime, newTime, STARTTIME=starttime, ENDTIME=endtime
       PRO papco_DrawTimeRange, newStart, newEnd, CLEAR_ONLY=CLEAR_ONLY
       PRO papco_main_Event, Event
       PRO papco_Refresh, TIME=TIME, LIST=LIST, NEW_TIMERANGE=NEW_TIMERANGE,
             ALL=ALL, PRINTER=PRINTER,
             SELECT_TIME_METHOD=SELECT_TIME_METHOD
       PRO papco_RefreshList
       PRO papco_Input, DISABLE=DISABLE, ENABLE=ENABLE
       PRO papco, GROUP=Group

 MODIFICATION HISTORY: (applies to all routines in this file)
     august,september 1995, written by A.Keese
     november 1995, modified by R.Friedel
     march 1996, modified by H.Korth
     october 1996, modified by R.Friedel
     january 1997, modified by R.Friedel
     october 1997, modified by R.Friedel
     constant updates by R Friedel, latest January 2003

(See /home/jbf/ct/papco/working/papco/papco/papco.pro:98)

file papco_cursor.pro

 [Previous Routine] [Next Routine] [List of Routines] 
 FILE:
    $PAPCO_PATH/papco_cursor.pro

    This file belongs to the main-window of the papco-project. See
    papco.pro for further information.

 DESCRIPTION:
    implements the handling of mouse-events for the widgetData.dw_draw-
    widget.

    There are two main functionalities in this file:

         1. Providing all the procedures for standard papco slices
         2. Calling user defined routines for user added slices.

    Adding of user slices is done in the papco main routine papco.pro
    The way this works: the user sets up an environmnetal variable
    called USER_MOUSE_ACTIONS in papco_set_variables before starting
    up papco. This variable contains a string of the names of the
    user-defined mouse actions in the following format:
    'user_slice_a/user_slice_b/user_slice_c'  etc. Seperate words
    Seperate words by underscores, slices types by backslash.
    These slice types are added to the Mouse Action menu. When chosen,
    and enabled by your plot_type, papco_cursor will attempt to call
    a function "user_slice_plot_type" to handle the slice.

    Currently papco provides 5 "pre-written" slice types. Two of these
    function work as they are:

         zooming
         haircursor

    The first enables the user create a rectangular area in the drawing
    widget by dragging the mouse. While dragging, data-coordinates are
    displayed in a small window. Afterwards, the user may zoom into this
    rectangle.
    The second displays a large hair cursor and prints out the
    x,y,z values of the mouse click both at the mouse click and
    at the top of the draw window.

    The remaining three are functioning templates which don't do much
    by themselves, but can be easily extended by the user

         drawing a slice of data
         accessing level zero application
         writing out data from a plot

    When slicing, the user selects a time by clicking into the drawing-
    widget. Then, the data for this time are displayed in a small window,
    which contains a draw window for a user-defined plot. Possible uses
    are to draw a line spectrum for a color spectrogram.

    When accessing level zero, another widget application can be called.
    This application only needs to know the time, which is passed
    across in the call. The idea is to use this slice option to call
    a "level zero" tool for the data, which can display individual detecors,
    distribution functions etc.

    When writing out data, the mouse returns the panel and the x/y
    coordinates. The user can then open a file to write the data into.
    This is usefull for reading off a series of event times into a file.

    Those procedures are contained:

       FUNCTION papco_cursor_time,panelnr
	     ->

       FUNCTION papco_Normal_To_Data, panelNr, normal_position
	     -> convert normal coordinates of the plot-panel to data-
		coordinates of one plot.

	 FUNCTION papco_Data_To_Normal, panelNr, data_position
	     -> convert data-coordinates of one plot to normal coordinates

       FUNCTION papco_cursor_WhichPanel, normal_x, normal_y
	     -> return the number of the panelplot, the normal position
		'normal_x, normal_y' belongs to

	 PRO papco_cursor_Reset, FULLY=FULLY
	     -> clear mouse-selection

	 PRO papco_vert_slice_Event, Event
	     -> called, when an event occured in the slice-info-window

	 PRO papco_vert_slice, panelNr, seconds, yValue, CLOSE=CLOSE
	     -> draw a slice

	 PRO papco_cursor_UpdateData, YSCL=YSCL, TIME=TIME
	     -> update cursor-selection

	 PRO papco_cursor_Rect_Event, event
	     -> called, when an event occured in the zoom-info-window

	 PRO papco_cursor_Rect, panelNr, normal_x, normal_y, CLOSE=CLOSE
	     -> draw zoom-rectangle

	 PRO papco_cursor_ShowSelection, panelNr, x, y, normal_x, normal_y, $
				         ERASE_ONLY=ERASE_ONLY
	     -> show current selection

       PRO papco_cursor_SetPointer, panelNr, normal_x, normal_y
	     -> set the pointer-icon

	 PRO papco_cursor, event
	     -> handles all events for the draw-widget

       PRO papco_cursor_HairCursor
	     -> draws a large hair cursor and x,y,z value

       FUNCTION papco_slice_value,slice_name
	     -> returns slice value for a slice name

 MODIFICATION HISTORY:
     august,september 1995, written by A.Keese
     may 1996, modified R. Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_cursor.pro:117)

file papco_draw_window.pro

 [Previous Routine] [Next Routine] [List of Routines] 
 FILE:
    $papco_PATH/papco_draw_window.pro

 DESCRIPTION:
    This file contains routines for creating and maintaining papco Draw
    windows.
       - the draw-widget-construction-routines
       - the event-handlers.

 FILES BELONGING TO THE MAIN-WINDOW:

      See the header in papco.pro

 COMMON-BLOCKS:
    One Common-Block is defined:
 COMMON papco_DRAW, drawWidgetData

 STRUCTURES:
    The structures defined in this file are:
        drawWidgetData     -> a structure to hold the description of
				the current draw window

    They are described in the file
	  $papco_BASE/papco_doc/papco_variables.text

    Those procedures are contained:
       PROCEDURE papco_draw_window, name
       PROCEDURE papco_draw_window_Event, Event

 MODIFICATION HISTORY:
    october 1996, written by R.Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_draw_window.pro:33)

file papco_editslots.pro

 [Previous Routine] [Next Routine] [List of Routines] 
 FILE:
    $papco_PATH/papco_editslots.pro

    This file belongs to the main-window of the papco-project. See
    papco.pro for further information.

 DESCRIPTION:
    Contained are procedures for changing the panel editor list.

    Those procedures are contained:

      pro papco_stripemptyslots
	   -> removes any gaps (empty slots) in the panel editor window,
            preserving any overplots!

	pro papco_resetslots
         -> resets all panels to height one, top at bottom, ascending

      pro papco_resortslots
         -> resorts the panels so that current bottom plot goes
            to bottom of list, ascending upwards

 KEYWORDS:

 MODIFICATION HISTORY:
     june,1996, written by R. Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_editslots.pro:28)

file papco_forward.pro

 [Previous Routine] [Next Routine] [List of Routines] 
 FILE:
    $PAPTO_PATH/papco_forward.pro

 DESCRIPTION:
    This contains some FORWARD_FUNCTION - statements that must be
    run/compiled before the rest of papco is run.

 HOW TO START:
    This file is run implicitly when executing @papco_init
    You can start it from IDL by typing
       @papco_forward

 MODIFICATION HISTORY:
     august/september 1995, written by A.Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_forward.pro:16)

file papco_get_remote_data.pro

 [Previous Routine] [Next Routine] [List of Routines] 
 FILE:
    $papco_PATH/papco_get_remote_data.pro

    This file belongs to the papco-project and provides a papco
    standard utility for papco modules.

 DESCRIPTION:
    Contained are procedures accessing and downloading data files
    via ftp using the UNIX GNU freeware "wget".
    It is up to the module writer to use and access the routines contained
    here. The idea is that if a data file cannot be found on the
    user's local system, then these routines are used to "get" data from
    a remote site.

    Those procedures are contained:

      FUNCTION papco_get_remote_host_name
       -> extracts user and password from host name string

      PRO papco_get_remote_data
       -> downloads data from a remote system using wget

      FUNCTION process_active
       -> checks if a specific process is running

      FUNCTION download_status_get_FileName
       -> get name of file in transfer by parsing the wget logfile.

      FUNCTION download_status_get_FileLength
       -> get length of file in transfer by parsing the wget logfile.

      FUNCTION download_status_get_BytesRead
       -> get bytes transferred of file by parsing the wget logfile.

      PRO limit_download
       -> limits the number of wget prosesses that can run at a time

      FUNCTION download_status
       -> displays the download status by parsing the wget logfile.

      PRO papco_get_remote_data_event
       -> Event handler for papco_get_remote_data

      PRO papco_get_remote_file_list_event
       -> Event handler for papco_get_remote_file_list

      PRO papco_get_remote_file_list
       -> download the file list of a remote  directory using wget

      PRO papco_get_remote_account_info
       -> checks the url for user&pwd  and gets these interactively

      PRO papco_get_remote_account_info_event
           -> Event handler for papco_get_remote_account_info

 MODIFICATION HISTORY:
     written september 1997, Torsten Heise

(See /home/jbf/ct/papco/working/papco/papco/papco_get_remote_data.pro:59)

file papco_init.pro

 [Previous Routine] [Next Routine] [List of Routines] 
 FILE:
    $PAPTO_PATH/papco_init.pro

 DESCRIPTION:
    initialize papco and compile all needed programs

 HOW TO START:
    from IDL, type @papco_init
    now called automatically by papco_startup
    afterwards, you can start papco by executing the command "papco"

 MODIFICATION HISTORY:
     August/september 1995, written by A. Keese
     November 1995, modified R. Friedel
     September 2002, modified R. Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_init.pro:17)

file papco_output.pro

 [Previous Routine] [Next Routine] [List of Routines] 
 FILE:
    $PAPCO_PATH/papco_output.pro

    This file belongs to the core of the PAPCO project.

 DESCRIPTION:
    This file provides generic routines for PAPCO modules to make their
    data avauilable. This data can either be made available in memory
    or in a variety of output file formats.
    These routines get called by the user-written data plot routine.

    Those procedures are contained:

      PROCEDURE papco_write_data, time, data
	     -> writes the calling modules' panel plot data to file.

       FUNCTION papco_unformat_idlstring, idlstr
	     -> Removes any "!" format strings from a given string


 MODIFICATION HISTORY:
    January 1998, written by R. Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_output.pro:24)

file papco_slice_panel.pro

 [Previous Routine] [Next Routine] [List of Routines] 
 FILE:
    $PAPCO_PATH/papco_slice_panel.pro

    This file belongs to the PAPCO-project. See $PAPCO_PATH/papco.pro for
    further information.

 DESCRIPTION:
    This file contains the default PAPCO panel editor for the slice
    type plot for any module.

    Any slices listed in the module's plot_type_slice.pro header
    will be automatically included in this panel.

 COMMON-BLOCKS:
    papco_slice_panel_data	contains the window-information

 STRUCTURES:
    This module creates one concrete structure, that inherits from the
    PAPCO_PANEL_EDITOR-structure (see $PAPCO_PATH/papco_panel.pro for a
    description).
       {papco_slice_panel_DATA,
	     ; imagine the PAPCO_PANEL_EDITOR-structure was inserted...

    For a more complete description see $PAPCO_PATH/papco_variables.text

 OVERVIEW:
    This function creates the editor-window:
       FUNCTION  papco_slice_panel, plotinfo, GROUP=group, ACTION=ACTION
    You might try this:
	 print, papco_slice_panel(PAPCO_getPlotInfoStruct())
       which calls up the window.

 MODIFICATION HISTORY:
     November 2000, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/slice_thumbs/papco_slice_panel.pro:36)

file papco_startup_init.pro

 [Previous Routine] [Next Routine] [List of Routines] 
 FILE:
    $PAPTO_PATH/papco_startup_init.pro

 DESCRIPTION:
    initialize papco routines needed for startup widget only.

 CALLED FROM:
    papco_set_variables.pro

 MODIFICATION HISTORY:
    February 1999, written R.Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_startup_init.pro:13)

find_with_def

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     : SOHO - CDS

 Name        : 
	FIND_WITH_DEF()
 Purpose     : 
	Searches for files with a default path and extension.
 Explanation :
	Finds files using default paths and extensions, similar to using the
	DEFAULT keyword with the OPEN statement in VMS.  Using this routine
	together with environment variables allows an OS-independent approach
	to finding files.
 Use         : 
	Result = FIND_WITH_DEF( FILENAME, PATHS  [, EXTENSIONS ] )

	FILENAME = ''
	READ, 'File to open: ', FILENAME
	FILE = FIND_WITH_DEF( FILENAME, 'SERTS_DATA', '.fix' )
	IF FILE NE '' THEN ...

 Inputs      : 
	FILENAME   = Name of file to be searched for.  It may either be a
		     complete filename, or the path or extension could be left
		     off, in which case the routine will attempt to find the
		     file using the default paths and extensions.

	PATHS	   = One or more default paths to use in the search in case
		     FILENAME does not contain a path itself.  The individual
		     paths are separated by commas, although in UNIX, colons
		     can also be used.  In other words, PATHS has the same
		     format as !PATH, except that commas can be used as a
		     separator regardless of operating system.  The current
		     directory is always searched first, unless the keyword
		     NOCURRENT is set.

		     A leading $ can be used in any path to signal that what
		     follows is an environmental variable, but the $ is not
		     necessary.  (In VMS the $ can either be part of the path,
		     or can signal logical names for compatibility with Unix.)
		     Environmental variables can themselves contain multiple
		     paths.

 Opt. Inputs : 
	EXTENSIONS = One or more extensions to append to end of filename if the
		     filename does not contain one (e.g. ".dat").  The period
		     is optional.  Multiple extensions can be separated by
		     commas or colons.
 Outputs     : 
	The result of the function is the name of the file if successful, or
	the null string if unsuccessful.
 Opt. Outputs: 
	None.
 Keywords    : 
	NOCURRENT = If set, then the current directory is not searched.
 Calls       : 
	STR_SEP, BREAK_PATH
 Common      : 
	None.
 Restrictions: 
	None.
 Side effects: 
	None.
 Category    : 
	Utilities, Operating_system
 Prev. Hist. : 
	None, but influenced by TEST_OPENR by William Thompson, and CONCAT_DIR
	by M. Morrison.
 Written     : 
	William Thompson, GSFC, 5 April 1993.
 Modified    : 
	Version 1, William Thompson, GSFC, 3 May 1993.
		Removed trailing / and : characters.
		Fixed bugs
		Allow for commas within values of logical names.
		Added keyword NOCURRENT.
		Changed to call BREAK_PATH
	Version 2, William Thompson, GSFC, 3 November 1994
		Made EXTENSIONS optional.
 Version     : 
	Version 2, 3 November 1994

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/system/find_with_def.pro:83)

fixmax

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: FIXMAX

 PURPOSE:
	Calculates the nearest integer larger than a given number.
	
 CATEGORY: General Math

 CALLING SEQUENCE:

	Y = FIXMAX(X)

 INPUTS:
	X can be of any numeric type or array structure.

 OUTPUTS:
	Y is INTEGER and LARGER THAN X.

 MODIFICATION HISTORY:
 	Written by:M.Fraenz jun 93

(See /home/jbf/ct/papco/working/papco/papco_lib/axis_label/fixmax.pro:22)

fixmin

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: FIXMIN

 PURPOSE:
	Calculates the nearest integer smaller than a given number.
	
 CATEGORY: General Math

 CALLING SEQUENCE:

	Y = FIXMIN(X)

 INPUTS:
	X can be of any numeric type or array structure.

 OUTPUTS:
	Y is INTEGER and SMALLER THAN X.

 MODIFICATION HISTORY:
 	Written by:M.Fraenz jun 93

(See /home/jbf/ct/papco/working/papco/papco_lib/axis_label/fixmin.pro:22)

fx_root

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
       FX_ROOT

 PURPOSE:
       This function computes real and complex roots (zeros) of
       a univariate nonlinear function.

 CATEGORY:
       Nonlinear Equations/Root Finding

 CALLING SEQUENCE:
       Result = FX_ROOT(X, Func)

 INPUTS:
       X :      A 3-element initial guess vector of type real or complex.
                Real initial guesses may result in real or complex roots.
                Complex initial guesses will result in complex roots.

       Func:    A scalar string specifying the name of a user-supplied IDL
                function that defines the univariate nonlinear function.
                This function must accept the vector argument X.

 KEYWORD PARAMETERS:
       DOUBLE:  If set to a non-zero value, computations are done in
                double precision arithmetic.

       ITMAX:   Set this keyword to specify the maximum number of iterations
                The default is 100.

       STOP:    Set this keyword to specify the stopping criterion used to
                judge the accuracy of a computed root, r(k).
                STOP = 0 implements an absolute error criterion between two
                successively-computed roots, |r(k) - r(k+1)|.
                STOP = 1 implements a functional error criterion at the
                current root, |Func(r(k))|. The default is 0.

       TOL:     Set this keyword to specify the stopping error tolerance.
                If the STOP keyword is set to 0, the algorithm stops when
                |x(k) - x(k+1)| < TOL.
                If the STOP keyword is set to 1, the algorithm stops when
                |Func(x(k))| < TOL. The default is 1.0e-4.

 EXAMPLE:
       Define an IDL function named FUNC.
         function FUNC, x
           return, exp(sin(x)^2 + cos(x)^2 - 1) - 1
         end

       Define a real 3-element initial guess vector.
         x = [0.0, -!pi/2, !pi]

       Compute a root of the function using double-precision arithmetic.
         root = FX_ROOT(x, 'FUNC', /double)

       Check the accuracy of the computed root.
         print, exp(sin(root)^2 + cos(root)^2 - 1) - 1

       Define a complex 3-element initial guess vector.
         x = [complex(-!pi/3, 0), complex(0, !pi), complex(0, -!pi/6)]

       Compute a root of the function.
         root = FX_ROOT(x, 'FUNC')

       Check the accuracy of the computed root.
         print, exp(sin(root)^2 + cos(root)^2 - 1) - 1

 PROCEDURE:
       FX_ROOT implements an optimal Muller's method using complex
       arithmetic only when necessary.

 REFERENCE:
       Numerical Recipes, The Art of Scientific Computing (Second Edition)
       Cambridge University Press
       ISBN 0-521-43108-5

 MODIFICATION HISTORY:
       Written by:  GGS, RSI, March 1994
       Modified:    GGS, RSI, September 1994
                    Added support for double-precision complex inputs.

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_fx_root.pro:85)

gen_fit_release[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 program from Jack Scudder - for detector intercallibration work.

(See /home/jbf/ct/papco/working/papco/papco_lib/fit/gen_fit_release.pro:3)

gen_fit_release[2]

 [Previous Routine] [Next Routine] [List of Routines] 
=====================================================================
ME: gen_fit_release.pro

rpose: To develop general fitting routine by
       hypothesis testing for straight line model
       with smart start and Marquardt back end
       including error estimates.

itten,  5/1/97, Jack Scudder
dified, 5/2/97, Pamela Puhl-Quinn and Jeremy Faden
        5/19/97, added guess_slope keyword
        6/27/97, added intercept-only code JDS/RDH (gen_fit_mod)
        8/11/97 placed in common directory and renamed gen_fit_v04
        1/17/98 renamed gen_fit_v05, fixed c95 dependence on
                nparms
        5/14/98 -  * Renamed gen_fit_release
                   * Added force_kappa_search keyword:
                         Kappa search method will be used to
                         bracket the zero; error estimates in SLOPE
                         ONLY will be made using the kappa
                         surface itself; these estimates are 
                         returned in ks_68, ks_95 and ks_99.
                   * Added n_iterations keyword
                   * Cleaned up user interface (doc_library friendly)
                     Just type gen_fit_release to see the documentation
        10/15/98 - Refined the logic regarding determining errors
                   when reduced chisq is < 1.  Renormalize the chisq
                   surface so that the minimum value is on the
                   order of the # of degrees of freedom, THEN
                   find errors on the fit parameters from this temporary
                   chisq surface.  This logic applies to the
                   determination of c68, c95, c99, ks_68, ks_95,
                   ks_99.
        04/13/99 - Fixed the rchisq normalization - Wasn't correct
                   for nparms not equal to 2.

rator, Pamela Puhl-Quinn, ppq@space-theory.physics.uiowa.edu

----------------- KEYWORDS ----------------------

  INFO:   Calls doc_library to display this header documentation.
          1: print to terminal, 2: print to default printer

x,sigma_x=sigma_x       - abscissa data and errors (IN)
y,sigma_y=sigma_y       - ordinate data and errors (IN)
tstr=titstr             - title string for kappa picture (IN)
iterations=n_iterations - Maximum # of iterations to use when 
                          Bolzano is zeroing in (default=100) (IN)
arms=nparms             - number of parameters to fit (IN)
                            0 = intercept only (slope=1)
                            1 = slope only (intercept=0)
                            2 = slope and intercept (default)
ess_slope=guess_slope   - your best guess on the slope value (IN,optional)
rorpercent=errorpercent - converge to this rel. tolerence (IN)
                            .06    = agreement w/i 3 sig. figs
                            .002   = agreement w/i 4 sig. figs (default)
                            .0002  = agreement w/i 5 sig. figs
                            .00004 = agreement w/i 6 sig. figs
                            .000001= agreement w/i 7 sig. figs
ope=slope               - slope (OUT)
tercept=intercept       - intercept (OUT)
isq=chisq               - chi-squared of the fit (OUT)
hisq=rchisq             - reduced chi-squared of the fit (OUT)
=s2                     - (normalized distance of each point from fit) ^ 2

8=c68, c95=c95, c99=c99 - 68%, 95% and 99% confidence
                          level symmetric errors in slope AND intercept
                          (OUT)
                 e.g., c68=[slope error, intercept error]

_c68=ks_c68,ks_c95=ks_c95,ks_c99=ks_c99
                        - 68%, 95% and 99% confidence
                          level asymmetric error in SLOPE ONLY
                          (OUT only when force_kappa_search is set)
                 e.g., ks_c68=[slope error to left, slope error to right]
                 NOTE: 68, 95 AND 99 CAN ALL BE IDENTICAL IF 
                       THE NUMBER OF DATA POINTS IS LARGE AND THE
                       CHI-SQUARED IS NARROW (RUN INTO CHI-SQUARED
                       GRID RESOLUTION LIMITATIONS). USE THE
                       kappa_picture KEYWORD IF YOU WANT TO SEE THIS..

_range_deg=[x,y]       specify range for kappa search.
     
orce_kappa_search       - Forces kappa search method to bracket zero;
                          ks_c68, ks_c95, ks_c99 are filled with
                          asymmetric slope errors determined from
                          the kappa surface itself

erbose                  - Diagnostics written out

ppa_picture=nwindow     - window number for kappa vs f1 plot (nonzero) (IN)
rint                    - In case you want to print the above plot
ime=itime               - Pam's diag parameter (IN)
ppa_data=kappa_data     - Data to make the kappa vs f1 picture (OUT)
atus=status         - 2=fail, kappa search failed (OUT)
                      1=pass, zero bracketed,passed tolerence test on f1
                      0=fail, dkappadf1 < 1.e-19
                      3=fail, zero brack., passed tol., MAXIMUM!
                      4=pass, For nparms=0, slope=1 used, intercept found
                      5=fail, Couldn't converge within n_iterations
=====================================================================

(See /home/jbf/ct/papco/working/papco/papco_lib/fit/gen_fit_release.pro:344)

get_leap_sec

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     :	SOHO - CDS

 Name        :	GET_LEAP_SEC

 Purpose     :	Returns the dates of all known leap seconds.

 Explanation :	The routine returns the Modified Julian Day number of all known
		leap seconds.  The dates are taken from the file
		'leap_seconds.dat' in the directory given by the environment
		variable TIME_CONV.  That file is read in the first time that
		GET_LEAP_SEC is called.  These values are then stored in an
		internal common block for subsequent calls.  The file is also
		reread whenever the current day number changes.

 Use         :	GET_LEAP_SEC, MJD

 Inputs      :	None.

 Opt. Inputs :	None.

 Outputs     :	MJD	= An array containing the Modified Julian Day numbers
			  for all dates on which a leap second was inserted,
			  starting with 31 December 1971.

 Opt. Outputs:	None.

 Keywords    :	ERRMSG	=  If defined and passed, then any error messages 
			   will be returned to the user in this parameter 
			   rather than using the IDL MESSAGE utility.  If no
			   errors are encountered, then a null string is
			   returned.  In order to use this feature, the 
			   string ERRMSG must be defined first, e.g.,

				ERRMSG = ''
				GET_LEAP_SEC, MJD, ERRMSG=ERRMSG
				IF ERRMSG NE '' THEN ...

 Calls       :	FIND_WITH_DEF, GET_UTC

 Common      :	LEAP_SECONDS is an internal common block.

 Restrictions:	This procedure requires a file containing the dates of all leap
		second insertions starting with 31 December 1971.  This file
		must have the name 'leap_seconds.dat', and must be in the
		directory given by the environment variable TIME_CONV.  It must
		be properly updated as new leap seconds are announced.

 Side effects:	None.

 Category    :	Utilities, time.

 Prev. Hist. :	None.

 Written     :	William Thompson, GSFC, 21 September 1993.

 Modified    :	Version 1, William Thompson, GSFC, 21 September 1993.
		Version 2, William Thompson, GSFC, 14 November 1994
			Changed .DAY to .MJD
		Version 3, Donald G. Luttermoser, GSFC/ARC, 20 December 1994
			Added the keyword ERRMSG.
		Version 4, Donald G. Luttermoser, GSFC/ARC, 30 January 1995
			Added ERRMSG keyword to internally called procedures.
			Made the error handling procedures more robust.
		Version 5, William Thompson, GSFC, 15 March 1995
			Changed CDS_TIME to TIME_CONV

 Version     :	Version 5, 15 March 1995

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/get_leap_sec.pro:70)

get_lib

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     : SOHO - CDS

 Name        : 
	GET_LIB()
 Purpose     : 
	Place elements of !PATH into a string array..
 Explanation : 
	Place library and directory elements of !PATH into a string array.
	Used by SCANPATH.
 Use         : 
	Result = GET_LIB()
	Result = GET_LIB( PATH )
 Inputs      : 
	None required.
 Opt. Inputs : 
       PATH = Path name (default is !path).
 Outputs     : 
	Function result is a string array of path elements.
 Opt. Outputs: 
	None.
 Keywords    : 
	None.
 Calls       : 
	PATH_EXPAND, GETTOK
 Common      : 
	None.
 Restrictions: 
	None.
 Side effects: 
	None.
 Category    : 
	Documentation, Online_help.
 Prev. Hist. : 
       Written DMZ (ARC) April 1991
	William Thompson, Dec 1991, modified to be compatible with UNIX, and
				    with VMS logical names.  Also, to be
				    compatible with changes in SCANPATH
 Written     : 
	D. Zarro, GSFC/SDAC, April 1991.
 Modified    : 
	Version 1, William Thompson, GSFC, 23 April 1993.
		Incorporated into CDS library.
	Version 2, William Thompson, GSFC, 7 May 1993.
		Added IDL for Windows compatibility.
	Version 3, William Thompson, GSFC, 24 September 1993.
		Changed EXPAND_PATH to PATH_EXPAND.
       Version 3.1, Dominic Zarro, GSFC, 1 August 1994.
               Added check for current directory in path.
 Version     : 
	Version 3.1, 1 August 1994.

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/cdsxtra/get_lib.pro:52)

get_mag_onera[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 DESCRIPTION:  
      General routine to calculate mag coords and values from models
      using the onera fortran library 
 
 INPUTS:       
      tai         time in TAI (int. atomic time) format    (can be array)
      pos         structure containing position            (can be array)
      kcompstr    component format: SPH (spherical), CAR (cartesian)
      kinstr      coordinate system of pos: GED, GEO, GEI, MAG, SM, GSM, GSE
      
 KEYWORDS:
      -----------------------------------------------------------------------
      EXTMOD      external field model index
                      0: none
                      1: Mead & Fairfield [1975]
                      2: Tsyganenko short [1987]
                      3: Tsyganenko long [1987]
                      4: Tsyganenko [1989c]
                      5: Olson & Pfitzer quiet [1977]             (default)
                      6: Olson & Pfitzer dynamic [1988]
                      7: Tsyganenko [1996]
                      8: Ostapenko & Maltsev [1997]
                      9: Tsyganenko [2001]
                     10: Tsyganenko [2001] storm
                     11: Tsyganenko [2004] storm
                     12: Alexeev [2000]
      -----------------------------------------------------------------------
      INTMOD      internal field model index
                      0: DGRF/IGRF 1945-2000                      (default)
      -----------------------------------------------------------------------
      PITCH       pitch angle for which L is calculated (default 90 deg)
      KP          kp index value, (default=2)
      INT_NAME    returns the name of the internal model
      EXT_NAME    returns the name of the external model
      HAVE_MDATE  time is already in format mdate required by onera
      LSTAR       Calculate Roederer L-value, default McIlwain only
      -----------------------------------------------------------------------
      Inputs for dynamic magnetic field models
      -----------------------------------------------------------------------
      MAG_DYN      0: use static default values, 1:use OMNI values
      -----------------------------------------------------------------------
      Any of the following overwrite default or OMNI values
      -----------------------------------------------------------------------
      KP          single value or array of KP, OMNI format (*10)
      DST         single value or array of DST values
      PRES        single value or array of solar wind pressure (nP)
      DENS        single value or array of solar wind density  (cm-3)
      VELO        single value or array of solar wind velocity (lm/s)
      IMBX        single value or array of interp. mag field x (nT)
      IMBY        single value or array of interp. mag field y (nT)
      IMBZ        single value or array of interp. mag field z (nT)
      G1          single value or array,used for T01 model
      G2          single value or array,used for T01 model
      G3          single value or array,used for T01 model
      -----------------------------------------------------------------------
      DO_IK       1, calcualte I, K; default=0, no calculation. K=I*sqrt(Bm)
                  I: Re K: G^1/2Re
      IKVALUES    values of I(0),K(1) hold in array (nt, pa,0/1)
      -----------------------------------------------------------------------
      TRACEMP     1, trace mirror points; default=0, no tracing
      MPPOS       values of mirror points pos. (nt,pa,0/1/2) in Re(GEO)
 
 OUTPUTS
      -----------------------------------------------------------------------
      bvec        magnetic field vector in coordinate system 'GSM'' - nT
      bequ        mag field at equator on field line - nT
      Lm          L-value McIlwain
      Lstar       L-value Roeder
      MLT         Magnetic local time - hour
      mlat        Magnetic latitude - deg
      equ_fl      GEO xyz of equatorial crossing of field line
      -----------------------------------------------------------------------
      error       error status
                    1: ONERA library not fond / not available for OS
                    2: OMNI data files not found
                    3: only nodata in one or more of omni variables needed
      -----------------------------------------------------------------------

 CALLING SEQUENCE:
      stand-alone

 MODIFICATION HISTORY:       
      June 2004, written by R.Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/onera/get_mag_onera.pro:85)

get_mag_onera[2]

 [Previous Routine] [Next Routine] [List of Routines] 
 Ggroup is array of input parameters for models of [T01,T01S, and on]
 Ggroup=[n_elem(tai),10] and Ggroup(t0,*)=[G1, G2, G3, G4,...,G10]

 G1 is an input paramter used by Tsyganenko [2001] 
 G1= 
    where the <> mean an average over the previous 1 hour, Vsw is the
    solar wind speed, Bperp is the transverse IMF component (GSM) and
    theta it's clock angle.  

 G2 is an input paramter used by Tsyganenko [2001] & Tsyganenko [2001] storm
 G2=a 
    where the <> mean an average over the previous 1 hour, sw is the
    solar wind speed, Bs=|IMF Bz| when IMF Bz < 0 and Bs=0 when IMF
    Bz > 0, a=0.005. 

 G3 is an input paramter used by Tsyganenko [2001] storm
 G3=< Vsw*Dsw*Bs /2000.> 
    where the <> mean an average over the  previous 1 hour, Vsw is
    the solar wind speed, Dsw is the solar wind  density, Bs=|IMF Bz|
    when IMF Bz < 0 and Bs=0 when IMF Bz > 0.  
*
* INPUTS:       
*      tai         time in TAI (int. atomic time) format    (can be array)
*      
* KEYWORDS:
*      -----------------------------------------------------------------------
*      WF_G1       weight function for g1
*      WF_G2       weight function for g2
*      WF_G3       weight function for g3
* 
* OUTPUT: 
*      Ggroup      array (n_elem(tai), 10) of G's,

(See /home/jbf/ct/papco/working/papco/papco_lib/onera/get_mag_onera.pro:120)

get_new_button[3]

 [Previous Routine] [Next Routine] [List of Routines] 

UNCTION:     
     FUNCTION get_new_button, BATCH_BUTTON=BATCH_BUTTON

ESCRIPTION:  
    Returns the bitmap for a new button

NPUTS:       
one

EYWORDS:
ATCH_BUTTON       :  BATCH_BUTTON bitmap array is returned           
    BMPUP              :  BMPUP bitmap array is returned
    BMPDOWN            :  BMPDOWN bitmap array is returned
    BMP_SHRINK         :  BMP_SHRINK bitmap array is returned
    BMP_ENLARGE        :  BMP_ENLARGE bitmap array is returned
    BMP_OTHERS_ENLARGE :  BMP_OTHERS_ENLARGE bitmap array is returned
    BMP_OTHERS_SHRINK  :  BMP_OTHERS_SHRINK bitmap array is returned

UTPUT:	 
    -1	   :   if no keyword is set
    byte array :   bitmap of button

ALLING EXAMPLE:
    user_button=get_new_button(\BATCH_BUTTON)

ODIFICATION HISTORY:       
   may 1996, written by R. Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/get_new_button.pro:53)

get_plotStyle_value

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: get_plotStyle_value, plotinfo

 DESCRIPTION:
	Called by function papco_panel_add_PlotStyleButtons. This function
	sets the correct value for the plot style slider widget. it is
	neccessary because the all user defined symbols use the plot
	style psym=8

 INPUTS:

      plotinfo  a PLOTINFO - structure
		   the info-structure-instance edited in this widget

 KEYWORDS:
 	none

 OUTPUT:

      returns the slider value in plotinfo.plotStyle


 CALLING SEQUENCE:
     value=get_plotStyle_value(plotinfo)

 MODIFICATION HISTORY:
     written march 1996, Haje Korth

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:214)

get_user_symbol

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE: get_user_symbol, userstyle, userx, usery

 DESCRIPTION:
	The procedure contains the user defined plot symbols. For adding
      new plot symbols see file papco_EXTENDING.TEXT

 INPUTS:

      userstyle - number of user defined symbol

 KEYWORDS:
 	none

 OUTPUT:

      returns the vectors userx, usery of the user defined symbol


 CALLING SEQUENCE:
     get_user_symbol, userstyle, userx, usery

 MODIFICATION HISTORY:
     written march 1996, Haje Korth
     jbf: did away with 2, the very thin triangle, and replaced with upsidedown triangle
     jbf: all symbols bigger

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:258)

get_utc

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     :	SOHO - CDS

 Name        :	GET_UTC

 Purpose     :	Gets the current date/time in UTC.

 Explanation :	This procedure uses the IDL SYSTIME() function to calculate
		the current UTC date/time, and formats it into one of the CDS
		standard UTC time formats.  For notes on various time formats,
		see file aaareadme.txt.

 Use         :	GET_UTC, UTC
		GET_UTC, UTC, /EXTERNAL
		GET_UTC, UTC, /CCSDS
		GET_UTC, UTC, /ECS

 Inputs      :	None.

 Opt. Inputs :	None.

 Outputs     :	UTC  = The UTC current calendar time in one of several formats,
		       depending on the keywords passed.

			Internal:  A structure containing the tags:

				MJD:	The Modified Julian Day number.
				TIME:	The time of day, in milliseconds since
					the beginning of the day.

				   Both are long integers.  This is the default
				   format.

			External:  A structure containing the integer tags
				   YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, and
				   MILLISECOND.

			CCSDS:	   An ASCII string containing the UTC time to
				   millisecond accuracy in the format
				   recommended by the Consultative Committee
				   for Space Data Systems (ISO 8601), e.g.

					"1988-01-18T17:20:43.123Z"

			ECS:	   Similar to CCSDS, except that the date has
				   the format:

					"1988/01/18 17:20:43.123"

			VMS:	   The date and time has the format

					"18-JAN-1988 17:20:43.123"

			STIME:	   The date and time has the format

					"18-JAN-1988 17:20:43.12"

				   See UTC2STR for more information

 Opt. Outputs:	None.

 Keywords    :	EXTERNAL = If set, then the output is in external format, as
			   explained above.

		CCSDS	 = If set, then the output is in CCSDS format, as
			   explained above.

		ECS	 = If set, then the output is in ECS format, as
			   explained above.

		VMS	  = If set, then the output will be in VMS format, as
			    described above.

		STIME	  = If set, then the output will be in STIME format, as
			    described above.

		The following keywords are only valid if one of the string
		formats is selected.

		TRUNCATE  = If set, then the time will be truncated to 1 second
			    accuracy.  Note that this is not the same thing as
			    rounding off to the nearest second, but is a
			    rounding down.

		DATE_ONLY = If set, then only the date part of the string is
			    returned.

		TIME_ONLY = If set, then only the time part of the string is
			    returned.

		UPPERCASE = If set, then the month field in either the VMS or
			    STIME format is returned as uppercase.

		The following keyword is always valid.

		ERRMSG   = If defined and passed, then any error messages will
			   be returned to the user in this parameter rather
			   than using the IDL MESSAGE utility.  If no errors
			   are encountered, then a null string is returned.
			   In order to use this feature, the string ERRMSG
			   must be defined first, e.g., 

				ERRMSG = ''
				GET_UTC, UTC, ERRMSG=ERRMSG
				IF ERRMSG NE '' THEN ...


 Calls       :	INT2UTC

 Common      :	None.

 Restrictions:	This routine depends on the behavior of IDL's SYSTIME function.
		Currently, it is believed that this routine will return the
		time in UTC on all properly configured Unix systems.  However,
		the result may be different in other operating systems; e.g. on
		VMS and MacIntosh computers it gives the local time instead.
		It is believed to work correctly in IDL for Windows.

		In order to get around this difficulty, the file
		"local_diff.dat" can be placed in the directory given by the
		environment variable TIME_CONV.  If this file exists, then this
		program will read the value (local-UTC in hours) from this file
		and use it as a correction factor.  For example, for U.S.
		Eastern Standard Time, this file would contain the value -5.
		(See local_diff.pro for more information.)  This means then,
		that this file must contain the correct value, and must be
		updated to reflect changes between standard and daylight
		savings time.

		On the other hand, if the second line in the "local_diff.dat"
		file reads "GMT", then it is assumed that the computer is
		running on GMT instead of local time, and no correction is
		made.

		The accuracy of the time returned by this routine depends on
		that of the computer's system clock.

 Side effects:	None.

 Category    :	Utilities, time.

 Prev. Hist. :	None.  However, the concept of "internal" and "external" time
		is based in part on the Yohkoh software by M. Morrison and G.
		Linford, LPARL.

 Written     :	William Thompson, GSFC, 21 September 1993.

 Modified    :	Version 1, William Thompson, GSFC, 21 September 1993.
		Version 2, William Thompson, GSFC, 3 November 1994
			Added test for "local_diff.dat" file.
		Version 3, William Thompson, GSFC, 14 November 1994
			Added test for "GMT" line in "local_diff.dat" file
			Changed .DAY to .MJD
		Version 4, William Thompson, GSFC, 17 November 1994
			Fixed bug introduced in version 3
		Version 5, William Thompson, GSFC, 20 December 1994
			Added keywords TRUNCATE, DATE_ONLY, TIME_ONLY
		Version 6, Donald G. Luttermoser, GSFC/ARC, 20 December 1994
			Added the keyword ERRMSG.
		Version 7, William Thompson, GSFC, 25 January 1995
			Changed to call intrinsic ROUND instead of NINT.  The
			version of NINT in the Astronomy User's Library doesn't
			automatically select between short and long integers as
			the CDS version does.
		Version 8, Donald G. Luttermoser, GSFC/ARC, 30 January 1995
			Added ERRMSG keyword to internally called procedures.
			Made the error handling procedures more robust.
		Version 9, William Thompson, GSFC, 14 March 1995
			Added keywords VMS, STIME, UPPERCASE
		Version 10, William Thompson, GSFC, 15 March 1995
			Changed CDS_TIME to TIME_CONV

 Version     :	Version 10, 15 March 1995

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/get_utc.pro:177)

int2utc

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     :	SOHO - CDS

 Name        :	INT2UTC()

 Purpose     :	Converts CDS internal time to calendar format.

 Explanation :	This procedure takes the UTC calendar time in "internal" format
		(Modified Julian Day number, and time of day in milliseconds),
		and converts it to a calendar format, either as a structure or
		as a string.  For notes on other time formats, see file
		aaareadme.txt.

 Use         :	Result = INT2UTC( INT )
		Result = INT2UTC( INT, /CCSDS )
		Result = INT2UTC( INT, /ECS )

 Inputs      :	INT	= The UTC date/time as a data structure with the
			  elements:

				MJD	= The Modified Julian Day number
				TIME	= The time of day, in milliseconds
					  since the start of the day.

			  Both are long integers.

 Opt. Inputs :	None.

 Outputs     :	The result of the function will be a structure containing the
		tag elements YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, and
		MILLISECOND.

		Alternatively, if the CCSDS switch is set, then the result will
		be the calendar date in the format recommended by the
		Consultative Committee for Space Data Systems (ISO 8601), e.g.

			"1988-01-18T17:20:43.123Z"

		Or if the ECS switch is set, then the result will be a calendar
		date in the format used by the EOF Core System, e.g.

			"1988/01/18 17:20:43.123"

		Note that this isn't exactly the ECS string format, because the
		ECS does not use fractional seconds.  However, if /ECS is
		combined with /TRUNCATE, then the following output will result

			"1988/01/18 17:20:43"

		which matches what the ECS expects to see.

		Using the keyword /VMS writes out the time in a format similar
		to that used by the VMS operating system, e.g.

			"18-Jan-1988 17:20:43.123"

		A variation of this is obtained with the /STIME keyword, which
		emulates the value of !STIME in IDL.  It is the same as using
		/VMS except that the time is only output to 0.01 second
		accuracy, e.g.

			"18-Jan-1988 17:20:43.12"

		The keywords /DATE_ONLY and TIME_ONLY can be used to extract
		either the date or time part of the string.

 Opt. Outputs:	None.

 Keywords    :	CCSDS	  = If set, then the output is in CCSDS format, as
			    explained above.

		ECS	  = If set, then the output is in ECS format, as
			    explained above.

		VMS	  = If set, then the output will be in VMS format, as
			    described above.

		STIME	  = If set, then the output will be in STIME format, as
			    described above.

		Only one of the above keywords can be set.  If none of them are
		set, the the time is output in external format.  The following
		keywords are only valid if one of the above keywords is set.

		TRUNCATE  = If set, then the time will be truncated to 1 second
			    accuracy.  Note that this is not the same thing as
			    rounding off to the nearest second, but is a
			    rounding down.

		DATE_ONLY = If set, then only the date part of the string is
			    returned.

		TIME_ONLY = If set, then only the time part of the string is
			    returned.

		UPPERCASE = If set, then the month field in either the VMS or
			    STIME format is returned as uppercase.

		The following keyword is always valid.

		ERRMSG	  = If defined and passed, then any error messages 
			    will be returned to the user in this parameter 
			    rather than being handled by the IDL MESSAGE 
			    utility.  If no errors are encountered, then a null
			    string is returned.  In order to use this feature,
			    the string ERRMSG must be defined first, e.g.,

				ERRMSG = ''
				MJD = INT2UTC ( INT, ERRMSG=ERRMSG )
				IF ERRMSG NE '' THEN ...

 Calls       :	DATATYPE, UTC2STR, MJD2DATE

 Common      :	None.

 Restrictions:	None.

 Side effects:	The result of an array with a single element may be a scalar.
		If an error occurs and the ERRMSG keyword has been set, the
		result returned from INT2UTC is an integer scalar of value -1.

 Category    :	Utilities, Time.

 Prev. Hist. :	None.  However, the concept of "internal" and "external" time
		is based in part on the Yohkoh software by M. Morrison and G.
		Linford, LPARL.

 Written     :	William Thompson, GSFC, 20 September 1993.

 Modified    :	Version 1, William Thompson, GSFC, 21 September 1993.
		Version 2, William Thompson, GSFC, 14 November 1994
			Changed .DAY to .MJD
		Version 3, William Thompson, GSFC, 20 December 1994
			Added keywords TRUNCATE, DATE_ONLY, TIME_ONLY
		Version 4, Donald G. Luttermoser, GSFC/ARC, 28 December 1994
			Added the keyword ERRMSG.  Added check to the structure
			tag names in INT.
		Version 5, William Thompson, GSFC, 25 January 1995
			Changed to call intrinsic ROUND instead of NINT.  The
			version of NINT in the Astronomy User's Library doesn't
			automatically select between short and long integers as
			the CDS version does.
		Version 6, Donald G. Luttermoser, GSFC/ARC, 30 January 1995
			Added ERRMSG keyword to internally called procedures.
			Made the error handling procedure more robust.  Note
			that this routine accepts both scalar and vector 
			input.
		Version 7, William Thompson, GSFC, 14 March 1995
			Added keywords VMS, STIME, UPPERCASE

 Version     :	Version 7, 14 March 1995

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/int2utc.pro:155)

isAllCaps

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: isAllCaps
 DESCRIPTION: scan string to see if it is already all upper case.
 INPUTS:   
   STR, string, the string to scan.
 KEYWORDS:
 RETURNS: 
   boolean, 0 if the string contains lowercase letters, 0 otherwise.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
   print, isAllCaps( 'PAPCO_UTIL_FUNC_1' )   ; prints "1"
   print, isAllCaps( 'papco_utilFunc1' )     ; prints "0"
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.15 $
 CURATOR: Jeremy Faden
 HISTORY:  
   20 April 2007, 1.13, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/string_functions.pro:246)

isDigits

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: isDigits

 FUNCTION:
      FUNCTION isDigits, string

 DESCRIPTION:
      check if a string contains digits only - blanks in 'string' are ignored !

 INPUTS:
      STRING, string, the string to check for all digits and spaces

 OUTPUT:
      boolean, 1 if 'string' contains digits (that is, '0','1',...,'9') only, 0 otherwise

 CALLING SEQUENCE:
      if not isDigits('123') then print, 'error in isDigits()'
      if not isDigits('1 2 3') then print, 'error in isDigits()'
      if not isDigits('123   ') then print, 'error in isDigits()'

      if isDigits('123x') then print, 'error in isDigits()'
      if isDigits('x ') then print, 'error in isDigits()'

 MODIFICATION HISTORY:
      september 1995, written by A.Keese

(See /home/jbf/ct/papco/working/papco/papco_lib/string_functions.pro:215)

left_side_label

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: LEFT_SIDE_LABEL
 DESCRIPTION:  same as right_side_label but used for labeling the left hand y-axis.  Check 
     for "overplots" - don't label if overplot
 INPUTS:   
     PANEL, intarr[3], vector for position of panel
     LABEL, string, string to be used as label
  KEYWORDS:    
     ROT90, keyw, rotates output string by 90 degrees, used for plots with papco_colorbar
     POS, int, indicates position. 
               0 (default) aligned with top of panel 
               1  aligned with bottom of panel
     AUTO, keyw, attempts to scale string into space.
     _EXTRA, extra keywords to be passed to xyouts procedure
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.22 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_panel_label.pro:935)

limit_download

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO limit_download

 DESCRIPTION:
      Checks if maximum number of allowed downloads specified in
      the total_allowed variabled is exceeded.

 INPUTS:
      none
 OUTPUTS:
      allowed     set if download is possible.

 KEYWORDS:
  none

 MODIFICATION HISTORY:
     written July 1997, Haje Korth

(See /home/jbf/ct/papco/working/papco/papco/papco_get_remote_data.pro:429)

local_diff

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     :	SOHO - CDS

 Name        :	LOCAL_DIFF()

 Purpose     :	Gets the current difference between local and UTC time.

 Explanation :	This procedure uses the IDL SYSTIME() function in different
		ways to calculate the current local and UTC date/time values,
		and calculates the difference (local - UTC) in hours between
		them.

 Use         :	Result = LOCAL_DIFF()

 Inputs      :	None.

 Opt. Inputs :	None.

 Outputs     :	The result of the function is the current difference in hours
		between local and UTC time, i.e. local-UTC.

 Opt. Outputs:	None.

 Keywords    :	ERRMSG	= If defined and passed, then any error messages 
			  will be returned to the user in this parameter 
			  rather than being handled by the IDL MESSAGE 
			  utility.  If no errors are encountered, then a null
			  string is returned.  In order to use this feature,
			  the string ERRMSG must be defined first, e.g.,

				ERRMSG = ''
				RESULT = LOCAL_DIFF ( ERRMSG=ERRMSG )
				IF ERRMSG NE '' THEN ...

			  Note that no intrinsic errors will ever be
			  encountered in this procedure.  However, this 
			  ERRMSG keyword has been installed since it calls
			  other procedures that include the ERRMSG keyword.

 Calls       :	INT2UTC, TRIM

 Common      :	None.

 Restrictions:	This routine depends on the behavior of IDL's SYSTIME function.
		Currently, it is believed that this routine will return the
		time difference correctly on all properly configured Unix
		systems.  However, the result may be different in other
		operating systems; e.g. on VMS and MacIntosh computers it
		always returns zero.  It is believed to work correctly in IDL
		for Windows.

		In order to get around this difficulty, the file
		"local_diff.dat" can be placed in the directory given by the
		environment variable TIME_CONV.  If this file exists, then this
		program will read the value from this file rather than try to
		calculate.  For example, for U.S. Eastern Standard Time, this
		file would contain the value -5.  This means then, that this
		file must contain the correct value, and must be updated to
		reflect changes between standard and daylight savings time.

		The accuracy of the time difference returned by this routine
		depends on the proper configuration of the computer.

 Side effects:	None.

 Category    :	Utilities, time.

 Prev. Hist. :	None.

 Written     :	William Thompson, GSFC, 2 October 1994

 Modified    :	Version 1, William Thompson, GSFC, 2 October 1994
		Version 2, William Thompson, GSFC, 3 October 1994
			Added check for file local_diff.dat
		Version 3, William Thompson, GSFC, 14 November 1994
			Changed .DAY to .MJD
		Version 4, Donald G. Luttermoser, GSFC/ARC, 28 December 1994
			Added the keyword ERRMSG.
		Version 5, William Thompson, GSFC, 25 January 1995
			Changed to call intrinsic ROUND instead of NINT.  The
			version of NINT in the Astronomy User's Library doesn't
			automatically select between short and long integers as
			the CDS version does.
		Version 6, Donald G. Luttermoser, GSFC/ARC, 30 January 1995
			Added ERRMSG keyword to internally called procedures.
		Version 7, William Thompson, GSFC, 15 March 1995
			Changed CDS_TIME to TIME_CONV

 Version     :	Version 7, 15 March 1995

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/local_diff.pro:91)

logaxis

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: LOGAXIS

 PURPOSE:
 This procedure draws nicer labels for logarithmic 
 (and linear) axes for the types given in the IDL-1 AXIS-procedure. 
 The boundaries are taken from the !CRANGE-values.
 Thus the procedure has to be called AFTER
 the PLOT-call. Labels at the top of the axes are only
 plotted if the actual window-boundaries are >= the window-boundaries
 defined by the MPOSITION-common variables.
	
 CATEGORY: Plotting

 CALLING SEQUENCE: LOGAXIS,type [,size,labnum,ticklen=tl,decbit=decbit]

 INPUTS:           type: 0: y left lin
                         1: y left log
                         2: y right lin
                         3: y right log
                         4: x bottom lin
                         5: x bottom log
                         6: x top lin
                         7: x top log

 OPTIONAL INPUTS:
                   size: character size (default:0.9)
                   labnum: plot only every labnum-th label (def:1)

 KEYWORD PARAMETERS:
       decbit:         (0/1)  for decimal point representation
       ticklen:	ticklength for 'major' ticks, as a fraction
			of the plot window size.
			Default: -0.04
	
 COMMON BLOCKS:
 The MAIN-viewport boundaries must be defined by:                
  COMMON MAINVIEW,lposition,mposition

 RESTRICTIONS:
 The procedure has to be called AFTER the PLOT-call.
 Labels at the top of the axes are only
 plotted if the actual window-boundaries are >= the window-boundaries
 defined by the MPOSITION-common variables.

 PROCEDURE:

 MODIFICATION HISTORY:
 	Written by:M.Fraenz 92 IDL1
       12-jun-93: IDL3-version setting decimal numbers if the
                  range is between 0.001 and 100.0, using
                  TICKNAME and TICKV sysvars.

(See /home/jbf/ct/papco/working/papco/papco_lib/axis_label/logaxis.pro:54)

messagebox[3]

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:     
      messageBox_event
 
 DESCRIPTION:  
      this is the event-handler. It is called by XMANAGER only
 
 INPUTS:       
      event 	: the event to be handled
 
 OUTPUT:	 
      none

 CALLING SEQUENCE:
      this procedure is to be called by XMANAGER only

(See /home/jbf/ct/papco/working/papco/papco_lib/messagebox.pro:45)

messagebox[4]

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     
       FUNCTION messageBox, strArray, buttons, CENTER=center
 
 DESCRIPTION:  
      A window containing a text and buttons is displayed modally.
      The index of the pressed button is returned

 INPUTS:       
	strArray:   An array containing the text to be displayed
	buttons :   a string-array containing the buttonlabels

 KEYWORDS:
      SCROL   :   if set, contains lines and scoll
	CENTER  :   If set, the displayed text is horizontally centered 
      TITLE   :   The title of the message-box

 OUTPUT:	 
      -1	:   if no button was selected
      Integer :   if a button was selected, its index is returned 
		    the first button has index 0

 CALLING EXAMPLE:
      IF MessageBox(['Exit','Program'], ['Yes', 'No'],$
                      TITLE='Exit Message', /CENTER) EQ 0 $
         THEN EXIT

(See /home/jbf/ct/papco/working/papco/papco_lib/messagebox.pro:89)

mission_createOrbitInfo

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:   mission_createOrbitInfo 
 
 DESCRIPTION: for all MISSION-ephemeris-files in the directory MISSION_EPH, 
	        orbit-infos are created and written to the file  
              $MISSION_EPH/orbits.info 

 INPUTS:      none
 
 OUTPUT:	none

 CALLING SEQUENCE: mission_createOrbitInfo
 
 MODIFICATION HISTORY: December 1997, written by R. Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/mission_createorbitinfo.pro:15)

mjd2date

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     :	SOHO - CDS

 Name        :	MJD2DATE

 Purpose     :	Converts MJD to year, month, and day.

 Explanation :	This procedure takes a Modified Julian Day number, and returns
		the corresponding calendar date in year, month, day.

 Use         :	MJD2DATE, MJD, YEAR, MONTH, DAY

 Inputs      :	MJD	= Modified Julian Day number.

 Opt. Inputs :	None.

 Outputs     :	YEAR	= Calendar year corresponding to MJD.
		MONTH	= Calendar month, from 1-12.
		DAY	= Calendar day, from 1-31, depending on the month.

 Opt. Outputs:	None.

 Keywords    :	ERRMSG	= If defined and passed, then any error messages 
			  will be returned to the user in this parameter 
			  rather than being handled by the IDL MESSAGE 
			  utility.  If no errors are encountered, then a null 
			  string is returned.  In order to use this feature, 
			  the string ERRMSG must be defined first, e.g.,

				ERRMSG = ''
				MJD2DATE, MJD, YEAR, MONTH, DAY, ERRMSG=ERRMSG
				IF ERRMSG NE '' THEN ...

 Calls       :	None.

 Common      :	None.

 Restrictions:	None.

 Side effects:	None.

 Category    :	Utilities, Time.

 Prev. Hist. :	None.  However, part of the logic of this routine is taken from
		DAYCNV by B. Pfarr, GSFC.

 Written     :	William Thompson, GSFC, 13 September 1993.

 Modified    :	Version 1, William Thompson, GSFC, 13 September 1993.
		Version 2, Donald G. Luttermoser, GSFC/ARC, 28 December 1994.
			Added the keyword ERRMSG.  Note that there are no
			internally called procedures that use the ERRMSG 
			keyword.
		Version 3, Donald G. Luttermoser, GSFC/ARC, 30 January 1995.
			Made the error handling procedure more robust.  Note
			that this routine handles both scalars and vectors as
			input.

 Version     :	Version 3, 30 January 1995.

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/mjd2date.pro:61)

mk_html_help

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
	MK_HTML_HELP

 PURPOSE:
	Given a list of IDL procedure files (.PRO) or directories that
	contain such files, this procedure generates a file in the HTML
	format that contains the documentation for those routines that
	contain a DOC_LIBRARY style documentation template.  The output
	file is compatible with World Wide Web browsers.

 CATEGORY:
	Help, documentation.

 CALLING SEQUENCE:
	MK_HTML_HELP, Sources, Outfile

 INPUTS:
     Sources:  A string or string array containing the name(s) of the
		.pro files (or the names of directories containing such files)
		for which help is desired. If a source file is an IDL procedure,
		it must include the .PRO file extension. All other source files
		are assumed to be directories.

     Outfile:	The name of the output file which will be generated.

 KEYWORDS:
     TITLE:	If present, a string which supplies the name that
		should appear as the Document Title for the help.

     VERBOSE:	Normally, MK_HTML_HELP does its work silently.
		Setting this keyword to a non-zero value causes the procedure
		to issue informational messages that indicate what it
		is currently doing. !QUIET must be 0 for these messages
               to appear.

     STRICT: If this keyword is set to a non-zero value, MK_HTML_HELP
     will adhere strictly to the HTML format by scanning the document
     headers for characters that are reserved in HTML (<,>,&,").
     These are then converted to the appropriate HTML syntax in the
     output file. By default, this keyword is set to zero (to allow
     for faster processing).

 COMMON BLOCKS:
	None.

 SIDE EFFECTS:
	A help file with the name given by the Outfile argument is
	created.

 RESTRICTIONS:
	The following rules must be followed in formatting the .pro
	files that are to be searched.
		(a) The first line of the documentation block contains
		    only the characters ";+", starting in column 1.
     (b) There must be a line which contains the string "NAME:",
         which is immediately followed by a line containing the
         name of the procedure or function being described in
         that documentation block.  If this NAME field is not
         present, the name of the source file will be used.
		(c) The last line of the documentation block contains
		    only the characters ";-", starting in column 1.
		(d) Every other line in the documentation block contains
		    a ";" in column 1.

  Note that a single .pro file can contain multiple procedures and/or
  functions, each with their own documentation blocks. If it is desired
  to have "invisible" routines in a file, i.e. routines which are only
  for internal use and should not appear in the help file, simply leave
  out the ";+" and ";-" lines in the documentation block for those
  routines.

	No reformatting of the documentation is done.

 MODIFICATION HISTORY:
  July 5, 1995, DD, RSI. Original version.
  July 13, 1995, Mark Rivers, University of Chicago. Added support for
          multiple source directories and multiple documentation
          headers per .pro file.
  July 17, 1995, DD, RSI. Added code to alphabetize the subjects;
          At the end of each description block in the HTML file,
          added a reference to the source .pro file.
  July 18, 1995, DD, RSI. Added STRICT keyword to handle angle brackets.
  July 19, 1995, DD, RSI. Updated STRICT to handle & and ".
          Changed calling sequence to accept .pro filenames, .tlb
          text library names, and/or directory names.
          Added code to set default subject to name of file if NAME
          field is not present in the doc header.
  27 August 2003, AB, Remove VMS support. Fix bug with leaking
          file units.
  8 March 2005, DD, RSI. If none of the input .pro files contain
          documentation headers, display an informative error
          message, clean up, and exit. Also report the full path
          to the output file after creation.

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_make_html_help.pro:100)

mpcurvefit

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
   MPCURVEFIT

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov
   UPDATED VERSIONs can be found on my WEB PAGE: 
      http://cow.physics.wisc.edu/~craigm/idl/idl.html

 PURPOSE:
   Perform Levenberg-Marquardt least-squares fit (replaces CURVEFIT)

 MAJOR TOPICS:
   Curve and Surface Fitting

 CALLING SEQUENCE:
   YFIT = MPCURVEFIT(X, Y, WEIGHTS, P, [SIGMA,] FUNCTION_NAME=FUNC, 
                     ITER=iter, ITMAX=itmax, 
                     CHISQ=chisq, NFREE=nfree, DOF=dof, 
                     NFEV=nfev, COVAR=covar, [/NOCOVAR, ] [/NODERIVATIVE, ]
                     FUNCTARGS=functargs, PARINFO=parinfo,
                     FTOL=ftol, XTOL=xtol, GTOL=gtol, TOL=tol,
                     ITERPROC=iterproc, ITERARGS=iterargs,
                     NPRINT=nprint, QUIET=quiet, 
                     ERRMSG=errmsg, STATUS=status)

 DESCRIPTION:

  MPCURVEFIT fits a user-supplied model -- in the form of an IDL
  function -- to a set of user-supplied data.  MPCURVEFIT calls
  MPFIT, the MINPACK-1 least-squares minimizer, to do the main
  work.

  Given the data and their uncertainties, MPCURVEFIT finds the best
  set of model parameters which match the data (in a least-squares
  sense) and returns them in the parameter P.  

  MPCURVEFIT returns the best fit function.
  
  The user must supply the following items:
   - An array of independent variable values ("X").
   - An array of "measured" *dependent* variable values ("Y").
   - An array of weighting values ("WEIGHTS").
   - The name of an IDL function which computes Y given X ("FUNC").
   - Starting guesses for all of the parameters ("P").

  There are very few restrictions placed on X, Y or FUNCT.  Simply
  put, FUNCT must map the "X" values into "Y" values given the
  model parameters.  The "X" values may represent any independent
  variable (not just Cartesian X), and indeed may be multidimensional
  themselves.  For example, in the application of image fitting, X
  may be a 2xN array of image positions.

  MPCURVEFIT carefully avoids passing large arrays where possible to
  improve performance.

  See below for an example of usage.
   
 USER FUNCTION

  The user must define a function which returns the model value.  For
  applications which use finite-difference derivatives -- the default
  -- the user function should be declared in the following way:

    PRO MYFUNCT, X, P, YMOD
     ; The independent variable is X
     ; Parameter values are passed in "P"
     YMOD = ... computed model values at X ...
    END

  The returned array YMOD must have the same dimensions and type as
  the "measured" Y values.

  User functions may also indicate a fatal error condition
  using the ERROR_CODE common block variable, as described
  below under the MPFIT_ERROR common block definition.

  See the discussion under "ANALYTIC DERIVATIVES" and AUTODERIVATIVE
  in MPFIT.PRO if you wish to compute the derivatives for yourself.
  AUTODERIVATIVE is accepted and passed directly to MPFIT.  The user
  function must accept one additional parameter, DP, which contains
  the derivative of the user function with respect to each parameter
  at each data point, as described in MPFIT.PRO.

 CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD

  The behavior of MPFIT can be modified with respect to each
  parameter to be fitted.  A parameter value can be fixed; simple
  boundary constraints can be imposed; limitations on the parameter
  changes can be imposed; properties of the automatic derivative can
  be modified; and parameters can be tied to one another.

  These properties are governed by the PARINFO structure, which is
  passed as a keyword parameter to MPFIT.

  PARINFO should be an array of structures, one for each parameter.
  Each parameter is associated with one element of the array, in
  numerical order.  The structure can have the following entries
  (none are required):
  
     .VALUE - the starting parameter value (but see the START_PARAMS
              parameter for more information).
  
     .FIXED - a boolean value, whether the parameter is to be held
              fixed or not.  Fixed parameters are not varied by
              MPFIT, but are passed on to MYFUNCT for evaluation.
  
     .LIMITED - a two-element boolean array.  If the first/second
                element is set, then the parameter is bounded on the
                lower/upper side.  A parameter can be bounded on both
                sides.  Both LIMITED and LIMITS must be given
                together.
  
     .LIMITS - a two-element float or double array.  Gives the
               parameter limits on the lower and upper sides,
               respectively.  Zero, one or two of these values can be
               set, depending on the values of LIMITED.  Both LIMITED
               and LIMITS must be given together.
  
     .PARNAME - a string, giving the name of the parameter.  The
                fitting code of MPFIT does not use this tag in any
                way.  However, the default ITERPROC will print the
                parameter name if available.
  
     .STEP - the step size to be used in calculating the numerical
             derivatives.  If set to zero, then the step size is
             computed automatically.  Ignored when AUTODERIVATIVE=0.
             This value is superceded by the RELSTEP value.

     .RELSTEP - the *relative* step size to be used in calculating
                the numerical derivatives.  This number is the
                fractional size of the step, compared to the
                parameter value.  This value supercedes the STEP
                setting.  If the parameter is zero, then a default
                step size is chosen.

     .MPSIDE - the sidedness of the finite difference when computing
               numerical derivatives.  This field can take four
               values:

                  0 - one-sided derivative computed automatically
                  1 - one-sided derivative (f(x+h) - f(x)  )/h
                 -1 - one-sided derivative (f(x)   - f(x-h))/h
                  2 - two-sided derivative (f(x+h) - f(x-h))/(2*h)

              Where H is the STEP parameter described above.  The
              "automatic" one-sided derivative method will chose a
              direction for the finite difference which does not
              violate any constraints.  The other methods do not
              perform this check.  The two-sided method is in
              principle more precise, but requires twice as many
              function evaluations.  Default: 0.

     .MPMAXSTEP - the maximum change to be made in the parameter
                  value.  During the fitting process, the parameter
                  will never be changed by more than this value in
                  one iteration.

                  A value of 0 indicates no maximum.  Default: 0.
  
     .TIED - a string expression which "ties" the parameter to other
             free or fixed parameters.  Any expression involving
             constants and the parameter array P are permitted.
             Example: if parameter 2 is always to be twice parameter
             1 then use the following: parinfo(2).tied = '2 * P(1)'.
             Since they are totally constrained, tied parameters are
             considered to be fixed; no errors are computed for them.
             [ NOTE: the PARNAME can't be used in expressions. ]

     .MPPRINT - if set to 1, then the default ITERPROC will print the
                parameter value.  If set to 0, the parameter value
                will not be printed.  This tag can be used to
                selectively print only a few parameter values out of
                many.  Default: 1 (all parameters printed)

  
  Future modifications to the PARINFO structure, if any, will involve
  adding structure tags beginning with the two letters "MP".
  Therefore programmers are urged to avoid using tags starting with
  the same letters; otherwise they are free to include their own
  fields within the PARINFO structure, and they will be ignored.
  
  PARINFO Example:
  parinfo = replicate({value:0.D, fixed:0, limited:[0,0], $
                       limits:[0.D,0]}, 5)
  parinfo(0).fixed = 1
  parinfo(4).limited(0) = 1
  parinfo(4).limits(0)  = 50.D
  parinfo(*).value = [5.7D, 2.2, 500., 1.5, 2000.]
  
  A total of 5 parameters, with starting values of 5.7,
  2.2, 500, 1.5, and 2000 are given.  The first parameter
  is fixed at a value of 5.7, and the last parameter is
  constrained to be above 50.

 INPUTS:
   X - Array of independent variable values.

   Y - Array of "measured" dependent variable values.  Y should have
       the same data type as X.  The function FUNCT should map
       X->Y.

   WEIGHTS - Array of weights to be used in calculating the
             chi-squared value.  If WEIGHTS is specified then the ERR
             parameter is ignored.  The chi-squared value is computed
             as follows:

                CHISQ = TOTAL( (Y-FUNCT(X,P))^2 * ABS(WEIGHTS) )

             Here are common values of WEIGHTS:

                1D/ERR^2 - Normal weighting (ERR is the measurement error)
                1D/Y     - Poisson weighting (counting statistics)
                1D       - Unweighted

   P - An array of starting values for each of the parameters of the
       model.  The number of parameters should be fewer than the
       number of measurements.  Also, the parameters should have the
       same data type as the measurements (double is preferred).

       Upon successful completion the new parameter values are
       returned in P.

       If both START_PARAMS and PARINFO are passed, then the starting
       *value* is taken from START_PARAMS, but the *constraints* are
       taken from PARINFO.
 
   SIGMA - The formal 1-sigma errors in each parameter, computed from
           the covariance matrix.  If a parameter is held fixed, or
           if it touches a boundary, then the error is reported as
           zero.

           If the fit is unweighted (i.e. no errors were given, or
           the weights were uniformly set to unity), then SIGMA will
           probably not represent the true parameter uncertainties.

           *If* you can assume that the true reduced chi-squared
           value is unity -- meaning that the fit is implicitly
           assumed to be of good quality -- then the estimated
           parameter uncertainties can be computed by scaling SIGMA
           by the measured chi-squared value.

              DOF     = N_ELEMENTS(X) - N_ELEMENTS(P) ; deg of freedom
              CSIGMA  = SIGMA * SQRT(CHISQ / DOF)     ; scaled uncertainties

 RETURNS:

   Returns the array containing the best-fitting function.

 KEYWORD PARAMETERS:

   CHISQ - the value of the summed, squared, weighted residuals for
           the returned parameter values, i.e. the chi-square value.

   COVAR - the covariance matrix for the set of parameters returned
           by MPFIT.  The matrix is NxN where N is the number of
           parameters.  The square root of the diagonal elements
           gives the formal 1-sigma statistical errors on the
           parameters IF errors were treated "properly" in MYFUNC.
           Parameter errors are also returned in PERROR.

           To compute the correlation matrix, PCOR, use this:
           IDL> PCOR = COV * 0
           IDL> FOR i = 0, n-1 DO FOR j = 0, n-1 DO $
                PCOR(i,j) = COV(i,j)/sqrt(COV(i,i)*COV(j,j))

           If NOCOVAR is set or MPFIT terminated abnormally, then
           COVAR is set to a scalar with value !VALUES.D_NAN.

   DOF - number of degrees of freedom, computed as
             DOF = N_ELEMENTS(DEVIATES) - NFREE
         Note that this doesn't account for pegged parameters (see
         NPEGGED).

   ERRMSG - a string error or warning message is returned.

   FTOL - a nonnegative input variable. Termination occurs when both
          the actual and predicted relative reductions in the sum of
          squares are at most FTOL (and STATUS is accordingly set to
          1 or 3).  Therefore, FTOL measures the relative error
          desired in the sum of squares.  Default: 1D-10

   FUNCTION_NAME - a scalar string containing the name of an IDL
                   procedure to compute the user model values, as
                   described above in the "USER MODEL" section.

   FUNCTARGS - A structure which contains the parameters to be passed
               to the user-supplied function specified by FUNCT via
               the _EXTRA mechanism.  This is the way you can pass
               additional data to your user-supplied function without
               using common blocks.

               By default, no extra parameters are passed to the
               user-supplied function.

   GTOL - a nonnegative input variable. Termination occurs when the
          cosine of the angle between fvec and any column of the
          jacobian is at most GTOL in absolute value (and STATUS is
          accordingly set to 4). Therefore, GTOL measures the
          orthogonality desired between the function vector and the
          columns of the jacobian.  Default: 1D-10

   ITER - the number of iterations completed.

   ITERARGS - The keyword arguments to be passed to ITERPROC via the
              _EXTRA mechanism.  This should be a structure, and is
              similar in operation to FUNCTARGS.
              Default: no arguments are passed.

   ITERPROC - The name of a procedure to be called upon each NPRINT
              iteration of the MPFIT routine.  It should be declared
              in the following way:

              PRO ITERPROC, FUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
                PARINFO=parinfo, QUIET=quiet, ...
                ; perform custom iteration update
              END
         
              ITERPROC must either accept all three keyword
              parameters (FUNCTARGS, PARINFO and QUIET), or at least
              accept them via the _EXTRA keyword.
          
              FUNCT is the user-supplied function to be minimized,
              P is the current set of model parameters, ITER is the
              iteration number, and FUNCTARGS are the arguments to be
              passed to FUNCT.  FNORM should be the
              chi-squared value.  QUIET is set when no textual output
              should be printed.  See below for documentation of
              PARINFO.

              In implementation, ITERPROC can perform updates to the
              terminal or graphical user interface, to provide
              feedback while the fit proceeds.  If the fit is to be
              stopped for any reason, then ITERPROC should set the
              common block variable ERROR_CODE to negative value (see
              MPFIT_ERROR common block below).  In principle,
              ITERPROC should probably not modify the parameter
              values, because it may interfere with the algorithm's
              stability.  In practice it is allowed.

              Default: an internal routine is used to print the
                       parameter values.

   ITMAX - The maximum number of iterations to perform.  If the
             number is exceeded, then the STATUS value is set to 5
             and MPFIT returns.
             Default: 200 iterations

   NFEV - the number of FUNCT function evaluations performed.

   NFREE - the number of free parameters in the fit.  This includes
           parameters which are not FIXED and not TIED, but it does
           include parameters which are pegged at LIMITS.

   NOCOVAR - set this keyword to prevent the calculation of the
             covariance matrix before returning (see COVAR)

   NODERIVATIVE - if set, then the user function will not be queried
                  for analytical derivatives, and instead the
                  derivatives will be computed by finite differences
                  (and according to the PARINFO derivative settings;
                  see above for a description).

   NPRINT - The frequency with which ITERPROC is called.  A value of
            1 indicates that ITERPROC is called with every iteration,
            while 2 indicates every other iteration, etc.  Note that
            several Levenberg-Marquardt attempts can be made in a
            single iteration.
            Default value: 1

   PARINFO - Provides a mechanism for more sophisticated constraints
             to be placed on parameter values.  When PARINFO is not
             passed, then it is assumed that all parameters are free
             and unconstrained.  Values in PARINFO are never 
             modified during a call to MPFIT.

             See description above for the structure of PARINFO.

             Default value:  all parameters are free and unconstrained.

   QUIET - set this keyword when no textual output should be printed
           by MPFIT

   STATUS - an integer status code is returned.  All values other
            than zero can represent success.  It can have one of the
            following values:

	   0  improper input parameters.
         
	   1  both actual and predicted relative reductions
	      in the sum of squares are at most FTOL.
         
	   2  relative error between two consecutive iterates
	      is at most XTOL
         
	   3  conditions for STATUS = 1 and STATUS = 2 both hold.
         
	   4  the cosine of the angle between fvec and any
	      column of the jacobian is at most GTOL in
	      absolute value.
         
	   5  the maximum number of iterations has been reached
         
	   6  FTOL is too small. no further reduction in
	      the sum of squares is possible.
         
	   7  XTOL is too small. no further improvement in
	      the approximate solution x is possible.
         
	   8  GTOL is too small. fvec is orthogonal to the
	      columns of the jacobian to machine precision.

   TOL - synonym for FTOL.  Use FTOL instead.

   XTOL - a nonnegative input variable. Termination occurs when the
          relative error between two consecutive iterates is at most
          XTOL (and STATUS is accordingly set to 2 or 3).  Therefore,
          XTOL measures the relative error desired in the approximate
          solution.  Default: 1D-10

   YERROR - upon return, the root-mean-square variance of the
            residuals.


 EXAMPLE:

   ; First, generate some synthetic data
   npts = 200
   x  = dindgen(npts) * 0.1 - 10.                  ; Independent variable 
   yi = gauss1(x, [2.2D, 1.4, 3000.])              ; "Ideal" Y variable
   y  = yi + randomn(seed, npts) * sqrt(1000. + yi); Measured, w/ noise
   sy = sqrt(1000.D + y)                           ; Poisson errors

   ; Now fit a Gaussian to see how well we can recover
   p0 = [1.D, 1., 1000.]                           ; Initial guess
   yfit = mpcurvefit(x, y, 1/sy^2, p0, $
                   FUNCTION_NAME='GAUSS1P')        ; Fit a function
   print, p

   Generates a synthetic data set with a Gaussian peak, and Poisson
   statistical uncertainty.  Then the same function is fitted to the
   data to see how close we can get.  GAUSS1 and GAUSS1P are
   available from the same web page.


 COMMON BLOCKS:

   COMMON MPFIT_ERROR, ERROR_CODE

     User routines may stop the fitting process at any time by
     setting an error condition.  This condition may be set in either
     the user's model computation routine (MYFUNCT), or in the
     iteration procedure (ITERPROC).

     To stop the fitting, the above common block must be declared,
     and ERROR_CODE must be set to a negative number.  After the user
     procedure or function returns, MPFIT checks the value of this
     common block variable and exits immediately if the error
     condition has been set.  By default the value of ERROR_CODE is
     zero, indicating a successful function/procedure call.

 REFERENCES:

   MINPACK-1, Jorge More', available from netlib (www.netlib.org).
   "Optimization Software Guide," Jorge More' and Stephen Wright, 
     SIAM, *Frontiers in Applied Mathematics*, Number 14.

 MODIFICATION HISTORY:
   Translated from MPFITFUN, 25 Sep 1999, CM
   Alphabetized documented keywords, 02 Oct 1999, CM
   Added QUERY keyword and query checking of MPFIT, 29 Oct 1999, CM
   Check to be sure that X and Y are present, 02 Nov 1999, CM
   Documented SIGMA for unweighted fits, 03 Nov 1999, CM
   Changed to ERROR_CODE for error condition, 28 Jan 2000, CM
   Copying permission terms have been liberalized, 26 Mar 2000, CM
   Propagated improvements from MPFIT, 17 Dec 2000, CM
   Corrected behavior of NODERIVATIVE, 13 May 2002, CM
   Documented RELSTEP field of PARINFO (!!), CM, 25 Oct 2002
   Make more consistent with comparable IDL routines, 30 Jun 2003, CM
   Minor documentation adjustment, 03 Feb 2004, CM

  $Id: mpcurvefit.pro,v 1.1 2005/09/07 18:46:44 aasnes Exp $

(See /home/jbf/ct/papco/working/papco/papco_lib/fit/mpcurvefit.pro:484)

mpfit

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
   MPFIT

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov
   UPDATED VERSIONs can be found on my WEB PAGE: 
      http://cow.physics.wisc.edu/~craigm/idl/idl.html

 PURPOSE:
   Perform Levenberg-Marquardt least-squares minimization (MINPACK-1)

 MAJOR TOPICS:
   Curve and Surface Fitting

 CALLING SEQUENCE:
   parms = MPFIT(MYFUNCT, start_parms, FUNCTARGS=fcnargs, NFEV=nfev,
                 MAXITER=maxiter, ERRMSG=errmsg, NPRINT=nprint, QUIET=quiet, 
                 FTOL=ftol, XTOL=xtol, GTOL=gtol, NITER=niter, 
                 STATUS=status, ITERPROC=iterproc, ITERARGS=iterargs,
                 COVAR=covar, PERROR=perror, BESTNORM=bestnorm,
                 PARINFO=parinfo)

 DESCRIPTION:

  MPFIT uses the Levenberg-Marquardt technique to solve the
  least-squares problem.  In its typical use, MPFIT will be used to
  fit a user-supplied function (the "model") to user-supplied data
  points (the "data") by adjusting a set of parameters.  MPFIT is
  based upon MINPACK-1 (LMDIF.F) by More' and collaborators.

  For example, a researcher may think that a set of observed data
  points is best modelled with a Gaussian curve.  A Gaussian curve is
  parameterized by its mean, standard deviation and normalization.
  MPFIT will, within certain constraints, find the set of parameters
  which best fits the data.  The fit is "best" in the least-squares
  sense; that is, the sum of the weighted squared differences between
  the model and data is minimized.

  The Levenberg-Marquardt technique is a particular strategy for
  iteratively searching for the best fit.  This particular
  implementation is drawn from MINPACK-1 (see NETLIB), and seems to
  be more robust than routines provided with IDL.  This version
  allows upper and lower bounding constraints to be placed on each
  parameter, or the parameter can be held fixed.

  The IDL user-supplied function should return an array of weighted
  deviations between model and data.  In a typical scientific problem
  the residuals should be weighted so that each deviate has a
  gaussian sigma of 1.0.  If X represents values of the independent
  variable, Y represents a measurement for each value of X, and ERR
  represents the error in the measurements, then the deviates could
  be calculated as follows:

    DEVIATES = (Y - F(X)) / ERR

  where F is the analytical function representing the model.  You are
  recommended to use the convenience functions MPFITFUN and
  MPFITEXPR, which are driver functions that calculate the deviates
  for you.  If ERR are the 1-sigma uncertainties in Y, then

    TOTAL( DEVIATES^2 ) 

  will be the total chi-squared value.  MPFIT will minimize the
  chi-square value.  The values of X, Y and ERR are passed through
  MPFIT to the user-supplied function via the FUNCTARGS keyword.

  Simple constraints can be placed on parameter values by using the
  PARINFO keyword to MPFIT.  See below for a description of this
  keyword.

  MPFIT does not perform more general optimization tasks.  See TNMIN
  instead.  MPFIT is customized, based on MINPACK-1, to the
  least-squares minimization problem.

 USER FUNCTION

  The user must define a function which returns the appropriate
  values as specified above.  The function should return the weighted
  deviations between the model and the data.  For applications which
  use finite-difference derivatives -- the default -- the user
  function should be declared in the following way:

    FUNCTION MYFUNCT, p, X=x, Y=y, ERR=err
     ; Parameter values are passed in "p"
     model = F(x, p)
     return, (y-model)/err
    END

  See below for applications with analytical derivatives.

  The keyword parameters X, Y, and ERR in the example above are
  suggestive but not required.  Any parameters can be passed to
  MYFUNCT by using the FUNCTARGS keyword to MPFIT.  Use MPFITFUN and
  MPFITEXPR if you need ideas on how to do that.  The function *must*
  accept a parameter list, P.
  
  In general there are no restrictions on the number of dimensions in
  X, Y or ERR.  However the deviates *must* be returned in a
  one-dimensional array, and must have the same type (float or
  double) as the input arrays.

  User functions may also indicate a fatal error condition using the
  ERROR_CODE common block variable, as described below under the
  MPFIT_ERROR common block definition (by setting ERROR_CODE to a
  number between -15 and -1).

 ANALYTIC DERIVATIVES
 
  In the search for the best-fit solution, MPFIT by default
  calculates derivatives numerically via a finite difference
  approximation.  The user-supplied function need not calculate the
  derivatives explicitly.  However, if you desire to compute them
  analytically, then the AUTODERIVATIVE=0 keyword must be passed.  As
  a practical matter, it is often sufficient and even faster to allow
  MPFIT to calculate the derivatives numerically, and so
  AUTODERIVATIVE=0 is not necessary.

  Also, the user function must be declared with one additional
  parameter, as follows:

    FUNCTION MYFUNCT, p, dp, X=x, Y=y, ERR=err
     model = F(x, p)
     
     if n_params() GT 1 then begin
       ; Compute derivatives
       dp = make_array(n_elements(x), n_elements(p), value=x(0)*0)
       for i = 0, n_elements(p)-1 do $
         dp(*,i) = FGRAD(x, p, i)
     endif
    
     return, (y-model)/err
    END

  where FGRAD(x, p, i) is a user function which must compute the
  derivative of the model with respect to parameter P(i) at X.  When
  finite differencing is used for computing derivatives (ie, when
  AUTODERIVATIVE=1), the parameter DP is not passed.  Therefore
  functions can use N_PARAMS() to indicate whether they must compute
  the derivatives or not.

  Derivatives should be returned in the DP array. DP should be an m x
  n array, where m is the number of data points and n is the number
  of parameters.  dp(i,j) is the derivative at the ith point with
  respect to the jth parameter.  
  
  The derivatives with respect to fixed parameters are ignored; zero
  is an appropriate value to insert for those derivatives.  Upon
  input to the user function, DP is set to a vector with the same
  length as P, with a value of 1 for a parameter which is free, and a
  value of zero for a parameter which is fixed (and hence no
  derivative needs to be calculated).  This input vector may be
  overwritten as needed.

  If the data is higher than one dimensional, then the *last*
  dimension should be the parameter dimension.  Example: fitting a
  50x50 image, "dp" should be 50x50xNPAR.
  
 CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD

  The behavior of MPFIT can be modified with respect to each
  parameter to be fitted.  A parameter value can be fixed; simple
  boundary constraints can be imposed; limitations on the parameter
  changes can be imposed; properties of the automatic derivative can
  be modified; and parameters can be tied to one another.

  These properties are governed by the PARINFO structure, which is
  passed as a keyword parameter to MPFIT.

  PARINFO should be an array of structures, one for each parameter.
  Each parameter is associated with one element of the array, in
  numerical order.  The structure can have the following entries
  (none are required):
  
     .VALUE - the starting parameter value (but see the START_PARAMS
              parameter for more information).
  
     .FIXED - a boolean value, whether the parameter is to be held
              fixed or not.  Fixed parameters are not varied by
              MPFIT, but are passed on to MYFUNCT for evaluation.
  
     .LIMITED - a two-element boolean array.  If the first/second
                element is set, then the parameter is bounded on the
                lower/upper side.  A parameter can be bounded on both
                sides.  Both LIMITED and LIMITS must be given
                together.
  
     .LIMITS - a two-element float or double array.  Gives the
               parameter limits on the lower and upper sides,
               respectively.  Zero, one or two of these values can be
               set, depending on the values of LIMITED.  Both LIMITED
               and LIMITS must be given together.
  
     .PARNAME - a string, giving the name of the parameter.  The
                fitting code of MPFIT does not use this tag in any
                way.  However, the default ITERPROC will print the
                parameter name if available.
  
     .STEP - the step size to be used in calculating the numerical
             derivatives.  If set to zero, then the step size is
             computed automatically.  Ignored when AUTODERIVATIVE=0.
             This value is superceded by the RELSTEP value.

     .RELSTEP - the *relative* step size to be used in calculating
                the numerical derivatives.  This number is the
                fractional size of the step, compared to the
                parameter value.  This value supercedes the STEP
                setting.  If the parameter is zero, then a default
                step size is chosen.

     .MPSIDE - the sidedness of the finite difference when computing
               numerical derivatives.  This field can take four
               values:

                  0 - one-sided derivative computed automatically
                  1 - one-sided derivative (f(x+h) - f(x)  )/h
                 -1 - one-sided derivative (f(x)   - f(x-h))/h
                  2 - two-sided derivative (f(x+h) - f(x-h))/(2*h)

              Where H is the STEP parameter described above.  The
              "automatic" one-sided derivative method will chose a
              direction for the finite difference which does not
              violate any constraints.  The other methods do not
              perform this check.  The two-sided method is in
              principle more precise, but requires twice as many
              function evaluations.  Default: 0.

     .MPMAXSTEP - the maximum change to be made in the parameter
                  value.  During the fitting process, the parameter
                  will never be changed by more than this value in
                  one iteration.

                  A value of 0 indicates no maximum.  Default: 0.
  
     .TIED - a string expression which "ties" the parameter to other
             free or fixed parameters.  Any expression involving
             constants and the parameter array P are permitted.
             Example: if parameter 2 is always to be twice parameter
             1 then use the following: parinfo(2).tied = '2 * P(1)'.
             Since they are totally constrained, tied parameters are
             considered to be fixed; no errors are computed for them.
             [ NOTE: the PARNAME can't be used in expressions. ]

     .MPPRINT - if set to 1, then the default ITERPROC will print the
                parameter value.  If set to 0, the parameter value
                will not be printed.  This tag can be used to
                selectively print only a few parameter values out of
                many.  Default: 1 (all parameters printed)

     .MPFORMAT - IDL format string to print the parameter within
                 ITERPROC.  Default: '(G20.6)' An empty string will
                 also use the default.

  
  Future modifications to the PARINFO structure, if any, will involve
  adding structure tags beginning with the two letters "MP".
  Therefore programmers are urged to avoid using tags starting with
  the same letters; otherwise they are free to include their own
  fields within the PARINFO structure, and they will be ignored.
  
  PARINFO Example:
  parinfo = replicate({value:0.D, fixed:0, limited:[0,0], $
                       limits:[0.D,0]}, 5)
  parinfo(0).fixed = 1
  parinfo(4).limited(0) = 1
  parinfo(4).limits(0)  = 50.D
  parinfo(*).value = [5.7D, 2.2, 500., 1.5, 2000.]
  
  A total of 5 parameters, with starting values of 5.7,
  2.2, 500, 1.5, and 2000 are given.  The first parameter
  is fixed at a value of 5.7, and the last parameter is
  constrained to be above 50.


 HARD-TO-COMPUTE FUNCTIONS: "EXTERNAL" EVALUATION

  The normal mode of operation for MPFIT is for the user to pass a
  function name, and MPFIT will call the user function multiple times
  as it iterates toward a solution.

  Some user functions are particularly hard to compute using the
  standard model of MPFIT.  Usually these are functions that depend
  on a large amount of external data, and so it is not feasible, or
  at least highly impractical, to have MPFIT call it.  In those cases
  it may be possible to use the "(EXTERNAL)" evaluation option.

  In this case the user is responsible for making all function *and
  derivative* evaluations.  The function and Jacobian data are passed
  in through the EXTERNAL_FVEC and EXTERNAL_FJAC keywords,
  respectively.  The user indicates the selection of this option by
  specifying a function name (MYFUNCT) of "(EXTERNAL)".  No
  user-function calls are made when EXTERNAL evaluation is being
  used.

  At the end of each iteration, control returns to the user, who must
  reevaluate the function at its new parameter values.  Users should
  check the return value of the STATUS keyword, where a value of 9
  indicates the user should supply more data for the next iteration,
  and re-call MPFIT.  The user may refrain from calling MPFIT
  further; as usual, STATUS will indicate when the solution has
  converged and no more iterations are required.

  Because MPFIT must maintain its own data structures between calls,
  the user must also pass a named variable to the EXTERNAL_STATE
  keyword.  This variable must be maintained by the user, but not
  changed, throughout the fitting process.  When no more iterations
  are desired, the named variable may be discarded.


 INPUTS:
   MYFUNCT - a string variable containing the name of the function to
             be minimized.  The function should return the weighted
             deviations between the model and the data, as described
             above.

             For EXTERNAL evaluation of functions, this parameter
             should be set to a value of "(EXTERNAL)".

   START_PARAMS - An array of starting values for each of the
                  parameters of the model.  The number of parameters
                  should be fewer than the number of measurements.
                  Also, the parameters should have the same data type
                  as the measurements (double is preferred).

                  This parameter is optional if the PARINFO keyword
                  is used (but see PARINFO).  The PARINFO keyword
                  provides a mechanism to fix or constrain individual
                  parameters.  If both START_PARAMS and PARINFO are
                  passed, then the starting *value* is taken from
                  START_PARAMS, but the *constraints* are taken from
                  PARINFO.
 
 RETURNS:

   Returns the array of best-fit parameters.


 KEYWORD PARAMETERS:

   AUTODERIVATIVE - If this is set, derivatives of the function will
                    be computed automatically via a finite
                    differencing procedure.  If not set, then MYFUNCT
                    must provide the (analytical) derivatives.
                    Default: set (=1) 
                    NOTE: to supply your own analytical derivatives,
                      explicitly pass AUTODERIVATIVE=0

   BESTNORM - the value of the summed squared weighted residuals for
              the returned parameter values, i.e. TOTAL(DEVIATES^2).

   COVAR - the covariance matrix for the set of parameters returned
           by MPFIT.  The matrix is NxN where N is the number of
           parameters.  The square root of the diagonal elements
           gives the formal 1-sigma statistical errors on the
           parameters IF errors were treated "properly" in MYFUNC.
           Parameter errors are also returned in PERROR.

           To compute the correlation matrix, PCOR, use this example:
           IDL> PCOR = COV * 0
           IDL> FOR i = 0, n-1 DO FOR j = 0, n-1 DO $
                PCOR(i,j) = COV(i,j)/sqrt(COV(i,i)*COV(j,j))

           If NOCOVAR is set or MPFIT terminated abnormally, then
           COVAR is set to a scalar with value !VALUES.D_NAN.

   DOF - number of degrees of freedom, computed as
             DOF = N_ELEMENTS(DEVIATES) - NFREE
         Note that this doesn't account for pegged parameters (see
         NPEGGED).

   ERRMSG - a string error or warning message is returned.

   EXTERNAL_FVEC - upon input, the function values, evaluated at
                   START_PARAMS.  This should be an M-vector, where M
                   is the number of data points.

   EXTERNAL_FJAC - upon input, the Jacobian array of partial
                   derivative values.  This should be a M x N array,
                   where M is the number of data points and N is the
                   number of parameters.  NOTE: that all FIXED or
                   TIED parameters must *not* be included in this
                   array.

   EXTERNAL_STATE - a named variable to store MPFIT-related state
                    information between iterations (used in input and
                    output to MPFIT).  The user must not manipulate
                    or discard this data until the final iteration is
                    performed.

   FASTNORM - set this keyword to select a faster algorithm to
              compute sum-of-square values internally.  For systems
              with large numbers of data points, the standard
              algorithm can become prohibitively slow because it
              cannot be vectorized well.  By setting this keyword,
              MPFIT will run faster, but it will be more prone to
              floating point overflows and underflows.  Thus, setting
              this keyword may sacrifice some stability in the
              fitting process.
              
   FTOL - a nonnegative input variable. Termination occurs when both
          the actual and predicted relative reductions in the sum of
          squares are at most FTOL (and STATUS is accordingly set to
          1 or 3).  Therefore, FTOL measures the relative error
          desired in the sum of squares.  Default: 1D-10

   FUNCTARGS - A structure which contains the parameters to be passed
               to the user-supplied function specified by MYFUNCT via
               the _EXTRA mechanism.  This is the way you can pass
               additional data to your user-supplied function without
               using common blocks.

               Consider the following example:
                if FUNCTARGS = { XVAL:[1.D,2,3], YVAL:[1.D,4,9],
                                 ERRVAL:[1.D,1,1] }
                then the user supplied function should be declared
                like this:
                FUNCTION MYFUNCT, P, XVAL=x, YVAL=y, ERRVAL=err

               By default, no extra parameters are passed to the
               user-supplied function, but your function should
               accept *at least* one keyword parameter.  [ This is to
               accomodate a limitation in IDL's _EXTRA
               parameter-passing mechanism. ]

   GTOL - a nonnegative input variable. Termination occurs when the
          cosine of the angle between fvec and any column of the
          jacobian is at most GTOL in absolute value (and STATUS is
          accordingly set to 4). Therefore, GTOL measures the
          orthogonality desired between the function vector and the
          columns of the jacobian.  Default: 1D-10

   ITERARGS - The keyword arguments to be passed to ITERPROC via the
              _EXTRA mechanism.  This should be a structure, and is
              similar in operation to FUNCTARGS.
              Default: no arguments are passed.

   ITERPRINT - The name of an IDL procedure, equivalent to PRINT,
               that ITERPROC will use to render output.  ITERPRINT
               should be able to accept at least four positional
               arguments.  In addition, it should be able to accept
               the standard FORMAT keyword for output formatting; and
               the UNIT keyword, to redirect output to a logical file
               unit (default should be UNIT=1, standard output).
               These keywords are passed using the ITERARGS keyword
               above.  The ITERPRINT procedure must accept the _EXTRA
               keyword.

   ITERPROC - The name of a procedure to be called upon each NPRINT
              iteration of the MPFIT routine.  ITERPROC is always
              called in the final iteration.  It should be declared
              in the following way:

              PRO ITERPROC, MYFUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
                PARINFO=parinfo, QUIET=quiet, DOF=dof, ...
                ; perform custom iteration update
              END
         
              ITERPROC must either accept all three keyword
              parameters (FUNCTARGS, PARINFO and QUIET), or at least
              accept them via the _EXTRA keyword.
          
              MYFUNCT is the user-supplied function to be minimized,
              P is the current set of model parameters, ITER is the
              iteration number, and FUNCTARGS are the arguments to be
              passed to MYFUNCT.  FNORM should be the chi-squared
              value.  QUIET is set when no textual output should be
              printed.  DOF is the number of degrees of freedom,
              normally the number of points less the number of free
              parameters.  See below for documentation of PARINFO.

              In implementation, ITERPROC can perform updates to the
              terminal or graphical user interface, to provide
              feedback while the fit proceeds.  If the fit is to be
              stopped for any reason, then ITERPROC should set the
              common block variable ERROR_CODE to negative value
              between -15 and -1 (see MPFIT_ERROR common block
              below).  In principle, ITERPROC should probably not
              modify the parameter values, because it may interfere
              with the algorithm's stability.  In practice it is
              allowed.

              Default: an internal routine is used to print the
                       parameter values.

   ITERSTOP - Set this keyword if you wish to be able to stop the
              fitting by hitting the predefined ITERKEYSTOP key on
              the keyboard.  This only works if you use the default
              ITERPROC.

   ITERKEYSTOP - A keyboard key which will halt the fit (and if
                 ITERSTOP is set and the default ITERPROC is used).
                 ITERSTOPKEY may either be a one-character string
                 with the desired key, or a scalar integer giving the
                 ASCII code of the desired key.  
                 Default: 7b (control-g)

                 NOTE: the default value of ASCI 7 (control-G) cannot
                 be read in some windowing environments, so you must
                 change to a printable character like 'q'.

   MAXITER - The maximum number of iterations to perform.  If the
             number is exceeded, then the STATUS value is set to 5
             and MPFIT returns.
             Default: 200 iterations

   NFEV - the number of MYFUNCT function evaluations performed.

   NFREE - the number of free parameters in the fit.  This includes
           parameters which are not FIXED and not TIED, but it does
           include parameters which are pegged at LIMITS.

   NITER - the number of iterations completed.

   NOCOVAR - set this keyword to prevent the calculation of the
             covariance matrix before returning (see COVAR)

   NPEGGED - the number of free parameters which are pegged at a
             LIMIT.

   NPRINT - The frequency with which ITERPROC is called.  A value of
            1 indicates that ITERPROC is called with every iteration,
            while 2 indicates every other iteration, etc.  Be aware
            that several Levenberg-Marquardt attempts can be made in
            a single iteration.  Also, the ITERPROC is *always*
            called for the final iteration, regardless of the
            iteration number.
            Default value: 1

   PARINFO - Provides a mechanism for more sophisticated constraints
             to be placed on parameter values.  When PARINFO is not
             passed, then it is assumed that all parameters are free
             and unconstrained.  Values in PARINFO are never 
             modified during a call to MPFIT.

             See description above for the structure of PARINFO.

             Default value:  all parameters are free and unconstrained.

   PERROR - The formal 1-sigma errors in each parameter, computed
            from the covariance matrix.  If a parameter is held
            fixed, or if it touches a boundary, then the error is
            reported as zero.

            If the fit is unweighted (i.e. no errors were given, or
            the weights were uniformly set to unity), then PERROR
            will probably not represent the true parameter
            uncertainties.  

            *If* you can assume that the true reduced chi-squared
            value is unity -- meaning that the fit is implicitly
            assumed to be of good quality -- then the estimated
            parameter uncertainties can be computed by scaling PERROR
            by the measured chi-squared value.

              DOF     = N_ELEMENTS(X) - N_ELEMENTS(PARMS) ; deg of freedom
              PCERROR = PERROR * SQRT(BESTNORM / DOF)   ; scaled uncertainties

   QUIET - set this keyword when no textual output should be printed
           by MPFIT

   RESDAMP - a scalar number, indicating the cut-off value of
             residuals where "damping" will occur.  Residuals with
             magnitudes greater than this number will be replaced by
             their logarithm.  This partially mitigates the so-called
             large residual problem inherent in least-squares solvers
             (as for the test problem CURVI, http://www.maxthis.com/-
             curviex.htm).  A value of 0 indicates no damping.
             Default: 0

             Note: RESDAMP doesn't work with AUTODERIV=0

   STATUS - an integer status code is returned.  All values greater
            than zero can represent success (however STATUS EQ 5 may
            indicate failure to converge).  It can have one of the
            following values:

        -16  a parameter or function value has become infinite or an
             undefined number.  This is usually a consequence of
             numerical overflow in the user's model function, which
             must be avoided.

        -15 to -1 
             these are error codes that either MYFUNCT or ITERPROC
             may return to terminate the fitting process (see
             description of MPFIT_ERROR common below).  If either
             MYFUNCT or ITERPROC set ERROR_CODE to a negative number,
             then that number is returned in STATUS.  Values from -15
             to -1 are reserved for the user functions and will not
             clash with MPFIT.

	   0  improper input parameters.
         
	   1  both actual and predicted relative reductions
	      in the sum of squares are at most FTOL.
         
	   2  relative error between two consecutive iterates
	      is at most XTOL
         
	   3  conditions for STATUS = 1 and STATUS = 2 both hold.
         
	   4  the cosine of the angle between fvec and any
	      column of the jacobian is at most GTOL in
	      absolute value.
         
	   5  the maximum number of iterations has been reached
         
	   6  FTOL is too small. no further reduction in
	      the sum of squares is possible.
         
	   7  XTOL is too small. no further improvement in
	      the approximate solution x is possible.
         
	   8  GTOL is too small. fvec is orthogonal to the
	      columns of the jacobian to machine precision.

          9  A successful single iteration has been completed, and
             the user must supply another "EXTERNAL" evaluation of
             the function and its derivatives.  This status indicator
             is neither an error nor a convergence indicator.

   XTOL - a nonnegative input variable. Termination occurs when the
          relative error between two consecutive iterates is at most
          XTOL (and STATUS is accordingly set to 2 or 3).  Therefore,
          XTOL measures the relative error desired in the approximate
          solution.  Default: 1D-10


 EXAMPLE:

   p0 = [5.7D, 2.2, 500., 1.5, 2000.]
   fa = {X:x, Y:y, ERR:err}
   p = mpfit('MYFUNCT', p0, functargs=fa)

   Minimizes sum of squares of MYFUNCT.  MYFUNCT is called with the X,
   Y, and ERR keyword parameters that are given by FUNCTARGS.  The
   resulting parameter values are returned in p.


 COMMON BLOCKS:

   COMMON MPFIT_ERROR, ERROR_CODE

     User routines may stop the fitting process at any time by
     setting an error condition.  This condition may be set in either
     the user's model computation routine (MYFUNCT), or in the
     iteration procedure (ITERPROC).

     To stop the fitting, the above common block must be declared,
     and ERROR_CODE must be set to a negative number.  After the user
     procedure or function returns, MPFIT checks the value of this
     common block variable and exits immediately if the error
     condition has been set.  This value is also returned in the
     STATUS keyword: values of -1 through -15 are reserved error
     codes for the user routines.  By default the value of ERROR_CODE
     is zero, indicating a successful function/procedure call.

   COMMON MPFIT_PROFILE
   COMMON MPFIT_MACHAR
   COMMON MPFIT_CONFIG

     These are undocumented common blocks are used internally by
     MPFIT and may change in future implementations.

 THEORY OF OPERATION:

   There are many specific strategies for function minimization.  One
   very popular technique is to use function gradient information to
   realize the local structure of the function.  Near a local minimum
   the function value can be taylor expanded about x0 as follows:

      f(x) = f(x0) + f'(x0) . (x-x0) + (1/2) (x-x0) . f''(x0) . (x-x0)
             -----   ---------------   -------------------------------  (1)
     Order    0th          1st                      2nd

   Here f'(x) is the gradient vector of f at x, and f''(x) is the
   Hessian matrix of second derivatives of f at x.  The vector x is
   the set of function parameters, not the measured data vector.  One
   can find the minimum of f, f(xm) using Newton's method, and
   arrives at the following linear equation:

      f''(x0) . (xm-x0) = - f'(x0)                            (2)

   If an inverse can be found for f''(x0) then one can solve for
   (xm-x0), the step vector from the current position x0 to the new
   projected minimum.  Here the problem has been linearized (ie, the
   gradient information is known to first order).  f''(x0) is
   symmetric n x n matrix, and should be positive definite.

   The Levenberg - Marquardt technique is a variation on this theme.
   It adds an additional diagonal term to the equation which may aid the
   convergence properties:

      (f''(x0) + nu I) . (xm-x0) = -f'(x0)                  (2a)

   where I is the identity matrix.  When nu is large, the overall
   matrix is diagonally dominant, and the iterations follow steepest
   descent.  When nu is small, the iterations are quadratically
   convergent.

   In principle, if f''(x0) and f'(x0) are known then xm-x0 can be
   determined.  However the Hessian matrix is often difficult or
   impossible to compute.  The gradient f'(x0) may be easier to
   compute, if even by finite difference techniques.  So-called
   quasi-Newton techniques attempt to successively estimate f''(x0)
   by building up gradient information as the iterations proceed.

   In the least squares problem there are further simplifications
   which assist in solving eqn (2).  The function to be minimized is
   a sum of squares:

       f = Sum(hi^2)                                         (3)

   where hi is the ith residual out of m residuals as described
   above.  This can be substituted back into eqn (2) after computing
   the derivatives:

       f'  = 2 Sum(hi  hi')     
       f'' = 2 Sum(hi' hj') + 2 Sum(hi hi'')                (4)

   If one assumes that the parameters are already close enough to a
   minimum, then one typically finds that the second term in f'' is
   negligible [or, in any case, is too difficult to compute].  Thus,
   equation (2) can be solved, at least approximately, using only
   gradient information.

   In matrix notation, the combination of eqns (2) and (4) becomes:

        hT' . h' . dx = - hT' . h                          (5)

   Where h is the residual vector (length m), hT is its transpose, h'
   is the Jacobian matrix (dimensions n x m), and dx is (xm-x0).  The
   user function supplies the residual vector h, and in some cases h'
   when it is not found by finite differences (see MPFIT_FDJAC2,
   which finds h and hT').  Even if dx is not the best absolute step
   to take, it does provide a good estimate of the best *direction*,
   so often a line minimization will occur along the dx vector
   direction.

   The method of solution employed by MINPACK is to form the Q . R
   factorization of h', where Q is an orthogonal matrix such that QT .
   Q = I, and R is upper right triangular.  Using h' = Q . R and the
   ortogonality of Q, eqn (5) becomes

        (RT . QT) . (Q . R) . dx = - (RT . QT) . h
                     RT . R . dx = - RT . QT . h         (6)
                          R . dx = - QT . h

   where the last statement follows because R is upper triangular.
   Here, R, QT and h are known so this is a matter of solving for dx.
   The routine MPFIT_QRFAC provides the QR factorization of h, with
   pivoting, and MPFIT_QRSOLV provides the solution for dx.
   
 REFERENCES:

   MINPACK-1, Jorge More', available from netlib (www.netlib.org).
   "Optimization Software Guide," Jorge More' and Stephen Wright, 
     SIAM, *Frontiers in Applied Mathematics*, Number 14.
   More', Jorge J., "The Levenberg-Marquardt Algorithm:
     Implementation and Theory," in *Numerical Analysis*, ed. Watson,
     G. A., Lecture Notes in Mathematics 630, Springer-Verlag, 1977.

 MODIFICATION HISTORY:
   Translated from MINPACK-1 in FORTRAN, Apr-Jul 1998, CM
   Fixed bug in parameter limits (x vs xnew), 04 Aug 1998, CM
   Added PERROR keyword, 04 Aug 1998, CM
   Added COVAR keyword, 20 Aug 1998, CM
   Added NITER output keyword, 05 Oct 1998
      D.L Windt, Bell Labs, windt@bell-labs.com;
   Made each PARINFO component optional, 05 Oct 1998 CM
   Analytical derivatives allowed via AUTODERIVATIVE keyword, 09 Nov 1998
   Parameter values can be tied to others, 09 Nov 1998
   Fixed small bugs (Wayne Landsman), 24 Nov 1998
   Added better exception error reporting, 24 Nov 1998 CM
   Cosmetic documentation changes, 02 Jan 1999 CM
   Changed definition of ITERPROC to be consistent with TNMIN, 19 Jan 1999 CM
   Fixed bug when AUTDERIVATIVE=0.  Incorrect sign, 02 Feb 1999 CM
   Added keyboard stop to MPFIT_DEFITER, 28 Feb 1999 CM
   Cosmetic documentation changes, 14 May 1999 CM
   IDL optimizations for speed & FASTNORM keyword, 15 May 1999 CM
   Tried a faster version of mpfit_enorm, 30 May 1999 CM
   Changed web address to cow.physics.wisc.edu, 14 Jun 1999 CM
   Found malformation of FDJAC in MPFIT for 1 parm, 03 Aug 1999 CM
   Factored out user-function call into MPFIT_CALL.  It is possible,
     but currently disabled, to call procedures.  The calling format
     is similar to CURVEFIT, 25 Sep 1999, CM
   Slightly changed mpfit_tie to be less intrusive, 25 Sep 1999, CM
   Fixed some bugs associated with tied parameters in mpfit_fdjac, 25
     Sep 1999, CM
   Reordered documentation; now alphabetical, 02 Oct 1999, CM
   Added QUERY keyword for more robust error detection in drivers, 29
     Oct 1999, CM
   Documented PERROR for unweighted fits, 03 Nov 1999, CM
   Split out MPFIT_RESETPROF to aid in profiling, 03 Nov 1999, CM
   Some profiling and speed optimization, 03 Nov 1999, CM
     Worst offenders, in order: fdjac2, qrfac, qrsolv, enorm.
     fdjac2 depends on user function, qrfac and enorm seem to be
     fully optimized.  qrsolv probably could be tweaked a little, but
     is still <10% of total compute time.
   Made sure that !err was set to 0 in MPFIT_DEFITER, 10 Jan 2000, CM
   Fixed small inconsistency in setting of QANYLIM, 28 Jan 2000, CM
   Added PARINFO field RELSTEP, 28 Jan 2000, CM
   Converted to MPFIT_ERROR common block for indicating error
     conditions, 28 Jan 2000, CM
   Corrected scope of MPFIT_ERROR common block, CM, 07 Mar 2000
   Minor speed improvement in MPFIT_ENORM, CM 26 Mar 2000
   Corrected case where ITERPROC changed parameter values and
     parameter values were TIED, CM 26 Mar 2000
   Changed MPFIT_CALL to modify NFEV automatically, and to support
     user procedures more, CM 26 Mar 2000
   Copying permission terms have been liberalized, 26 Mar 2000, CM
   Catch zero value of zero a(j,lj) in MPFIT_QRFAC, 20 Jul 2000, CM
      (thanks to David Schlegel )
   MPFIT_SETMACHAR is called only once at init; only one common block
     is created (MPFIT_MACHAR); it is now a structure; removed almost
     all CHECK_MATH calls for compatibility with IDL5 and !EXCEPT;
     profiling data is now in a structure too; noted some
     mathematical discrepancies in Linux IDL5.0, 17 Nov 2000, CM
   Some significant changes.  New PARINFO fields: MPSIDE, MPMINSTEP,
     MPMAXSTEP.  Improved documentation.  Now PTIED constraints are
     maintained in the MPCONFIG common block.  A new procedure to
     parse PARINFO fields.  FDJAC2 now computes a larger variety of
     one-sided and two-sided finite difference derivatives.  NFEV is
     stored in the MPCONFIG common now.  17 Dec 2000, CM
   Added check that PARINFO and XALL have same size, 29 Dec 2000 CM
   Don't call function in TERMINATE when there is an error, 05 Jan
     2000
   Check for float vs. double discrepancies; corrected implementation
     of MIN/MAXSTEP, which I still am not sure of, but now at least
     the correct behavior occurs *without* it, CM 08 Jan 2001
   Added SCALE_FCN keyword, to allow for scaling, as for the CASH
     statistic; added documentation about the theory of operation,
     and under the QR factorization; slowly I'm beginning to
     understand the bowels of this algorithm, CM 10 Jan 2001
   Remove MPMINSTEP field of PARINFO, for now at least, CM 11 Jan
     2001
   Added RESDAMP keyword, CM, 14 Jan 2001
   Tried to improve the DAMP handling a little, CM, 13 Mar 2001
   Corrected .PARNAME behavior in _DEFITER, CM, 19 Mar 2001
   Added checks for parameter and function overflow; a new STATUS
     value to reflect this; STATUS values of -15 to -1 are reserved
     for user function errors, CM, 03 Apr 2001
   DAMP keyword is now a TANH, CM, 03 Apr 2001
   Added more error checking of float vs. double, CM, 07 Apr 2001
   Fixed bug in handling of parameter lower limits; moved overflow
     checking to end of loop, CM, 20 Apr 2001
   Failure using GOTO, TERMINATE more graceful if FNORM1 not defined,
     CM, 13 Aug 2001
   Add MPPRINT tag to PARINFO, CM, 19 Nov 2001
   Add DOF keyword to DEFITER procedure, and print degrees of
     freedom, CM, 28 Nov 2001
   Add check to be sure MYFUNCT is a scalar string, CM, 14 Jan 2002
   Addition of EXTERNAL_FJAC, EXTERNAL_FVEC keywords; ability to save
     fitter's state from one call to the next; allow '(EXTERNAL)'
     function name, which implies that user will supply function and
     Jacobian at each iteration, CM, 10 Mar 2002
   Documented EXTERNAL evaluation code, CM, 10 Mar 2002
   Corrected signficant bug in the way that the STEP parameter, and
     FIXED parameters interacted (Thanks Andrew Steffl), CM, 02 Apr
     2002
   Allow COVAR and PERROR keywords to be computed, even in case of
     '(EXTERNAL)' function, 26 May 2002
   Add NFREE and NPEGGED keywords; compute NPEGGED; compute DOF using
     NFREE instead of n_elements(X), thanks to Kristian Kjaer, CM 11
     Sep 2002
   Hopefully PERROR is all positive now, CM 13 Sep 2002
   Documented RELSTEP field of PARINFO (!!), CM, 25 Oct 2002
   Error checking to detect missing start pars, CM 12 Apr 2003
   Add DOF keyword to return degrees of freedom, CM, 30 June 2003
   Always call ITERPROC in the final iteration; add ITERKEYSTOP
     keyword, CM, 30 June 2003
   Correct bug in MPFIT_LMPAR of singularity handling, which might
     likely be fatal for one-parameter fits, CM, 21 Nov 2003
     (with thanks to Peter Tuthill for the proper test case)
   Minor documentation adjustment, 03 Feb 2004, CM
   Correct small error in QR factorization when pivoting; document
     the return values of QRFAC when pivoting, 21 May 2004, CM
   Add MPFORMAT field to PARINFO, and correct behavior of interaction
     between MPPRINT and PARNAME in MPFIT_DEFITERPROC (thanks to Tim
     Robishaw), 23 May 2004, CM
   Add the ITERPRINT keyword to allow redirecting output, 26 Sep
     2004, CM
   Correct MAXSTEP behavior in case of a negative parameter, 26 Sep
     2004, CM
   Fix bug in the parsing of MINSTEP/MAXSTEP, 10 Apr 2005, CM

  $Id: mpfit.pro,v 1.2 2005/09/07 18:46:44 aasnes Exp $

(See /home/jbf/ct/papco/working/papco/papco_lib/fit/mpfit.pro:888)

mpfit2dfun

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
   MPFIT2DFUN

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov
   UPDATED VERSIONs can be found on my WEB PAGE: 
      http://cow.physics.wisc.edu/~craigm/idl/idl.html

 PURPOSE:
   Perform Levenberg-Marquardt least-squares fit to a 2-D IDL function

 MAJOR TOPICS:
   Curve and Surface Fitting

 CALLING SEQUENCE:
   parms = MPFIT2DFUN(MYFUNCT, X, Y, Z, ERR, start_parms, ...)

 DESCRIPTION:

  MPFIT2DFUN fits a user-supplied model -- in the form of an IDL
  function -- to a set of user-supplied data.  MPFIT2DFUN calls
  MPFIT, the MINPACK-1 least-squares minimizer, to do the main
  work.  MPFIT2DFUN is a specialized version for two-dimensional 
  data.

  Given the data and their uncertainties, MPFIT2DFUN finds the best set
  of model parameters which match the data (in a least-squares
  sense) and returns them in an array.
  
  The user must supply the following items:
   - Two arrays of independent variable values ("X", "Y").
   - An array of "measured" *dependent* variable values ("Z").
   - An array of "measured" 1-sigma uncertainty values ("ERR").
   - The name of an IDL function which computes Z given (X,Y) ("MYFUNCT").
   - Starting guesses for all of the parameters ("START_PARAMS").

  There are very few restrictions placed on X, Y, Z, or MYFUNCT.
  Simply put, MYFUNCT must map the (X,Y) values into Z values given
  the model parameters.  The (X,Y) values are usually the independent
  X and Y coordinate positions in the two dimensional plane, but need
  not be.

  MPFIT2DFUN carefully avoids passing large arrays where possible to
  improve performance.

  See below for an example of usage.
   
 USER FUNCTION

  The user must define a function which returns the model value.  For
  applications which use finite-difference derivatives -- the default
  -- the user function should be declared in the following way:

    FUNCTION MYFUNCT, X, Y, P
     ; The independent variables are X and Y
     ; Parameter values are passed in "P"
     ZMOD = ... computed model values at (X,Y) ...
     return, ZMOD
    END

  The returned array YMOD must have the same dimensions and type as
  the "measured" Z values.

  User functions may also indicate a fatal error condition
  using the ERROR_CODE common block variable, as described
  below under the MPFIT_ERROR common block definition.

  See the discussion under "ANALYTIC DERIVATIVES" and AUTODERIVATIVE
  in MPFIT.PRO if you wish to compute the derivatives for yourself.
  AUTODERIVATIVE is accepted and passed directly to MPFIT.  The user
  function must accept one additional parameter, DP, which contains
  the derivative of the user function with respect to each parameter
  at each data point, as described in MPFIT.PRO.

 CREATING APPROPRIATELY DIMENSIONED INDEPENDENT VARIABLES

  The user must supply appropriate independent variables to
  MPFIT2DFUN.  For image fitting applications, this variable should
  be two-dimensional *arrays* describing the X and Y positions of
  every *pixel*.  [ Thus any two dimensional sampling is permitted,
  including irregular sampling. ]
  
  If the sampling is regular, then the x coordinates are the same for
  each row, and the y coordinates are the same for each column.  Call
  the x-row and y-column coordinates XR and YC respectively.  You can
  then compute X and Y as follows:
  
      X = XR # (YC*0 + 1)             eqn. 1
      Y = (XR*0 + 1) # YC             eqn. 2
  
  For example, if XR and YC have the following values:
  
    XR = [  1, 2, 3, 4, 5,]  ;; X positions of one row of pixels
    YC = [ 15,16,17 ]        ;; Y positions of one column of
                                pixels
  
  Then using equations 1 and 2 above will give these values to X and
  Y:
  
     X :  1  2  3  4  5       ;; X positions of all pixels
          1  2  3  4  5
          1  2  3  4  5
  
     Y : 15 15 15 15 15       ;; Y positions of all pixels
         16 16 16 16 16
         17 17 17 17 17
  
  Using the above technique is suggested, but *not* required.  You
  can do anything you wish with the X and Y values.  This technique
  only makes it easier to compute your model function values.

 CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD

  The behavior of MPFIT can be modified with respect to each
  parameter to be fitted.  A parameter value can be fixed; simple
  boundary constraints can be imposed; limitations on the parameter
  changes can be imposed; properties of the automatic derivative can
  be modified; and parameters can be tied to one another.

  These properties are governed by the PARINFO structure, which is
  passed as a keyword parameter to MPFIT.

  PARINFO should be an array of structures, one for each parameter.
  Each parameter is associated with one element of the array, in
  numerical order.  The structure can have the following entries
  (none are required):
  
     .VALUE - the starting parameter value (but see the START_PARAMS
              parameter for more information).
  
     .FIXED - a boolean value, whether the parameter is to be held
              fixed or not.  Fixed parameters are not varied by
              MPFIT, but are passed on to MYFUNCT for evaluation.
  
     .LIMITED - a two-element boolean array.  If the first/second
                element is set, then the parameter is bounded on the
                lower/upper side.  A parameter can be bounded on both
                sides.  Both LIMITED and LIMITS must be given
                together.
  
     .LIMITS - a two-element float or double array.  Gives the
               parameter limits on the lower and upper sides,
               respectively.  Zero, one or two of these values can be
               set, depending on the values of LIMITED.  Both LIMITED
               and LIMITS must be given together.
  
     .PARNAME - a string, giving the name of the parameter.  The
                fitting code of MPFIT does not use this tag in any
                way.  However, the default ITERPROC will print the
                parameter name if available.
  
     .STEP - the step size to be used in calculating the numerical
             derivatives.  If set to zero, then the step size is
             computed automatically.  Ignored when AUTODERIVATIVE=0.
             This value is superceded by the RELSTEP value.

     .RELSTEP - the *relative* step size to be used in calculating
                the numerical derivatives.  This number is the
                fractional size of the step, compared to the
                parameter value.  This value supercedes the STEP
                setting.  If the parameter is zero, then a default
                step size is chosen.

     .MPSIDE - the sidedness of the finite difference when computing
               numerical derivatives.  This field can take four
               values:

                  0 - one-sided derivative computed automatically
                  1 - one-sided derivative (f(x+h) - f(x)  )/h
                 -1 - one-sided derivative (f(x)   - f(x-h))/h
                  2 - two-sided derivative (f(x+h) - f(x-h))/(2*h)

              Where H is the STEP parameter described above.  The
              "automatic" one-sided derivative method will chose a
              direction for the finite difference which does not
              violate any constraints.  The other methods do not
              perform this check.  The two-sided method is in
              principle more precise, but requires twice as many
              function evaluations.  Default: 0.

     .MPMINSTEP - the minimum change to be made in the parameter
                  value.  During the fitting process, the parameter
                  will be changed by multiples of this value.  The
                  actual step is computed as:

                     DELTA1 = MPMINSTEP*ROUND(DELTA0/MPMINSTEP)

                  where DELTA0 and DELTA1 are the estimated parameter
                  changes before and after this constraint is
                  applied.  Note that this constraint should be used
                  with care since it may cause non-converging,
                  oscillating solutions.

                  A value of 0 indicates no minimum.  Default: 0.

     .MPMAXSTEP - the maximum change to be made in the parameter
                  value.  During the fitting process, the parameter
                  will never be changed by more than this value.

                  A value of 0 indicates no maximum.  Default: 0.
  
     .TIED - a string expression which "ties" the parameter to other
             free or fixed parameters.  Any expression involving
             constants and the parameter array P are permitted.
             Example: if parameter 2 is always to be twice parameter
             1 then use the following: parinfo(2).tied = '2 * P(1)'.
             Since they are totally constrained, tied parameters are
             considered to be fixed; no errors are computed for them.
             [ NOTE: the PARNAME can't be used in expressions. ]
  
  Future modifications to the PARINFO structure, if any, will involve
  adding structure tags beginning with the two letters "MP".
  Therefore programmers are urged to avoid using tags starting with
  the same letters; otherwise they are free to include their own
  fields within the PARINFO structure, and they will be ignored.
  
  PARINFO Example:
  parinfo = replicate({value:0.D, fixed:0, limited:[0,0], $
                       limits:[0.D,0]}, 5)
  parinfo(0).fixed = 1
  parinfo(4).limited(0) = 1
  parinfo(4).limits(0)  = 50.D
  parinfo(*).value = [5.7D, 2.2, 500., 1.5, 2000.]
  
  A total of 5 parameters, with starting values of 5.7,
  2.2, 500, 1.5, and 2000 are given.  The first parameter
  is fixed at a value of 5.7, and the last parameter is
  constrained to be above 50.

 INPUTS:
   MYFUNCT - a string variable containing the name of an IDL
             function.  This function computes the "model" Z values
             given the X,Y values and model parameters, as described above.

   X - Array of "X" independent variable values, as described above.
       These values are passed directly to the fitting function
       unmodified.

   Y - Array of "Y" independent variable values, as described
       above. X and Y should have the same data type.

   Z - Array of "measured" dependent variable values.  Z should have
       the same data type as X and Y.  The function MYFUNCT should
       map (X,Y)->Z.

   ERR - Array of "measured" 1-sigma uncertainties.  ERR should have
         the same data type as Z.  ERR is ignored if the WEIGHTS
         keyword is specified.

   START_PARAMS - An array of starting values for each of the
                  parameters of the model.  The number of parameters
                  should be fewer than the number of measurements.
                  Also, the parameters should have the same data type
                  as the measurements (double is preferred).

                  This parameter is optional if the PARINFO keyword
                  is used (see MPFIT).  The PARINFO keyword provides
                  a mechanism to fix or constrain individual
                  parameters.  If both START_PARAMS and PARINFO are
                  passed, then the starting *value* is taken from
                  START_PARAMS, but the *constraints* are taken from
                  PARINFO.
 
 RETURNS:

   Returns the array of best-fit parameters.

 KEYWORD PARAMETERS:

   BESTNORM - the value of the summed, squared, weighted residuals
              for the returned parameter values, i.e. the chi-square value.

   COVAR - the covariance matrix for the set of parameters returned
           by MPFIT.  The matrix is NxN where N is the number of
           parameters.  The square root of the diagonal elements
           gives the formal 1-sigma statistical errors on the
           parameters IF errors were treated "properly" in MYFUNC.
           Parameter errors are also returned in PERROR.

           To compute the correlation matrix, PCOR, use this:
           IDL> PCOR = COV * 0
           IDL> FOR i = 0, n-1 DO FOR j = 0, n-1 DO $
                PCOR(i,j) = COV(i,j)/sqrt(COV(i,i)*COV(j,j))

           If NOCOVAR is set or MPFIT terminated abnormally, then
           COVAR is set to a scalar with value !VALUES.D_NAN.

   DOF - number of degrees of freedom, computed as
             DOF = N_ELEMENTS(DEVIATES) - NFREE
         Note that this doesn't account for pegged parameters (see
         NPEGGED).

   ERRMSG - a string error or warning message is returned.

   FTOL - a nonnegative input variable. Termination occurs when both
          the actual and predicted relative reductions in the sum of
          squares are at most FTOL (and STATUS is accordingly set to
          1 or 3).  Therefore, FTOL measures the relative error
          desired in the sum of squares.  Default: 1D-10

   FUNCTARGS - A structure which contains the parameters to be passed
               to the user-supplied function specified by MYFUNCT via
               the _EXTRA mechanism.  This is the way you can pass
               additional data to your user-supplied function without
               using common blocks.

               By default, no extra parameters are passed to the
               user-supplied function.

   GTOL - a nonnegative input variable. Termination occurs when the
          cosine of the angle between fvec and any column of the
          jacobian is at most GTOL in absolute value (and STATUS is
          accordingly set to 4). Therefore, GTOL measures the
          orthogonality desired between the function vector and the
          columns of the jacobian.  Default: 1D-10

   ITERARGS - The keyword arguments to be passed to ITERPROC via the
              _EXTRA mechanism.  This should be a structure, and is
              similar in operation to FUNCTARGS.
              Default: no arguments are passed.

   ITERPROC - The name of a procedure to be called upon each NPRINT
              iteration of the MPFIT routine.  It should be declared
              in the following way:

              PRO ITERPROC, MYFUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
                PARINFO=parinfo, QUIET=quiet, ...
                ; perform custom iteration update
              END
         
              ITERPROC must either accept all three keyword
              parameters (FUNCTARGS, PARINFO and QUIET), or at least
              accept them via the _EXTRA keyword.
          
              MYFUNCT is the user-supplied function to be minimized,
              P is the current set of model parameters, ITER is the
              iteration number, and FUNCTARGS are the arguments to be
              passed to MYFUNCT.  FNORM should be the
              chi-squared value.  QUIET is set when no textual output
              should be printed.  See below for documentation of
              PARINFO.

              In implementation, ITERPROC can perform updates to the
              terminal or graphical user interface, to provide
              feedback while the fit proceeds.  If the fit is to be
              stopped for any reason, then ITERPROC should set the
              common block variable ERROR_CODE to negative value (see
              MPFIT_ERROR common block below).  In principle,
              ITERPROC should probably not modify the parameter
              values, because it may interfere with the algorithm's
              stability.  In practice it is allowed.

              Default: an internal routine is used to print the
                       parameter values.

   MAXITER - The maximum number of iterations to perform.  If the
             number is exceeded, then the STATUS value is set to 5
             and MPFIT returns.
             Default: 200 iterations

   NFEV - the number of MYFUNCT function evaluations performed.

   NITER - the number of iterations completed.

   NOCOVAR - set this keyword to prevent the calculation of the
             covariance matrix before returning (see COVAR)

   NPRINT - The frequency with which ITERPROC is called.  A value of
            1 indicates that ITERPROC is called with every iteration,
            while 2 indicates every other iteration, etc.  Note that
            several Levenberg-Marquardt attempts can be made in a
            single iteration.
            Default value: 1

   PARINFO - Provides a mechanism for more sophisticated constraints
             to be placed on parameter values.  When PARINFO is not
             passed, then it is assumed that all parameters are free
             and unconstrained.  Values in PARINFO are never 
             modified during a call to MPFIT.

             See description above for the structure of PARINFO.

             Default value:  all parameters are free and unconstrained.

   PERROR - The formal 1-sigma errors in each parameter, computed
            from the covariance matrix.  If a parameter is held
            fixed, or if it touches a boundary, then the error is
            reported as zero.

            If the fit is unweighted (i.e. no errors were given, or
            the weights were uniformly set to unity), then PERROR
            will probably not represent the true parameter
            uncertainties.  *If* you can assume that the true reduced
            chi-squared value is unity -- meaning that the fit is
            implicitly assumed to be of good quality -- then the
            estimated parameter uncertainties can be computed by
            scaling PERROR by the measured chi-squared value.

              DOF     = N_ELEMENTS(Z) - N_ELEMENTS(PARMS) ; deg of freedom
              PCERROR = PERROR * SQRT(BESTNORM / DOF)   ; scaled uncertainties

   QUIET - set this keyword when no textual output should be printed
           by MPFIT

   STATUS - an integer status code is returned.  All values other
            than zero can represent success.  It can have one of the
            following values:

	   0  improper input parameters.
         
	   1  both actual and predicted relative reductions
	      in the sum of squares are at most FTOL.
         
	   2  relative error between two consecutive iterates
	      is at most XTOL
         
	   3  conditions for STATUS = 1 and STATUS = 2 both hold.
         
	   4  the cosine of the angle between fvec and any
	      column of the jacobian is at most GTOL in
	      absolute value.
         
	   5  the maximum number of iterations has been reached
         
	   6  FTOL is too small. no further reduction in
	      the sum of squares is possible.
         
	   7  XTOL is too small. no further improvement in
	      the approximate solution x is possible.
         
	   8  GTOL is too small. fvec is orthogonal to the
	      columns of the jacobian to machine precision.

   WEIGHTS - Array of weights to be used in calculating the
             chi-squared value.  If WEIGHTS is specified then the ERR
             parameter is ignored.  The chi-squared value is computed
             as follows:

                CHISQ = TOTAL( (Z-MYFUNCT(X,Y,P))^2 * ABS(WEIGHTS) )

             Here are common values of WEIGHTS:

                1D/ERR^2 - Normal weighting (ERR is the measurement error)
                1D/Z     - Poisson weighting (counting statistics)
                1D       - Unweighted

   XTOL - a nonnegative input variable. Termination occurs when the
          relative error between two consecutive iterates is at most
          XTOL (and STATUS is accordingly set to 2 or 3).  Therefore,
          XTOL measures the relative error desired in the approximate
          solution.  Default: 1D-10

   YFIT - the best-fit model function, as returned by MYFUNCT.

 EXAMPLE:

   p  = [2.2D, -0.7D, 1.4D, 3000.D]
   x  = (dindgen(200)*0.1 - 10.) # (dblarr(200) + 1)
   y  = (dblarr(200) + 1) # (dindgen(200)*0.1 - 10.)
   zi = gauss2(x, y, p)
   sz = sqrt(zi>1)
   z  = zi + randomn(seed, 200, 200) * sz

   p0 = [0D, 0D, 1D, 10D]
   p = mpfit2dfun('GAUSS2', x, y, z, sz, p0)
   
   Generates a synthetic data set with a Gaussian peak, and Poisson
   statistical uncertainty.  Then the same function (but different
   starting parameters) is fitted to the data to see how close we can
   get.

   It is especially worthy to notice that the X and Y values are
   created as full images, so that a coordinate is attached to each
   pixel independently.  This is the format that GAUSS2 accepts, and
   the easiest for you to use in your own functions.


 COMMON BLOCKS:

   COMMON MPFIT_ERROR, ERROR_CODE

     User routines may stop the fitting process at any time by
     setting an error condition.  This condition may be set in either
     the user's model computation routine (MYFUNCT), or in the
     iteration procedure (ITERPROC).

     To stop the fitting, the above common block must be declared,
     and ERROR_CODE must be set to a negative number.  After the user
     procedure or function returns, MPFIT checks the value of this
     common block variable and exits immediately if the error
     condition has been set.  By default the value of ERROR_CODE is
     zero, indicating a successful function/procedure call.


 REFERENCES:

   MINPACK-1, Jorge More', available from netlib (www.netlib.org).
   "Optimization Software Guide," Jorge More' and Stephen Wright, 
     SIAM, *Frontiers in Applied Mathematics*, Number 14.

 MODIFICATION HISTORY:
   Written, transformed from MPFITFUN, 26 Sep 1999, CM
   Alphabetized documented keywords, 02 Oct 1999, CM
   Added example, 02 Oct 1999, CM
   Tried to clarify definitions of X and Y, 29 Oct 1999, CM
   Added QUERY keyword and query checking of MPFIT, 29 Oct 1999, CM
   Check to be sure that X, Y and Z are present, 02 Nov 1999, CM
   Documented PERROR for unweighted fits, 03 Nov 1999, CM
   Changed to ERROR_CODE for error condition, 28 Jan 2000, CM
   Copying permission terms have been liberalized, 26 Mar 2000, CM
   Propagated improvements from MPFIT, 17 Dec 2000, CM
   Documented RELSTEP field of PARINFO (!!), CM, 25 Oct 2002
   Add DOF keyword to return degrees of freedom, CM, 23 June 2003
   Minor documentation adjustment, 03 Feb 2004, CM
   Fix the example to prevent zero errorbars, 28 Mar 2005, CM

  $Id: mpfit2dfun.pro,v 1.1 2005/09/07 18:46:44 aasnes Exp $

(See /home/jbf/ct/papco/working/papco/papco_lib/fit/mpfit2dfun.pro:520)

mpfitexpr

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
   MPFITEXPR

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov
   UPDATED VERSIONs can be found on my WEB PAGE: 
      http://cow.physics.wisc.edu/~craigm/idl/idl.html

 PURPOSE:
   Perform Levenberg-Marquardt least-squares fit to arbitrary expression

 MAJOR TOPICS:
   Curve and Surface Fitting

 CALLING SEQUENCE:
   MYFUNCT = 'X*(1-X)+3'
   parms = MPFITEXPR(MYFUNCT, XVAL, YVAL, ERR, start_parms, ...)

 DESCRIPTION:

  MPFITEXPR fits a user-supplied model -- in the form of an arbitrary IDL
  expression -- to a set of user-supplied data.  MPFITEXPR calls
  MPFIT, the MINPACK-1 least-squares minimizer, to do the main
  work.

  Given the data and their uncertainties, MPFITEXPR finds the best set
  of model parameters which match the data (in a least-squares
  sense) and returns them in an array.
  
  The user must supply the following items:
   - An array of independent variable values ("X").
   - An array of "measured" *dependent* variable values ("Y").
   - An array of "measured" 1-sigma uncertainty values ("ERR").
   - A text IDL expression which computes Y given X.
   - Starting guesses for all of the parameters ("START_PARAMS").

  There are very few restrictions placed on X, Y or the expression of
  the model.  Simply put, the expression must map the "X" values into
  "Y" values given the model parameters.  The "X" values may
  represent any independent variable (not just Cartesian X), and
  indeed may be multidimensional themselves.  For example, in the
  application of image fitting, X may be a 2xN array of image
  positions.

  Some rules must be obeyed in constructing the expression.  First,
  the independent variable name *MUST* be "X" in the expression,
  regardless of the name of the variable being passed to MPFITEXPR.
  This is demonstrated in the above calling sequence, where the X
  variable passed in is called "XVAL" but the expression still refers
  to "X".  Second, parameter values must be referred to as an array
  named "P".

  If you do not pass in starting values for the model parameters,
  MPFITEXPR will attempt to determine the number of parameters you
  intend to have (it does this by looking for references to the array
  variable named "P").  When no starting values are passed in, the
  values are assumed to start at zero.

  MPFITEXPR carefully avoids passing large arrays where possible to
  improve performance.

  See below for an example of usage.

 EVALUATING EXPRESSIONS

  This source module also provides a function called MPEVALEXPR.  You
  can use this function to evaluate your expression, given a list of
  parameters.  This is one of the easier ways to compute the model
  once the best-fit parameters have been found.  Here is an example:

       YMOD = MPEVALEXPR(MYFUNCT, XVAL, PARMS)

  where MYFUNCT is the expression (see MYFUNCT below), XVAL is the
  list of "X" values, and PARMS is an array of parameters.  The
  returned array YMOD contains the expression MYFUNCT evaluated at
  each point in XVAL.

 PASSING PRIVATE DATA TO AN EXPRESSION

  The most complicated optimization problems typically involve other
  external parameters, in addition to the fitted parameters.  While
  it is extremely easy to rewrite an expression dynamically, in case
  one of the external parameters changes, the other possibility is to
  use the PRIVATE data structure.

  The user merely passes a structure to the FUNCTARGS keyword.  The
  user expression receives this value as the variable PRIVATE.
  MPFITEXPR nevers accesses this variable so it can contain any
  desired values.  Usually it would be an IDL structure so that any
  named external parameters can be passed to the expression.


 CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD

  The behavior of MPFIT can be modified with respect to each
  parameter to be fitted.  A parameter value can be fixed; simple
  boundary constraints can be imposed; limitations on the parameter
  changes can be imposed; properties of the automatic derivative can
  be modified; and parameters can be tied to one another.

  These properties are governed by the PARINFO structure, which is
  passed as a keyword parameter to MPFIT.

  PARINFO should be an array of structures, one for each parameter.
  Each parameter is associated with one element of the array, in
  numerical order.  The structure can have the following entries
  (none are required):
  
     .VALUE - the starting parameter value (but see the START_PARAMS
              parameter for more information).
  
     .FIXED - a boolean value, whether the parameter is to be held
              fixed or not.  Fixed parameters are not varied by
              MPFIT, but are passed on to MYFUNCT for evaluation.
  
     .LIMITED - a two-element boolean array.  If the first/second
                element is set, then the parameter is bounded on the
                lower/upper side.  A parameter can be bounded on both
                sides.  Both LIMITED and LIMITS must be given
                together.
  
     .LIMITS - a two-element float or double array.  Gives the
               parameter limits on the lower and upper sides,
               respectively.  Zero, one or two of these values can be
               set, depending on the values of LIMITED.  Both LIMITED
               and LIMITS must be given together.
  
     .PARNAME - a string, giving the name of the parameter.  The
                fitting code of MPFIT does not use this tag in any
                way.  However, the default ITERPROC will print the
                parameter name if available.
  
     .STEP - the step size to be used in calculating the numerical
             derivatives.  If set to zero, then the step size is
             computed automatically.  Ignored when AUTODERIVATIVE=0.
             This value is superceded by the RELSTEP value.

     .RELSTEP - the *relative* step size to be used in calculating
                the numerical derivatives.  This number is the
                fractional size of the step, compared to the
                parameter value.  This value supercedes the STEP
                setting.  If the parameter is zero, then a default
                step size is chosen.

     .MPSIDE - the sidedness of the finite difference when computing
               numerical derivatives.  This field can take four
               values:

                  0 - one-sided derivative computed automatically
                  1 - one-sided derivative (f(x+h) - f(x)  )/h
                 -1 - one-sided derivative (f(x)   - f(x-h))/h
                  2 - two-sided derivative (f(x+h) - f(x-h))/(2*h)

              Where H is the STEP parameter described above.  The
              "automatic" one-sided derivative method will chose a
              direction for the finite difference which does not
              violate any constraints.  The other methods do not
              perform this check.  The two-sided method is in
              principle more precise, but requires twice as many
              function evaluations.  Default: 0.

     .MPMINSTEP - the minimum change to be made in the parameter
                  value.  During the fitting process, the parameter
                  will be changed by multiples of this value.  The
                  actual step is computed as:

                     DELTA1 = MPMINSTEP*ROUND(DELTA0/MPMINSTEP)

                  where DELTA0 and DELTA1 are the estimated parameter
                  changes before and after this constraint is
                  applied.  Note that this constraint should be used
                  with care since it may cause non-converging,
                  oscillating solutions.

                  A value of 0 indicates no minimum.  Default: 0.

     .MPMAXSTEP - the maximum change to be made in the parameter
                  value.  During the fitting process, the parameter
                  will never be changed by more than this value.

                  A value of 0 indicates no maximum.  Default: 0.
  
     .TIED - a string expression which "ties" the parameter to other
             free or fixed parameters.  Any expression involving
             constants and the parameter array P are permitted.
             Example: if parameter 2 is always to be twice parameter
             1 then use the following: parinfo(2).tied = '2 * P(1)'.
             Since they are totally constrained, tied parameters are
             considered to be fixed; no errors are computed for them.
             [ NOTE: the PARNAME can't be used in expressions. ]
  
  Future modifications to the PARINFO structure, if any, will involve
  adding structure tags beginning with the two letters "MP".
  Therefore programmers are urged to avoid using tags starting with
  the same letters; otherwise they are free to include their own
  fields within the PARINFO structure, and they will be ignored.
  
  PARINFO Example:
  parinfo = replicate({value:0.D, fixed:0, limited:[0,0], $
                       limits:[0.D,0]}, 5)
  parinfo(0).fixed = 1
  parinfo(4).limited(0) = 1
  parinfo(4).limits(0)  = 50.D
  parinfo(*).value = [5.7D, 2.2, 500., 1.5, 2000.]
  
  A total of 5 parameters, with starting values of 5.7,
  2.2, 500, 1.5, and 2000 are given.  The first parameter
  is fixed at a value of 5.7, and the last parameter is
  constrained to be above 50.

 INPUTS:
   MYFUNCT - a string variable containing an IDL expression.  The
             only restriction is that the independent variable *must*
             be referred to as "X" and model parameters *must* be
             referred to as an array called "P".  Do not use symbol
             names beginning with the underscore, "_".

             The expression should calculate "model" Y values given
             the X values and model parameters.  Using the vector
             notation of IDL, this can be quite easy to do.  If your
             expression gets complicated, you may wish to make an IDL
             function which will improve performance and readibility.

             The resulting array should be of the same size and
             dimensions as the "measured" Y values.

   X - Array of independent variable values.

   Y - Array of "measured" dependent variable values.  Y should have
       the same data type as X.  The function MYFUNCT should map
       X->Y.

   ERR - Array of "measured" 1-sigma uncertainties.  ERR should have
         the same data type as Y.  ERR is ignored if the WEIGHTS
         keyword is specified.

   START_PARAMS - An array of starting values for each of the
                  parameters of the model.  The number of parameters
                  should be fewer than the number of measurements.
                  Also, the parameters should have the same data type
                  as the measurements (double is preferred).

                  This parameter is optional if the PARINFO keyword
                  is used (see MPFIT).  The PARINFO keyword provides
                  a mechanism to fix or constrain individual
                  parameters.  If both START_PARAMS and PARINFO are
                  passed, then the starting *value* is taken from
                  START_PARAMS, but the *constraints* are taken from
                  PARINFO.

                  If no parameters are given, then MPFITEXPR attempts
                  to determine the number of parameters by scanning
                  the expression.  Parameters determined this way are
                  initialized to zero.  This technique is not fully
                  reliable, so users are advised to pass explicit
                  parameter starting values.
 

 RETURNS:

   Returns the array of best-fit parameters.


 KEYWORD PARAMETERS:

   BESTNORM - the value of the summed, squared, weighted residuals
              for the returned parameter values, i.e. the chi-square value.

   COVAR - the covariance matrix for the set of parameters returned
           by MPFIT.  The matrix is NxN where N is the number of
           parameters.  The square root of the diagonal elements
           gives the formal 1-sigma statistical errors on the
           parameters IF errors were treated "properly" in MYFUNC.
           Parameter errors are also returned in PERROR.

           To compute the correlation matrix, PCOR, use this:
           IDL> PCOR = COV * 0
           IDL> FOR i = 0, n-1 DO FOR j = 0, n-1 DO $
                PCOR(i,j) = COV(i,j)/sqrt(COV(i,i)*COV(j,j))

           If NOCOVAR is set or MPFIT terminated abnormally, then
           COVAR is set to a scalar with value !VALUES.D_NAN.

   DOF - number of degrees of freedom, computed as
             DOF = N_ELEMENTS(DEVIATES) - NFREE
         Note that this doesn't account for pegged parameters (see
         NPEGGED).

   ERRMSG - a string error or warning message is returned.

   FTOL - a nonnegative input variable. Termination occurs when both
          the actual and predicted relative reductions in the sum of
          squares are at most FTOL (and STATUS is accordingly set to
          1 or 3).  Therefore, FTOL measures the relative error
          desired in the sum of squares.  Default: 1D-10

   FUNCTARGS - passed directly to the expression as the variable
               PRIVATE.  Any user-private data can be communicated to
               the user expression using this keyword.
               Default: PRIVATE is undefined in user expression

   GTOL - a nonnegative input variable. Termination occurs when the
          cosine of the angle between fvec and any column of the
          jacobian is at most GTOL in absolute value (and STATUS is
          accordingly set to 4). Therefore, GTOL measures the
          orthogonality desired between the function vector and the
          columns of the jacobian.  Default: 1D-10

   ITERARGS - The keyword arguments to be passed to ITERPROC via the
              _EXTRA mechanism.  This should be a structure, and is
              similar in operation to FUNCTARGS.
              Default: no arguments are passed.

   ITERPROC - The name of a procedure to be called upon each NPRINT
              iteration of the MPFIT routine.  It should be declared
              in the following way:

              PRO ITERPROC, MYFUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
                PARINFO=parinfo, QUIET=quiet, ...
                ; perform custom iteration update
              END
         
              ITERPROC must either accept all three keyword
              parameters (FUNCTARGS, PARINFO and QUIET), or at least
              accept them via the _EXTRA keyword.
          
              MYFUNCT is the user-supplied function to be minimized,
              P is the current set of model parameters, ITER is the
              iteration number, and FUNCTARGS are the arguments to be
              passed to MYFUNCT.  FNORM should be the
              chi-squared value.  QUIET is set when no textual output
              should be printed.  See below for documentation of
              PARINFO.

              In implementation, ITERPROC can perform updates to the
              terminal or graphical user interface, to provide
              feedback while the fit proceeds.  If the fit is to be
              stopped for any reason, then ITERPROC should set the
              common block variable ERROR_CODE to negative value (see
              MPFIT_ERROR common block below).  In principle,
              ITERPROC should probably not modify the parameter
              values, because it may interfere with the algorithm's
              stability.  In practice it is allowed.

              Default: an internal routine is used to print the
                       parameter values.

   MAXITER - The maximum number of iterations to perform.  If the
             number is exceeded, then the STATUS value is set to 5
             and MPFIT returns.
             Default: 200 iterations

   NFEV - the number of MYFUNCT function evaluations performed.

   NFREE - the number of free parameters in the fit.  This includes
           parameters which are not FIXED and not TIED, but it does
           include parameters which are pegged at LIMITS.

   NITER - the number of iterations completed.

   NOCOVAR - set this keyword to prevent the calculation of the
             covariance matrix before returning (see COVAR)

   NPEGGED - the number of free parameters which are pegged at a
             LIMIT.

   NPRINT - The frequency with which ITERPROC is called.  A value of
            1 indicates that ITERPROC is called with every iteration,
            while 2 indicates every other iteration, etc.  Note that
            several Levenberg-Marquardt attempts can be made in a
            single iteration.
            Default value: 1

   PARINFO - Provides a mechanism for more sophisticated constraints
             to be placed on parameter values.  When PARINFO is not
             passed, then it is assumed that all parameters are free
             and unconstrained.  Values in PARINFO are never 
             modified during a call to MPFIT.

             See description above for the structure of PARINFO.

             Default value:  all parameters are free and unconstrained.

   PERROR - The formal 1-sigma errors in each parameter, computed
            from the covariance matrix.  If a parameter is held
            fixed, or if it touches a boundary, then the error is
            reported as zero.

            If the fit is unweighted (i.e. no errors were given, or
            the weights were uniformly set to unity), then PERROR
            will probably not represent the true parameter
            uncertainties.  

            *If* you can assume that the true reduced chi-squared
            value is unity -- meaning that the fit is implicitly
            assumed to be of good quality -- then the estimated
            parameter uncertainties can be computed by scaling PERROR
            by the measured chi-squared value.

              DOF     = N_ELEMENTS(X) - N_ELEMENTS(PARMS) ; deg of freedom
              PCERROR = PERROR * SQRT(BESTNORM / DOF)   ; scaled uncertainties

   QUIET - set this keyword when no textual output should be printed
           by MPFIT

   STATUS - an integer status code is returned.  All values other
            than zero can represent success.  It can have one of the
            following values:

	   0  improper input parameters.
         
	   1  both actual and predicted relative reductions
	      in the sum of squares are at most FTOL.
         
	   2  relative error between two consecutive iterates
	      is at most XTOL
         
	   3  conditions for STATUS = 1 and STATUS = 2 both hold.
         
	   4  the cosine of the angle between fvec and any
	      column of the jacobian is at most GTOL in
	      absolute value.
         
	   5  the maximum number of iterations has been reached
         
	   6  FTOL is too small. no further reduction in
	      the sum of squares is possible.
         
	   7  XTOL is too small. no further improvement in
	      the approximate solution x is possible.
         
	   8  GTOL is too small. fvec is orthogonal to the
	      columns of the jacobian to machine precision.

   WEIGHTS - Array of weights to be used in calculating the
             chi-squared value.  If WEIGHTS is specified then the ERR
             parameter is ignored.  The chi-squared value is computed
             as follows:

                CHISQ = TOTAL( (Y-MYFUNCT(X,P))^2 * ABS(WEIGHTS) )

             Here are common values of WEIGHTS:

                1D/ERR^2 - Normal weighting (ERR is the measurement error)
                1D/Y     - Poisson weighting (counting statistics)
                1D       - Unweighted

   XTOL - a nonnegative input variable. Termination occurs when the
          relative error between two consecutive iterates is at most
          XTOL (and STATUS is accordingly set to 2 or 3).  Therefore,
          XTOL measures the relative error desired in the approximate
          solution.  Default: 1D-10

   YFIT - the best-fit model function, as returned by MYFUNCT.


 EXAMPLE:

   ; First, generate some synthetic data
   x  = dindgen(200) * 0.1 - 10.                   ; Independent variable 
   yi = gauss1(x, [2.2D, 1.4, 3000.]) + 1000       ; "Ideal" Y variable
   y  = yi + randomn(seed, 200) * sqrt(yi)         ; Measured, w/ noise
   sy = sqrt(y)                                    ; Poisson errors

   ; Now fit a Gaussian to see how well we can recover
   expr = 'P(0) + GAUSS1(X, P(1:3))'               ; fitting function
   p0 = [800.D, 1.D, 1., 500.]                     ; Initial guess
   p = mpfitexpr(expr, x, y, sy, p0)               ; Fit the expression
   print, p

   plot, x, y                                      ; Plot data
   oplot, x, mpevalexpr(expr, x, p)                ; Plot model

   Generates a synthetic data set with a Gaussian peak, and Poisson
   statistical uncertainty.  Then a model consisting of a constant
   plus Gaussian is fit to the data.


 COMMON BLOCKS:

   COMMON MPFIT_ERROR, ERROR_CODE

     User routines may stop the fitting process at any time by
     setting an error condition.  This condition may be set in either
     the user's model computation routine (MYFUNCT), or in the
     iteration procedure (ITERPROC).

     To stop the fitting, the above common block must be declared,
     and ERROR_CODE must be set to a negative number.  After the user
     procedure or function returns, MPFIT checks the value of this
     common block variable and exits immediately if the error
     condition has been set.  By default the value of ERROR_CODE is
     zero, indicating a successful function/procedure call.


 REFERENCES:

   MINPACK-1, Jorge More', available from netlib (www.netlib.org).
   "Optimization Software Guide," Jorge More' and Stephen Wright, 
     SIAM, *Frontiers in Applied Mathematics*, Number 14.

 MODIFICATION HISTORY:
   Written, Apr-Jul 1998, CM
   Added PERROR keyword, 04 Aug 1998, CM
   Added COVAR keyword, 20 Aug 1998, CM
   Added NITER output keyword, 05 Oct 1998
      D.L Windt, Bell Labs, windt@bell-labs.com;
   Added ability to return model function in YFIT, 09 Nov 1998
   Parameter values can be tied to others, 09 Nov 1998
   Added MPEVALEXPR utility function, 09 Dec 1998
   Cosmetic documentation updates, 16 Apr 1999, CM
   More cosmetic documentation updates, 14 May 1999, CM
   Made sure to update STATUS value, 25 Sep 1999, CM
   Added WEIGHTS keyword, 25 Sep 1999, CM
   Changed from handles to common blocks, 25 Sep 1999, CM
     - commons seem much cleaner and more logical in this case.
   Alphabetized documented keywords, 02 Oct 1999, CM
   Added QUERY keyword and query checking of MPFIT, 29 Oct 1999, CM
   Check to be sure that X and Y are present, 02 Nov 1999, CM
   Documented PERROR for unweighted fits, 03 Nov 1999, CM
   Removed ITERPROC='' when quiet EQ 1, 10 Jan 2000, CM
   Changed to ERROR_CODE for error condition, 28 Jan 2000, CM
   Updated the EXAMPLE, 26 Mar 2000, CM
   Copying permission terms have been liberalized, 26 Mar 2000, CM
   Propagated improvements from MPFIT, 17 Dec 2000, CM
   Correct reference to _WTS in MPFITEXPR_EVAL, 25 May 2001, CM
      (thanks to Mark Fardal)
   Added useful FUNCTARGS behavior (as yet undocumented), 04 Jul
      2002, CM
   Documented FUNCTARGS/PRIVATE behavior, 22 Jul 2002, CM
   Added NFREE and NPEGGED keywords, 13 Sep 2002, CM
   Documented RELSTEP field of PARINFO (!!), CM, 25 Oct 2002
   Add DOF keyword, CM, 31 Jul 2003
   Add FUNCTARGS keyword to MPEVALEXPR, CM 08 Aug 2003
   Minor documentation adjustment, 03 Feb 2004, CM

  $Id: mpfitexpr.pro,v 1.1 2005/09/07 18:46:44 aasnes Exp $

(See /home/jbf/ct/papco/working/papco/papco_lib/fit/mpfitexpr.pro:540)

mpfitfun

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
   MPFITFUN

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov
   UPDATED VERSIONs can be found on my WEB PAGE: 
      http://cow.physics.wisc.edu/~craigm/idl/idl.html

 PURPOSE:
   Perform Levenberg-Marquardt least-squares fit to IDL function

 MAJOR TOPICS:
   Curve and Surface Fitting

 CALLING SEQUENCE:
   parms = MPFITFUN(MYFUNCT, X, Y, ERR, start_params, ...)

 DESCRIPTION:

  MPFITFUN fits a user-supplied model -- in the form of an IDL
  function -- to a set of user-supplied data.  MPFITFUN calls
  MPFIT, the MINPACK-1 least-squares minimizer, to do the main
  work.

  Given the data and their uncertainties, MPFITFUN finds the best set
  of model parameters which match the data (in a least-squares
  sense) and returns them in an array.
  
  The user must supply the following items:
   - An array of independent variable values ("X").
   - An array of "measured" *dependent* variable values ("Y").
   - An array of "measured" 1-sigma uncertainty values ("ERR").
   - The name of an IDL function which computes Y given X ("MYFUNCT").
   - Starting guesses for all of the parameters ("START_PARAMS").

  There are very few restrictions placed on X, Y or MYFUNCT.  Simply
  put, MYFUNCT must map the "X" values into "Y" values given the
  model parameters.  The "X" values may represent any independent
  variable (not just Cartesian X), and indeed may be multidimensional
  themselves.  For example, in the application of image fitting, X
  may be a 2xN array of image positions.

  MPFITFUN carefully avoids passing large arrays where possible to
  improve performance.

  See below for an example of usage.

 USER FUNCTION

  The user must define a function which returns the model value.  For
  applications which use finite-difference derivatives -- the default
  -- the user function should be declared in the following way:

    FUNCTION MYFUNCT, X, P
     ; The independent variable is X
     ; Parameter values are passed in "P"
     YMOD = ... computed model values at X ...
     return, YMOD
    END

  The returned array YMOD must have the same dimensions and type as
  the "measured" Y values.

  User functions may also indicate a fatal error condition
  using the ERROR_CODE common block variable, as described
  below under the MPFIT_ERROR common block definition.

  See the discussion under "ANALYTIC DERIVATIVES" and AUTODERIVATIVE
  in MPFIT.PRO if you wish to compute the derivatives for yourself.
  AUTODERIVATIVE is accepted by MPFITFUN and passed directly to
  MPFIT.  The user function must accept one additional parameter, DP,
  which contains the derivative of the user function with respect to
  each parameter at each data point, as described in MPFIT.PRO.

 CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD

  The behavior of MPFIT can be modified with respect to each
  parameter to be fitted.  A parameter value can be fixed; simple
  boundary constraints can be imposed; limitations on the parameter
  changes can be imposed; properties of the automatic derivative can
  be modified; and parameters can be tied to one another.

  These properties are governed by the PARINFO structure, which is
  passed as a keyword parameter to MPFIT.

  PARINFO should be an array of structures, one for each parameter.
  Each parameter is associated with one element of the array, in
  numerical order.  The structure can have the following entries
  (none are required):
  
     .VALUE - the starting parameter value (but see the START_PARAMS
              parameter for more information).
  
     .FIXED - a boolean value, whether the parameter is to be held
              fixed or not.  Fixed parameters are not varied by
              MPFIT, but are passed on to MYFUNCT for evaluation.
  
     .LIMITED - a two-element boolean array.  If the first/second
                element is set, then the parameter is bounded on the
                lower/upper side.  A parameter can be bounded on both
                sides.  Both LIMITED and LIMITS must be given
                together.
  
     .LIMITS - a two-element float or double array.  Gives the
               parameter limits on the lower and upper sides,
               respectively.  Zero, one or two of these values can be
               set, depending on the values of LIMITED.  Both LIMITED
               and LIMITS must be given together.
  
     .PARNAME - a string, giving the name of the parameter.  The
                fitting code of MPFIT does not use this tag in any
                way.  However, the default ITERPROC will print the
                parameter name if available.
  
     .STEP - the step size to be used in calculating the numerical
             derivatives.  If set to zero, then the step size is
             computed automatically.  Ignored when AUTODERIVATIVE=0.
             This value is superceded by the RELSTEP value.

     .RELSTEP - the *relative* step size to be used in calculating
                the numerical derivatives.  This number is the
                fractional size of the step, compared to the
                parameter value.  This value supercedes the STEP
                setting.  If the parameter is zero, then a default
                step size is chosen.

     .MPSIDE - the sidedness of the finite difference when computing
               numerical derivatives.  This field can take four
               values:

                  0 - one-sided derivative computed automatically
                  1 - one-sided derivative (f(x+h) - f(x)  )/h
                 -1 - one-sided derivative (f(x)   - f(x-h))/h
                  2 - two-sided derivative (f(x+h) - f(x-h))/(2*h)

              Where H is the STEP parameter described above.  The
              "automatic" one-sided derivative method will chose a
              direction for the finite difference which does not
              violate any constraints.  The other methods do not
              perform this check.  The two-sided method is in
              principle more precise, but requires twice as many
              function evaluations.  Default: 0.

     .MPMINSTEP - the minimum change to be made in the parameter
                  value.  During the fitting process, the parameter
                  will be changed by multiples of this value.  The
                  actual step is computed as:

                     DELTA1 = MPMINSTEP*ROUND(DELTA0/MPMINSTEP)

                  where DELTA0 and DELTA1 are the estimated parameter
                  changes before and after this constraint is
                  applied.  Note that this constraint should be used
                  with care since it may cause non-converging,
                  oscillating solutions.

                  A value of 0 indicates no minimum.  Default: 0.

     .MPMAXSTEP - the maximum change to be made in the parameter
                  value.  During the fitting process, the parameter
                  will never be changed by more than this value.

                  A value of 0 indicates no maximum.  Default: 0.
  
     .TIED - a string expression which "ties" the parameter to other
             free or fixed parameters.  Any expression involving
             constants and the parameter array P are permitted.
             Example: if parameter 2 is always to be twice parameter
             1 then use the following: parinfo(2).tied = '2 * P(1)'.
             Since they are totally constrained, tied parameters are
             considered to be fixed; no errors are computed for them.
             [ NOTE: the PARNAME can't be used in expressions. ]
  
  Future modifications to the PARINFO structure, if any, will involve
  adding structure tags beginning with the two letters "MP".
  Therefore programmers are urged to avoid using tags starting with
  the same letters; otherwise they are free to include their own
  fields within the PARINFO structure, and they will be ignored.
  
  PARINFO Example:
  parinfo = replicate({value:0.D, fixed:0, limited:[0,0], $
                       limits:[0.D,0]}, 5)
  parinfo(0).fixed = 1
  parinfo(4).limited(0) = 1
  parinfo(4).limits(0)  = 50.D
  parinfo(*).value = [5.7D, 2.2, 500., 1.5, 2000.]
  
  A total of 5 parameters, with starting values of 5.7,
  2.2, 500, 1.5, and 2000 are given.  The first parameter
  is fixed at a value of 5.7, and the last parameter is
  constrained to be above 50.

 INPUTS:
   MYFUNCT - a string variable containing the name of an IDL function.
             This function computes the "model" Y values given the
             X values and model parameters, as desribed above.

   X - Array of independent variable values.

   Y - Array of "measured" dependent variable values.  Y should have
       the same data type as X.  The function MYFUNCT should map
       X->Y.

   ERR - Array of "measured" 1-sigma uncertainties.  ERR should have
         the same data type as Y.  ERR is ignored if the WEIGHTS
         keyword is specified.

   START_PARAMS - An array of starting values for each of the
                  parameters of the model.  The number of parameters
                  should be fewer than the number of measurements.
                  Also, the parameters should have the same data type
                  as the measurements (double is preferred).

                  This parameter is optional if the PARINFO keyword
                  is used (see MPFIT).  The PARINFO keyword provides
                  a mechanism to fix or constrain individual
                  parameters.  If both START_PARAMS and PARINFO are
                  passed, then the starting *value* is taken from
                  START_PARAMS, but the *constraints* are taken from
                  PARINFO.
 

 RETURNS:

   Returns the array of best-fit parameters.


 KEYWORD PARAMETERS:

   BESTNORM - the value of the summed squared residuals for the
              returned parameter values.

   COVAR - the covariance matrix for the set of parameters returned
           by MPFIT.  The matrix is NxN where N is the number of
           parameters.  The square root of the diagonal elements
           gives the formal 1-sigma statistical errors on the
           parameters IF errors were treated "properly" in MYFUNC.
           Parameter errors are also returned in PERROR.

           To compute the correlation matrix, PCOR, use this:
           IDL> PCOR = COV * 0
           IDL> FOR i = 0, n-1 DO FOR j = 0, n-1 DO $
                PCOR(i,j) = COV(i,j)/sqrt(COV(i,i)*COV(j,j))

           If NOCOVAR is set or MPFIT terminated abnormally, then
           COVAR is set to a scalar with value !VALUES.D_NAN.

   CASH - when set, the fit statistic is changed to a derivative of
          the CASH statistic.  The model function must be strictly
          positive.

   DOF - number of degrees of freedom, computed as
             DOF = N_ELEMENTS(DEVIATES) - NFREE
         Note that this doesn't account for pegged parameters (see
         NPEGGED).

   ERRMSG - a string error or warning message is returned.

   FTOL - a nonnegative input variable. Termination occurs when both
          the actual and predicted relative reductions in the sum of
          squares are at most FTOL (and STATUS is accordingly set to
          1 or 3).  Therefore, FTOL measures the relative error
          desired in the sum of squares.  Default: 1D-10

   FUNCTARGS - A structure which contains the parameters to be passed
               to the user-supplied function specified by MYFUNCT via
               the _EXTRA mechanism.  This is the way you can pass
               additional data to your user-supplied function without
               using common blocks.

               By default, no extra parameters are passed to the
               user-supplied function.

   GTOL - a nonnegative input variable. Termination occurs when the
          cosine of the angle between fvec and any column of the
          jacobian is at most GTOL in absolute value (and STATUS is
          accordingly set to 4). Therefore, GTOL measures the
          orthogonality desired between the function vector and the
          columns of the jacobian.  Default: 1D-10

   ITERARGS - The keyword arguments to be passed to ITERPROC via the
              _EXTRA mechanism.  This should be a structure, and is
              similar in operation to FUNCTARGS.
              Default: no arguments are passed.

   ITERPROC - The name of a procedure to be called upon each NPRINT
              iteration of the MPFIT routine.  It should be declared
              in the following way:

              PRO ITERPROC, MYFUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
                PARINFO=parinfo, QUIET=quiet, ...
                ; perform custom iteration update
              END
         
              ITERPROC must either accept all three keyword
              parameters (FUNCTARGS, PARINFO and QUIET), or at least
              accept them via the _EXTRA keyword.
          
              MYFUNCT is the user-supplied function to be minimized,
              P is the current set of model parameters, ITER is the
              iteration number, and FUNCTARGS are the arguments to be
              passed to MYFUNCT.  FNORM should be the
              chi-squared value.  QUIET is set when no textual output
              should be printed.  See below for documentation of
              PARINFO.

              In implementation, ITERPROC can perform updates to the
              terminal or graphical user interface, to provide
              feedback while the fit proceeds.  If the fit is to be
              stopped for any reason, then ITERPROC should set the
              common block variable ERROR_CODE to negative value (see
              MPFIT_ERROR common block below).  In principle,
              ITERPROC should probably not modify the parameter
              values, because it may interfere with the algorithm's
              stability.  In practice it is allowed.

              Default: an internal routine is used to print the
                       parameter values.

   MAXITER - The maximum number of iterations to perform.  If the
             number is exceeded, then the STATUS value is set to 5
             and MPFIT returns.
             Default: 200 iterations

   NFEV - the number of MYFUNCT function evaluations performed.

   NFREE - the number of free parameters in the fit.  This includes
           parameters which are not FIXED and not TIED, but it does
           include parameters which are pegged at LIMITS.

   NITER - the number of iterations completed.

   NOCOVAR - set this keyword to prevent the calculation of the
             covariance matrix before returning (see COVAR)

   NPEGGED - the number of free parameters which are pegged at a
             LIMIT.

   NPRINT - The frequency with which ITERPROC is called.  A value of
            1 indicates that ITERPROC is called with every iteration,
            while 2 indicates every other iteration, etc.  Note that
            several Levenberg-Marquardt attempts can be made in a
            single iteration.
            Default value: 1

   PARINFO - Provides a mechanism for more sophisticated constraints
             to be placed on parameter values.  When PARINFO is not
             passed, then it is assumed that all parameters are free
             and unconstrained.  Values in PARINFO are never 
             modified during a call to MPFIT.

             See description above for the structure of PARINFO.

             Default value:  all parameters are free and unconstrained.

   PERROR - The formal 1-sigma errors in each parameter, computed
            from the covariance matrix.  If a parameter is held
            fixed, or if it touches a boundary, then the error is
            reported as zero.

            If the fit is unweighted (i.e. no errors were given, or
            the weights were uniformly set to unity), then PERROR
            will probably not represent the true parameter
            uncertainties.  

            *If* you can assume that the true reduced chi-squared
            value is unity -- meaning that the fit is implicitly
            assumed to be of good quality -- then the estimated
            parameter uncertainties can be computed by scaling PERROR
            by the measured chi-squared value.

              DOF     = N_ELEMENTS(X) - N_ELEMENTS(PARMS) ; deg of freedom
              PCERROR = PERROR * SQRT(BESTNORM / DOF)   ; scaled uncertainties

   QUIET - set this keyword when no textual output should be printed
           by MPFIT

   STATUS - an integer status code is returned.  All values other
            than zero can represent success.  It can have one of the
            following values:

	   0  improper input parameters.
         
	   1  both actual and predicted relative reductions
	      in the sum of squares are at most FTOL.
         
	   2  relative error between two consecutive iterates
	      is at most XTOL
         
	   3  conditions for STATUS = 1 and STATUS = 2 both hold.
         
	   4  the cosine of the angle between fvec and any
	      column of the jacobian is at most GTOL in
	      absolute value.
         
	   5  the maximum number of iterations has been reached
         
	   6  FTOL is too small. no further reduction in
	      the sum of squares is possible.
         
	   7  XTOL is too small. no further improvement in
	      the approximate solution x is possible.
         
	   8  GTOL is too small. fvec is orthogonal to the
	      columns of the jacobian to machine precision.

   WEIGHTS - Array of weights to be used in calculating the
             chi-squared value.  If WEIGHTS is specified then the ERR
             parameter is ignored.  The chi-squared value is computed
             as follows:

                CHISQ = TOTAL( (Y-MYFUNCT(X,P))^2 * ABS(WEIGHTS) )

             Here are common values of WEIGHTS:

                1D/ERR^2 - Normal weighting (ERR is the measurement error)
                1D/Y     - Poisson weighting (counting statistics)
                1D       - Unweighted

   XTOL - a nonnegative input variable. Termination occurs when the
          relative error between two consecutive iterates is at most
          XTOL (and STATUS is accordingly set to 2 or 3).  Therefore,
          XTOL measures the relative error desired in the approximate
          solution.  Default: 1D-10

   YFIT - the best-fit model function, as returned by MYFUNCT.

   
 EXAMPLE:

   ; First, generate some synthetic data
   npts = 200
   x  = dindgen(npts) * 0.1 - 10.                  ; Independent variable 
   yi = gauss1(x, [2.2D, 1.4, 3000.])              ; "Ideal" Y variable
   y  = yi + randomn(seed, npts) * sqrt(1000. + yi); Measured, w/ noise
   sy = sqrt(1000.D + y)                           ; Poisson errors

   ; Now fit a Gaussian to see how well we can recover
   p0 = [1.D, 1., 1000.]                   ; Initial guess (cent, width, area)
   p = mpfitfun('GAUSS1', x, y, sy, p0)    ; Fit a function
   print, p

   Generates a synthetic data set with a Gaussian peak, and Poisson
   statistical uncertainty.  Then the same function is fitted to the
   data (with different starting parameters) to see how close we can
   get.


 COMMON BLOCKS:

   COMMON MPFIT_ERROR, ERROR_CODE

     User routines may stop the fitting process at any time by
     setting an error condition.  This condition may be set in either
     the user's model computation routine (MYFUNCT), or in the
     iteration procedure (ITERPROC).

     To stop the fitting, the above common block must be declared,
     and ERROR_CODE must be set to a negative number.  After the user
     procedure or function returns, MPFIT checks the value of this
     common block variable and exits immediately if the error
     condition has been set.  By default the value of ERROR_CODE is
     zero, indicating a successful function/procedure call.

 REFERENCES:

   MINPACK-1, Jorge More', available from netlib (www.netlib.org).
   "Optimization Software Guide," Jorge More' and Stephen Wright, 
     SIAM, *Frontiers in Applied Mathematics*, Number 14.

 MODIFICATION HISTORY:
   Written, Apr-Jul 1998, CM
   Added PERROR keyword, 04 Aug 1998, CM
   Added COVAR keyword, 20 Aug 1998, CM
   Added ITER output keyword, 05 Oct 1998
      D.L Windt, Bell Labs, windt@bell-labs.com;
   Added ability to return model function in YFIT, 09 Nov 1998
   Analytical derivatives allowed via AUTODERIVATIVE keyword, 09 Nov 1998
   Parameter values can be tied to others, 09 Nov 1998
   Cosmetic documentation updates, 16 Apr 1999, CM
   More cosmetic documentation updates, 14 May 1999, CM
   Made sure to update STATUS, 25 Sep 1999, CM
   Added WEIGHTS keyword, 25 Sep 1999, CM
   Changed from handles to common blocks, 25 Sep 1999, CM
     - commons seem much cleaner and more logical in this case.
   Alphabetized documented keywords, 02 Oct 1999, CM
   Added QUERY keyword and query checking of MPFIT, 29 Oct 1999, CM
   Corrected EXAMPLE (offset of 1000), 30 Oct 1999, CM
   Check to be sure that X and Y are present, 02 Nov 1999, CM
   Documented PERROR for unweighted fits, 03 Nov 1999, CM
   Changed to ERROR_CODE for error condition, 28 Jan 2000, CM
   Corrected errors in EXAMPLE, 26 Mar 2000, CM
   Copying permission terms have been liberalized, 26 Mar 2000, CM
   Propagated improvements from MPFIT, 17 Dec 2000, CM
   Added CASH statistic, 10 Jan 2001
   Added NFREE and NPEGGED keywords, 11 Sep 2002, CM
   Documented RELSTEP field of PARINFO (!!), CM, 25 Oct 2002
   Add DOF keyword to return degrees of freedom, CM, 23 June 2003

  $Id: mpfitfun.pro,v 1.2 2005/09/07 18:46:44 aasnes Exp $

(See /home/jbf/ct/papco/working/papco/papco_lib/fit/mpfitfun.pro:503)

os_family

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     :	SOHO - CDS

 Name        :	OS_FAMILY()

 Purpose     :	Return current operating system as in !VERSION.OS_FAMILY

 Category    :	Utilities, Operating_system

 Explanation :	Return the current operating system as in !VERSION.OS_FAMILY

	OS_FAMILY is assumed to be 'unix' if !VERSION.OS is not 'windows',
		'MacOS' or 'vms'

	To make procedures from IDL V4.0 and later compatibile with earlier
	versions of IDL, replace calls to !VERSION.OS_FAMILY with OS_FAMILY().

	Can also be used to replace calls to !VERSION.OS if care is taken with
	the change of case between 'Windows', which is what this routine
	returns, and 'windows' which is what !VERSION.OS returned in versions
	of IDL prior to 4.0.

 Syntax      :	Result = OS_FAMILY()

 Examples    :	IF OS_FAMILY() EQ 'vms' THEN ...

 Inputs      :	None.

 Opt. Inputs :	None.

 Outputs     :	The result of the function is a scalar string containing one of
		the four values 'Windows','MacOS','vms' or 'unix'

 Opt. Outputs:	None.

 Keywords    :	None.

 Calls       :	TAG_EXISTS

 Common      :	None.

 Restrictions:	None.

 Side effects:	None.

 Prev. Hist. :	Written,  W. Landsman

 History     :	Version 1, 29-Aug-1995, William Thompson, GSFC
			Incorporated into CDS library

 Contact     :	WTHOMPSON

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/system/os_family.pro:53)

panelset

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: panelset

 DESCRIPTION: 
       used by papco modules to set !p.position before drawing the panel.

 INPUTS:       
	 panel:  panel vector passed from PAPCO. Sets the
               position and height of the panel.
               panel(0): number of the panel (numbered
                         from 0 from the bottom of the  page up
               panel(1): total number of panels
               panel(2): height of a panel in multiples of panel height 
                         given by viewport divided by number of panels. 
               Sets the global IDL system variable !p.position

 KEYWORDS:
	TOTAL, keyw, if set, !p.position is set to the normal coords
               of the total area of the panel, not just the plot area.
      AXIS, float, if set leave room at bottom of panel for this many lines
      TITLE, float, if set leave room at top for a title, in normalized units, 100%=page length.

 SIDE EFFECTS:
      Sets the global IDL system variable !p.position

 CALLING EXAMPLE:
      panelset, panel
         
 MODIFICATION HISTORY:       
      April 1998, written by R. Friedel
      May 2005, added absolute limits on areas around plot

(See /home/jbf/ct/papco/working/papco/papco_lib/panelset.pro:32)

papco

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco

 DESCRIPTION:
   The main - program. Initialize the widgets-hierarchy, set the
   COMMON PLOT_COMPOSER, widgetdata, read the defaults, call XManager

 INPUTS:           none

 KEYWORDS:
   GROUP       You may specify a GROUP_LEADER here.
   PRODUCT     If set, papco is loaded with this Product at startup
   BATCH       If set, also needs a valid PRODUCT name. papco is
               started, the PRODUCT is loaded, and then the BATCH
               is run and produces postcript output files.
   DRAW        if set and PRODUCT set that product is drawn on startup
   SET_ONLY    sets up structures and common blocks only. Used for working
               in the "PAPCO environment"  without starting the widget.
   _EXTRA      collects all other keywors in a structure. Used to
               overwrite defaults in widgetdata, see NOTE below.
   INFO        prints out information for this routine
   HEADLESS    if set, force headless mode
   RUNTIMEVM   if set, force runtime vm mode (for testing)

 CALLING SEQUENCE:
   papco, [optional keywords]
   To run papco, you must run @papco_setup or @papco_startup first !

 A NOTE ON EXTRA KEYWORDS:
   Undeclared keywords implicitly set widgetData.default and widgetData tag
   values.  This supports batch functions, and other functions.  Refer to
   the widgetData structure for these options, and this should be used with
   caution.  Also we (the papco developers) warn that some of these keywords may
   not work in future versions.


 MODIFICATION HISTORY:
   written august 1995, Andreas Keese
   november 1995, modified by R.Friedel
   september 1997, modified by Torsten Heise
   February 1998, modified by R.Friedel
   January 2001, modified by R.Friedel - updated command line features

(See /home/jbf/ct/papco/working/papco/papco/papco.pro:815)

papco_2D_interplol

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_2D_interplol

 DESCRIPTION:  designed for color spec plots to make nicer looking
               spectra plots. Takes low resolution zmat (few energy channels)
               and expands this to more channels to get smooth,continuous
               spectra.
               Further options aloow smoothing / filling in along
               time too. All is done preserving nodata flags!

 KEYWORDS:     NODATA  - bad data flag, default is -99.0
               YCH_NUM - new number of y-channels: 0 does nothing

 INPUTS:       zmat - spec array zmat(time, ch)
               time - time array, start/stop time(time, 2)
               yarr - channel assignments yarr(ch,2)

 OUTPUT:       updated interpolated zmat, yarr, time

 HISTORY:      written Febriary 2004, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:1859)

papco_2D_interpol

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_2D_interpol

 DESCRIPTION:  designed for color spec plots to make nicer looking
               spectra plots. Takes low resolution zmat (few energy channels)
               and expands this to more channels to get smooth,continuous
               spectra.
               Further options aloow smoothing / filling in along
               time too. All is done preserving nodata flags!

 KEYWORDS:     NODATA  - bad data flag, default is -99.0
               YCH_NUM - new number of y-channels: 0 does nothing

 INPUTS:       zmat - spec array zmat(time, ch)
               time - time array, start/stop time(time, 2)
               yarr - channel assignments yarr(ch,2)

 OUTPUT:       updated interpolated zmat, yarr, time

 HISTORY:      written February 2004, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_math.pro:722)

papco_accessdir

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_accessdir, path

 DESCRIPTION:  an operating system independent routine to check if a given
               directory path can be written to.

 INPUTS:       path       string which contains the path to be checked

 OUTPUT:       Function returns:
               1   directory pointed to in path can be written to
               0   otherwise

 KEYWORDS:     none

 HISTORY:      written May 1998, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:189)

papco_addpath

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_addpath, path, new

 DESCRIPTION:  an operating system independent routine to add a path to
               an exisiting path. New is in UNIX format.

 INPUTS:       path       string which contains the original path
               new        string which contains path to be added

 OUTPUT:       Function returns the new path

 KEYWORDS:     none

 HISTORY:      written Octoberr 1997, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:339)

papco_addToRecentFiles

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_addToRecentFiles
 DESCRIPTION:  adds filename to the convenient list of recently used files.
 INPUTS:   
   FILENAME, string, the filename to add.
 KEYWORDS: none
 SIDE EFFECTS: modifies widgetData.default.recentPapcoFiles, and the item will appear in the main widget->file->open recent menu.
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.42 $
 CURATOR: Jeremy Faden
 HISTORY:  
   26-Oct-2005, 1.23, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco/papco_files.pro:148)

papco_addUserModule

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_addUserModule

 DESCRIPTION:
      Adds user module to the list.

 INPUTS:
      none

 KEYWORDS:
  EDIT     Edit user module instead of add.

 OUTPUT:
      Modifies the common variable userModules.

 MODIFICATION HISTORY:
     written July 1997, Haje Korth

(See /home/jbf/ct/papco/working/papco/papco/papco_configure.pro:581)

papco_addUserModule_event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_addUserModule_event

 DESCRIPTION:
      Event handler for papco_addUserModule.pro

 INPUTS:
      event     Event

 KEYWORDS:
  none

 MODIFICATION HISTORY:
     written July 1997, Haje Korth

(See /home/jbf/ct/papco/working/papco/papco/papco_configure.pro:656)

papco_add_mag

 [Previous Routine] [Next Routine] [List of Routines] 
  NAME:        papco_add_mag

  DESCRIPTION: adds magnetic field model coords to a given ephemeris
               file - keeps adding structures. 
               uses get_mag_onera - onera fortran library

  INPUT:       cor_type  -  coordinate type of input ephemeris
               cor_sys   -  coordinate system of input ephemeris
               control   -  the module's control structure

  OUTPUT:      

  DATE:        July 2003

  AUTHOR:      R. Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_add_mag.pro:17)

papco_add_module_path

 [Previous Routine] [Next Routine] [List of Routines] 
 function:     papco_add_module_path, path_name

 description:  returns the entry needed in the papco_include_modules.pro
               file to extend the idl search path by the path_name

 inputs:       path_name

 output:       the extend path string

 keywords:     none.

 author:       R. Friedel, November 1997

 changes:      Jeremy Faden, September 2004
               use papco_add_to_path, which only adds to the path if the
                 directory is not on the path already.  This allows the
                 use (hopefully) of IDL's .reset command. .reset does not
                 clear the path.

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:842)

papco_add_panel

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: PAPCO_ADD_PANEL
 DESCRIPTION:  method for adding a panel to papco.  The panel is added to end of the list of plots.
 INPUTS:   
   PANELWIDGETDATA, type, description
 KEYWORDS:
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 NOTES: makes a copy of the contents of use_ptr1.
 CVSTAG: 
   $Name:  $
   $Revision: 1.91 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco/papco.pro:574)

papco_Add_Plot

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_Add_Plot, panel_name, panelKind, $
			    INITIALPLOTINFO=initialPlotInfo

 DESCRIPTION:
      Used to add a new plot. This procedure is called from the main
	event-routine, papco_Event.

 INPUTS:
      panel_name	a string
			this is the name of the panel-editor-function.
			will be used in the 'CALL_FUNCTION'- command.

      panel_kind	a string
			this is the panel-kind.

 KEYWORDS:
      INITIALPLOTINFO a plotInfo-structure
			usually, this routine creates the initial plotInfo-
			structure by calling 'papco_getPlotInfoStruct()'.
			If you want to use other initial settings, you may
			pass a plotInfo-structure to this procedure by
			using this keyword.

 CALLING SEQUENCE:
      papco_Add_Plot, panel_name, panelKind
	;-----
      defaults=papco_getPlotInfoStruct()
      defaults.typeVector(3)=15
      papco_Add_Plot, panel_name, panelKind, initialPlotInfo=defaults

 MODIFICATION HISTORY:
      september 1995, written by A.Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_plotedit.pro:588)

papco_annotate[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_annotate

 DESCRIPTION:
	changed version of the IDL-supplied procedure ANNOTATE, to
      work with PAPCO. Some minor bug fixes.

 INPUTS:
	none

 KEYWORDS:
 	Same as original annotate.pro plus
      EXIT            papco: only active if LOAD_FILE is set. Draw
                      annotation from file only, then exit
      PAPCO_PS        papco: only active if LOAD_FILE is set. Draw
                      annotation from file to postscript only, then exit

 CALLING SEQUENCE:
	papco_annotate

 MODIFICATION HISTORY:
      October 1998, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_annotate.pro:24)

papco_annotate[2]

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
	PAPCO_ANNOTATE

 PURPOSE:
	This procedure is a general purpose drawing program/widget to
	annotate displays. Drawing objects include text, lines, arrows,
	polygons, rectangles, circles, and ellipses.

 CATEGORY:
	Widgets.  Will also work with plain windows.

 CALLING SEQUENCE:
	PAPCO_ANNOTATE

 INPUTS:
	No required inputs.

 KEYWORD PARAMETERS:
	COLOR_INDICES:	an array of color indices from which the user
			can choose colors. For example, to allow the user
			to choose 10 colors, spread evenly over the
			available indices, set the keyword as folows:
			COLOR_INDICES = INDGEN(10) * (!D.N_COLORS-1) / 9
	DRAWABLE:	the widget ID of the draw widget for the annotations.
			This is mutually exclusive with WINDOW.
	LOAD_FILE:	the name of an annotation format file to load after
			initialization.
	TEK_COLORS:	if set, the Tektronix color table is loaded
			starting at color index TEK_COLORS(0), with
			TEK_COLORS(1) color indices. The Tektronix color
			table contains up to 32 distinct colors suitable
			for graphics.
	WINDOW:		the window index number of the window to receive the
			annotations.
       EXIT:           papco: only active if LOAD_FILE is set. Draw
                       annotation from file only, then exit
       PAPCO_PS        papco: only active if LOAD_FILE is set. Draw
                       annotation from file to postscript only, then exit
    BATCH: batch mode simply draws the loaded file, so don't bother with the interactive gui.
    INLINE: draw the annotations by simply calling object draw commands and assuming the
       device is properly configured.

 OUTPUTS:
	This procedure has no explicit outputs. Menu choices exist to
	write TIFF, GIF, or PostScript bitmap files. Encapsulated
	or standalone PostScript files may also be created.

 SIDE EFFECTS:
	Annotations are made in the designated window or draw widget.

 RESTRICTIONS:
	This is a simple drawing program.

 PROCEDURE:
	If neither TEK_COLORS or COLOR_INDICES are specified, the default
	is to load 10 colors, evenly distributed over those available.

	If neither WINDOW or DRAWABLE are specified, the current window
	is used.

 EXAMPLE:
	TVSCL, HANNING(300,200)	;Output an image in the current window
	PAPCO_ANNOTATE		;Annotate it

 MODIFICATION HISTORY:
	DMS, RSI, July, 1993.  Original version.

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_annotate.pro:1157)

papco_autorange

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      papco_autorange

 DESCRIPTION:
	Attempts to establish the range of data values in an array.
      In order to discriminate against data glitches
      (uncharacteristically low or high values) a top and bottom %
      of data points can be excluded from this process. This also maximizes
      the use of the color range.
      The minimum for the log range is one decade!

 INPUTS:
	arr       the array to be scaled
      
 OUTPUTS:
      min,max   the max and min values for arr

 KEYWORDS:
	LOG       set for logarythmic scaling
      NODATA    set to the nodata flag(s) of arr - can be an array
      EXCLUDE   set to % of top and bottom data points to exclude
      ROBUST_AV normalize all data with respect to a ROBUST_AV per channel
      VERBOSE   set to give diagnostic output

 CALLING SEQUENCE:
	papco_autorange,arr,min,max

 MODIFICATION HISTORY:
     written April 1998, Reiner Friedel
     modified, March 2007, Arne Aasnes
       updated algorithm to exclude data (using sort) and allow
       separate lower and upper limits

(See /home/jbf/ct/papco/working/papco/papco_lib/autoscaling/papco_autorange.pro:34)

papco_batch

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_batch, fName, PREVIEW=PREVIEW

 DESCRIPTION:
      This procedure does the batch-plotting of panel-plots.
  When doing a batch-plot, the currently entered panel-plots are drawn
  for a list containing orbits and/or time-ranges.
  This list is read from a file. The file has this format:
  -> empty lines or lines starting with '#' are ignored
  -> it contains one orbit and/or time-description per line
  -> a line has this format (in BNF) :
        line=orbit [, time-range] | time-range
        orbit = aNumber
        time-range= t90-time "-" t90-time
        t90-time=date [" " time]
        date = doy"/"year | day_om"."month"."year | month"/"day_om"/"year
        (doy=aNumber, year=aNumber, day_om=aNumber, month=aNumber)
        time = hour":"minutes[":"seconds]
        (time=aNumber, minutes=aNumber, seconds=aNumber)

 INPUTS:
      fName    the file-name including the path

 KEYWORDS:
      PREVIEW  if specified, the output goes to the screen. If not specified,
           the output goes to a file whose name is derived from the
           standard-filename-template.
         =2    output digital mode
      QUIET    if set, this routine puts out no x-windows
      dryrun   if set, perform a quick dry run to check for errors
      log      papco_logger

 MODIFICATION HISTORY:
      september 1995, written by A.Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_batch.pro:89)

papco_canYouPlot

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      FUNCTION papco_canYouPlot

 DESCRIPTION:
      check, if all data needed to plot is specified
      For plotting, those data are needed:
	    an orbit-number
	    at least on plot-description

	If a plot can not be done, a message-box tells the user about this

 INPUTS:
	none

 KEYWORDS:
 	none

 OUTPUT:
      a Boolean Integer (0 or 1)
	1	  If a plot can be done
	0	  if a plot can't be done

 CALLING SEQUENCE:
	IF papco_CanYouPLot() THEN $
	   ; do the plot

 MODIFICATION HISTORY:
     written august and september 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_draw.pro:129)

papco_cdf_cracker[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 some useful cdf utilites, like to find out variables, attributes,
 etc. in CDF files. Needs CDF V 2.6 linked into IDL.

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_cdf_cracker.pro:4)

papco_cdf_cracker[2]

 [Previous Routine] [Next Routine] [List of Routines] 
  NAME:        papco_cdf_cracker

  DESCRIPTION: Return information about variables and attributes in
               cdf file

  INPUT:       id  - CDF file id returned by cdf_open

  KEYWORDS:    GLOBAL_ATTRIB  - returns all global attributes of cdf file
               VAR_ATTRIB     - returns all variable attribturs of cdf file
               ZVARIABLES     - returns list of zVariables 
               RVARIABLES     - returns list of rVariables 
               GET_VAR_ATTRIB - returns all variable attributes of
                                this variable
               VERBOSE        - print results of enquiery to screen


  OUTPUT:      none (places data into variables passed by keywords)

  DATE:        October 2000

  AUTOR:       R. Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_cdf_cracker.pro:29)

papco_change_startup

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_change_startup

 DESCRIPTION:
      Changes papco_startup file to restore or compile on startup
      depending on how the env. variable papco_STARTUP_MODE is set

 INPUTS:
      none

 KEYWORDS:
      none

 MODIFICATION HISTORY:
      written July 1997, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_configure.pro:138)

papco_channel_labels

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:    papco_channel_labels, e_arr

 DESCRIPTION:  performs time averageing of data onto fixed time intervals

 KEYWORDS:     

 INPUTS:       

 OUTPUT:       string array of lables.

 HISTORY:      written February 2007, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:2795)

papco_checkdirname

 [Previous Routine] [Next Routine] [List of Routines] 
 function:     papco_checkdirname, dir

 description:  checks if dir path has vaild ending

 inputs:       dir : the name of the dir to be checked

 output:       valid dir

 author:       R. Friedel, November 1997

 changes:      Jan 1999. modified to handle multiple directories

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:137)

papco_check_data_env

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:     papco_check_data_env

 DESCRIPTION:  a routine to check if a given environmental variable
               exists and points to a valid directory.

 INPUTS:       
    env, string, environmental variable name

 RETURNS:   
    boolean,  1 indicates environmental variable is set,   0   otherwise

 KEYWORDS:    
   NODIR, boolean, do not perform check for existence of directory
   URL, boolean, constrain result to URL.

 OUTPUT KEYWORDS:
   PATH, string, returns the env variable

 HISTORY:      written September 1999, Reiner Friedel
               updated to look for $PAPCO_DLNK in paths, January
               also looks for $PAPCO_USER, jbf--for PUM modules
                 2003, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:383)

papco_check_plotinfos

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      papco_check_plotinfos

 DESCRIPTION:
	check whether the entry in widgetData.old_plotinfos(plotNr) is the same
      as that in widgetData.plotinfos(plotNr). Returns true (1) if they
      are the same.

 INPUTS:
	plotNr  -  the number of the plot intry to be checked.

 KEYWORDS:
	none

 CALLING SEQUENCE:
	result=papco_check_plotinfos(plotNr)

 MODIFICATION HISTORY:
     written May 1998, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_draw.pro:639)

papco_check_window_device

 [Previous Routine] [Next Routine] [List of Routines] 
 function:     papco_check_window_device

 description:

 inputs:

 output:

 author:       R. Friedel, June 1998

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:1043)

papco_chmod

 [Previous Routine] [Next Routine] [List of Routines] 
 Procedure:    papco_chmod

 description:  Changes file permissions only for UNIX.


 inputs:       String containing requested permission changes, eg 'g+rw'

 output:       None.

 keywords:     None.

 author:       J. Roeder, November 2003

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:1286)

papco_cleanup

 [Previous Routine] [Next Routine] [List of Routines] 
 Procedure:    papco_cleanup

 description:  Called on exiting the PAPCO main window. Used to delete
               temporary files etc

 inputs:       none

 output:       none

 keywords:     none.

 author:       R. Friedel, October 1997

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:1319)

papco_Clear_Drawing

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_Clear_Drawing

 DESCRIPTION:
	The drawing-widget, widgetData.dw_draw is erased
	Additionally, the variables controlling the plots-drawn-info
	and the display of the timerange are reset.

 INPUTS:
	none

 KEYWORDS:
 	none

 CALLING SEQUENCE:
	papco_Clear_Drawing

 MODIFICATION HISTORY:
     written august and september 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_draw.pro:77)

papco_clear_panel

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      papco_clear_panel

 DESCRIPTION:
	Clears the position indicated by panelVector by filling with
      background color.

 INPUTS:
	panelVector  -  position of the panel

 KEYWORDS:
	RIGHT_SIDE   - only clear the right side label area

 CALLING SEQUENCE:
	result=papco_clear_panel,panelVector

 MODIFICATION HISTORY:
      written April 1998, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_draw.pro:683)

papco_colorbar[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_colorbar

 PURPOSE:
 This IDL-procedure plots a papco_colorbar on the right side of the screen
	
 CATEGORY:
       Plotting (Color)

 CALLING SEQUENCE:

       papco_colorbar,ZMIN,ZMAX,relbit [,azimbit,ztitle]

 INPUTS:     in accordance with PLOT_CLR
             ZMIN     float bottom value of color axis
             ZMAX     float top value of color axis
             relbit    =0: logarithmic z-scaling (particle fluxes)
                       =1: linear z-scaling      (relative intensities[%])
                       =2: linear z-scaling      (particle fluxes)
                       =3: linear z-scaling      (azimuth angles [deg])
                      according ytitles are drawn

 OPTIONAL INPUTS:
             azimbit   =0: color values ranging from 2-255(def)
                       =1: color values ranging from 1-223
	
 PROCEDURE:  The color sequence is (and must be) linear, even for
	      logarithmic z-scaling.
             Axes are drawn using the AXIS- and LOGAXIS-procedures.
             Viewport and data-screen relation are restored at the end.

 MODIFICATION HISTORY:
       written jan 92 M.Fraenz,N.Krupp

(See /home/jbf/ct/papco/working/papco/papco_lib/color_plot/papco_colorbar.pro:34)

papco_colorbar[3]

 [Previous Routine] [Next Routine] [List of Routines] 
                   linear and logarithmic scaling)

(See /home/jbf/ct/papco/working/papco/papco_lib/color_plot/papco_colorbar.pro:75)

papco_colorbar_label

 [Previous Routine] [Next Routine] [List of Routines] 
  NAME:        papco_colorbar_label

  DESCRIPTION: Puts a label to mark a panel to the right of the panel.
               calculates position form system variable !p.position
               Does "correct" new line with enough space
               Can attempt to autoscale label into available space.

  INPUT:    
     PANEL, intarr[3], vector for position of panel
     LABEL, string, string to be used as label

  KEYWORDS     ROT90 : rotates output string by 90 degrees, used for plots
                       with papco_colorbar
               POS   : 0 (default) aligned with top of panel
                       1           aligned with bottom of panel
               AUTO  : 0 no scaling
                       1 attempt to scale into space.
               _extra: extra keywords to be passed to xyouts procedure

  OUTPUT:      plots on current plotting device

  DATE:        August 1995

  AUTOR:       R. Friedel

  SIDEEFFECTS: -

  MODIFICATIONS: Jan 1997 -  made charsize controlled by !P.CHARSIZE
                             system variable R. Friedel
                 Oct 1997 -  Better New Line spacing added
                 Jan 1999 -  Keyword POS added
                 Feb 1999 -  Keyword AUTO added.

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_panel_label.pro:785)

papco_color_bar[2]

 [Previous Routine] [Next Routine] [List of Routines] 
                   linear and logarithmic scaling)

(See /home/jbf/ct/papco/working/papco/papco_lib/color_plot/papco_color_bar.pro:138)

papco_compact_user_mod_list

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
     PRO papco_compact_user_mod_list

 DESCRIPTION:
     Removes empty positions in between the components of
     the userModules variable.

 INPUTS:
     none

 KEYWORDS:
     none

 OUTPUT:
     Modifies the userModules variable.

 MODIFICATION HISTORY:
     written July 1997, Haje Korth

(See /home/jbf/ct/papco/working/papco/papco/papco_configure.pro:762)

papco_compare_struct

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_compare_struct

 DESCRIPTION:  checks if two structures have the same conents.
               structures must be of the same type!

 KEYWORDS:     none

 INPUTS:       struct_1, struct_2

 RETURNS:      boolean, 0 = the same, 1 = not the same

 HISTORY:      written May 2003, Reiner Friedel
               recurse for nested structures, Jeremy Faden, July 2005

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:1106)

papco_configure

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_configure

 DESCRIPTION:
      Creates papco_include_modules.pro for papco startup.
      Makes PAPCO configuration widget.

 INPUTS:
      none

 KEYWORDS:
      RECONFIG   disables some parts of widget for reconfiguration work

 MODIFICATION HISTORY:
      written July 1997, Haje Korth
      modified August 1999, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_configure.pro:885)

papco_configure_addins_event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_configure_addins_event

 DESCRIPTION:
      event handler called by XMANAGER

 INPUTS:
      none

 KEYWORDS:

 CALLING SEQUENCE:
      handled by XMANAGER

 MODIFICATION HISTORY:
      written December 1998, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_configure.pro:1206)

papco_configure_event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_configure_event

 DESCRIPTION:
      Event handler for papco_configure.pro

 INPUTS:
      event    Event

 KEYWORDS:
      none

 MODIFICATION HISTORY:
      written July 1997, Haje Korth
      added module dependency checks, Octobner 2003, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_configure.pro:1253)

papco_configure_refresh

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_configure_refresh

 DESCRIPTION:
      Event handler for papco_configure.pro

 INPUTS:
      none

 KEYWORDS:
      ALL
      FILE
      USER_LIST
      STANDARD_MODULES

 MODIFICATION HISTORY:
      written December 1998, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_configure.pro:1099)

papco_coord_tx

 [Previous Routine] [Next Routine] [List of Routines] 
 Convert from GSM to GSE knowing the angle between GSE and GSM
 coordinate system.
 INPUT:  xarr: X coords (array)
         yarr: Y coords (array)
         zarr: Z cords (array)
         dipangle: angle between GSE and GSM in degrees (array(
 KEYWORDS:
          GSE - input is in GSE, not GSM -> skip first conversion

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_coord_tx.pro:180)

papco_create_compile_script

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_create_compile_script
 DESCRIPTION: creates a script to compile all the files in a directory 
 INPUTS:   
   DIR, string, root of directory tree in which to search for '*.pro' files
   SCRIPTFILE, string, filename of the compile script that is created.
 KEYWORDS:
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: developer.runtime
 CVSTAG: 
   $Name:  $
   $Revision: 1.19 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco/papco_create_compile_script.pro:52)

papco_create_compile_script_batch

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_create_compile_script_batch
 DESCRIPTION: creates compile scripts for everything
 INPUTS: none
 KEYWORDS:
   ALL, keyw, find all modules
   MODULES, strarr, list of modules
   LOADED, keyw, just the loaded modules
 OUTPUT KEYWORDS:
   SCRIPTS, strarr, list of all the created scripts
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: developer.runtime
 CVSTAG: 
   $Name:  $
   $Revision: 1.19 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco/papco_create_compile_script.pro:127)

papco_create_compile_script_master

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_create_compile_script_master
 DESCRIPTION: creates the scripts to compile the rt papco core and modules, and the
    master script that runs all of those.
 INPUTS:   
 OUTPUT KEYWORDS:
   SCRIPTS, strarr, output a strarr list of the scripts created.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: developer.runtime
 CVSTAG: 
   $Name:  $
   $Revision: 1.19 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco/papco_create_compile_script.pro:223)

papco_create_dir

 [Previous Routine] [Next Routine] [List of Routines] 
 procedure:    papco_create_dir, path

 description:  checks if path contains a directory, and creates it
               if not. Checks for each dir in path!

 inputs:       path : directory path

 output:       none

 keywords:     NOASK    don't ask for confirmation on create

 author:       R. Friedel, November 2000

 changes:      Opsys independent form J L Roeder, Nov 2003

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:118)

papco_create_istp_cdf.pro

 [Previous Routine] [Next Routine] [List of Routines] 
  NAME:        papco_create_istp_cdf.pro

  DESCRIPTION: Routine to create an empty ISTP compliant cdf file
               based on the skeleton information in skel_file.

  INPUT:       none - use keywords to override defaults

  OUTPUT:      none 

  KEYWORDS:    VERBOSE   : if set, print comments. Default is no comments.
               SKEL_FILE : full path to .skel file
               FILE      : full path of output .cdf file. 
                           default is 'papco_istp.cdf'
               MJDT      : uses common mjdt for date
               YEAR      : integer, 0-9999, e.g. 2001  
               MONTH     : byte, 1-12, e.g. 12
               DAY       : byte, 1-31, e.g. 31
               VERSION   : integer 0-99 to set cdf file version number


  DATE:        October 2004

  AUTOR:       R. Friedel. Based on createcdf.pro from A. Sicard, ONERA

  CHANGES:     S. Bourdarie to add version keyword

(See /home/jbf/ct/papco/working/papco/papco_lib/cdf/papco_create_istp_cdf.pro:27)

papco_create_main_widget

 [Previous Routine] [Next Routine] [List of Routines] 
 CALL: papco_create_widget.pro

 DESCRIPTION:
   Initialize the widgets-hierarchy and define the gui data
   structure.

 KEYWORDS:
           HEADLESS     only return guiData with dummies.

 INPUTS:           none

(See /home/jbf/ct/papco/working/papco/papco/papco_create_main_widget.pro:352)

papco_cursor

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_cursor, event

 DESCRIPTION:
	Whenever the mouse moves over the main papco-window drawing-widget,
	this procedure is called to handle that event.
	Here, the cursor-pointer is set according to the mouse-position, and
	slice-actions are processed according to the allowed slice-modes.

 INPUTS:
	event	 an XMANAGER-event

 KEYWORDS:
 	MOUSE_DOESSLICE   overwrites this value in widgetdata if
                        set. used for recusive calls to this rotuine

 CALLING SEQUENCE:
	called by papco_event

 MODIFICATION HISTORY:
     written august and september 1995, Andreas Keese
     Torsten Heise modified September 1997,
     Reiner Friedel modified October 1997 to make slices configurable
     Reiner Friedel modified October 1998 to enable panel editor calling

(See /home/jbf/ct/papco/working/papco/papco/papco_cursor.pro:879)

papco_cursor_HairCursor

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:   PRO papco_cursor_HairCursor

 DESCRIPTION: draw a hair-cursor in the selected panel and show the
              x and y values.

 INPUTS:      panelNr - number of the selected panel
              event   - a cursor event

 KEYWORDS:    ERASE - delete the hair cursor from screen
              INXY - an input in event x,y for  the time to draw a
                     cursor. To be used by other calkling programs.

 MODIFICATION HISTORY:  written september 1997, Torsten Heise
 modified February 2001 R. Friedel addad TAI

(See /home/jbf/ct/papco/working/papco/papco/papco_cursor.pro:1480)

papco_cursor_Rect

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_cursor_Rect, panelNr, normal_x, normal_y, CLOSE=CLOSE

 DESCRIPTION:
	This procedure is called whenever the zoom-function is active and
	the mouse is dragged in the draw-widget.
	A zoom-window is opened - this is a small window, in which data
	about the selected rectangle is displayed.
      To be independent of the actual time axis format used by the plot,
      this routine uses the system variable !X.CRANGE and converts the
      cursor time returned to the papco internal time format.

      N.B.!!: For this to work, the user plot routine needs to adhere to the
      papco philosophy and ALWAYS plot data for the time range given by
      COMMON mjdt, mjdt_start, mjdt_end

 INPUTS:
	panelNr	 	an integer
			the number of the panel for which the rectangular
			selection is done
	normal_x	a float
	normal_y	a float
			the normal coordinates of the last mouse-position

 KEYWORDS:
 	CLOSE		if set, the window is closed

 MODIFICATION HISTORY:
     written august and september 1995, Andreas Keese
     modified February 1997 by Reiner Friedel, to be independent of x-axis
                                                format and to use mjdt time

(See /home/jbf/ct/papco/working/papco/papco/papco_cursor.pro:579)

papco_cursor_Rect_Event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_cursor_Rect_Event, event

 DESCRIPTION:
      The ZOOOM-window is a small window, in which data about the selected
	rectangle is displayed.
	This procedure handles events for that window.

 INPUTS:
	event	 an XMANAGER-event

 KEYWORDS:
 	none

 CALLING SEQUENCE:
	called by XMANAGER

 MODIFICATION HISTORY:
     written august and september 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_cursor.pro:477)

papco_cursor_SetMouseDataStruct

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:   PRO papco_cursor_SetMouseDataStruct

 DESCRIPTION: Initialisation of a structure, that contains mouse
              information (needed by papco_cursor_HairCursor)


 INPUTS:      none

 OUTOUTS:     initialisation of common block MOUSE_INFORMATION

 KEYWORDS:    none

 MODIFICATION HISTORY:  written september 1997, Torsten Heise

(See /home/jbf/ct/papco/working/papco/papco/papco_cursor.pro:1445)

papco_cursor_SetPointer

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_cursor_SetPointer, panelNr, normal_x, normal_y

 DESCRIPTION:
	When the mouse is moved into a valid panel, the pointer changes to
	a hand-symbol. When it's not inside a valid panel, the pointer
	becomes an ugly symbol...
	When the mouse is dragged in a valid panel, the pointer is changed to
	a sizing-symbol.

 INPUTS:
	panelNr	 	an integer
			the number of the panel for which the rectangular
			selection is done
	normal_x	a float
	normal_y	a float
			the normal coordinates of the current mouse-position

 KEYWORDS:
 	none


 MODIFICATION HISTORY:
     written august and september 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_cursor.pro:754)

papco_cursor_ShowSelection

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO  papco_cursor_ShowSelection, panelNr, x, y, normal_x, normal_y, $
				         ERASE_ONLY=ERASE_ONLY

 DESCRIPTION:
	Draw the selection the user has made dragging his mouse in the draw-
	widget. Before the new selection is drawn, the last selection shown
	is erased.
	In zoom-mode, the selection is a rectangle
	In slice-mode, it is a vertical line
      In access level zero, it is a vertical line
      In view ephemeris, it is a vertical line
      In write paneldata, it is a vertical line

 INPUTS:
	panelNr	 	an integer
			the number of the panel for which the rectangular
			selection is done
	normal_x	a float
	normal_y	a float
			  the normal coordinates of the last mouse-position
	x		a float
	y		a float
			  these is the location of the last mouse-position in
			  data-coordinates of the panel 'panelNr'

 KEYWORDS:
 	ERASE_ONLY	when set, the current selection is not shown but the
			last selection is hidden.

 MODIFICATION HISTORY:
     written august and september 1995, Andreas Keese
     modified september 1997 Torsten Heise
     Reiner Friedel modified october 1997 to make show selection configurable

(See /home/jbf/ct/papco/working/papco/papco/papco_cursor.pro:1239)

papco_cursor_showselection_TYPE

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE: papco_cursor_showselection_TYPE

 DESCRIPTION:  The routines papco_cursor_showselection_TYPE are bunch of 
    for each selection type currently supported by PAPCO.  They all share a
    common interface.  Users may add thier own routines externally! 

 IMPLEMENTATIONS:
   papco_cursor_showselection_vert_line
   papco_cursor_showselection_horz_line
   papco_cursor_showselection_hair_cursor
   papco_cursor_showselection_box

 INPUTS: none 
 
 KEYWORDS:
   ERASE, keyw, erase the drawn selection
   DRAW, keyw, draw the selection

 SIDE EFFECTS: the graphics device is affected

 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 NOTES:
    the common block MOUSE_SELECT is used to get the common block
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.30 $
 CURATOR: Reiner Friedel
 HISTORY:  
   written February 1998, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_cursor.pro:1352)

papco_cursor_time

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      papco_cursor_time,panelnr

 DESCRIPTION:
	Given the cursor time and Panel Nr. finds time of cursor.
      Reurns a verbose string of the time.

 INPUTS:
      user_time       User time value returned by cursor
	panelNr         Panel No of cursor

 KEYWORDS:
 	MJDT            if set, returns time in mjdt format.

 CALLING SEQUENCE:
	result=papco_cursor_time(time,panelnr)

 MODIFICATION HISTORY:
     written october 1997, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_cursor.pro:140)

papco_cursor_UpdateData

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_cursor_UpdateData, YSCL=YSCL, TIME=TIME

 DESCRIPTION:
      The ZOOOM-window is a small window, in which data about the selected
	rectangle is displayed.
	In this window, there are three update-buttons. If the user selects
	one, the time-range and/or the y-range of a plot is changed to the
	by mouse selected range.
	This procedure handles the pressing of such a button - the y-range
	and/or the time-range of a plot are changed.

	These changes are not performed, if the orbit has changed since
	drawing the plots.

 INPUTS:
	none

 KEYWORDS:
 	YSCL	if specified, the y-range of the plot described in
		COMMON PAPCO_CURSOR_ECT, cursorWidgetData
		is changed.
      TIME	if specified, the time-range of all plots is changed to
		the current selection.

 CALLING SEQUENCE:
	papco_cursor_UpdateData, /YSCL, /TIME
	papco_cursor_UpdateData, /YSCL
	papco_cursor_UpdateData, /TIME

 MODIFICATION HISTORY:
     written august and september 1995, Andreas Keese
     modified February 1997 by Reiner Friedel, to be independent of x-axis
                                                format and to use mjdt time

(See /home/jbf/ct/papco/working/papco/papco/papco_cursor.pro:370)

papco_cursor_WhichPanel

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      FUNCTION papco_cursor_WhichPanel, normal_x, normal_y

 DESCRIPTION:
      find out to which panel the normal coordinates normal_x and normal_y
	belong.

 INPUTS:
	normal_x 	a float
	normal_y	a float
			this are the normal coordinates of some point in the
			drawing-widget

 KEYWORDS:
 	none

 OUTPUT:
      an integer
	the number of the panel is returned. If the point does not lie in
	any panel, -1 is returned. if the cursor lies to the right or
      left of a panel, -panel-2 is returned. We return the undelying
      panel no. in the case of overplots.

 CALLING SEQUENCE:
	panelNr=papco_cursor_WhichPanel( normal_x, normal_y)
	IF panelNr EQ -1 THEN $
	   print, 'No panel selected' $
	ELSE $
	   print, 'selected panel-info:', widgetData.plotsDrawn(panelNr)

 MODIFICATION HISTORY:
     written August and September 1995, Andreas Keese
     modified October 1998, Reiner Friedel, to include indication of
     "right/left of panel" for use in calling the panel editor.

(See /home/jbf/ct/papco/working/papco/papco/papco_cursor.pro:305)

papco_cw_bgroup

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
   PAPCO_CW_BGROUP

 PURPOSE:
   PAPCO_CW_BGROUP is a compound widget that simplifies creating
   a base of buttons. 

   This is a modification of the IDL 5.4 CW_BGROUP function
   To allow individual button ID's to be returned. None of the
   default behaviour of the original CW_BGROUP is changed.
   See the IDL documentation for a full description of the
   CW_BGROUP routine.

   Only modifications / additions are described here.

 CATEGORY:
   Compound widgets.

 CALLING SEQUENCE:
       Widget = PAPCO_CW_BGROUP(Parent, Names)

 KEYWORD PARAMETERS:

   BUTTON_IDS: Set to a variable to Return widget ID's of the
   individual buttons created

 MODIFICATION HISTORY:
   Aug. 2001, RF Added BUTTON_IDS keyword to return button Id's

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_cw_bgroup.pro:44)

papco_data_cache

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache    
 DESCRIPTION: creates a papco_data_cache object for listing, accessing, local and remote stores of data files.
 INPUTS:   
   LOCALROOT, string, directory of local filesystem
   FILETEMPLATE, string, template for generating names:
     %Y four digit year
     %y two digit year
     %j day of year in three digits
     %m month in two digits
     %b month as string
     %d day of month in two digits
     %H hour in two digits
     %M minute in two digits
     %S second in two digits
     %v version number in four digits -- pick best by number ordering
     %V version string in four digits -- pick best by alpha ordering
     %{id} matches arbitary string    -- pick all by constraint
     %{o:spacecraft}  matches orbit number of spacecraft
 KEYWORDS:
   REMOTEURL, string, URL of the remote cache.  A remote filesystem object is created from the URL.  http, ftp, ssh, are supported.
   SECONDARYCACHE, , check this cache before downloading data.
   EXPLICIT_WIDTH, intarr[7], defines the length in [ years, months, days, ..., seconds, nanos ] of each file.  Normally,
      this is determined implicitly by the fields.
   LAZY, boolean, be lazy about resolving remote file list (interactive, partial listing)
   EAGER, boolean, be eager about resolving remote file list. (batch, complete listing)
   AUTOGZIP, boolean, compress the files in the local filesystem.
   ENABLEGZIP, boolean, automatically decompress files when .gz extension is found.  The .gz should not be part of the
      template name.
 RETURNS: 
   , object for listing, accessing, local and remote stores of data files.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
    local= papco_getenv( 'PAPCO_DLNK' ) + 'mydata'
    cache= papco_data_cache( local, '%Y%m%d_hyd_sv_v%v.cdf'  )
    print, cache->get( papco_new_time( '2005-001 00:00' ) )
 UNIT TEST: test_papco_data_cache
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: Jeremy Faden
 HISTORY:  
   2005, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:1855)

papco_data_cache::download

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::download    
 DESCRIPTION: transfers the file from the remote to the local filesystem. 
 INPUTS:   
   FILE, string, id (name within the filesystem) of the file to transfer.
 KEYWORDS:
   MONITOR, optional , monitor to monitor download progress.
   DIALOG_PARENT, optional? long widget id, the widget to use if dialogs need to be displayed.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:707)

papco_data_cache::file_width

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::file_width    
 DESCRIPTION: returns the width of files in the cache, an intarr[7]:
   [years,months,days,hours,minutes,seconds,nanos]
 INPUTS:   
   NAME, type, description
 KEYWORDS:
   NAME, type, description
 RETURNS: 
   intarr[7], [years,months,days,hours,minutes,seconds,nanos]
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
    cache= papco_data_cache( 'c:', '%Y.dat' )
    print, cache->file_width() ; [ 1,0,0,0,0,0,0] 
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: Jeremy Faden
 HISTORY:  
   2005, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:298)

papco_data_cache::get

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::get    
 DESCRIPTION: attempt to get a copy of the file, allow transfer if it's not
    local.  The fully-qualified, openable, file name is returned.  If the file
    is not available, return ''. 
 INPUTS:   
   MJDT1, , time that the file should contain.
 KEYWORDS:
   _EXTRA, extra keywords are names that set custom fields like %{spacecraft}.
   DRYRUN, boolean, just do a dry-run, so don't transfer or unzip.
      When using dryrun, the result is an file id that can be downloaded.
   NODOWNLOAD, boolean, don't download the file, even if it is available remotely.
 OUTPUT KEYWORDS:
   ISREMOTE, boolean, 1 indicates the file was remote
 RETURNS: 
   string, filename of file that can be opened for reading.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:979)

papco_data_cache::get_fileGlob

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::get_fileGlob    
 DESCRIPTION: returns the wildcard string that matches internal files.
 INPUTS: none
 KEYWORDS: none
 RETURNS: 
   string, file wildcard glob
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:592)

papco_data_cache::get_files

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::get_files   
 DESCRIPTION: returns the fully qualified names (externalized names) of files the data cache can provide.
   If data is available remotely but not locally, then the data is
   transfered.  If the data is compressed is used, then it is uncompressed.  It
   is guarenteed that each of the files may be opened and used.
 INPUTS:   
   TARGETRANGE, , get files that cover this range.
 KEYWORDS:
   MONITOR, , progress monitor.
   _EXTRA, extra keywords are appearently ignored.
 OUTPUT KEYWORDS:
   COUNT, int, number of files found.
 RETURNS: 
   strarr, array of openable filenames.  TODO: verify this for all cases.  Some cases
     look as though they return the file id.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:1167)

papco_data_cache::get_local_fs[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::get_local_fs
 DESCRIPTION: returns local filesystem object, for reference only  
 INPUTS: none
 KEYWORDS: none
 RETURNS: 
   , the local filesystem object.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: Jeremy Faden
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:548)

papco_data_cache::get_local_fs[2]

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::get_local_fs
 DESCRIPTION: returns remote filesystem object, for reference only  
 INPUTS: none
 KEYWORDS: none
 RETURNS: 
   , the remote filesystem object.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: Jeremy Faden
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:570)

papco_data_cache::get_names

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::get_names    
 DESCRIPTION: returns the set of filenames that cover the range specified.  Note
   These are filenames within the filesystems, and cannot be opened.  Use get_files
   to get readable file names.
 INPUTS:   
   TIMERANGE, , timerange to cover
 KEYWORDS:
   _EXTRA, name value pairs for custom fields.
   VERSION, float, use this version.
 RETURNS: 
   strarr, the names of the files that cover, within the filesystems.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: Jeremy Faden
 HISTORY:  
   2005, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:179)

papco_data_cache::get_name_for_date

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::get_name_for_date
 DESCRIPTION: returns the name of the file for the date and options within the
   filesystem.
 INPUTS:   
   MJDT, , the time the the file should contain.
 KEYWORDS:
   _EXTRA, keywords are name/value pairs for custom fields like %{spacecraft}
   VERSION, float, plug in this version number.  If not specified, wildcards are inserted.
 RETURNS: 
   String, the name of the file within the local and remote filesystems.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
   cache= omni_cache()
   print, cache->get_name_for_date( papco_new_time( '2001-001' ) )
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: Jeremy Faden
 HISTORY:  
   2005, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:78)

papco_data_cache::get_secondary_cache

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::get_secondary_cache    
 DESCRIPTION: accesses the secondary cache.  
 INPUTS: none
 KEYWORDS: none
 RETURNS: 
   , the secondary cache.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:1420)

papco_data_cache::has_secondary_cache

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::has_secondary_cache    
 DESCRIPTION: returns 1 if the cache has a secondary cache.  
 INPUTS: none
 KEYWORDS: none
 RETURNS: 
   boolean, 1 if the cache has a secondary cache.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:1398)

papco_data_cache::Init

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::Init    
 DESCRIPTION: initializer for papco_data_cache object.  This never called directly.
   PAPCO_NEW_FILESYSTEM should be used to create objects.
 INPUTS:   
   LOCALFS, , canonical location of the data
   FILETEMPLATE, string, template for generating names, see PAPCO_NEW_FILESYSTEM
 KEYWORDS:
   REMOTEFS, , the remote filesystem for getting files.
   USERFS, , this is a writable, faster medium to check first.  
      Downloads to here if localFS is READONLY.
   REMOTEURL, string, URL of the remote cache.  A remote filesystem object is created from the URL.  http, ftp, ssh, are supported.
   SECONDARYCACHE, , check this cache before downloading data.
   EXPLICIT_WIDTH, intarr[7], defines the length in [ years, months, days, ..., seconds, nanos ] of each file.  Normally,
      this is determined implicitly by the fields.
   LAZY, boolean, be lazy about resolving remote file list (interactive, partial listing)
   EAGER, boolean, be eager about resolving remote file list. (batch, complete listing)
   AUTOGZIP, boolean, compress the files in the local filesystem.
   ENABLEGZIP, boolean, automatically decompress files when .gz extension is found.  The .gz should not be part of the
      template name.
 RETURNS: 
   int, 1 if successful, 0 otherwise.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:1666)

papco_data_cache::list_files_local

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::list_files_local    
 DESCRIPTION: return a listing of the local file id's, that intersect with time range
   TARGETRANGE.
 INPUTS:   
   TARGETRANGE, , limit list to this range.
 KEYWORDS:
   MONITOR, optional , monitor the listing, which can be sub-interactive.
 OUTPUT KEYWORDS:
   COUNT, int, return the number of files listed for convenience.
   FILESYSTEMS, objarr, a list of filesystems,
 RETURNS: 
   strarr, an array of all the names within the range.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:854)

papco_data_cache::list_files_remote

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::list_files_remote
 DESCRIPTION: return a listing of the remote file ID's, that intersect with time range
   TARGETRANGE.
 INPUTS:   
   TARGETRANGE, , limit list to this range.
 KEYWORDS:
   MONITOR, optional , monitor the listing, which can be sub-interactive.
   DIALOG_PARENT, optional? long widget id, the widget to use if dialogs need to be displayed.
   NO_WARN, boolean, don't warn about a missing remote filesystem.
 OUTPUT KEYWORDS:
   COUNT, int, return the number of files listed for convenience.
   FILESYSTEMS, objarr, a list of filesystems,
 RETURNS: 
   strarr, an array of all the names within the range.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:913)

papco_data_cache::matches

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::matches    
 DESCRIPTION: indicates if the file id belongs to this cache. 
 INPUTS:   
   FILE, string, file id 
 KEYWORDS:
 RETURNS: 
   boolean, 1 if the file matches the cache data file spec, 0 otherwise
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:1290)

papco_data_cache::p_getParentCache

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::p_getParentCache 
 DESCRIPTION: provide access to parent data cache, if it exists.  The parent
    cache describes how to generate directory names containing this cache's 
    files.  For example, if the template is /data/%Y/%Y%d%m.dat, then /data/%Y.
 INPUTS: none
 KEYWORDS: none
 RETURNS: 
   , the parent cache or null if no parent exists.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:1502)

papco_data_cache::p_get_best_file

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::p_get_best_file   
 DESCRIPTION: returns version of the best file found in the array of
    filesystems. resultFile contains the internal file id of the file, and
    resultFS contains the FileSystem containing the file. 
 INPUTS:   
   MJDT1, , time to find a file containing.
   FILESYSTEMS, objarr, check each filesystem for the file.
 KEYWORDS: none
 OUTPUTS:
    RESULTFILE, string, the id of the file found.
    RESULTFS, , the filesystem in which the file is found.
 RETURNS: 
   float, version number found.  -1 indicates none found.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:621)

papco_data_cache::p_get_files2

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::p_get_files2    
 DESCRIPTION: same as get_files, but different algorithm that doesn't assume
 fixed width and takes longer.  This is used for orbits. 
 INPUTS:   
   TARGETRANGE, , get files that cover this range.
 KEYWORDS:
   MONITOR, , progress monitor.
   _EXTRA, extra keywords are appearently ignored.
 OUTPUT KEYWORDS:
   COUNT, int, number of files found.
 RETURNS: 
   strarr, array of openable filenames.  TODO: verify this for all cases.  Some cases
     look as though they return the file id.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:1091)

papco_data_cache::p_get_remote

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::p_get_remote    
 DESCRIPTION: returns id of the best available remote file
 INPUTS:   
   NAME, type, description
 KEYWORDS:
   NAME, type, description
 RETURNS: 
   type, description
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 NOTES: TODO: check
   validity for secondary caches.  This logic should probably be
   only implemented when externalized filename is returned.
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:947)

papco_data_cache::p_implicit_width

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::p_implicit_width    
 DESCRIPTION: returns the width implied by the cache, an intarr[7]:
   [years,months,days,hours,minutes,seconds,nanos]
 INPUTS:  none
 KEYWORDS: none
 RETURNS: 
   intarr[7], [years,months,days,hours,minutes,seconds,nanos]
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: Jeremy Faden
 HISTORY:  
   2005, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:256)

papco_data_cache::p_isGZipEnabled

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::p_isGZipEnabled    
 DESCRIPTION: returns true if gzip is enabled, used only by the dataCacheTool.
 RETURNS: 
   boolean, 1 if gzip is enabled.
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:1590)

papco_data_cache::p_list_files

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::p_list_files    
 DESCRIPTION: returns array of IDs in FILESYSTEM that intersect with time range 
  TARGETRANGE, optimized 
  to use parentDataCache and generalized to work on either local or
  remote filesystem
 INPUTS:   
   FILESYSTEM, , filesystem to list.
   TARGETRANGE, , limit list to this range.
 KEYWORDS:
   MONITOR, optional , monitor the listing, which can be sub-interactive.
 OUTPUT KEYWORDS:
   COUNT, int, return the number of files listed for convenience.
 RETURNS: 
   strarr, array of names of files that match, or '' if none are found.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:757)

papco_data_cache::p_mark_listed[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::p_mark_listed  
 DESCRIPTION: sets the flag indicating the data cache as listed.
 INPUTS:
   LISTED, boolean, 1 indicates that the cache has been listed (and listing
      remotes should be cheap.
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:1607)

papco_data_cache::p_mark_listed[2]

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::p_mark_listed    
 DESCRIPTION:  
 INPUTS: none
 KEYWORDS: none
 RETURNS: 
   boolean, returns flag indicating listed.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:1629)

papco_data_cache::p_parentCache

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::p_parentCache    
 DESCRIPTION: identify if parent cache can be defined to optimize operations.  If
    a slash (/) exists before the first dateFormat, then a parent cache exists.
    It is assumed that the parent "files" contain (timeRange-wise) the
    child "files", e.g. %Y/%Y%m%d.dat, or the init of the parent will
    crash. 
 INPUTS: none
 KEYWORDS: none
 RETURNS: 
   , the calculated parent cache, or null.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:1529)

papco_data_cache::p_wild

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::p_wild    
 DESCRIPTION: returns the wild card-filled glob string that files must match
   note that there are two kinds of fields within each name, those of
   known length ( e.g.  %Y or %4v ), and those for which the length
   is not known.  Note that two of those fields cannot be adjacent.
   note also that the wildcard matches file IDs within the filesystems. 
 INPUTS: none
 KEYWORDS: none
 RETURNS: 
   string, the wildcard-filled globstring, such as omni_????.dat.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: Jeremy Faden
 HISTORY:  
   2005, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:221)

papco_data_cache::range

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::range
 DESCRIPTION: returns the timerange covered by the name FILE.  
 INPUTS:   
   FILE, String, the name of the file, within the filesystem.
 KEYWORDS: none
 OUTPUT KEYWORDS:
   IDS, struct of strings, the custom tag values.
   VERSION, string, returns version number of file if specified.
 RETURNS: 
   type, description
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:328)

papco_data_cache::remote_available

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::remote_available
 DESCRIPTION: returns a timerange that contains all of the remote data.  This may
   be optimized by giving a larger interval than specified.  For
   example, it may return the remote_available of the parent cache. 
 INPUTS: none
 KEYWORDS: none
 RETURNS: 
   , timerange accurately (though not precisely) reflecting the 
   remotely available data.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:1356)

papco_data_cache::reset

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::reset    
 DESCRIPTION: resets any internal state.  Resets the filesystems as well.
 INPUTS: none
 KEYWORDS: none
 SIDE EFFECTS: resets filesystems, userFS, etc.
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: Jeremy Faden
 HISTORY:  
   2005, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:508)

papco_data_cache::toString

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache::toString
 DESCRIPTION: returns string consisely describing the cache, for consumption by human. 
 INPUTS:   none
 KEYWORDS:   none
 RETURNS: 
   string, for display to human.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:1316)

papco_data_cache__define

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_data_cache__define    
 DESCRIPTION: automatic definition of data_cache object fields.  This should
    not be called directly.
 FIELDS:   
    localFS , the local filesystem object ( windows or unix )
    remoteFS, , the remote filesystem object
    userFS, 
    downloadFS, , download to here. eq userFS when the localFS is Read Only.
    remoteUrl is the url of the remote data store, can be http or ftp
    fileTemplate contains {0}, which is replaced by the date,etc.
    secondaryCache should be checked before attempting a web transfer.
    monitor  see papco_monitor.pro for monitor interface
 KEYWORDS: none
 RETURNS: 
   { papco_data_cache }, structure
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:1451)

papco_Data_ToNormal

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      FUNCTION papco_Data_ToNormal, panelNr, normal_position

 DESCRIPTION:
      Convert data coordinates of a certain panel to normal coordinates.

 INPUTS:
	panelNr	    an integer
		    the coordinates will be transformed using the
		    coordinate-system of widgetData.plotsDrawn(panelNr)
	position    a two-dimensional float-array
			 position(0)   : x-coordinate
			 position(1)   : y-coordinate

 KEYWORDS:
 	TO_DATA if set, input is data coords, output is normal

 OUTPUT:
      a two dimensional array
	output(0)        x-normal-coordinate
	output(1)        y-normal-coordinate
 CALLING SEQUENCE:
	tmp=papco_Data_ToNormal(0, [x_data, y_data])
	x_normal=tmp(0)
	y_normal=tmp(1)

 MODIFICATION HISTORY:
     written august and september 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_cursor.pro:249)

papco_defaults_event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      papco_defaults_event

 DESCRIPTION:
      this is the event-handler. It is called by XMANAGER only

 INPUTS:
      event 	: the event to be handled

 OUTPUT:
      none

 CALLING SEQUENCE:
      this procedure is to be called by XMANAGER only

(See /home/jbf/ct/papco/working/papco/papco/papco_defaults.pro:87)

papco_DeletePlot

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_DeletePlot, plotNumber

 DESCRIPTION:
      Remove a plot.
	The user has to assure this action in a messagebox. After this is
	done, the element at index 'plotNumber' of widgetData.plotInfos is
	removed an widgetData.numberOfPlots is decreased.
	Afterwards, the display is refreshed.

 INPUTS:
	plotNumber	anInteger. 0<=plotNumber<=widgetData.numberOfPlots
			the index of the plot in widgetData.plotInfos.

 KEYWORDS:
 	comfirm=0   don't confirm
  refresh=0    don't refresh

 CALLING SEQUENCE:
	papco_DeletePlot, anInteger

 MODIFICATION HISTORY:
      written august 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_plotedit.pro:514)

papco_DescriptionFor

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      papco_DescriptionFor, plotInfo, totalHeight

 DESCRIPTION:
	Create a verbose description of the plot specified by plotInfo.
	Each plot that is listed in the plot-descriptions - listbox
	is described by two lines of text. The first line contains
	a number identifying the plot and the type of the plot (that
	is plotInfo.panelKind).
	The second line of the description is created by this function.

 INPUTS:
	plotInfo	a papco_PLOTINFO-structure
			the plot for which a description is wanted

	totalHeight	a positive integer
 			the descriptions contain the panelplot-vector.
			In order to construct it, the total height of
			the plots is needed.
 KEYWORDS:
 	none

 OUTPUT:
      a string containg the plot-description

 CALLING SEQUENCE:
	descript=papco_DescriptionFor(aPlotInfoStruct, anInteger)

 MODIFICATION HISTORY:
     written august, september 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_plotedit.pro:100)

papco_diff[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      papco_diff
     
 Differentiate array (as simple as it gets)

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_math.pro:19)

papco_diff[2]

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      papco_diff

 Differentiate array (as simple as it gets)

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:1677)

papco_dirfilter

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_dirfilter, dirlist, path_name

 DESCRIPTION:  checks a proposed list of directories and filters out
               non-directories

 INPUTS:       dirlist     string array containing the list of files to be
                           checked, or -1 is none are found
               path_name   path of directory containing dirlist

 OUTPUT:       Function returns:      list of directories

 KEYWORDS:     none

 HISTORY:      written March 1998, S. Claflin

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:219)

papco_dirsep

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_dirsep
 DESCRIPTION: returns a separator that delimits folder names in a path name 
     for the OS.  For example, / for unix, \ for windows.
 INPUTS: none
 KEYWORDS: none
 RETURNS: 
   string, character that delimits folder names in a path.
 SIDE EFFECTS:
 EXCEPTIONS: 
   'OS not supported': OS is not recognized ('unix', 'Windows' )
 EXAMPLES:
    ff= str_sep( papco_getenv('PAPCO_USER'), papco_dirsep() )
 UNIT TEST: 
 CATEGORY: opsys
 CVSTAG: 
   $Name:  $
   $Revision: 1.47 $
 CURATOR: Jeremy Faden
 HISTORY:  
   2004, REV, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:1494)

papco_DrawPlots

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_DrawPlots
 DESCRIPTION: draw the papco product on to the screen device.  PAPCO_DRAW_PANEL
    is called to draw the product.
 INPUTS: none
 KEYWORDS:
 SIDE EFFECTS:
    selected panel is cleared and cursor selection is reset.
    modules read and plot data.
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.64 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco/papco_draw.pro:178)

papco_DrawTimeRange

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_DrawTimeRange, newStart, newEnd, CLEAR_ONLY=CLEAR_ONLY

 DESCRIPTION:
      when the start- or endtime sliders are dragged and if plots were
      drawn yet, the newly selected time-range is displayed by a colored
	bar in the drawing widget. This functions handles its drawing.

 INPUTS:
      newStart	a number
			the new start of the time-range in the T90-format
	newEnd		a number
			the new end of the time-range in the T90-format

 KEYWORDS:
 	CLEAR_ONLY	if specified, the timerange-selector is erased

 CALLING SEQUENCE:
      papco_DrawTimeRange, 0, convert_tzero_to_t90(100,2,90)
	papco_DrawTimeRange, /CLEAR_ONLY

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_settime.pro:444)

papco_Draw_Border

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_Draw_Border

 DESCRIPTION:
	This routine draws a border around the active papco plot area.

 INPUTS:
	none

 KEYWORDS:
	none

 CALLING SEQUENCE:
	papco_Draw_Border

 MODIFICATION HISTORY:
     written October 1997, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_draw.pro:602)

papco_Draw_CheckResult

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: papco_Draw_CheckResult, panelKind, panelVector, orbitNr, $
					 typeVector, channel

 DESCRIPTION:
      Check, if the plot-data could be read successfully.
      The read-routines define a common-block,
	    COMMON get_error, get_err_no, get_err_msg
	that may be used to find out if an error occured. If an error
	occured, 'get_err_no NE 0', and then get_err_msg contains the
	error-description.
	If an error is found, an empty panel is plotted and 'get_err_msg'
	is displayed in the empty panel. If the error occurs in the bottom
      panel, also draw a time axis.

 INPUTS:
	panelKind	a string
			if an error occured, the plot-type is drawn to
			the empty panel.
	panelVector	a three-element int-array
			this panel-vector is used to find out, where to
			draw an empty panel.
	orbitNr		an integer
			the orbit - number of the plot.
	typeVector	a four-element int-array
			the plot's type-vector
	channel		an integer
			the channel-field for this plot from the
			plot-info-structure

 KEYWORDS:
 	none

 OUTPUT:
      boolean, 1 if An error occured. In this case, the empty panel has been
		 drawn, 0 otherwise.

 MODIFICATION HISTORY:
     written august and september 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_draw.pro:484)

papco_Draw_IdentStamp

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_Draw_IdentStamp

 DESCRIPTION:
	This routine draws a identification string in the bottom left corner
	of the plot window to identify papco version, date and time of plot,
	and product (.prod) filename if specified

 INPUTS:
	none	 all necessary data are contained in COMMON PLOT_COMPOSER.

 KEYWORDS:
	none

 CALLING SEQUENCE:
	papco_Draw_IdentStamp

 MODIFICATION HISTORY:
     written september 1996, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_draw.pro:569)

papco_draw_panel

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_draw_panel, SCREEN=SCREEN

 DESCRIPTION:
	This routine does the plotting.
	Before it is called, the plotting-device has to be set.
	The routine does not check, if all data needed to plot is specified.
	The latter has to be done before calling this procedure.

	For each plot, the parameters for the reading/plotting-routines
	are set, then the data are read and afterwards the plots are done.
	If the output is done to the screen (must be indicated by the
	SCREEN-keyword), information about the plots are stored in the
	widgetData.plotsDrawn - array.

 INPUTS:
	none	 all necessary data are contained in COMMON PLOT_COMPOSER.

 KEYWORDS:
 	SCREEN	 used to tell this procedure, whether it plots to the display
		 or not.

 CALLING SEQUENCE:
	papco_draw_panel
	papco_draw_panel, /SCREEN

 MODIFICATION HISTORY:
     written august and september 1995, Andreas Keese
     changed july 1997, Haje Korth, Thickness and Linestyle added

(See /home/jbf/ct/papco/working/papco/papco/papco_draw.pro:745)

papco_draw_slice[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_draw_slice, panelVector, currPlotInfo, orbitNo $
                          get_data_call, slice_type, IsRead
 DESCRIPTION:
	This procedure performs the actual data read call and the plot call
      for the slice thumb panel.


 INPUTS:
	panelVector	position of the plot (see papco_conventions.text, 6)
	currPlotInfo	structure containing all data for this plot.
                      (structure type: PAPCO_PLOTINFO,
                                             see papco_variables.text)

 OUTPUTS:
   	get_data_call	a string containing the data call. Used by other
                      routines that need to know how to get the data
                      in a panel, e.g. to draw spectra, distrib. functions
      IsRead		a boolean which is set when the the data is read the
                      first time. Useful if a given data read puts data
                      into commons which can be plotted in many ways.
                      When set, data does not have to be read again.
      slice_type      Selects which slices are supported and for which
                      slice routines have been written.
                      This is a byte logical with 8 swittches. Currently
                      Three are supported (this may be extended later)
                       1 = mouse zooms (default, always possible)
                       2 = mouse slices
                       4 = mouse calls level zero
                       8, 16, 32, 64, 128 = not supported yet
                      you can support more than one type of slice
                      by arythmetically adding the options, eg
                      slice_type=5  support zoom and level zero

 KEYWORDS:
 	none

 CALLING SEQUENCE:
	papco_draw_slice, panelVector, currPlotInfo, orbitNo, $
                               get_data_call, slice_type, IsRead
 MODIFICATION HISTORY:
     written November 2000, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/slice_thumbs/papco_draw_slice.pro:44)

papco_draw_time_axis

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: PAPCO_DRAW_TIME_AXIS
 DESCRIPTION: draw the time axis for a panel
 INPUTS:   
   PANEL, intarr[3], panel vector provided by papco to the module.
 KEYWORDS:
   OVERPLOT, keyw, don't do anything, just return
   FORCE, keyw, description
   XTICKVALS, type, description
   MINOR, type, no used!
   YTICKPOS, int,
    0: BEGIN  ;normal, yaxis left, ticks & labels outward
    1: BEGIN  ;yaxis left, ticks & labels inward
    2: BEGIN  ;yaxis right,ticks & labels inward
    3: BEGIN  ;yaxis right,  ticks & labels outward
   XTICKPOS, type, description
    0: BEGIN                    ;both xaxis ticks
    1: BEGIN                    ;top xaxis only
    2: BEGIN                    ;bottom x-axis only
    3: BEGIN                    ;inhibit both
   _EXTRA, extra keywords make thier way to plot.
 OUTPUT_KEYWORDS:
   NTICKS, int, number of ticks used.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.6 $
 CURATOR: NAME
 HISTORY:  
   2003, 1.1, written by Reiner Freidel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_draw_time_axis.pro:34)

papco_draw_window

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      papco_draw_window, name

 DESCRIPTION:
	This function is used whenever a new draw window is being created.

 INPUTS:
	name	the name under which the window is to be registered with
              the xmanager.

 KEYWORDS:
 	CLOSE   closes and destrys this wondow.
      DUMMY   makes an un-mapped dummy containing only the draw widget.
              used by the annotate procedure.

 OUTPUT:
      a long integer of the idl plot window number
	this number is used in directing the output of all idl plot routines

 CALLING SEQUENCE:
	draw_window_index=papco_draw_window()

 MODIFICATION HISTORY:
     October 1996, written by R.Friedel
     October 1998, modified by R. Friedel to include PRINT and OUTPUT

(See /home/jbf/ct/papco/working/papco/papco/papco_draw_window.pro:61)

papco_draw_window_event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_draw_window_event, event

 DESCRIPTION:
      The main XMANAGER-event-handler.
	All events to the main-window are processed here

 INPUTS:
	event		an XManager-Event

 KEYWORDS:
 	none

 CALLING SEQUENCE:
	Called by XMANAGER only !

 MODIFICATION HISTORY:
     written october 1995, by R.Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_draw_window.pro:382)

papco_ds_append

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_append
 DESCRIPTION: appends the datasets on the first index.  Currently, this only
   supports datasets of compatible dimensionality.
 INPUTS:   
   DS1, papco dataset, rank N dataset.
   DS2, papco dataset, rank N dataset with tags 1..(N-1) equivalent to those of DS1.
 KEYWORDS:
   none.
 RETURNS: 
   papco dataset, a rank N dataset containing the data of both DS1 and DS2.  Data is
     trimmed where the two datasets overlap in depend_0.
 SIDE_EFFECTS:
   a heap_gc is performed.  This is a good time to do clean-up.
 EXAMPLES:
   ds1= papco_ds_testDs(0)
   ds2= papco_ds_testDs(0)
   ds2.time.data += 1.  ;; simulate another days' data
   ds3= papco_ds_append( ds1, ds2 )
 UNIT TEST: test_papco_ds_append
 CVSTAG: 
   $Name:  $
   $Revision: 1.5 $
 CURATOR: Jeremy Faden
 HISTORY:  
   Sept 2005, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_append.pro:27)

papco_ds_bin_width

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_bin_width

 DESCRIPTION: retrieve or guess the nominal bin width of the tags dataset.

 RETURNS:
   float  if one number identifies the nominal width
   or fltarr  if the widths are varying. 

 HISTORY:
   Written, March 2006, Jeremy Faden
   Support for "bins" dataset convention, Feb 2007, Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_range.pro:112)

papco_ds_builder

 [Previous Routine] [Next Routine] [List of Routines] 
 name:     PAPCO_DS_BUILDER

 purpose:  create a dataset, checking for validity

 inputs:   
  DATA, fltarr(1,...,N)
  DS0NAME, DS0VALUE,  string, {dataset}, dim 0 tags 
  DS1NAME, DS1VALUE,  string, {dataset}, dim 1 tags
  DS2NAME, DS2VALUE,  string, {dataset}, dim 2 tags

 keywords:
  LABEL, string, concise (10-20chars) label for axes.
  TITLE, string, longer title describing the dataset.
  UNITS, string, unit identifier.  see papco_ds_units for canonical unit ids. 
  BIN_WIDTH, double, indicates the cadence of the tags.
  DEPEND_, string, name for the dimension dataset.
  , { dataset }, the dataset tagging the dimension.
  ADDNAMES, strarr, an array of additional properties for the dataset.
  ADDVALUES, ptrarr, the values for those property names.
  CHECK, boolean, check validity.  (1 is default.)
  VALID_RANGE, fltarr(2), the range of valid data.  This is used to indicate fill, 
    there's no such thing as a fill value with papco datasets. (For example, use -1e31 and a
    valid_range=[-1e30,1e30]).
  TYPICAL_RANGE, fltarr(2), typical range that is a reasonable default range for an axis.
  
 returns: 
  new dataset with the same metadata and new tags.
 
 side effects:
   right now, the data type of the data is left alone.  We may in the future convert
   intarr and lonarr to fltarr.

 examples:
   ttags= papco_ds_builder( findgen(6260)*13.8/86400, label='time, UT', bin_width=13.8/86400, units='mjd2000' )
   ds= papco_ds_builder( randomn(6260), name='randomData', depend_0='time', time=ttags )
   ds= papco_ds_builder( randomn(6260), name='randomData', 'time', ttags )

 unit_test: test_papco_ds_builder  

 author:   Jeremy Faden, March 2006

 cvstag: 
   $Name:  $
   $Revision: 1.7 $

 changes:

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_builder.pro:117)

papco_ds_cache::getId

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_cache::getId
 DESCRIPTION: returns the identifier for the cache.
 RETURNS: a string that uniquely identifies the cache
 EXAMPLES: print, cache->getId()
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.25 $
 CURATOR: Jeremy Faden
 HISTORY:  
   16-Sep-2005, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_cache.pro:348)

papco_ds_cache::ramMegabytes

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:  papco_ds_cache::ramMegabytes
 DESCRIPTION: return the size of the data in this cache.
 INPUTS: none
 KEYWORDS: none
 RETURNS: 
   long, estimated size in megabytes of all the data sets.
 EXAMPLES: print, cache->ramMegabytes()
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.25 $
 CURATOR: Jeremy Faden
 HISTORY:  
   10-March-2006, 1.14, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_cache.pro:60)

papco_ds_cache::reset

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_cache::reset
 DESCRIPTION: remove all datasets from the cache.
 INPUTS: none
 KEYWORDS: none
 SIDE EFFECTS: resets cache, doing a ptr_free on all datasets.
 EXAMPLES: cache->reset
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.25 $
 CURATOR: Jeremy Faden
 HISTORY:  
   16-Sep-2005, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_cache.pro:296)

papco_ds_cache::retrieve

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_cache::retrieve
 DESCRIPTION: look for a dataset identified by ID that covers the TIMERANGE.
 INPUTS:   
   ID, string, unique string identifier for the dataset.
 OUTPUTS:
   DATASET, papco dataset, the dataset, if found.
 KEYWORDS:
   RELEASE, keyw, hint to the cache that the dataset will no longer be needed.
   NO_COPY, keyw, insist that the dataset is no longer needed and don't copy the data.
 RETURNS: 
   boolean, 1 if a dataset was found, 0 if not.  The dataset in the second parameter.
 SIDE EFFECTS:
   The cache entry for the dataset is marked to indicate the cache hit, decreasing
   the likelihood that the entry will be released.
 EXCEPTIONS:
   'timerange must be specified': timerange not specified when cache value has a timerange attached to it.
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.25 $
 CURATOR: Jeremy Faden
 HISTORY:  
   16-Sep-2005, written by Jeremy Faden
   07-Feb-2006, added protected and release keywords
   17-Apr-2007, added NO_COPY keyword.

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_cache.pro:242)

papco_ds_cache::show_all

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_cache::show_all
 DESCRIPTION: dumps information about all the caches into the logger.  This 
   should probably be removed to the "static" method papco_ds_cache_show_all.
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.25 $
 CURATOR: Jeremy Faden
 HISTORY:  
   9-Feb-2006, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_cache.pro:374)

papco_ds_cache::store

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_cache::store
 DESCRIPTION: store a dataset in the cache.  The dataset is tagged by an 
   identifier and the timerange covered by the dataset.  If papco is in batch 
   mode, than only one dataset is stored for any ID.
 INPUTS:   
   ID, string, a unique identifier for the dataset type.
   DATASET, papco dataset, the dataset to store.  Currently, this can be any
       IDL value, not just papco datasets.
 KEYWORDS:
   TIMERANGE, {papco_timerange}, the time range covered by the dataset.  Requests
       made for this ID and a timerange within this timerange will receive DATASET.
   PROTECTED, keyw, hint that the dataset must be stored until it is released.
   NO_COPY, keyw, rather than copy the source data, leaving DATASET undefined.  
 SIDE EFFECTS:
   The dataset will have a pointer to it and the cache object this modified.
   If NO_COPY is set, then DATASET will be undefined.
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.25 $
 CURATOR: Jeremy Faden
 HISTORY:  
   16-Sep-2005, written by Jeremy Faden
   07-Feb-2006, added protected and release keywords
   17-Apr-2007, added NO_COPY keyword.

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_cache.pro:151)

papco_ds_cache::swap_out

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_cache::swap_out
 DESCRIPTION: throw out the most useless datasets from any cache in order to 
   reduce the total size down to the specified limit.  This should probably
   be a static procedure.
 INPUTS: none
 KEYWORDS:
   MEMLIMIT, long, limit in megabytes.  If not specified I believe 
      papco's defaults settings are used.
 SIDE EFFECTS: datasets are removed from any of the caches.
 EXAMPLES: cache->swap_out, memLimit=256
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.25 $
 CURATOR: Jeremy Faden
 HISTORY:  
   10-March-2006, 1.14, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_cache.pro:88)

papco_ds_cache::toString

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_cache::toString
 DESCRIPTION: returns a string representation of the cache.
 RETURNS: a several-line string representing the cache.
 EXAMPLES: print, cache->toString()
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.25 $
 CURATOR: Jeremy Faden
 HISTORY:  
   16-Sep-2005, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_cache.pro:318)

papco_ds_cache::totalRAMMegabytes

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:  papco_ds_cache::totalRAMMegabytes    
 DESCRIPTION: return the total amount of memory used by the data caches.  This
   will be made into a "static" function.
 INPUTS: none
 KEYWORDS: none
 RETURNS: 
   long, estimated size in megabytes of all the data sets.
 SIDE EFFECTS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.25 $
 CURATOR: Jeremy Faden
 HISTORY:  
   10-March-2006, 1.14, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_cache.pro:30)

papco_ds_cache_reset_all

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_cache_reset_all
 DESCRIPTION: resets all the caches.
 KEYWORDS:
    LOG, { papco_logger }, dump the feedback messages into here.
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.25 $
 CURATOR: Jeremy Faden
 HISTORY:  
   8-Feb-2006, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_cache.pro:428)

papco_ds_cache_show_all

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_cache_show_all
 DESCRIPTION: dumps information about all the caches into the logger. 
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.25 $
 CURATOR: Jeremy Faden
 HISTORY:  
   9-Feb-2006, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_cache.pro:398)

papco_ds_cdf[1]

 [Previous Routine] [Next Routine] [List of Routines] 

AME: papco_ds_cdf_readable

ESCRIPTION: returns a list of all the quantities that can be read into a
  papco dataset.

NPUTS:
 FILE, string, a cdf filename to open and query

ETURNS:
strarr, a list of cdf variable names.

UTHOR:  Jeremy Faden, February 2007

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_cdf.pro:153)

papco_ds_cdf[2]

 [Previous Routine] [Next Routine] [List of Routines] 

AME: papco_ds_from_cdf

ESCRIPTION: converts the structure returned from cda library into papco dataset.

NPUTS:
 DAT, struct, the structure returned from cda library "read_mycdf"
 VARIABLE, string, a string identifying the tag to use as the primary dataset. 
    (presumably other tags are depends variables.)

EYWORDS:
  rename_depend_1, string, new name for depend_1
  /caa put in kludges for cluster active archive.

ETURNS:
papco dataset, the structure reformed into dataset, preserving and 
     canonizing as much metadata as possible.

UTHOR:  Jeremy Faden, March 2006

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_cdf.pro:243)

papco_ds_cdf_dump

 [Previous Routine] [Next Routine] [List of Routines] 
 
 NAME: papco_ds_cdf_dump

 DESCRIPTION: returns a list of all the quantities that can be read into a
    papco dataset.

 INPUTS:
   FILE, string, a cdf filename to open and query

 RETURNS:
  strarr, a list of cdf variable names.

 AUTHOR:  Jeremy Faden, February 2007

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_cdf.pro:175)

papco_ds_collapse

 [Previous Routine] [Next Routine] [List of Routines] 
 name:     PAPCO_DS_COLLAPSE

 purpose:  collapse a dataset along one or more dimensions, reducing rank, by
      averaging or totalling along the dimension.

 inputs:   
  DS_IN, papco dataset, a papco dataset of rank N to be reduced.
  DIMS, optional strarr, the dimensions to collapse

 keywords:
  TOTAL, int, if keyword_set don't normalize the results. By default, the collapsed dimension is averaged.
  SL_TIMERANGE, {papco_timerange}, is ignored as input and used for output.
  , intarr(2), trim this dimension before collapsing

 returns: 
   papco dataset, a papco dataset of rank N-1. This dataset will have
      additional properties '_range' where  is each dimension 
      reduced.
 
 exceptions:
   IDL_M_USER_ERR, named dimension doesn't exist.

 side effects:
    SL_TIMERANGE, {papco_timerange}, contains papco_timerange object if a collapsed dimension had time units.

 examples:
     x= papco_ds_collapse( ds, 'time' )
     x= papco_ds_collapse( ds, time=[40, 50] )

 unit_test: test_papco_ds_collapse.pro
     
 author:   Jeremy Faden, March 2006

 cvstag: 
   $Name:  $
   $Revision: 1.13 $

 changes:  
   added total keyword, Jan 2007, rev 1.7

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_collapse.pro:42)

papco_ds_coord_xform

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_coord_xform
 DESCRIPTION: transforms vector data in frame ds.frame to new frame "toFrame" 
   This wraps papco_coord_tx.
 INPUTS:   
   DS, papco dataset, rank 1 of vectors.  Tag frame equals GSM, GSE, SM, etc,
      and timetags must be depend_0.
   TOFRAME, string, name of the target coordinate frame.  Examples include GSM, GSE, SM.
 KEYWORDS: none
 RETURNS: 
   papco dataset, rank 1 dataset of vectors in coordinate frame TOFRAME
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.2 $
 CURATOR: Jeremy Faden
 HISTORY:  
   09-March-2006, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_coord_xform.pro:22)

papco_ds_dependNames

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_dependNames
 DESCRIPTION: convenient method for getting the dependency names.  These refer
    to the tags of the structure that tag each dimension, and are the values of
    depend_0, depend_1, ...
 INPUTS:   
   DS, papco dataset, a rank N dataset
 KEYWORDS:
   COUNT, returns int, a named variable in which to put the count.
 RETURNS: 
   strarr(N), the names of the datasets that tag each dimension.
 EXCEPTIONS:
 EXAMPLES: 
   print, papco_ds_dependNames( papco_ds_testDs(0) )
 UNIT TEST: test_papco_ds_dependnames
 CVSTAG: 
   $Name:  $
   $Revision: 1.19 $
 CURATOR: Jeremy Faden
 HISTORY:  
   Sept 2005, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds.pro:255)

papco_ds_fill

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_fill

 PURPOSE: returns an array that is indexed along with ds.data, where
    1 indicates the point is fill, 0 indicates the point is valid.  
    Accepts either a single or set of datasets.  When more than one dataset
    is given, the result is 1 if any of the datasets contain a fill value at that
    point, 0 if all are valid.  Also in the case,
    dimensionality is checked to verify that the datasets are indexed the same way.
 
 INPUT:
    DS, dataset or array of datasets.
    DS2, DS3, DS4 additional datasets, for convenience.  After that you're on your own.

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_range.pro:386)

papco_ds_format

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_format

 returns the format string to use for the dataset.  If the
 the dataset doesn't have a tag 'format', then '(f10.2)' is
 returned.

 KEYWORDS:
   format, string, explicit format to use.  (Provided to clean up code.)

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_range.pro:207)

papco_ds_gcd_dataset

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_gcd_dataset  
 DESCRIPTION: 
   return a cadence that is a integer division of ds1's dataset, and sufficient to
   accurately locate ds2 tags.
 INPUTS:   
   DS1, papco tags dataset
   DS2, papco tags dataset
 KEYWORDS:
   NAME, type, description
 RETURNS: 
   papco dataset
 OUTPUT KEYWORDS:
   FACTOR, int, the resolution factor for ds1.  Each bin of DS1 is divided into FACTOR bins.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.2 $
 CURATOR: Jeremy Faden
 HISTORY:  
   23-March-2007, 1.2, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_spectrogram2.pro:82)

papco_ds_getTag

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_getTag
 DESCRIPTION: returns the data in tag.  This is a convenience method to 
     discourage use of execute.  If TAGNAME is not found and default is 
     specified, DEFAULT is returned.
 INPUTS:   
   DS, papco dataset, dataset from which the tag is extracted.
   TAGNAME, string, name of the tag to look for. (case insensitive)
   [DEFAULT], the value to return if the tag is not found.
 KEYWORDS:
   none
 RETURNS: 
   the value found, or the default value if provided.
 SIDE EFFECTS:
 EXCEPTIONS:
   IDL_M_BADARRSUB, if the tag is not found and a default is not provided.
 EXAMPLES:
   ttags= papco_ds_getTag( ds, 'time' )
 UNIT TEST: test_papco_ds_range
 CVSTAG: 
   $Name:  $
   $Revision: 1.19 $
 CURATOR: Jeremy Faden
 HISTORY:  
   Nov 2005, written by NAME
   Feb 2007, 1.11, added default parameter

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds.pro:171)

papco_ds_getTagDs

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_getTagDs 
 DESCRIPTION: return the tag dataset for this dimension.  
 INPUTS:   
   DS, papco dataset, a dataset with dependencies.
   DIM, int, the dimension number 0,1,2,...
 KEYWORDS:
   none
 RETURNS: 
   papco dataset, of the tags for this dimension.
 EXCEPTIONS:
   IDL_M_USER_ERR, if the tag depend_DIM is not found.
   IDL_M_BADARRSUB, if the tag indicated by DIM is not found.
 EXAMPLES:
   ds= papco_ds_testDs(0)
   tds= papco_ds_getTagDs( ds, 0 )
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.19 $
 CURATOR: Jeremy Faden
 HISTORY:  
   March 2007, 1.12, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds.pro:210)

papco_ds_getUnits

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_getUnits

 DESCRIPTION: return the units of the dataset.  If the dataset doesn't have a tag
   'units,' then '' is returned.

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_range.pro:88)

papco_ds_grid

 [Previous Routine] [Next Routine] [List of Routines] 
 name:     PAPCO_DS_GRID

 purpose:  apply dataset into new bins using IDL's interpolate.  This is intended to
    provide data regridding, or taking irregular data onto a regular grid. 
    By default, nearest neighbor is done, but IDL's interpolate function is used for
    speed and /interpolate will allow interpolation to be done.

 inputs:   
  DS, {papco dataset}, a papco dataset of rank N to be gridded.
  [xds], {papco dataset}, xtags to rebin to.
  [yds], {papco dataset}, ytags to rebin to.

 keywords:
  , {papco dataset}, new tags for the dataset.
  /interpolate, boolean, interpolate onto the new grid.

 returns: 
  {papco dataset} 
 
 side effects:

 examples:

 unit_test:  test_papco_ds_grid

 see also:

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_grid.pro:66)

papco_ds_isValid

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_isValid    
 DESCRIPTION: return 1's where the data is valid, 0's where not valid.
 INPUTS:   
   DS, papco dataset, a rank N papco dataset, but not a tags dataset.
 KEYWORDS:
   NAME, type, description
 RETURNS: 
   intarr, array with dimensions equal to N
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name: $
   $Revision: $
 CURATOR: Jeremy Faden
 HISTORY:  
   2007-07-06, 1.27, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_range.pro:59)

papco_ds_magnitude

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_magnitude 
 DESCRIPTION: return the magnitude of a rank 1 dataset of vectors, propogating fill
    and metadata.
 INPUTS:   
   DS, papco dataset, rank 1 dataset of vectors.
 KEYWORDS: none
 RETURNS: 
   papco dataset, rank 1 of scalars.
 SIDE EFFECTS: none
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: test_papco_ds_magnitude
 CVSTAG: 
   $Name:  $
   $Revision: 1.3 $
 CURATOR: Jeremy Faden
 HISTORY:  
   Jan 2007, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_magnitude.pro:20)

papco_ds_make_lvt

 [Previous Routine] [Next Routine] [List of Routines] 
 name: papco_ds_make_lvt
  
 purpose: rebin dataset into L and time bins.  This wraps papco_make_lvt,
    but uses datasets for the interface.
 
 arguments:
     zds  the z values to rebin.
     lds  the L values for each z value

 keywords:
     l_min, double, the low y tag of the output.
     l_max, double, the high y tag of the output.
     l_name, string, use this name for the tag name for the L dataset.  'l_shell' is default.

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_make_lvt.pro:16)

papco_ds_max

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_max
 DESCRIPTION: returns the max of the dataset, paying attention to fill.
 PARAMETERS: 
   DS, papco dataset
 KEYWORDS:
   _extra keywords are passed on to max.
 SIDE EFFECTS:
 HISTORY:
   21-Mar-2007, 1.15, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds.pro:318)

papco_ds_min

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_min
 DESCRIPTION: returns the min of the dataset, paying attention to fill.
 PARAMETERS: 
   DS, papco dataset
 KEYWORDS:
   _extra keywords are passed on to min.
 SIDE EFFECTS:
 HISTORY:
   21-Mar-2007, 1.15, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds.pro:297)

papco_ds_output

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:   papco_ds_output  
 DESCRIPTION:   Writes the dataset out to a file based on the printer template.  
   This wraps papco_write_data, and is used by papco_lineplot and papco_spectrogram
   to provide the output function.
 INPUTS:   
   DS, papco dataset, rank 1 or rank 2 dataset
 KEYWORDS:
   TITLE, string, required for papco_write_data
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.2 $
 CURATOR: Jeremy Faden
 HISTORY:  
   13-Apr-2006, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_output.pro:20)

papco_ds_properties

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_properties    
 DESCRIPTION:  returns all the tags of the dataset except for data and all the dependencies
 INPUTS:   
   DS, papco dataset, papco dataset of any rank.
 KEYWORDS:
   INCLUDE, strarr, include these tags as well. (case insensitive)
   EXCLUDE, strarr, exclude these tags.  (case insensitive)
 RETURNS: 
   struct, containing all the properties metadata.  If no metadata is found, a 
     structure { name:'' } is returned.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: test_papco_ds_properties
 CVSTAG: 
   $Name:  $
   $Revision: 1.4 $
 CURATOR: Jeremy Faden
 HISTORY:  
   10-Aug-2006, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_properties.pro:22)

papco_ds_rank

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_rank
 DESCRIPTION:  returns the rank of the dataset.  A rank 1 dataset is generally 
    plotted as a line plot, a rank 2 is a spectrogram, and
    higher rank datasets need to be sliced or collapsed to reduce the rank to 
    1 or 2.  Note that rank 1 datasets of vector data (x,y,z) are marginally 
    supported, but this function will return "1" when they are.  Also, tag 
    datasets will also return a 1.
 INPUTS:   
   DS, type, description
 KEYWORDS:
   NAME, type, description
 RETURNS: 
   type, description
 SIDE EFFECTS:
 EXAMPLES:
   print, papco_ds_rank( papco_ds_builder( fltarr(2,2) ) )
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.19 $
 CURATOR: Jeremy Faden
 HISTORY:  
   Sep 2005, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds.pro:130)

papco_ds_rebin

 [Previous Routine] [Next Routine] [List of Routines] 
 name:     PAPCO_DS_REBIN

 purpose:  reduce a dataset along one or more dimensions, by
     averaging along each dimension.

 inputs:   
  DS_IN, papco dataset, a papco dataset of rank N to be reduced.
  NEWDIM, optional intarr[N], specifies the output array size, as with rebin.

 keywords:
  SL_TIMERANGE, papco_timerange::, is ignored as input and used for output.
  , int, the number of adjacent bins to average.

 returns: 
  {papco dataset} 
 
 side effects:
    SL_TIMERANGE, papco_timerange::, contains papco_timerange object if a collapsed dimension had time units.

 examples:
     ds= papco_ds_testds(2)
     x= papco_ds_rebin( ds, xx=10, yy=10 )

 unit_test: test_papco_ds_rebin.pro

 see also:
    papco_ds_grid(), which grids irregular data (not implememented yet)
    
 author:   Jeremy Faden, March 2007

 cvstag: 
   $Name:  $
   $Revision: 1.2 $

 changes:

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_rebin.pro:65)

papco_ds_rebuilder

 [Previous Routine] [Next Routine] [List of Routines] 
 name:     PAPCO_DS_REBUILDER

 purpose:  rebuild the dataset with these new data arrays.  metadata is kept, 
    but data and depends are replaced.

 inputs:   
  DS, papco dataset, a papco dataset of rank N to be reduced.
  NEWDATA, fltarr
  NEWDATA0...NEWDATA2, data for each tags dataset.

 keywords:
 
 returns: 
  new dataset with the same metadata and new tags.
 
 side effects:

 examples:

 unit_test: 
     
 author:   Jeremy Faden, March 2007

 cvstag: 
   $Name:  $
   $Revision: 1.7 $

 changes:

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_builder.pro:31)

papco_ds_scale

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_scale
 DESCRIPTION:  return the scale range [ min, max, type ], overriding with RANGE if specified.  SCALE can be passed in, and 
  if defined and valid, it will be used.  This automatically handles the override logic.
 INPUTS:   
   DS, papco dataset, papco dataset of any rank.
 KEYWORDS:
   RANGE, fltarr[2], use this range, if defined.
   LOG, boolean, use this value for log, if defined.
   SCALE, fltarr[3], use this scale, if defined.
   EXCLUDE, fltarr[2], Arne to comment 
 RETURNS: 
   fltarr[3], a good scale to use.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name: $
   $Revision: $
 CURATOR: Jeremy Faden
 HISTORY:  
   2005, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_range.pro:276)

papco_ds_slice

 [Previous Routine] [Next Routine] [List of Routines] 
 name: papco_ds_slice
 purpose: slices the dataset at one or more tags.  the slice locations are 
    specified as an index in each dimension, where the keyword identifies the
    dimension.

 inputs:
    ds, papco dataset, dataset of rank N where N>1.  

 keywords:
   sl_timerange, papco_timerange, returns the timerange of the slice
   _extra=e, the keyword name indicates the dimension to slice.

 returns:
   papco dataset of rank N-1 where N is the rank of the input dataset.  This
     dataset has the property XXX_range, where XXX is the tag that was sliced.

 side effects:
   logs to the developer logger.

 examples:
   sliceDs= papco_ds_slice( ds, time=400 )

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_slice.pro:24)

papco_ds_taggen

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_taggen
 DESCRIPTION: generates a series of tags with regular spacing.   
 INPUTS:   
   COUNT, int, the number of tags in the dataset.
 KEYWORDS:
   START, required double, the value of the first tag.
   CADENCE, required double, the step size between measurements.
   LOG, boolean, start and cadence are specified in the log space.  Take 10^ to get the result
   STOP, double, if set infer COUNT by stopping before and within CADENCE of this value.
 RETURNS: 
   { papco dataset }, a rank1 tags dataset
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.3 $
 CURATOR: Jeremy Faden
 HISTORY:  
   21-Mar-2007, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_taggen.pro:23)

papco_ds_tagindex

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_tagindex
 DESCRIPTION: returns the index of the tag, or -1 if the tag isn't found.
 INPUTS:   
   DS, papco dataset, a papco dataset (or structure)
   TAGNAME, string, the name of the tag to find (case-insensitive).
 KEYWORDS:
   TAGS, optional strarr, array of precomputed tags, uppercase. 
 OUTPUT KEYWORDS:
   TAGS, output the computed tags
 RETURNS: 
   int, -1 if the tag is not found, the index otherwise.
 EXAMPLES:
   struct= { a:'one', b:'two' }
   i= papco_ds_tagIndex( struct, 'b' )
   print, struct.(i)
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.19 $
 CURATOR: Jeremy Faden
 HISTORY:  
   Sep 2005, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds.pro:24)

papco_ds_testDs

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_testDs    
 DESCRIPTION: creates datasets for testing.  New datasets are welcome!
 INPUTS:   
   DSNUM, int, a number identifying the dataset to return
      0= rank 3 dataset DEF( time, energy, pitch_angle ) energy is scale type log.
      1= similar dataset to 0, but uses dataset builder.
      2= rank 2 dataset of IDL "dist" function, plus some fill.
      3= rank 2 with irregular tags, data are ints
      4= rank 2 with irregular tags, descrete bins with low frequency structure.
      5= rank 2 "ripples" dataset from das2.
 KEYWORDS: none
 RETURNS: 
   papco dataset
 SIDE EFFECTS:
 EXCEPTIONS: IDL_M_USER_ERR if the number is not valid.
 EXAMPLES:
     ds= papco_ds_testDs(2)
     papco_spectrogram, ds
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.6 $
 CURATOR: Jeremy Faden
 HISTORY:  
   Sept 2005, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_testds.pro:27)

papco_ds_to_cdf

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_to_cdf 
 DESCRIPTION: convert papco dataset to cdf structure for output.
 INPUTS:   
   VARNAME, string, the variable name for the primary dataset.
   DATASET, papco dataset, a dataset to convert.  See notes section for tags to watch for.
 KEYWORDS:
 RETURNS: 
   struct, a struct ready for output via cdaweb library
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES: 
 UNIT TEST: test_papco_ds_cdf
 NOTES:
   tag "VARNAME" stores the case-sensitive name.
 CVSTAG: 
   $Name:  $
   $Revision: 1.14 $
 CURATOR: Jeremy Faden
 HISTORY:  
   15-Feb-2006, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_cdf.pro:396)

papco_ds_transpose

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_transpose    
 DESCRIPTION: transpose the indeces of the ds.  Note the input dataset is modified! 
 INPUTS:   
   DS, papco dataset, of rank 2 or more.
   P, intarr, a vector specifying how the dimensions of Array will be permuted. 
      The elements of P correspond to the dimensions of Array; the ith dimension 
      of the output array is dimension P[i] of the input array. Each element 
      of the vector P must be unique. Dimensions start at zero and can not 
      be repeated.  If P is not present, the order of the dimensions of Array is reversed. 
      (From the IDL transpose documentation.)  
 KEYWORDS:
 RETURNS: 
   papco data, the dataset, transposed.
 SIDE EFFECTS: 
 EXCEPTIONS:
 EXAMPLES:
   ds= papco_ds_testDs(2)
   print, papco_ds_dependNames(ds)
   ds= papco_ds_transpose( ds, [1,3,2] )
   print, papco_ds_dependNames(ds)
 UNIT TEST: test_papco_ds_transpose
 CVSTAG: 
   $Name:  $
   $Revision: 1.6 $
 CURATOR: Jeremy Faden
 HISTORY:  
   16-Sept-2005, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_transpose.pro:29)

papco_ds_trim

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_trim
 DESCRIPTION:  return a subset of a dataset.  dimensions are specified as keyword list, each
   keyword is a two-element array of the start, end (inclusive) of the subset.  
 INPUTS:   
   DS, papco dataset, rank N papco dataset.
 KEYWORDS:
   , intarr(2), dimension NAME is to be trimmed.
 RETURNS: 
   papco dataset, rank N dataset with fewer elements in given dimensions
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: test_papco_ds_trim
 CVSTAG: 
   $Name:  $
   $Revision: 1.7 $
 CURATOR: Jeremy Faden
 HISTORY:  
   13-Sept-2005, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_trim.pro:57)

papco_ds_trim_tag

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_trim_tag
 DESCRIPTION:   return a subset of a tags dataset, checking for bin_width, etc.
 INPUTS:   
   DS, papco dataset, rank 1 tags dataset.
   TRIMSTART, int, the first tag to keep
   TRIMEND, int, the last tag to keep, inclusive
 KEYWORDS:
 RETURNS: 
   papco dataset, a rank 1 tags dataset with a subset of the tags.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.7 $
 CURATOR: Jeremy Faden
 HISTORY:  
   2007-May-4, 1.6, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_trim.pro:21)

papco_ds_units

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ds_units
 DESCRIPTION: returns a structure with tags of canonical units.
 INPUTS:  none
 KEYWORDS:
 RETURNS: 
   struct, struct with tags of canonical units.  Here are some selected tags:
      mjd2000:'mjd2000',    ; decimal days since 1/1/2000
      t90:'t90',                    ; seconds since 1990.  
      t2010:'t2010', $          ; seconds since 2010. 
      epoch:'epoch', $         ; milliseconds since 0.  As is often seen in cdfs.
      tai:'tai', $                   ;  seconds from midnight, 1 January 1958, with leap seconds.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
   units= papco_ds_units()
   uc= papco_get_converter( units.mjd2000, units.epoch )
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.8 $
 CURATOR: Jeremy Faden
 HISTORY:  
   13-Sept-2005, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_units.pro:270)

papco_ds_valid_range

 [Previous Routine] [Next Routine] [List of Routines] 
 name: papco_ds_valid_range
 
 description: returns [ min, max, type ] of data set, guessing if not 
    specified.  A measurement is valid if it is >min and < max.  This routine
    should also be used as the canonical way of getting the scale type, since
    it is independent of the actual data.

 input:
   DS, papco dataset, the dataset for which to identify the range.

 returns:
   fltarr, [ min, max, type ]

 notes:
   These are returned as floats, regardless of how they are stored in the 
     this is to avoid roundoff errors when comparing to float data. 
   Negative min's are allowed, even when the scale type is log.

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_range.pro:24)

papco_ds_verify

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: PAPCO_DS_VERIFY
 DESCRIPTION: checks to see if the dataset is well-formed, in hopes to catch
   errors early.  Many of the dataset routines call this on their input so
   they can provide more meaningful error messages.
 INPUTS:   
   DS, struct, a structure that is probably a papco dataset.
 KEYWORDS:
   none
 RETURNS: 
   boolean, an int that is 1 if the dataset is valid, 0 otherwise
 SIDE EFFECTS:
   In the future this may add metadata to the structure.
 CVSTAG: 
   $Name:  $
   $Revision: 1.19 $
 CURATOR: Jeremy Faden
 HISTORY:  
   Sep 2005, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds.pro:60)

papco_EditPlot

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_EditPlot, plotNumber

 DESCRIPTION:
      Edit an existing Plot.
	According to the plot's panelKind-field, the panel editor is
	opened, in which the plot may be changed.
	Afterwards, the display is refreshed.

 INPUTS:
	plotNumber	anInteger. 0<=plotNumber<=widgetData.numberOfPlots
			the index of the plot in widgetData.plotInfos.

 KEYWORDS:
 	group  group-leader widget id

 CALLING SEQUENCE:
	papco_EditPlot, anInteger

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_plotedit.pro:325)

papco_editslots_group_members

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_editslots_group_members
 DESCRIPTION: returns an array of indeces of the plots that are tied to the
   selected plot.  These are fellow overplots. 
 INPUTS:   
   SELECTEDPLOT, int, the plot selected
 KEYWORDS:
 RETURNS: 
   intarr, the list of plots tied to the plot selected
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.10 $
 CURATOR: Jeremy Faden
 HISTORY:  
   27-Jan-2006, 1.7, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco/papco_editslots.pro:50)

papco_edit_Batch

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_edit_Batch

 DESCRIPTION:
      Allows interactive editing of batch files. Makes use of a lot
      of features from panel editors!

 INPUTS:
      none

 KEYWORDS:
      FILENAME  set to a variable returning the chosen Batch File
      BATCH_TIMES set to a variable containing an array of batch times

 MODIFICATION HISTORY:
      June 1998, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_files.pro:1555)

papco_edit_batch_event_event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_edit_batch_event_event, event

 DESCRIPTION:
  This processes events from the XMANAGER.
  As this example does not extend the basic functionality of plot-
  editors, it directly calls the default-handler, papco_PANEL_Event

 INPUTS:
  event       an XManager event

 KEYWORDS:
  none

 CALLING SEQUENCE:
  called by XMANAGER

 MODIFICATION HISTORY:
      June 1998, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_files.pro:1234)

papco_edit_batch_event_refresh

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_edit_batch_event_refresh

 DESCRIPTION:
  This processes refreshes papco_edit_batch widget

 INPUTS:
  none

 KEYWORDS:
            delta - update time step
            duration - update duration - default is delta

 CALLING SEQUENCE:
  called by XMANAGER

 MODIFICATION HISTORY:
      September 2000, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_files.pro:1328)

papco_edit_slice_thumb

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_edit_slice_thumb

 DESCRIPTION:
      Allows interactive editing of slice event files. Makes use of a lot
      of features from panel editors!

 INPUTS:
      plotinfo   a plotinfor structure

 KEYWORDS:
      MJDT        default time range to current papco time range
      BATCH_TIMES set to a variable containing an array of batch times

 MODIFICATION HISTORY:
      February 2003, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/slice_thumbs/papco_slice_panel.pro:604)

papco_edit_slice_thumb_event_event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_edit_slice_thumb_event_event, event

 DESCRIPTION:
	This processes events from the XMANAGER.
	As this example does not extend the basic functionality of plot-
	editors, it directly calls the default-handler, papco_PANEL_Event

 INPUTS:
	event		an XManager event

 KEYWORDS:
 	none

 CALLING SEQUENCE:
	called by XMANAGER

 MODIFICATION HISTORY:
      June 1998, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/slice_thumbs/papco_slice_panel.pro:421)

papco_edit_slice_thumb_event_refresh

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_edit_slice_thumb_event_refresh

 DESCRIPTION:
	This processes refreshes papco_edit_slice_thumb widget

 INPUTS:
	none

 KEYWORDS:
 	refresh actions to be taken

 CALLING SEQUENCE:
	called by XMANAGER

 MODIFICATION HISTORY:
      September 2000, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/slice_thumbs/papco_slice_panel.pro:501)

papco_edit_type[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     
      papco_edit_Type, aPlotInfo, GROUP=GROUP

 DESCRIPTION:  
	creates window with all plot types listed for user to choose new
      type.

 INPUTS:       
	none

 RETURN VALUE: a structure
      {canceled:widgetData.canceled, $
	 panelKind:panelkinds(widgetData.panelKindNr)} panelkind of chosen plot
   	
 KEYWORDS:
 	none
 
 CALLING SEQUENCE:
	papco_edit_Type(aPlotInfo, GROUP=GROUP)

 MODIFICATION HISTORY: 
      written Septembet 1995, Andreas Keese      
      modified December 1995, Reiner Friedel at Goddard

(See /home/jbf/ct/papco/working/papco/papco/papco_edit_type.pro:25)

papco_EnlargeMe

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_EnlargeMe
 DESCRIPTION: enlarges the selected panels and all others at this
    position unless ALONE is set.  Then a joinSlots is done to remove
    the new overlaps.  This is the "Absolute size, Increase" button's action.
 INPUTS:   
 KEYWORDS:
   NOJOIN, keyw, don't do the joinSlots.
   ALONE, keyw, affect just the selected panel.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.10 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco/papco_editslots.pro:509)

papco_EnlargeOthers

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_EnlargeOthers
 DESCRIPTION: enlarges the size of other panels relative to the current
   one.  This is the "Relative Size, Decrease" button's action.
   This is done in two ways:
     a) if the current panel is larger than height "1", it's height
        is reduced.
     b) if the current panel is of height "1", all others are
        enlarged by "1". 
 INPUTS:   
 KEYWORDS:
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.10 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco/papco_editslots.pro:565)

papco_error_handler

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      papco_error_handler

 DESCRIPTION:
	This routine is called when an error occurs on calling a
      user-defined interface routien. A message is printed to the IDL
      transcript window and into an empty panel in the draw window. This is
      useful for trapping errors in the draw loop without crashing PAPCO.

 INPUTS:
	none

 KEYWORDS:


 MODIFICATION HISTORY:
     written august and september 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco.pro:118)

papco_exclude

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_exclude
 DESCRIPTION:  makes a distribution in 200 bins (logarithmic if large enough span
    in data array, and sets top and bottom values to NAN (or NODATA)
 INPUTS:   
   ARRAY, type, description
 OUTPUTS:
   ARRAY, type, description
 KEYWORDS:
   EXCLUDE, type, description
   NODATA, type, description
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.14 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_math.pro:832)

papco_expand_path

 [Previous Routine] [Next Routine] [List of Routines] 
 function:     papco_expand_path

 description:  looks for the standard PAPCO environmental variables
               in a path and expands them.

 inputs:       a path name

 output:       expanded path name

 keywords:     none

 author:       R. Friedel, Febriary 2005

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:2364)

papco_expert

 [Previous Routine] [Next Routine] [List of Routines] 
 function:     papco_expert

 description:  checks if current user belongs to expert group

 inputs:       expert_users, string array of names

 output:       0: not an expert, 1: an expert

 keywords:     none

 author:       R. Friedel, February 2005

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:2419)

papco_file_delete

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_file_delete
 DESCRIPTION: wraps file_delete to support IDL 5.4.  See file_delete

(See /home/jbf/ct/papco/working/papco/papco_lib/opsys/papco_file_delete.pro:28)

papco_file_search

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_file_search
 DESCRIPTION: papco_file_search originally introduced to make idl 5.5's
   file_search run under idl 5.4.  See file_search
 INPUTS:   
   PATH, string|strarr, containing file paths to match
 OUTPUT KEYWORDS:
   COUNT, int, return the number of items found
 RETURNS: 
   strarr, the files found by file_search
 CVSTAG: 
   $Name:  $
   $Revision: 1.4 $
 CURATOR: Jeremy Faden
 HISTORY:  
   22-Sep-2004, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/opsys/papco_file_search.pro:17)

papco_file_template

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_file_template

 DESCRIPTION:  given a path/file template, return the full path to a file.
               This is to accomodate different directory structures
               for data at different sites.

               Recognized strings in template are replaced:
                    $yyyy - four digit year
                      $YY - two digit year
                      $dd - day of month
                      $mm - month of year
                     $doy - day of year
                   $MONTH - month name with same capitalization as input
                            ($MONTH/$Month/$month), truncated at CMONTH_LEN
                   $SATID - satellite name from SATID if set
                    $INST - instrument name from INST if set
                     $VER - version number from VER if set
                     $EXT - file extension from EXT if set

 KEYWORDS:     VERBOSE  - give verbose diagnostic output
               MJDT - use this for the date, default is mjdt_start
               CMONTH_LEN - use this for length of month string
               SATID - use this for satellite string
               INST - use this for instrument string
               VERSION - use this for version string
               EXT - use this for the file extension

 INPUTS:       template string, e.g. /data/GPS_$SATID/$yyyy/

 OUTPUT:       filename with recognized strings replaced

 HISTORY:      written September 2004, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:1972)

papco_file_unzip

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_file_unzip

 DESCRIPTION:  checks if the file is zipped. If yes, unzips the file.
               works on uniz spawn to gunzip
               to avoid rw permissions, files are unzipped to papco_download

 KEYWORDS:     VERBOSE  - give verbose diagnostic output

 INPUTS:       file - name of file. Routine looks for "file.gz"

 OUTPUT:       0 - file not found, zipped or unzipped
               1 - file found and was zipped, has been unzipped
               2 - file found and was not zipped
               3 - file found and was unzipped to tmp location now
                   in orig

 HISTORY:      written September 2004, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:2136)

papco_finddir

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_finddir, path

 DESCRIPTION:  an operating system independent routine to check if a given
               directory path exists.

 INPUTS:       path       string which contains the path to be checked

 OUTPUT:       Function returns:
               1   directory pointed to in path exists
               0   otherwise

 KEYWORDS:     none

 HISTORY:      written Octoberr 1997, Reiner Friedel
               modified to use "catch" and "cd", S. Claflin, March 1998

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:163)

papco_findfile

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_findfile, path, COUNT=COUNT

 DESCRIPTION:  a routine to allow findfile to expand "~" as home dir path

 INPUTS:       path (same as for idl findfile routine)

 OUTPUT:       files found (string array)

 KEYWORDS:     count (same as for idl findfile routine)

 HISTORY:      written October 1999, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:445)

papco_FindOverplots

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_FindOverplots
 DESCRIPTION: returns an array of indices corresponding to the panels
   which overplot the current panel EXACTLY. 
 INPUTS:   
   SPLOT, int, the panel to find overplots for.
 OUTPUTS:
   INDEX, intarr, the overplots for the panel.
 KEYWORDS:
   FULL, keyw, return the full overplot index array for all panels. 
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.10 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco/papco_editslots.pro:681)

papco_find_dates_todo

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_find_dates_todo, dates_source, dates_dest, MSG=MSG

 DESCRIPTION:  a routine to select which dates still need doing from
               a list of done dates and all available dates.
               Used for batch processing.

 INPUTS:       dates_source, dates_dest  string arrays of dates
               msg                    string of message to report

 OUTPUT:       string array of dates still to be done

 KEYWORDS:     VERSION_SOURCE string of source version info, same
                              size as dates_source
               VERSION_DEST   string of dest version info, same
                              size as dates_dest

 HISTORY:      written August 2000, Reiner Friedel
               updated February 2006 for version numbers, RF

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:1034)

papco_find_modules

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
     PRO papco_find_modules

 DESCRIPTION:
     Searches through the !path variable for all directories which include
     the directory called papco_interface
     writes the resulting file papco_module_init.pro (which needs to be
     compiled to compile all modules) to the user's PAPCO_USER.

 INPUTS:
     none

 KEYWORDS:
     NO_WRITE:   don't write an module_init compile file
     QUIET:      no verbose output

 CALLING SEQUENCE:
     papco_find_modules

 MODIFICATION HISTORY:
     written October 1997, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_find_modules.pro:23)

papco_find_shared

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_find_shared
 DESCRIPTION:  routine to find common values in two (or more) arrays
 INPUTS:   
   ARR1, type, description
   ARR2, type, description
   C, type, description
 KEYWORDS:
   IND, type, The common values are indices (or other integer numbers)
   TIME, type, Find common time indices within time resolution
                     given by TIME - NOTE!! Only works if time
                     resolution is the same for the
                     two arrays!
   NIND, type, description
   GEQUAL, type, allow equal (to Nind) or greater than of common occurrences
 OUTPUT KEYWORDS:
   RET_IND, type, the indices in first input array that hold common indices
   RET2_IND, type, the indices in the second input array that hold common indices
 RETURNS: 
   type, description
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.14 $
 CURATOR: NAME
 HISTORY:  
   August 2005, REV, written by A. Aasnes at LANL

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_math.pro:891)

papco_finish

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      papco_finish

 DESCRIPTION:
      perform end-of-life operations for papco session.  These include:
      erasing the state files, storing the default preference settings, etc.

 INPUTS:
      none

 KEYWORDS:
      none

 OUTPUT:

 CALLING SEQUENCE:

 MODIFICATION HISTORY:

(See /home/jbf/ct/papco/working/papco/papco/papco.pro:1429)

papco_flux2psd

 [Previous Routine] [Next Routine] [List of Routines] 
RNING: THERE MAY BE BUGS IN THIS CODE - To Be edited in the next
                                        few months (MH Aug 18, 2006)

ROCEDURE:     
    papco_flux2psd, mu_value, K_value, flux_data, time, eph_module,
    min_energy, max_energy, l_bins, time_bins, PSD

ESCRIPTION:  
    Program takes a value for mu and K, a
    time series array of flux data at a full range of different pitch
    angles (assumes pitch angle bins are evenly spaced from 0-180) and a
    range of energies, and a matching
    array of tai times - it then calculates the PSD (using
    the ephemeris module) vs. time and L*, holding mu and K at
     selected values
                
NPUTS:
    mu_value:  value for first adiabatic invariant, AS A
               PERCENTAGE of the range of mu values from data
               -the program overwrites this value with the value
               of mu in MeV/G
    K_value:   value for second adiabatic invariant, also as a percentage
               - this is also overwritten with units of G^1/2 Re
    flux_data: array of form (time,energy, pitch angle) in flux units of
               electrons/(cm^2 s sr keV)      
    eph_module:name of ephemeris module to retrieve data (K,L*,B) from  
    min_energy:array corresponding to minimum energies of electron
    channel bins, in keV
    max_energy: array corresponding to maximum channel energies

            
UTPUTS: PSD - 2D array of PSD values of form (time,L*) in units 
        (c/cm/MeV)^3  (c = speed of light)
        l_bins - array describing L* bins in PSD array
        time_bins - array describing time bins in PSD array

EYWORDS:  local_b - set this keyword if local measured b-field data
          exists (i.e. not calculated by ephemeris module) - set
          the value of the keyword to the magnetic field array

ALLING SEQUENCE:
   

ODIFICATION HISTORY:       
   written August 2006 Michael Hartinger

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_flux2psd.pro:47)

papco_fname

 [Previous Routine] [Next Routine] [List of Routines] 
 Function:     papco_fname, fname

 description:  formats the filename or directory string correctly for
               the given operating system. For VMS, removes version #

 inputs:       fname : name and value of the env. var. in above format

 output:       the correct fname string

 keywords:     none

 author:       R. Friedel, October 1997

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:400)

papco_gap_plot

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      papco_gap_plot, x, y, nodata, _EXTRA=e

 DESCRIPTION:
      Plots data without connecting y data points flagged with bad data flag.

 INPUTS:
      x,y     arrays to be plotted
      nodata  bad dat flag value

 KEYWORDS:
     same as for plot /oplot routine
     OPLOT     -   use oplot
     AVERAGE   -   average all points in a given range between gaps
                   into one point.
     JUMPS     -   time array has jumps - find and do not plot gaps.
                   value is used to indicate what to use as a "gap"
     SMOOTH    -   smooths data before plotting

 OUTPUTS:
      none

 CALLING SEQUENCE:
      papco_gap_plot, x, y, nodata, _EXTRA=e

 MODIFICATION HISTORY:
     written January 2001, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/line_plot/papco_line_plot_util.pro:150)

papco_GetColor_table

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      FUNCTION papco_GetColor_table

 DESCRIPTION:
	Returns the currently set sub color table index.

 INPUTS:
      none

 KEYWORDS:
      none

 OUTPUT:
      the current set sub color table index

 CALLING SEQUENCE:
	colorindicies=papco_GetColor_table()

 MODIFICATION HISTORY:
     february 1997, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_color.pro:587)

papco_getDrawnPlotInfoStruct

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      papco_getDrawnPlotInfoStruct

 DESCRIPTION:
      This function is used whenever an empty structure of type
      PAPCO_DRAWN_PLOTINFO is needed. To enable later modifications of PAPCO,
      structures of this kind are NEVER defined explicitly - they are
      always created using papco_getPlotInfoStruct(). This struture
      contains all the information needed for a given panel.

 INPUTS:
      none

 KEYWORDS:
      none

 OUTPUT:
      a default-structure of type PAPCO_DRAWN_PLOTINFO
      for its description see the top of this file and the file
      papco_variables.text

 CALLING SEQUENCE:
      aPlotInfoStruct=papco_getDrawnPlotInfoStruct()

 MODIFICATION HISTORY:
      written June 1998, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco.pro:282)

papco_getenv

 [Previous Routine] [Next Routine] [List of Routines] 
 function: papco_getenv, envname

 description:  get a value from an environent variable, checking the result type and possibly creating a
    directory for the first time.  By default, a path name is assumed and the result will end in slash (/).

 inputs:       
    ENVNAME, string, the name of the environment variable

 keywords:     
    URL, keyw, ensure that the env.var is a URL
    DIR, keyw, the env.var must be a directory (create if possible)
    NOFS, keyw, don't do the /dir check

 output:       
    string, the content of the environment variable named ENVNAME, constrained by keywords.

 author:       R. Friedel, October 1997

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:183)

papco_getOrbitInfoFor

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      FUNCTION papco_getOrbitInfoFor, SCraft, anOrbitNr

 DESCRIPTION:
      If possible, get the orbit-information for spacecraft 'SCraft'
      and the orbit with number 'anOrbitNr'
	To do this, the orbit-informations are fetched using
	'papco_readOrbitInfo'. If the hereby returned list contains an orbit
	with number 'anOrbitNr', it is returned.

	If it does not contain such an orbit, a string containing an
	error-text is returned

 INPUTS:
      SCraft          - name of space craft
      anOrbitNr	- an integer from 0..9999
			  the number of the orbit

 OUTPUT:
      an instance of the expanded PAPCO_ORBIT_INFO-structure
	or a string containing an error-description

 CALLING SEQUENCE:
      a=papco_getOrbitInfoFor, 'POLAR', 100
	if n_elements(size(a)) LE 3 then print, 'error'+a

 MODIFICATION HISTORY:
     october 1996, written by R. Friedel
     july 1997, Haje Korth
     May 1999, R. Friedel, to also return orbit time in MFDT format

(See /home/jbf/ct/papco/working/papco/papco/papco_orbitinfo.pro:315)

papco_getOrbitInfoStruct

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      papco_getOrbitInfoStruct

 DESCRIPTION:
      this function is used to create structures of the ORBIT_INFO-
      type. All procedures that use this type should create instances of
      the structure by using this function to enable maintaining.

 INPUTS:
      none

 OUTPUT:
      a Variable of the type ORBIT_INFO
      for a description of its structure, see top of this file

 CALLING SEQUENCE:
      template=papco_getOrbitInfoStruct()

 MODIFICATION HISTORY:
     october 1996, written by R. Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_orbitinfo.pro:76)

papco_getOrbitList

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      papco_getOrbitList

 DESCRIPTION:
	Given the times set by papco, and the satellite mission, this function
 	uses the orbit times file to return a list of orbits spanning the
      required time interval.

 INPUTS:
	none

 KEYWORDS:
      group	the widget-group of the window

 OUTPUT:
      if the user exits using the 'CHOOSE'-button:
         a POLAR_ORBIT_INFO-structure. Its fields are explained in the file
	   'papco_orbitinfo.pro'
	if the user exits using the 'CANCEL'-button:
	   -1

 CALLING SEQUENCE:
	orbInfo=papco_selectOrbit()

 MODIFICATION HISTORY:
     March 1997, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_orbitinfo.pro:871)

papco_getPlotInfoStruct

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_getPlotInfoStruct

 DESCRIPTION:
      This function is used whenever an empty structure of type
      PAPCO_PLOTINFO is needed. To enable later modifications of PAPCO,
      structures of this kind are NEVER defined explicitly - they are
      always created using papco_getPlotInfoStruct(). This struture
      contains all the information needed for a given panel.

      Modifications to this structure must only ADD tags. You will
      need to restart idl after changing this named structure.

 INPUTS: none
 KEYWORDS:  none

 OUTPUT:
      { PAPCO_PLOTINFO_22 }, a default-structure of type PAPCO_PLOTINFO
         for its description see the top of this file and the file
         papco_variables.text

 SIDE EFFECTS:
      modifies its own common block "papco_getPlotInfoStruct_common" which 
         keeps a sequence number useful for debugging.
      defines { PAPCO_PLOTINFO_22 }

 CALLING SEQUENCE:
      aPlotInfoStruct=papco_getPlotInfoStruct()

 MODIFICATION HISTORY:
      written august 1995, Andreas Keese
      modified May 2003, R. Friedel, added POINTER to struct

(See /home/jbf/ct/papco/working/papco/papco/papco.pro:208)

papco_getPrinterInfoStruct

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      FUNCTION papco_getPrinterInfoStruct

 DESCRIPTION:
      return an instance of the papco_PRINTER_INFO-structure

	To enable later modifications of papco,
	structures of this kind are NEVER defined explicitly -
	always use papco_getPrinterInfoStruct() to create such
	a structure.

 INPUTS:
      none

 OUTPUT:
      a papco_PRINTER_INFO-structure

 CALLING SEQUENCE:
      struct=papco_getPrinterInfoStruct()

 MODIFICATION HISTORY:
      september 1995, written by A.Keese
      february 1996, Haje Korth

(See /home/jbf/ct/papco/working/papco/papco/papco_printer.pro:92)

papco_get_Colorindices

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      FUNCTION papco_get_Colorindices

 DESCRIPTION:
	Return the start and end index for the sub color table in use.

 INPUTS:
	c_idx    the index of the papco internal subtable. Allowed Values
                 are 1,2,3. 0 is reserved for to papco default table

 KEYWORDS:
      none

 OUTPUT:
      a two element vector containig the start and end index.

 CALLING SEQUENCE:
	colorindicies=papco_get_Colorindices(c_idx)

 MODIFICATION HISTORY:
     february 1997, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_color.pro:542)

papco_get_converter

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_get_converter
 DESCRIPTION: get a units converter object that converts from FROMUNITS_IN to TOUNITS_IN.  
 INPUTS:   
   FROMUNITS_IN, string, identifier for source units.
   TOUNITS_IN, string, identified for target units.
 KEYWORDS:
   RESET, keyw, rebuild internal table of convertsions.
   P_CHECK_INVERT, keyw, private implementation keyword that indicates we are looking for the inverse.
 RETURNS: 
   , description
 SIDE EFFECTS:
 EXCEPTIONS:
    'unable to convert from...', no converter was found.
 EXAMPLES:
       uc= papco_get_converter( 'mjd2000', 'epoch' )
       pprint, uc  ; 'unitsConverter [ scale:86400000. offset: 6.3113904e+13 ]'
       time_mjd2000= 1.5d  ; noon, 2-Jan-2000
       time_epoch= uc->convert( time_mjd2000 )
       cdf_epoch,  /breakdown_epoch, time_epoch, yy, mon, dd, hr, min, sec
       print,  yy, mon, dd, hr, min, sec  ;         2000   1  2  12  0  0
 SEE ALSO: papco_has_converter
 UNIT TEST: test_papco_ds_units( 2 )
 NOTES: This is a quick and dirty way to handle times.  Note that no chaining is done, only inverting, 
    so all combinations of from and to must be explicitly specified in the implementation for now.
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.8 $
 CURATOR: Jeremy Faden
 HISTORY:  
   13-Sept-2005, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_units.pro:131)

papco_get_data_box

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_get_data_box
 DESCRIPTION:  routine to get data coordinates of box  made when dragging the
    mouse. The box is defined by the first clicked position and the
    release click position. 
 OUTPUTS:   
   STARTTIME, double, min of the time range, in seconds since axis start (TODO CHECK).
   ENDTIME, double, max of the time range, in seconds since axis start (TODO CHECK).
   STARTDATA, double, min of the box data range along Y.
   ENDDATA, double, max of the box data range along Y.
 KEYWORDS:
 SIDE EFFECTS:
 EXCEPTIONS:
   IDL_M_ILLGL_RANGE, when no box has been drawn (widgetData.mouse_panelNr=-1)
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: core.ui
 CVSTAG: 
   $Name:  $
   $Revision: 1.30 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco/papco_cursor.pro:705)

papco_get_default

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_get_default
 DESCRIPTION: returns the default value with this tag.  This provides a standard,
    safe way for getting default values.
 INPUTS:   
   DEFAULTNAME, string, a tag from widgetData.default
 KEYWORDS:
 RETURNS: 
   an IDL type depending on the default, the value of the defaults setting.
 SIDE EFFECTS:
 EXCEPTIONS:
   'default '+defaultName+' does not exist.': DEFAULTNAME is not a valid name, see widgetData.default.
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.91 $
 CURATOR: Jeremy Faden
 HISTORY:  
   2005, REV, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco/papco.pro:461)

papco_get_dirlist

 [Previous Routine] [Next Routine] [List of Routines] 
 function:     papco_get_dirlist, path_name

 description:  returns list of directories found in path_name, or ''
               if none are found

 inputs:       path_name

 output:       the array of directory names

 keywords:     none.

 author:       R. Friedel, November 1997

 changes:      implemented by file_search, jbf 4/28/2005

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:895)

papco_get_dirsep

 [Previous Routine] [Next Routine] [List of Routines] 
 function:     papco_get_dirsep

 description:  returns the character used in !PATH to seperate directories. 
     e.g. ';' for Windows, ':' for unix

 inputs:       none

 output:       the dirsep character

 keywords:     none

 author:       R. Friedel, November 1997

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:1233)

papco_get_ds_cache

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_get_ds_cache
 DESCRIPTION: retrieve the cache with the given ID.  The cache is created if 
   it does not exist.
 INPUTS:   
   CACHE_ID, string, a unique identifier for the cache
 KEYWORDS: none
 RETURNS: 
   { papco_cache }, a papco cache object
 SIDE EFFECTS:
   a cache object may be created and stored in the common block papco_ds_cache_common.
 EXAMPLES:
   cache= papco_get_ds_cache('lanl_gps')
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.25 $
 CURATOR: Jeremy Faden
 HISTORY:  
   Feb 8, 2006, 1.6, written by Reiner Friedel
   March 10, 2006, 1.14, use papco_object_cache to store caches. Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_cache.pro:481)

papco_get_eoln

 [Previous Routine] [Next Routine] [List of Routines] 
 function:     papco_get_eoln

 description:  returns the end-of-line characters for the OS.

 inputs:       none

 output:       string

 keywords:     none

 author:       J. Faden, March 2006

 changes:      -
 notes: consider need for support for darwin

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:1260)

papco_get_libname

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_get_libname

 DESCRIPTION:  return the correct external library name for the
               current operating system.

 KEYWORDS:     VERBOSE  - give verbose diagnostic output
               ONERA    - return ONERA/DESP library from S. Bourdarie

 INPUTS:       none

 OUTPUT:       library name string
               empty strin if not found or not available for opsys.

 HISTORY:      written September 2004, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/opsys/papco_get_libname.pro:16)

papco_get_logger

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_get_logger
 DESCRIPTION:  returns a reference to a logger object for a given role.  Example
     roles include 'end_user' and 'developer'. 
 INPUTS:   
   ROLE, string, logger role identifier.  papco initially defines:
     end_user -- scientist using papco for analysis
     developer -- papco software developer
     wget -- everyone is interested in messages particular to data transfer.  
 KEYWORDS:
 RETURNS: 
   type, description
 SIDE EFFECTS:
   If a logger has not been created already, then it is created with a generic
   logger (log to screen) at 'info' verbosity.
 EXCEPTIONS:
 EXAMPLES:
   logger= papco_get_logger('end_user')
   pprint, logger                          ;; [level warning, log to console]
   logger->finest, 'debugging message'     ;; doesn't print
   logger->warning, 'something great is happening'    ;; prints
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.17 $
 CURATOR: Jeremy Faden
 HISTORY:  
   15 Nov 2004, 1.1, written by Jeremy Faden
   18 Apr 2007, 1.16, automatically add logger

(See /home/jbf/ct/papco/working/papco/papco_lib/logger/papco_logger.pro:234)

papco_get_modstring

 [Previous Routine] [Next Routine] [List of Routines] 
  PROCEDURE:   papco_get_modstring

  DESCRIPTION: checks the control structure and returns the string
               describing the magnetic field model requested. The
               control structure need to contain tags EXTERNAL_MODEL
               and MAG_DYN.

  INPUT:       control structure

  OUTPUT:      model name (string) == ephemeris model tag name

  DATE:        July 2005

  AUTHOR:      A. Aasnes

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_add_mag.pro:715)

papco_get_module_names

 [Previous Routine] [Next Routine] [List of Routines] 
 function:     papco_get_module_names

 description:  given a list of module dirs, returns the module names.

 inputs:       none

 output:       list of module names

 keywords:     none.

 author:       R. Friedel, November 1997

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:967)

papco_get_pathsep

 [Previous Routine] [Next Routine] [List of Routines] 
 function:     papco_get_pathsep

 description:  returns the character used to seperate directories in
               a path name.  Eg. '\' for Windows, '/' for unix.

 inputs:       none

 output:       string, the pathsep character

 keywords:     none

 author:       R. Friedel, May 2003

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:1205)

papco_get_remote_account_info

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_get_remote_account_info

 DESCRIPTION:
      checks the url for "user:password" and gets these interactively.

 INPUTS:
      url   the WGET url string

 KEYWORDS:
  none

 MODIFICATION HISTORY:
     October 1997, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_get_remote_data.pro:871)

papco_get_remote_account_info_event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_get_remote_account_info_event

 DESCRIPTION:
      Event handler for papco_get_remote_account_info

 INPUTS:
      event    Event

 KEYWORDS:
  none

 MODIFICATION HISTORY:
     October 1997, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_get_remote_data.pro:1011)

papco_get_remote_data

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_get_remote_data

 DESCRIPTION:
      Routine downloads data from a remote system using the WGET
      program available from GNU Software.

 INPUTS:
      url            internet address inclusive path, user, passwrd. Syntax:
                     user:pwd@host/path     e.g.
                     friedel:*****@hydra.mpae.gwdg.de//pub/
                     if no user and pwd is given anoymous ftp is used.
                     see the wget man pages for further info.
      filename       filename of data file, e.g. test.dat
      download_dir   download directory

 KEYWORDS:
  none

 MODIFICATION HISTORY:
     written July 1997, Haje Korth
     revised to use file_delete instead of papco_spawn, Nov 2003, J L Roeder

(See /home/jbf/ct/papco/working/papco/papco/papco_get_remote_data.pro:1137)

papco_get_remote_file_list

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_get_remote_file_list

 DESCRIPTION:
      this procedure download the file list of the directory given
      by 'url' using gnu wget

 INPUTS:
      c_url  - the url of a remote host including username, password,
               hostname, path, (eg
               user:passwd@leadbelly.lanl.gov/~\lanl_geo/)
      c_dir  - where the file list shall be saved
      c_file - name of the file list

 KEYWORDS:
  none

 MODIFICATION HISTORY:
     september 1997, Torsten Heise

(See /home/jbf/ct/papco/working/papco/papco/papco_get_remote_data.pro:829)

papco_get_remote_file_list_event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_get_remote_file_list_event

 DESCRIPTION:
      Event handler for papco_get_remote_file_list

 INPUTS:
      event    Event

 KEYWORDS:
  BIN - if this keyword is set write binary file else write text
            file (only use bin if all files have same format )

 MODIFICATION HISTORY:
     september 1997, Torsten Heise

(See /home/jbf/ct/papco/working/papco/papco/papco_get_remote_data.pro:700)

papco_get_remote_host_name

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      FUNCTION papco_get_remote_host_name

 DESCRIPTION:
      this function returns from a given hostname-string the part of
      the string containing only the hostname without username and password

 INPUTS:
      c_host - name of the host
           ( eg ftp://username:password@leadbelly.lanl.gov/~\lanl_geo/ )

 KEYWORDS:
  none

 MODIFICATION HISTORY:
     written september 1997, Torsten Heise

(See /home/jbf/ct/papco/working/papco/papco/papco_get_remote_data.pro:135)

papco_get_slice_data

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_get_slice_data, panelNr

 DESCRIPTION:
      This routine is called by the built in OR user slices to get the
      data for the panel that the mouse is curently in.
      Also checks the ISREAD common, data might not need to be read again
      anyway!

      NEW for PAPCO 10: call the whole draw_plot_type routine. If
      get_data_call is empty, use this method - if not, stick to old
                                                method.

 INPUTS:
      panelNr      no of panel for which to read data

 KEYWORDS:
 	none

 CALLING SEQUENCE:
	called by XMANAGER

 MODIFICATION HISTORY:
     written April 2000, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_slices.pro:1376)

papco_Get_subtable_index

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      FUNCTION papco_Get_subtable_index

 DESCRIPTION:
	Returns the index of the color within the current color
      subtable for a given data value, given the data range.

 INPUTS:
      data    : the data range min, max assigned to the sub color
                table, two element vector
      val     : the data value

 KEYWORDS:
      LOG     : 0 uses linear scale (default), 1 uses log scale

 OUTPUT:
      the sub color table index for the data value.

 CALLING SEQUENCE:
	subtableindex=papco_Get_subtable_index(data,val)

 MODIFICATION HISTORY:
     September 1997, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_color.pro:623)

papco_get_timerange

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_get_timerange
 DESCRIPTION: returns papco's the current timerange control.
 INPUTS: none
 KEYWORDS: none
 RETURNS: 
   , the current timeaxis range.  (Note this is the zoom-in time, not the original timerange entered.)
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES: pprint, papco_get_timerange()
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.91 $
 CURATOR: Jeremy Faden
 HISTORY:  
   Apr 7, 2005, 1.39, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco/papco.pro:502)

papco_Get_zvalue

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      FUNCTION papco_Get_zvalue

 DESCRIPTION:
	Finds the current color sub-table and computes the corresponding
      zvalue for the color index supplied.

 INPUTS:
      index    : the color index to be converted to zvalue
      zrange   : the color bar range used

 KEYWORDS:
      LOG      : if set, then the z-axis is logarithmic

 OUTPUT:
      zval     : [from,to] the range of z-values corresponding to index

 CALLING SEQUENCE:
	zvals=papco_Get_zvalue(index,zrange)

 MODIFICATION HISTORY:
     September 1997, written by Reiner Friedel
     August 2003, modified to handle true color displays, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_color.pro:672)

papco_gunzip

 [Previous Routine] [Next Routine] [List of Routines] 
 Procedure:    papco_gunzip, cmdline, result

 description:  Runs operating system command for gunzipping files
               Action: gunzips files PRESERVING original gzipped file.


 inputs:       cmdline : command line string, needed
               result  : if passed in, pass out output of spawn in it.

 output:       result

 keywords:     VERBOSE - print cmdline before executing

 author:       J. Niehof February 2003 (from papco_unzip R. Friedel)

 changes:      J. Faden September 2004
                 use idl's open,/compress to implement gunzip for non-unix

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:647)

papco_gyroradius

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_gyroradius
 DESCRIPTION:  r = v(perp)/w = mv(perp) /(|q|B)
 INPUTS:   
   E, type, particle energy, in keV
   B, type, mag field, in nT
   ALPHA, type, particle pitch angle
   SPECIES, type, 0 elec, 1 ion, 2 oxygen
 KEYWORDS:
 RETURNS: 
   type,  v(perp)/w = mv(perp) /(|q|B)
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.14 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_math.pro:1117)

papco_gzip

 [Previous Routine] [Next Routine] [List of Routines] 
 Procedure:    papco_gzip, source, result

 description:  Runs operating system command for gzipping files
               Uses gzip -d on UNIX / MAC OS10
               No support for other MAC OS, Windows, or VMS yet.
               Action: gzips files NOT PRESERVING original un-zipped file.


 inputs:       cmdline : command line string, needed
               result  : if passed in, pass out output of spawn in it.

 output:       result

 keywords:     VERBOSE - print cmdline before executing

 author:       R. Friedel, February 2005

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:697)

papco_g_mag_coord

 [Previous Routine] [Next Routine] [List of Routines] 
  FUNCTION:    papco_g_mag_coord

  DESCRIPTION: extracts mag field coords to plot - for use in plot
               routines for ephemeris modules that use papco_add_mag

  INPUT:       control, data, yray, utitle, uytitle, tick_label

  KEYWORDS:    DESC - only return description string of coords, no data

  OUTPUT:      1 if successfull, 0 if coord not found

  DATE:        July 2005

  AUTHOR:      R. Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_add_mag.pro:506)

papco_hasdir

 [Previous Routine] [Next Routine] [List of Routines] 
 function:     papco_hasdir, fname

 description:  checks if fname contains a directory string for
               the given operating system.

 inputs:       fname : input string

 output:       1 if it contains a dir, 0 if not

 keywords:     none

 author:       R. Friedel, October 1997

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:217)

papco_has_converter

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_has_converter
 DESCRIPTION: check to see if papco has a convert that goes from  FROMUNITS to TOUNITS.
 INPUTS:   
   FROMUNITS, string, identifier for source units.
   TOUNITS, string, identified for target units.
 KEYWORDS:
 RETURNS: 
   boolean, 1 if a converter is found, 0 if not.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.8 $
 CURATOR: Jeremy Faden
 HISTORY:  
   13-Sept-2005, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_units.pro:229)

papco_helpfile

 [Previous Routine] [Next Routine] [List of Routines] 
 function:     papco_helpfile

 description:  uses the environment-variable 'PAPCO_PATH' to identify
                                                        the directory

 inputs:       the filename without directory

 output:   the complete filename

 author:       R. Friedel, March 1998

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:1021)

papco_hilmer_phase_space_density[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 papco_hilmer_phase_space_density.pro

 HILMER  PSD CALCULATION
 here we take values min max values of energy channels and calculate
 p^2c^2 as in Hilmer et al., Oct 2000 JGR

INPUTS:
  low_energy_channel_values                   an array containing
                                   values of low energy bins (keV)   

  top_energy_channel_values                   an array containing
                                  values of high energy bins (keV)

  diff_flux       data in diff number flux (#)(s-1 cm-2 sr-1 keV-1)

 KEYWORDS:
          GEM - output PSD in GEM units
          UNITS - return string of units
OUTPUTS:
  PSD   phase space density in units of  s^3 km^-6
 modified July 2003 to add in GEM conversion factor
 GEM PSD UNITS (c/MeV cm)^3

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_hilmer_phase_space_density.pro:24)

papco_horiz_slice

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_horiz_slice, panelNr, seconds, yValue, CLOSE=CLOSE

 DESCRIPTION:
	The slice-window displays a slice through the data,
	when the user clicks in the drawing-widget.
	This procedure opens that window and calls other routines, that draw
	the slice.

 INPUTS:
	panelNr	 	an integer
			the number of the panel for which the slice is to be
			drawn
	seconds		a float
	yvalue		a float
			the time and the y-value, for that the slice shall
			be drawn

 KEYWORDS:
 	CLOSE		when specified, the window is destroyed

 CALLING SEQUENCE:
	papco_horiz_slice, aPanel, seconds
	papco_horiz_slice, /CLOSE

 MODIFICATION HISTORY:
     written May 1998, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_slices.pro:1124)

papco_horiz_slice_Event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_horiz_slice_Event, Event

 DESCRIPTION:
	The slice-window displays a slice through the data,
	when the user clicks in the drawing-widget.
	This procedure handles events for that window.
 INPUTS:
	Event	 	an XMANAGER-event

 KEYWORDS:
 	none

 CALLING SEQUENCE:
	called by XMANAGER

 MODIFICATION HISTORY:
     written May 1998, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_slices.pro:1055)

papco_Input

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_Input, DISABLE=DISABLE, ENABLE=ENABLE

 DESCRIPTION:
      Enable or disable further input to the papco-mainwindow.

 INPUTS:
  none

 KEYWORDS:
  DISABLE     if set, all widgets are made insensitive
  ENABLE      if set, all widgets are made sensitive

 CALLING SEQUENCE:
  to disable input:
  papco_Input, /DISABLE

  to enable input:
  papco_Input, /ENABLE

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco.pro:374)

papco_insertBlankPanel

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_insertBlankPanel
 DESCRIPTION: inserts a blank panel.  This stub was never implemented, and the
    button Reform->"insert blank" does nothing.  TODO: correct this.
 INPUTS:   
 KEYWORDS:
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.10 $
 CURATOR: Jeremy Faden
 HISTORY:  
   10 Dec 2004, 1.4, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco/papco_editslots.pro:338)

papco_interpol[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_interpol

 DESCRIPTION:  wrapper to the IDL function interpol, but extended
               functionality to preserve bad data flags.

 KEYWORDS:     NODATA - bad data flag, default is -99.0
               HOUR   - indicates input array is in hours
                           (deal with 0-24 range)
               LONGITUDE - indicates input array is longitude
                           (deal with 0-360 range)

 INPUTS:       same as IDL function interpol

 OUTPUT:       interpolated array

 HISTORY:      written June 2003, Reiner Friedel
               Modified January 2006, A. Aasnes: Added longitude and
                                                 hour keywords

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_math.pro:630)

papco_interpol[2]

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_interpol, VV, XX, U
 DESCRIPTION:  wrapper to the IDL function interpol, but extended
               functionality to preserve bad data flags.
 INPUTS:   
   VV, fltarr[M], data VV a function of XX
   XX, fltarr[M], absissca values for VV
   U, fltarr[N], absissca values for result
 KEYWORDS:
   HOUR, keyw, use hour wrap around 24.
   LONGITUDE, keyw, use degrees wrap around 360.
   NODATA, double, bad data value, default is -99.0
   SKIP, keyw, do interpolation ignoring bad data points
   _EXTRA, extra keywords are passed to interpol
 RETURNS: 
   fltarr[N], interpolated values of the function VV(XX)
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
    X = FINDGEN(61)/10 - 3  
    V = SIN(X)  
    U = [-2.50, -2.25, -1.85, -1.55, -1.20, -0.85, -0.50, -0.10, $  
       0.30, 0.40, 0.75, 0.85, 1.05, 1.45, 1.85, 2.00, 2.25, 2.75 ]  
    result = INTERPOL(V, X, U)  
    PLOT, X, V  
    OPLOT, U, result  
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.77 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:1162)

papco_joinSlots

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_joinSlots
 DESCRIPTION: Action performed by Reform->"undo overlaps".   This removes all 
     overlaps, preserving panels that are exact overlays.
 INPUTS:   
 KEYWORDS:
   NOREFRESH, type, description
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.10 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco/papco_editslots.pro:241)

papco_keyword

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_keyword

 DESCRIPTION:  a routine set a keyword to a default if not set

 INPUTS:       keyword, default value

 OUTPUT:       value of keyword

 HISTORY:      written April 2002, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:1084)

papco_lastdir

 [Previous Routine] [Next Routine] [List of Routines] 
 function:     papco_lastdir, path

 description:  finds the last directory of a path

 inputs:       path: the name of the dir to be checked

 output:       last dir name

 author:       R. Friedel, February 1998

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:94)

papco_linefill_plot

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      papco_linefill_plot

 DESCRIPTION:
      This precedure fills the area outside, or inside two line
      plots and above or below a line plot
      y data points flagged with bad data flag.

 INPUTS:
      x,y     arrays to be "linefilled"
      nodata  bad dat flag value

 KEYWORDS:
      none

 OUTPUTS:
      plot to current graphics device

 CALLING SEQUENCE:
      papco_gap_plot, x, y, nodata

 MODIFICATION HISTORY:
     written October 2006, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/line_plot/papco_line_plot_util.pro:26)

papco_lineplot

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_lineplot    
 DESCRIPTION: draw a lineplot of a dataset.  If the dataset is vectors, then draw each component
 INPUTS:   
   DS, papco dataset, dataset to plot.  Axis labels etc are derived from properties.
 KEYWORDS:
   [XY]SCALE, fltarr(3), specified both range and log. [min,max,log]
   DRAW_COORDINATES, int,  control which coordinates are drawn.  1=X, 2=Y, 4=Z, 8=MAG
   OUTPUT, boolean, output the data instead of plotting.
   PANEL, intarr(3), papco panel vector indicating the plot is a panel and the axis
      is a timeaxis.
   TIMERANGE, { papco_timerange }, x axis timerange.
   _EXTRA keyword are passed to PAPCO_PLOT
 SIDE EFFECTS: plot coordinate frame is changed.
 EXCEPTIONS:
   wrong dimensionality.  dataset must be rank 1.
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.21 $
 CURATOR: Jeremy Faden
 HISTORY:  
   Sept 2005, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_lineplot.pro:25)

papco_LoadState

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      papco_LoadState

 DESCRIPTION:
      Load the plot product from a file.
  This procedure lets the user pick a filename, from which the data
  are read.

  The format of the written file is determined by the
  papco_getPlotInfoStruct. So, this routine should suffice even if
  you've extended the plotInfo-structure.

      This routine makes use of the general papco_read_struct function.

 INPUTS:
  none

 KEYWORDS:
  FILENAME    if set, don't enquire for name but use filename
  /noErase        if set, don't erase the drawing, which is the default.

 CALLING SEQUENCE:
  papco_LoadState

 MODIFICATION HISTORY:
     written  August 1995, Andreas Keese
     modified February 1997, keyword PRODUCT added, Reiner Friedel
              June 1998, added tag downward compatibilty, Reiner Friedel
              November 2000 to use papco_read_struct, Reiner Friedel
     March, 2007, better support for legacy files.  Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco/papco_files.pro:351)

papco_load_last_state

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      papco_load_last_state

 DESCRIPTION:
      loads up the last state of the panel editor from file. Used to
      recover from a crashed session. A last file should only exist
      if papco was exited abnormnally.
      Panel Editor state files are the same as papco product files.
      naming convention: state_00001.papco, etc, stored in the users
      papco_user/papco_products directory.

 INPUTS:
      none

 OUTPUT:
      none

 CALLING SEQUENCE:
      papco_load_last_state

(See /home/jbf/ct/papco/working/papco/papco/papco_files.pro:2105)

papco_load_next_state

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      papco_load_next_state

 DESCRIPTION:
      loads up the previous state of the panel editor from
      file. Panel Editor state files are the same as papco product files.
      naming convention: state_00001.papco, etc, stored in the users
      papco_user/papco_products directory.

 INPUTS:
      none

 OUTPUT:
      none

 CALLING SEQUENCE:
      papco_load_next_state

(See /home/jbf/ct/papco/working/papco/papco/papco_files.pro:2047)

papco_load_previous_state

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      papco_load_previous_state

 DESCRIPTION:
      loads up the previous state of the panel editor from
      file. Panel Editor state files are the same as papco product files.
      naming convention: state_00001.papco, etc, stored in the users
      papco_user/papco_products directory.

 INPUTS:
      none

 OUTPUT:
      none

 CALLING SEQUENCE:
      papco_load_previous_state

(See /home/jbf/ct/papco/working/papco/papco/papco_files.pro:1996)

papco_Load_SubTable

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_Load_SubTable

 DESCRIPTION:
	Folds a user-specified color table into one of the top three slots
      us the papco internally subdivided colortable. Selects the new
      color table as the active one, and sets it to being unsed.

 INPUTS:
	c_idx    the index of the papco internal subtable. Allowed Values
                 are 1,2,3. 0 is reserved for to papco default table abd
                 cannot be changed.
      r_user, g_user b_user  the three rgb color index arrays, 255
                 colors each.

 KEYWORDS:
 	TABLE      if set it contains the number of a standard IDL color
                 table to be loaded

 CALLING SEQUENCE:
	papco_Load_SubTable,c_idx, r_user, g_user, b_user, TABLE=table

 MODIFICATION HISTORY:
     february 1997, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_color.pro:331)

papco_logcenter

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_logcenter, inarr
 
 DESCRIPTION   calculate log center of array,
               for e.g. channel center energy (energy flux conversions)
 
 INPUTS:       inarr - array of lower and upper channel
                       limits. Format either 1d or 2d, with [2,N]
                       prefered, but [N,2] works as well. Note that
                       if N=2 then it will assume [2,N]

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_math.pro:1044)

papco_logger

 [Previous Routine] [Next Routine] [List of Routines] 
 wrapper for IDL message command.  Use this
 instead of message, so that the message can be 
 handled by a logger instead. 

 For now, just use IDL message.

(See /home/jbf/ct/papco/working/papco/papco_lib/logger/papco_logger.pro:289)

papco_lon64arr

 [Previous Routine] [Next Routine] [List of Routines] 
 function:     papco_lon64arr, dim

 description:  wrapper for lon64arr. returns a lonarr for versions 4
                or less, since these don't support lonar64.

 inputs:       dimension of array

 output:       lon64arr or lonarr

 author:       R. Friedel, October 1999

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco/papco_idlver.pro:129)

papco_mag_filter

 [Previous Routine] [Next Routine] [List of Routines] 
  PROCEDURE:   papco_mag_filter
 
  DESCRIPTION: Routine to filter an array by mag model coords. Note:
               y and eph must be for same time tags

  INPUT:       control - control structure
               utitle  - string for label info on what was filtered
               y       - array to be filtered
               eph     - ephemeris data array used for filtering

  OUTPUT:      y       - with filtered data set to nodata
               utitle  - modified with filter info label added

  KEYWORDS     LABEL   - return label with no xyout formatting
               NODATA  - nodata flag to use
               GET_EPH - read data from the eph module name set here
               INDEX   - array size of y with filtered positions
                         set to one. 
               TAI     - data time if not same as eph time

  DATE:        September 2006

  AUTHOR:      R. Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_add_mag.pro:760)

papco_main_Event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
     PRO papco_main_Event, Event

 DESCRIPTION:
     The main XMANAGER-event-handler.
     All events to the main-window are processed here

 INPUTS:
     event       an XManager-Event

 KEYWORDS:
     USER_EVENT set to the event uvalue for user call of this routine
     NOASK      set to skip any queries

 CALLING SEQUENCE:
     Called by XMANAGER only !

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese
     november 1995, modified by R.Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_event.pro:158)

papco_make_choice_names

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: papco_make_choice_names, INSTR

 DESCRIPTION:  converts the "_info" tag information from a module's
               control structure to a list of choice names fo button widgets.

 INPUTS:       
     INSTR, string, _info string of control block.  For example:
         'HEO Satellite Name; 0: heo_1, 1: heo_3'

 KEYWORDS:     
    TITLE, boolean, return title of choice

 OUTPUT KEYWORDS:
    TITLE, string, the title of the choice

 RETURNS: 
     strarr, list of choice names

 HISTORY:      written June 2003, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:1413)

papco_make_control_info

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_make_control_info

 DESCRIPTION:  creates the _info tag information used in a module's
               control structure.

 KEYWORDS:     TITLE - specifies title of widget

 INPUTS:       instrarr - array of names for choices

 OUTPUT:       list of choice names

 HISTORY:      written January 2007, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:1450)

papco_make_html_help

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: PAPCO_MAKE_HTML_HELP
 DESCRIPTION:  scrapes thorugh IDL files creating HTML documentation for papco's doc block conventions.
 INPUTS:   
   SOURCES, string|strarr, directories to search
   OUTFILE, string, html output file.
 KEYWORDS:
   VERBOSE, type, description
   TITLE, type, description
   STRICT, type, html symbols are escaped, e.g. '<' -> '<'
   STOPS, strarr, array of places to stop for debugging, each element in the format ":"
   RECURSIVE, keyw, recurse through sub directories as well.
   EXCLUDE, string|strarr, patterns that if strmatch is true, is excluded.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.3 $
 CURATOR: NAME
 HISTORY:  
   Apr 15 2007, 1.1, hacked from IDL mk_html_help by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_make_html_help.pro:576)

papco_make_Lvt

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_make_Lvt

 DESCRIPTION:  splits a data v. time array into an "L plot" array.

 KEYWORDS:     NODATA - bad data flag, default is -99.0
               NCUTS - guess at # of L-cuts, (overestimate!)

 INPUTS:       Yst, Yen - required L-range for binning
               t, y, l - time, data, l array, same base

 OUTPUT:       Y_arr - L-bins, start/end
               T_cut - start/end time of cut,
               Zarr  - L-binned data

 HISTORY:      written June 2003, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:1316)

papco_make_new_module[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 This file is part of the PAPCO software package.

 PAPCO is a free IDL package to combine data plots written and
 maintained by A. Keese and R. Friedel.

    For more information, check the papco home page at
    http://leadbelly/ccr/software/papco/papco.html
    for online Manual and downloadble latest version.

 Comments and questions can be directed to friedel@lanl.gov

 You are free to modify and distribute this file. However, and
 changes not communicated to R. Friedel will not become part of the
 next release of PAPCO.

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_make_new_module.pro:16)

papco_make_new_module[2]

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
     PAPCO_MAKE_NEW_MODULE

 PURPOSE:
     Utility program for papco developers - makes a "new" module directory
     structure. Takes the modules template and copies it to the newly created
     module directory. Then globally changes all occurrences of the module
     name in both files and file names to the name of the module.
     By default the new tree is created under the papco_modules directory
     in the distribution.

 CATEGORY:
     Developers utility

 CALLING SEQUENCE:
     papco_make_new_module, Name

 INPUTS:
     Name: String, the new module name

 KEYWORD PARAMETERS:
                   VAR_TYPE  ACTION                           DEFAULT
  MODULE_TEMPLATE: string    template module to use           'plot_type'
  MODULE_PATH:     string    location of new module.          location is
                             If = 'own', location is          $PAPCO_MODULES
                             $PAPCO_USER /papco_user_modules
         INFO:     integer   Calls doc_library to display     0 (no output)
                             this header documentation.
                             1: print to terminal,
                             2: print to default printer
  log     logger object to receive messages
  status  eq 0 success, ne 0 fail

 OUTPUTS:
     none. New module constructed.

 EXAMPLE:
     papco_make_new_module, 'crres_meb', MODULE_PATH='own'

 MODIFICATION HISTORY:
     Written by:  August 1998, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_make_new_module.pro:59)

papco_make_new_module[4]

 [Previous Routine] [Next Routine] [List of Routines] 
 CALL (add_sub_plot_type):
     PRO add_sub_plot_type, module, sub_type, MODULE_PATH=MODULE_PATH

 DESCRIPTION:
     Utility program for papco developers - adds a new sun plot type
     to an exisiting module.
     This assumes that the original module was either made with
     make_new_module or otherwise adheres to all PAPCO conventions.

 INPUTS:
    module    The exisiting module name, eg. "polar_ceppad"
    sub_type  The new subtype (not including module name) eg. "spec"

 KEYWORDS:     VAR_TYPE  ACTION                       DEFAULT
  MODULE_PATH  string    location of new module.      location is
                         If = 'own', location         $PAPCO_MODULES
                         is $PAPCO_USER
                              /papco_user_modules
     INFO      boolean   print this header and any    Do nothing
                         other info for routine
   TEMPLATE    string    use this module as template  use plot_type template

   PANEL_KIND  string(2) use panel_kind(0) kind of     ['',sub_type]
                         panel, renamed to panel_kind(1)
   PLOT_KIND   string(2) use plot_kind(0) kind of      ['line','line']
                         plot, renamed to plot_kind(1)
   READ_KIND   string(2) use read_kind(0) kind of      ['',sub_type]
                         read, renamed to read_kind(1)


 OUTPUT:
     none

 MODIFICATION HISTORY:
     written October 1999, Reiner Friedel
*****************************************************************************

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_make_new_module.pro:212)

papco_make_new_module_tool

 [Previous Routine] [Next Routine] [List of Routines] 
 create widget to get make new module parameters, 
 run make new module.

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_make_new_module_tool.pro:34)

papco_math[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 papco_levels

 DESCRIPTION locate levels (like median) in data array

 
 KEYWORDS: NODATA - bad data flag, default is -99.0
           CUMULATIVE - 

 INPUTS: arr - array to find levels in
         levels - array of levels to identify (0.5=median)

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_math.pro:437)

papco_math[2]

 [Previous Routine] [Next Routine] [List of Routines] 
 papco_total

 DESCRIPTION Wrapper routine to IDL total, do be able to check for
 nodata

 KEYWORDS: NODATA - bad data flag

 INPUTS: arr - array to sum
         dim - dimension to sum over, starting at 1 to comply with
               idl routines!!!

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_math.pro:463)

papco_math_gcd

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:   papco_math_gcd 
 DESCRIPTION:  rreturn the greatest common divisor of a set of numbers A, a number such
   that i*result = A[k] where i is an integer for all k.
 INPUTS:   
   A_IN, fltarr
 KEYWORDS:
   ERRTOT, float, tolerance for floating point numbers.  0 is default.
   GUESS, a starting guess for the iterative algorithm.
 RETURNS: 
   float, the greatest common divisor.
 SIDE EFFECTS:
 EXCEPTIONS:
   IDL_M_BADARRSUB, if all elements of A are zero.
 EXAMPLES:
    print, papco_math_gcd( [ 0.6, 0.9, 1.2, 0.0 ] )  ;  0.3 is result
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.14 $
 CURATOR: Jeremy Faden
 HISTORY:  
   1997, 1.10, written by Jeremy Faden at U of Iowa

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_math.pro:1300)

papco_math_gcd1

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:   papco_math_gcd1  
 DESCRIPTION:  return the greatest common divisor of two numbers, a number such
   that i*result = A_IN  and j*result=B_IN where i and j and integers.
 INPUTS:   
   A_IN, float, a non-zero float
   B_IN, float, a non-zero float
 KEYWORDS:
   ERRTOT, float, tolerance for floating point numbers.  0 is default.
 RETURNS: 
   float, the greatest common divisor.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.14 $
 CURATOR: Jeremy Faden
 HISTORY:  
   1997, 1.10, written by Jeremy Faden at U of Iowa

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_math.pro:1256)

papco_mean[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
       PAPCO_MEAN
 PURPOSE:
       Return the average value of an array, or 1 dimension of an array
 EXPLANATION:
       Calculate the average value of an array (in which case AVG is identical
       to the RSI procedure mean.pro), or calculate the average
       value over one dimension of an array as a function of all the other
       dimensions.

 CALLING SEQUENCE:
       RESULT = PAPCO_MEAN( ARRAY, [ DIMENSION, /NAN, /DOUBLE,NODATA=NODATA ] )

 INPUTS:
       ARRAY = Input array.  May be any type except string.

 OPTIONAL INPUT PARAMETERS:
       DIMENSION = Optional dimension to do average over, integer
       scalar (from 0)

 OPTIONAL KEYWORD INPUT:
      /NAN - Set this keyword to cause the routine to check for occurrences of
            the IEEE floating-point value NaN in the input data.  Elements with
            the value NaN are treated as missing data.
      /DOUBLE - By default, if the input Array is double-precision, complex,
                or double complex, the result is of the same type;  64 bit
                integers are also returned as double.   Otherwise the result
                the  result is floating-point.   Use of the /DOUBLE keyword
                forces a double precision output.   Note that internal
                computations are always done in double precision.
      NODATA -  Specify a value indicating missing or bad data that
                will be excluded from the mean
      EXCLUDE - 1 or 2 element array,N, between 0 and 1 (<0.5 if 2
                element). The bottom N(0), top N(1) part of the
                distribution is removed before taking the mean
 OUTPUTS:
       The average value of the array when called with one parameter.

       If DIMENSION is passed, then the result is an array with all the
       dimensions of the input array except for the dimension specified,
       each element of which is the average of the corresponding vector
       in the input array.

       For example, if A is an array with dimensions of (3,4,5), then the
       command B = AVG(A,1) is equivalent to

                       B = FLTARR(3,5)
                       FOR J = 0,4 DO BEGIN
                               FOR I = 0,2 DO BEGIN
                                       B[I,J] = TOTAL( A[I,*,J] ) / 4.
                               ENDFOR
                       ENDFOR

 RESTRICTIONS:
       Dimension specified must be valid for the array passed; otherwise the
       input array is returned as the output array.
 PROCEDURE:
       AVG(ARRAY) = TOTAL(ARRAY, /DOUBLE)/N_ELEMENTS(ARRAY) when called with
       one parameter.
 MODIFICATION HISTORY:
       William Thompson        Applied Research Corporation
       July, 1986              8201 Corporate Drive
                               Landover, MD  20785
       Converted to Version 2      July, 1990
       Replace SUM call with TOTAL    W. Landsman    May, 1992
       Converted to IDL V5.0   W. Landsman   September 1997
       Added /NAN keyword   W. Landsman      July 2000
       Accept a scalar input value    W. Landsman/jimm@berkeley   November 2000
       Internal calculations always in double precision W. Landsman March 2002
       Return NAN if all values in array are NAN  W. Landsman April 2002
       Fixed coding bug if all values in array are NAN W. Landsman
       Jan 2004
       Added exclude option /keyword A. Aasnes, October 2005

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_math.pro:256)

papco_mean[2]

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
       PAPCO_MEAN
 PURPOSE:
       Return the average value of an array, or 1 dimension of an array
 EXPLANATION:
       Calculate the average value of an array (in which case AVG is identical
       to the RSI procedure mean.pro), or calculate the average
       value over one dimension of an array as a function of all the other
       dimensions.

 CALLING SEQUENCE:
       RESULT = PAPCO_MEAN( ARRAY, [ DIMENSION, /NAN, /DOUBLE,NODATA=NODATA ] )

 INPUTS:
       ARRAY = Input array.  May be any type except string.

 OPTIONAL INPUT PARAMETERS:
       DIMENSION = Optional dimension to do average over, integer scalar

 OPTIONAL KEYWORD INPUT:
      /NAN - Set this keyword to cause the routine to check for occurrences of
            the IEEE floating-point value NaN in the input data.  Elements with
            the value NaN are treated as missing data.
      /DOUBLE - By default, if the input Array is double-precision, complex,
                or double complex, the result is of the same type;  64 bit
                integers are also returned as double.   Otherwise the result
                the  result is floating-point.   Use of the /DOUBLE keyword
                forces a double precision output.   Note that internal
                computations are always done in double precision.
      NODATA -  Specify a value indicating missing or bad data that
                will be excluded from the mean
      EXCLUDE - 1 or 2 element array,N, between 0 and 1 (<0.5 if 2
                element). The bottom N(0), top N(1) part of the
                distribution is removed before taking the mean
 OUTPUTS:
       The average value of the array when called with one parameter.

       If DIMENSION is passed, then the result is an array with all the
       dimensions of the input array except for the dimension specified,
       each element of which is the average of the corresponding vector
       in the input array.

       For example, if A is an array with dimensions of (3,4,5), then the
       command B = AVG(A,1) is equivalent to

                       B = FLTARR(3,5)
                       FOR J = 0,4 DO BEGIN
                               FOR I = 0,2 DO BEGIN
                                       B[I,J] = TOTAL( A[I,*,J] ) / 4.
                               ENDFOR
                       ENDFOR

 RESTRICTIONS:
       Dimension specified must be valid for the array passed; otherwise the
       input array is returned as the output array.
 PROCEDURE:
       AVG(ARRAY) = TOTAL(ARRAY, /DOUBLE)/N_ELEMENTS(ARRAY) when called with
       one parameter.
 MODIFICATION HISTORY:
       William Thompson        Applied Research Corporation
       July, 1986              8201 Corporate Drive
                               Landover, MD  20785
       Converted to Version 2      July, 1990
       Replace SUM call with TOTAL    W. Landsman    May, 1992
       Converted to IDL V5.0   W. Landsman   September 1997
       Added /NAN keyword   W. Landsman      July 2000
       Accept a scalar input value    W. Landsman/jimm@berkeley   November 2000
       Internal calculations always in double precision W. Landsman March 2002
       Return NAN if all values in array are NAN  W. Landsman April 2002
       Fixed coding bug if all values in array are NAN W. Landsman
       Jan 2004
       Added exclude option /keyword A. Aasnes, October 2005

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:1544)

papco_message

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_message, MSG
 DESCRIPTION: display a message to the user that requires
   acknowledgement, possibly holding up all other processing.
   Works in the headless or graphical environment. 
 INPUTS:   
   MSG, string|strarr, the message to convey
 KEYWORDS:
   INFORMATION, keyw, informational message only.
   QUESTION, keyw, question is asked.
   TITLE, string, dialog title
   HEADLESS, keyw, force headless mode--message is displayed on stdout
   ACTIONS, struct|structarr, add additional actions to the widget. 
      Structures have the form { label:'', callback:'' }
   THANKS, keyw, have okay button say "thanks" instead of "OK"
   DIALOG_PARENT, long, parent widget to follow.
 RETURNS: 
   string, the button label pressed ('ok', 'no', etc.)
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.11 $
 NOTES: currently this uses widget_message, until issues with modal are worked out.
 CURATOR: Jeremy Faden
 HISTORY:  
   Dec 2, 2004, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco/papco_message.pro:110)

papco_module_Configure

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_module_Configure

 DESCRIPTION:
      Displays the configuration widget for the environmental

 INPUTS:
      module, name, papco module name

 KEYWORDS:
    reset_out, boolean, 1 if the module was reset.

 OUTPUT:
      Writes configuration file containing environmental variables used
      by the module

 MODIFICATION HISTORY:
     written July 1997, Haje Korth
     modified October 1997, Reiner Friedel, to work under VMS

(See /home/jbf/ct/papco/working/papco/papco/papco_module_configure.pro:21)

papco_module_Configure_event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_module_Configure_event

 DESCRIPTION:
      Event handler for papco_module_Configure

 INPUTS:
      none

 KEYWORDS:
  none

 MODIFICATION HISTORY:
     written July 1997, Haje Korth

(See /home/jbf/ct/papco/working/papco/papco/papco_module_configure.pro:123)

papco_module_dependence

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_module_dependence

 DESCRIPTION:
      Looks up a list of modules that depend on other modules, sets
      those so that they also get compiled in.

 INPUTS:
      set     logical array for standard modules 0 - not set, 1 -
                                                     set
      unset= index  finish unset action by also unsetting codependent
                    modules

 KEYWORDS:
      none

 MODIFICATION HISTORY:
     written August 1999, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_configure.pro:1494)

papco_module_helpfile

 [Previous Routine] [Next Routine] [List of Routines] 
 function:     papco_module_helpfile

 description:  uses the environment-variable 'papco_modules' to identify
               the directory containing the helpfile

 inputs:       the filename without directory

 output:   the complete filename

 author:       A.Keese, august 1995

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:29)

papco_module_version

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
     PAPCO_MODULE_VERSION

 PURPOSE:
     This function returns a string containing the current version of
     a papco module. This information is read from the header of the
     help file associated with that module / subplot type.
     It is used to label the panel editor window of the module /sub
     type. Date MUST be of format "dd mmm yyyy" and MUST come at end
     of string. 

 CATEGORY:
     Documentation

 KEYWORD PARAMETERS:
     INFO:   Calls doc_library to display this header documentation.
             1: print to terminal, 2: print to default printer

 INPUTS:
     Module:  name of module, string

 CALLING SEQUENCE:
     Result = PAPCO_MODULE_VERSION()

 OUTPUTS:
     This function returns a string of the module version information.

 MODIFICATION HISTORY:
     Written by:  Reiner Friedel, May 1998
     Modified:    Each time a new version is released

(See /home/jbf/ct/papco/working/papco/papco/papco_module_version.pro:48)

papco_MoveDown

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_MoveDown
 DESCRIPTION:  moves the panel down by one.  This is the "Down" button's action.
 INPUTS:   
 KEYWORDS:
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.10 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco/papco_editslots.pro:396)

papco_MoveUp

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_MoveUp
 DESCRIPTION: moves the selected panel up by one.  This is the "Up" button's action.
 INPUTS:   
 KEYWORDS:
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.10 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco/papco_editslots.pro:363)

papco_multiple_slice_Event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_multiple_slice_Event, Event

 DESCRIPTION:
	The multiple slice-window displays a list of possible slices
      and allows the user to choose more than one.
	This procedure handles events for that window.

 INPUTS:
	Event	 	an XMANAGER-event

 KEYWORDS:
 	none

 CALLING SEQUENCE:
	called by XMANAGER

 MODIFICATION HISTORY:
      written march 2000, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_slices.pro:1272)

papco_mu_calculation[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:     
      papco_mu_calculation, low_channel_values, high_channel_values,
                            mu_value, particle_data, mag_data
 
 DESCRIPTION:  
	program takes energy bin information, particle (time vs
      channel) and magnetic field data (of same time range as
      particle data), and calculates PSD at selected mu value note
      (particle data in format (data, channel)) code calls
      papco_hilmer_phase_space_density to calculate PSD's   
                  
 INPUTS:
      low_channel_values:  energy bin top values in keV
      high_channel_values: energy bin bottom values in keV
      particle_data:       (data, channel) in dnf (cm-2 s-1 sr-1 KeV-1)
      mag_data:            mag field Mag., same timebase as particle_data
      mu_value:            mu in MeV/G 
        
              
 OUTPUTS: PSD_at_constant_mu, array of data same size as input data
         (ie one value per time step) containing PSD values
         (s3km-6) for constant mu value input
   
 KEYWORDS:
      
          
 CALLING SEQUENCE:
     

 MODIFICATION HISTORY:       
     written MARCH 2003 Matt Taylor
     MAY 2003 realised error in energy at mu not relativistic  
     Apr 2006 removing some unnecessary loops A. Aasnes @ lanl 
              ended up rewriting part of the module
                     - finding energy of constant mu and calculating
                       psd for given energy channels. Then
                       interpolate psd to energy of constant mu

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_mu_calculation.pro:39)

papco_m_batch

 [Previous Routine] [Next Routine] [List of Routines] 
  NAME:        papco_m_batch

  DESCRIPTION: Makes a batch list containing times for which a given
               source data file exists without a corresponding
               destination data file 

  INPUT:       none

  KEYWORDS:    VERBOSE - give verbose progress output to xterm
               BEFORE  - string of date to stop at, yyyymmdd
               FROM    - string of date to start from, yyyymmdd

               PROJECT - string of project, e.g. 'lanl_mpa'
               ROOT    - data root directory - default $PAPCO_DLNK

               SOURCE  - source file type
               DEST    - destination file type
               SAT     - string id of spacecraft
               FORCE   - 0: (default) Do all dates in source not in dest,
                            ignore problem file
                         1: Force all dates in source, ignore problem files
                         2: Do all dates in source not in dest
                         3: Force all dates in source
                         4: Force only problem files
               SAME    - instead of missing dates, report same dates
               WRITE   - write batch list to file
               DATES   - return here string array of the dates only
               SPAN    - # of +days to span batch times
               STEP    - # of days to step in batch
               FILLIN  - fill in all source days from first date - span
                         to last date + span
               VERSION - version number of destination file. Any
                         destination files with version numbners
                         lower than this need to be reprocessed

  OUTPUT:      batch_times - start / end times for available data
               filename    - suggested default filename for batch file

  DATE:        October 2006

  AUTOR:       R. Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_m_batch.pro:43)

papco_m_lspec

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:    papco_m_lspec, control, xut1, xut2, time, ymat, lval, yst, yen,
                              Y_arr, T_cut, Zarr, utitle, NODATA = nodata

 DESCRIPTION:  general method to make L-spec based on flux v. time and L
               v. time data. Needs lbin and ltav set in control structure.

 KEYWORDS:     NODATA = nodata value for invalid data in data array

 INPUTS:       

 OUTPUT:       

 HISTORY:      written February 2007, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:2843)

papco_new_time

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_new_time
 DESCRIPTION: creates a new timeDatum object from a variety of inputs. 
 INPUTS:   
   ARG, string|double, argument to be handled according to keywords.
 KEYWORDS:
   YEAR, int, description
   MONTH, int, description
   DOM, int, description
   DOY, int, description
   JULIAN, long, get year, month, day from here.
   MJD, int, datum's modified julian day, days since 1958.
   TAI, keyw, ARG is tai, use tai converter.
   HOURS, int, description
   MINUTES, int, description
   SECONDS, int, description
   MILLISECONDS, int, description
   MICROSECONDS, int, description
   NANOSECONDS, int, description
   TIMEARR, lonarr[7], [ year, month, day, hour, minutes, seconds, nanos ]
   COUNTRY, int, hint to use when formatting.  0=US, 1=Europe, 2=YEAR/DOY
   UNITS, string, units identifier like "mjd2000" when ARG is double.
 RETURNS: 
   , time object according to inputs
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
    t1= papco_new_time( '2004/005 00:09' )
    t2= papco_new_time( year=2004, doy=005, hour=0, minute=10 )
    pprint, t2->diffSeconds( t2 )
 NOTES:  Note that presently there is no garbage collection of timeDatum
   objects, so to be safe, be sure to destroy the objects when finished.
    This should not be an issue when < thousands of objects are
    produced.  This problem might be resolved by maintaining a pool
    of objects that are recycled.
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.25 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_time.pro:262)

papco_new_timerange

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_new_timerange, TIME1, TIME2
 DESCRIPTION: create a new timerange object, supporting a variety of specifications.
 INPUTS:   
   TIME1, string|double|{ mjdt struct }|, start time or time range string.
        if a string, then TIME1_IN is parsed as a time range using papco_parse_timerange.  
        if a double or { mjdt struct }, then a papco_new_time is called to create a  for the range start.
        if a , then this is the range start.
   TIME2, double|{ mjdt struct }|, stop time.
        if a double or { mjdt struct }, then a papco_new_time is called to create a  for the range start.
        if a , then this is the range start.
 KEYWORDS:
   _EXTRA, extra keywords are passed to papco_new_time, including:
   TAI, keyw, doubles are tai.                         
   UNITS, string, doubles are in this unit.
 RETURNS: 
   , a time range object.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
     tr= papco_new_timerange( 0, 86400, /tai )
     pprint, tr
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.23 $
 CURATOR: Jeremy Faden
 HISTORY:  
   31-Oct-2005, 1,1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_timerange.pro:63)

papco_Normal_To_Data

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      FUNCTION papco_Normal_To_Data, panelNr, normal_position

 DESCRIPTION:
      Convert a normal coordinate to data-coordinates of a certain
      panel.

 INPUTS:
	panelNr, int,    the coordinates will be transformed using the
			 coordinate-system of widgetData.plotsDrawn(panelNr)
	normal_position, fltarr[2], [ x-coordinate, y-coordinate ]

 KEYWORDS:
 	none

 RETURNS:
      fltarr[2], [ x-data-coordinate, y-data-coordinate ]

 CALLING SEQUENCE:
	tmp=papco_Normal_To_Data( 0, [x_normal, y_normal])
	x_data=tmp(0)
	y_data=tmp(1)

 MODIFICATION HISTORY:
     written august and september 1995, Andreas Keese
     modified october 1997, Reiner Friedel, to make USER mouse
     feateres configurable by user.

(See /home/jbf/ct/papco/working/papco/papco/papco_cursor.pro:201)

papco_Norm[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_Norm

 DESCRIPTION:  Wrapper routine to the IDL norm to be able to pass in
               arrays and check for NODATA flags

 KEYWORDS:     NODATA  - bad data flag, default is -99.0

 INPUTS:       x    - array of x component
               y    - array of y component
               z    - array of z component

 OUTPUT:       euclidian norm of [x,y,z]

 HISTORY:      written August 2005, Arne Aasnes

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_math.pro:502)

papco_Norm[2]

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_Norm

 DESCRIPTION:  Wrapper routine to the IDL norm to be able to pass in
               arrays and check for NODATA flags

 KEYWORDS:     NODATA  - bad data flag, default is -99.0

 INPUTS:       x    - array of x component
               y    - array of y component
               z    - array of z component

 OUTPUT:       euclidian norm of [x,y,z]

 HISTORY:      written August 2005, Arne Aasnes

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_math.pro:540)

papco_Norm[3]

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_Norm

 DESCRIPTION:  Wrapper routine to the IDL norm to be able to pass in
               arrays and check for NODATA flags

 KEYWORDS:     NODATA  - bad data flag, default is -99.0

 INPUTS:       x    - array of x component
               y    - array of y component
               z    - array of z component

 OUTPUT:       euclidian norm of [x,y,z]

 HISTORY:      written August 2005, Arne Aasnes

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:1651)

papco_Occupy_SubTable

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_Occupy_SubTable

 DESCRIPTION:
	Set the specified subtable as currently in use.

 INPUTS:
	c_idx    the index of the papco internal subtable. Allowed Values
                 are 1,2,3. 0 is reserved for to papco default table

 KEYWORDS:
      none

 CALLING SEQUENCE:
	papco_Occupy_SubTable, c_idx

 MODIFICATION HISTORY:
     february 1997, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_color.pro:510)

papco_oldPanelList::refresh

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_oldPanelList::refresh

 DESCRIPTION:
      Refresh the listbox to display the currently selected plots

 INPUTS:
  none

 KEYWORDS:
  LIST  =  if set to 2, then also reset total panels.

 CALLING SEQUENCE:
  papco_RefreshList

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese
     26 Jan 2006, converted into object, Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco/papco_panellist.pro:363)

papco_onera_init

 [Previous Routine] [Next Routine] [List of Routines] 
 DESCRIPTION:  Sets up commons for ONERA-DESp library, checks
               operating system and availablility of libraries

(See /home/jbf/ct/papco/working/papco/papco_lib/onera/papco_onera_init.pro:4)

papco_opsys_path

 [Previous Routine] [Next Routine] [List of Routines] 
 Procedure:    papco_opsys_path, path

 description:  Checks path string for conformity to operating system rules
               Changes all instances of directory separator character
               No support for other MAC OS or VMS .


 inputs:       path :    String containing paths, ie '/n/radbelt/crres'

 output:       path is modified in place

 keywords:     None.

 author:       J. Roeder, November 2003

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:1155)

papco_orbitDescriptionList

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      FUNCTION papco_orbitDescriptionList, orbitInfo, CACHE_THIS=CACHE_THIS

 DESCRIPTION:
      This function is mainly used by papco_selectOrbitinfo.pro. It creates
      a string array containing descriptions for all orbits in the
	parameter 'orbitInfo'.
	This list is the list that's displayed in the list-window of the
	orbit-selection-widget.
	Once the description-list is created, it is cached in the common-
	variable 'orbitDescriptions', if the keyword 'CACHE_THIS' was set.

 INPUTS:
      orbitInfo	the array of orbit-descriptions for which infos
			shall be generated

 KEYWORDS:
 	CACHE_THIS	if set, the generated descriptions are cached in
			'orbitDescriptions'.

 OUTPUT:
      a string array	containing verbose descriptions for each orbitInfo
			in the array 'orbitInfo'

 CALLING SEQUENCE:
      -

 MODIFICATION HISTORY:
     october 1996, written by R. Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_orbitinfo.pro:120)

papco_Orbit_Selected

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_Orbit_Selected, anOrbitInfo

 DESCRIPTION:
      This procedure is called, when the user chooses an orbit in the orbit
	select-window. The number of the orbit is passed to papco_SETOrbit

 INPUTS:
	anOrbitInfo	a structure of type papco_ORBITINFO

 KEYWORDS:
 	none

 CALLING SEQUENCE:
	papco_Orbit_Selected, anOrbitInfo
	called by papco_SelectOrbit ONLY

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_settime.pro:295)

papco_output

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION
      papco_unformat_idlstring

 DESCRIPTION:
	Removes any "!" format strings from a given string and
      converts it to readable straight text only.

 INPUTS:
      idlstr          the idl formatted string

 OUTPUTS:
      textstr         the unformatted text only string

 KEYWORDS:
 	none

 CALLING SEQUENCE:
	called from papco_write_data
      textstr=papco_unformat_idlstring(idlstr)

 MODIFICATION HISTORY:
     written May 1998, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_output.pro:50)

papco_panelList::refresh

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_panelList::refresh

 DESCRIPTION:
      Refresh the listbox to display the currently selected plots
  new format--try to make it look more like the page.

 INPUTS:
  none

 KEYWORDS:
  LIST  =  if set to 2, then also reset total panels.

 CALLING SEQUENCE:
  papco_RefreshList

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_panellist.pro:45)

papco_panel_AddActionButtons

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: papco_panel_AddActionButtons, aBase, action

 DESCRIPTION:
      Add the default-buttons to the panelplot-editor 'aBase'. These
      are the help-button, the cancel-button and the action-button.
	The action-button's label is the input-variable 'action'.

 INPUTS:
      aBase	 	a WIDGET_BASE
			the base, the widgets are to be added to
	action		a string
			this is the label of the 'done'-button

 KEYWORDS:
 	VERTICAL        sets vertical arrangement of action buttons
 	widgetInfo      add widgetInfo to this structure

 OUTPUT:
      a structure with the neccessary tag-fields

 CALLING SEQUENCE:
      widgets=papco_panel_AddActionButtons(panel_base, Action, plotinfo)
      additionalWData=create_struct(widgets, additionalWData)

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:676)

papco_panel_AddBatch_Widgets

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: papco_panel_AddBatch_Widgets, aBase, plotinfo
 DESCRIPTION:  
 INPUTS:   
   ABASE, long, widget base in which to install widget
   PLOTINFO, struct, description
 KEYWORDS:
   REDO, strarr, description
   _EXTRA, extra keywords are passed to widget_base.
 RETURNS: 
   struct, structure containing the data for the widget.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.60 $
 CURATOR: NAME
 HISTORY:  
   written January 2001, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:1675)

papco_panel_Addcolorbar_Widgets

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: papco_panel_Addcolorbar_Widgets, aBase, plotinfo

 DESCRIPTION:
      Add exclusive-buttons for selecting the papco internal Color Bars
      A choice of four color bars is built in. These are sub-colorbars
      dividing the main color bar into four. Color Bar 0 (bottom of table)
      is default (GSFC Rainbow).

 INPUTS:
	aBase	 	a WIDGET_BASE (an integer)
			the base, you want the widgets to add to
      plotinfo	a structure containing a least those fields from
			from the PAPCO_PLOTINFO-structure:
			     channel
			It is used to set the initial values for these
			widgets

 KEYWORDS:
 	widgetInfo      add widgetInfo to this structure

 OUTPUT:
      a structure containing the widget-ids of the added entry-fields

 CALLING SEQUENCE:
	tmp=papco_panel_Addcolorbar_Widgets(panelBase, plotinfo)

 MODIFICATION HISTORY:
      written february 1997, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:1036)

papco_panel_AddDescr_Widgets

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: papco_panel_AddDescr_Widgets, aBase, plotinfo

 DESCRIPTION:
      Add a widget for specifying own plot description label at right of
      panel.

 INPUTS:
	aBase	 	a WIDGET_BASE (an integer)
			the base, you want the widgets to add to
      plotinfo	a structure containing a least those fields from
			from the papco_PLOTINFO-structure:
			     soptions
			soptions(15) and iotions(15) is used to set the initial
			values for this widget.

 KEYWORDS:
 	VERTICAL        makes vertical slider if set. Default is horizontal.

 OUTPUT:
      a structure containing the widget-ids of the added entry-fields

 CALLING SEQUENCE:
	tmp=papco_panel_AddDescr_Widgets(panelBase, plotinfo)

 MODIFICATION HISTORY:
      written August 2000, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:1583)

papco_panel_AddFile_EditFile

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE: papco_panel_AddFile_EditFile

 DESCRIPTION:
      create or edit the user defined file

 INPUTS: none

 KEYWORDS: none

 MODIFICATION HISTORY:
      October 1997, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:1243)

papco_panel_AddFile_EditFile_event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_panel_AddFile_EditFile_event

 DESCRIPTION:
      event handler called by XMANAGER

 INPUTS:
    EVENT, struct, event structure from xmanager.

 KEYWORDS: none

 CALLING SEQUENCE:
      have a look at PRO events_panel_event

 MODIFICATION HISTORY:
      March 1996, Haje Korth

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:1310)

papco_panel_AddFile_Widgets

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: papco_panel_AddFile_Widgets, aBase, plotinfo

 DESCRIPTION:
      Add a widget for opening and editing simple text files. Includes
      a browse function, and crerates files if they do not exist.

 INPUTS:
	aBase	 	a WIDGET_BASE (an integer)
			the base, you want the widgets to add to
      plotinfo	a structure containing a least those fields from
			from the papco_PLOTINFO-structure:
			     filename
			It is used to set the initial values for this
			widget.

 KEYWORDS:
      DIRPATH, string, contains the "base" directory for the files
      FILTER, string, contains a file filter, e.g. '.dat'
      MODIFY, keyw
      NOEDIT, keyw, indicates files are not ascii and should just be
               saved or restored.

 OUTPUT:
      a structure containing the widget-ids of the added entry-fields

 CALLING SEQUENCE:
	tmp=papco_panel_AddFile_Widgets(panelBase, plotinfo)

 MODIFICATION HISTORY:
      written October 1997, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:1120)

papco_panel_AddHeightWidgets

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: papco_panel_AddHeightWidgets, aBase, height

 DESCRIPTION:
	Add a slider and label  to the WIDGET_BASE 'aBase' which the user
	may use to select the height of that panelplot (that is, the 3rd
	element of the panelvector).

 INPUTS:
      aBase	 	a WIDGET_BASE
			the base, the widgets are to be added to
	height		a positive integer
			the current height of this panelplot.

 KEYWORDS:
 	VERTICAL        makes vertical slider if set. Default is horizontal.
 	widgetInfo      add widgetInfo to this structure

 RETURNS:
      returns a structure
          {lbl_height:aWidget, $
            sl_height:aWidget, $
            panelHeight:aNumber}
      This fields of this structure have to be added to the widgetData of
      the panel-editor.

 CALLING SEQUENCE:
     widgets=papco_panel_AddHeightWidgets(panel_base, plotinfo)
     additionalWData=create_struct(widgets, additionalWData)

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:318)

papco_panel_AddUnits_Widgets

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: papco_panel_AddUnits_Widgets, aBase, plotinfo

 DESCRIPTION:
      Add a widget for selecting flux/conts/ energyflux etc units
      for particle spectra.

 INPUTS:
	aBase	 	a WIDGET_BASE (an integer)
			the base, you want the widgets to add to
      plotinfo	a structure containing a least those fields from
			from the papco_PLOTINFO-structure:
			     filename
			It is used to set the initial values for this
			widget.

 KEYWORDS:
   VERTICAL, keyw, make the widget vertical instead of horizontal
   SENSITIVE, keyw, not used!
   SHORTNAMES, keyw, use abbreviated names
   _EXTRA, extra keywords are passed to CW_BGROUP

 OUTPUT:
      struct, a structure containing the widget-ids of the added entry-fields

 CALLING SEQUENCE:
	tmp=papco_panel_AddUnits_Widgets(panelBase, plotinfo)

 MODIFICATION HISTORY:
      written February 2000, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:1367)

papco_panel_AddVar_Ave_Widgets

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: papco_panel_AddVar_Ave_Widgets, aBase, plotinfo

 DESCRIPTION:
      Add widgets for selecting averaging variables.

 INPUTS:
	aBase	 	a WIDGET_BASE (an integer)
			the base, you want the widgets to add to
   NAME, type, description
   ST, type, start
   EN, type, end
   V1, type, variable range min
   V2, type, variable range max
   VR, type, description
   FRMT, type, description

 KEYWORDS:
   STRUCT_ONLY, type, description

 OUTPUT:
      a structure containing the widget-ids of the added entry-fields

 CALLING SEQUENCE:
	tmp=papco_panel_AddVar_Ave_Widgets(panelBase, plotinfo)

 MODIFICATION HISTORY:
      written March 2003, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:1426)

papco_panel_AddVar_Sel_Widgets

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: papco_panel_AddVar_Sel_Widgets, aBase, plotinfo

 DESCRIPTION:
      Add a widget for selecting flux/conts/ energyflux etc units
      for particle spectra.

 INPUTS:
	aBase	 	a WIDGET_BASE (an integer)
			the base, you want the widgets to add to
   ST, type, start
   EN, type, end
   V1, type, variable range min
   V2, type, variable range max
   VR, type, description
   FRMT, type, description

 KEYWORDS:

 OUTPUT:
      a structure containing the widget-ids of the added entry-fields

 CALLING SEQUENCE:
	tmp=papco_panel_AddVar_Sel_Widgets(panelBase, plotinfo)

 MODIFICATION HISTORY:
      written March 2003, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:1499)

papco_panel_AddYScale_Widgets

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: papco_panel_AddYScale_Widgets, aBase, plotinfo

 DESCRIPTION:
      Add exclusive-buttons for selecting whether this plot shall use
	manual or automatic y-scaling and add entry fields for entering
	the lower and upper bound of the y-axis

 INPUTS:
	aBase	 	a WIDGET_BASE (an integer)
			the base, you want the widgets to add to
      plotinfo	a structure containing a least those fields from
			from the papco_PLOTINFO-structure:
			     manualYScaling
			     yScaleMin
			     yScaleMax
			It is used to set the initial values for these
			widgets

 KEYWORDS:
 	VERTICAL, keyw, arranges widget vertical
 	WIDGETINFO, struct, add widgetInfo to this structure

 OUTPUT:
      a structure containing the widget-ids of the added entry-fields

 CALLING SEQUENCE:
	tmp=papco_panel_AddYScale_Widgets(panelBase, plotinfo)
	widgetData.ef_yScaleFrom=tmp.ef_yScaleFrom
	widgetData.ef_yScaleTo  =tmp.ef_yScaleTo

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:898)

papco_panel_AddZScale_Widgets

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: papco_panel_AddZScale_Widgets, aBase, plotinfo

 DESCRIPTION:
      Add exclusive-buttons for selecting whether this plot shall use
	manual or automatic y-scaling and add entry fields for entering
	the lower and upper bound of the y-axis

 INPUTS:
	aBase, int,	a WIDGET_BASE the base, you want the widgets to add to
      plotinfo, struct, a structure containing a least those fields from
			from the papco_PLOTINFO-structure:
			     manualYScaling
			     zScaleMin
			     zScaleMax
			It is used to set the initial values for these
			widgets

 KEYWORDS:
 	widgetInfo, struct, add widgetInfo to this structure

 OUTPUT:
      a structure containing the widget-ids of the added entry-fields

 CALLING SEQUENCE:
	tmp=papco_panel_AddZScale_Widgets(panelBase, plotinfo)
	widgetData.ef_zScaleFrom=tmp.ef_zScaleFrom
	widgetData.ef_zScaleTo  =tmp.ef_zScaleTo

 MODIFICATION HISTORY:
     written february 1997, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:968)

papco_panel_Add_CoordSys_Widget

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: papco_panel_Add_CoordSys_Widget, aBase, plotinfo

 DESCRIPTION:
      Add a widget for adding coordinate transfor widget.

 INPUTS:
	aBase	 	a WIDGET_BASE (an integer)
			the base, you want the widgets to add to
      plotinfo	a structure containing a least these fields:


			     soptions
			soptions(15) and iotions(15) is used to set the initial
			values for this widget.

 KEYWORDS:
      STRUCT_ONLY, keyw, return the structure made for this widget only.

 OUTPUT:
      a structure containing the widget-ids of the added entry-fields

 CALLING SEQUENCE:
	tmp=papco_panel_Add_MagMod_Widgets(panelBase, plotinfo)

 MODIFICATION HISTORY:
      written May 2003, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:1957)

papco_panel_Add_LineFill_Widget

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: papco_panel_Add_LineFill_Widget, aBase, plotinfo

 DESCRIPTION:
      Add a widget for adding linefill widget.

 INPUTS:
	aBase	 	a WIDGET_BASE (an integer)
			the base, you want the widgets to add to
      plotinfo	a structure containing a least these fields:


 KEYWORDS:
      VERTICAL, keyw
      STRUCT_ONLY, keyw, return the structure made for this widget only.

 OUTPUT:
      a structure containing the widget-ids of the added entry-fields

 CALLING SEQUENCE:
	tmp=papco_panel_Add_MagMod_Widgets(panelBase, plotinfo)

 MODIFICATION HISTORY:
      written Nov 2006, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:2108)

papco_panel_Add_MagMod_Widgets

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: papco_panel_Add_MagMod_Widgets, aBase, plotinfo

 DESCRIPTION:
      Add a widget for specifying ONERA lib magnetic field models to use.
      Typically used by ephemeris modules

 INPUTS:
	aBase	 	a WIDGET_BASE (an integer)
			the base, you want the widgets to add to
      plotinfo	a structure containing a least these fields:


			     soptions
			soptions(15) and iotions(15) is used to set the initial
			values for this widget.

 KEYWORDS:
 	widgetInfo      add widgetInfo to this structure
      STRUCT_ONLY - return the structure made for this widget only.
      TICKS, type, description
      MODEL_ONLY, type, description
      STRUCT_ONLY, type, description
      LABEL, type, description
      WIDGETINFO, struct, add tags to this struct

 OUTPUT:
      a structure containing the widget-ids of the added entry-fields

 CALLING SEQUENCE:
	tmp=papco_panel_Add_MagMod_Widgets(panelBase, plotinfo)

 MODIFICATION HISTORY:
      written May 2003, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:1744)

papco_panel_add_PlotStyleButtons

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: papco_panel_add_PlotStyleButtons, aBase, plotinfo, isScatter

 DESCRIPTION:
      Add the plotstyle - buttons to the panel-editor.

 INPUTS:
      aBase      a Widget
		   the base the plotstyle-widgets will be added to
      plotinfo  a PLOTINFO - structure
		   the info-structure-instance edited in this widget

      isScatter  a boolean
		   if 0, the initial setting for PSYM will be smaller 0
			 which will produce a plot with connected points.
		   if 1, the initial setting for symbo-type will be gt 0,
			 which will produce a plot with isolated points.

 KEYWORDS:
 	VERTICAL        arranges widget vertical
 	widgetInfo      add widgetInfo to this structure

 OUTPUT:
      a structure with the neccessary tag-fields

 CALLING SEQUENCE:
      widgets=papco_panel_add_PlotStyleButtons(panel_base, plotinfo, 0)
      additionalWData=create_struct(widgets, additionalWData)

 MODIFICATION HISTORY:
      september 1995, written by A.Keese
      march 1996, Haje Korth, userstyle added
      july 1997, Haje Korth, Thickness and Linestyle added
      december 1999, Reiner Friedel, symsize added

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:525)

papco_panel_CreateWidgetData

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: papco_panel_CreateWidgetData, struct1, struct2

 DESCRIPTION:
      The structures struct1 and struct2 are merged via the IDL-command
	'create_struct'. Additionally: If they have a tag in common,
      the value from struct2 is copied to struct1

	This routine  is used to create the widgetData before realizing the
	editor-window. It is provided, because we don't know if in
	future-versions of papco_panel.pro other variables have to be added...

 INPUTS:
      STRUCT1, struct, a struct 
      STRUCT2, struct, a second struct

 OUTPUT:
      struct, a structure containing all tags from struct1 and struct2

 CALLING SEQUENCE:
    thisWidgetsData={helpfile:'papco_panel_template.help'}
    widgetData=papco_panel_CreateWidgetData(thisWidgetsData, additionalWData)

 MODIFICATION HISTORY:
      september 1995, written by A.Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:778)

papco_panel_draw_style_icon

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: PAPCO_PANEL_DRAW_STYLE_ICON
 DESCRIPTION: draw the icon nmemonic onto the current graphics device in the
   rectangle dposition 
 INPUTS:   
   PANELWIDGETDATA, type, description
   DPOSITION, type, description
 KEYWORDS:
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.60 $
 CURATOR: Jeremy Faden
 HISTORY:  
   22-Apr-2005, 1.25, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:2062)

papco_panel_Event

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: papco_panel_Event, event, panelWidgetData

 DESCRIPTION:
      This routine is called by the panel-editor widget-routines,
	to process events for the default widgets.
	How this should be done is demonstrated in the file
	$papco_PATH/papco_panel_template.pro

 INPUTS:
	EVENT, { widget event }, the event that invoked 'papco_panel_Event'
	PANELWIDGETDATA, struct, is a structure containing at least the
          elements for a papco_panel_EDIT-structure (this is no really 
          existing but a virtual structure
			- see the top of this file for its description)

 KEYWORDS:
     none

 CALLING SEQUENCE:
      called by XMANAGER-routines of panel-editors

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese
     modified july 1997, Haje Korth, Thickness and Linestyle added

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:2838)

papco_panel_exit

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: PAPCO_PANEL_EXIT
 DESCRIPTION: called as the widget closes, this checks log ranges, etc. 
 INPUTS:   
   PANELWIDGETDATA, struct, widgetData structure to finish up
 KEYWORDS:
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.60 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:2715)

papco_panel_Is_ScatterPlot

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: papco_panel_Is_ScatterPlot, widgetData, pType

 DESCRIPTION:
      set the flag in 'widgetData' that indicates, if the currently edited
	plot is a scatter-plot or not. This routine is provided so that you
	don't have to know the name of that tag from the outside of
	papco_panel.pro

 INPUTS:
      widgetData	the data of the current plot-editor
	pType		a boolean
			0 -> is no scatter-plot
			1 -> is a scatter-plot

 OUTPUT:
      widgetData is returned

 CALLING SEQUENCE:
      widgetData=papco_panel_Is_ScatterPlot(widgetData, 0)
	; or :
      widgetData=papco_panel_Is_ScatterPlot(widgetData, 1)

 MODIFICATION HISTORY:
      september 1995, written by A.Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:640)

papco_panel_label[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 routine to automatically scale any text on any device into a
 defined box size.
 This works using the Z-buffer, set to the resolution of the desired
 output device.
 returns charsize that fits the box on screen (may need scaling to PS)

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_panel_label.pro:17)

papco_panel_label[5]

 [Previous Routine] [Next Routine] [List of Routines] 
 program to draw a label to fit/expand into the size of a panel.
 used by papco_text module.

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_panel_label.pro:1116)

papco_panel_label[6]

 [Previous Routine] [Next Routine] [List of Routines] 
 program to draw a label to fit/expand into the size of a panel.
 used by papco_text module.

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_panel_label.pro:1165)

papco_panel_Realize

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE: papco_panel_Realize, aBase, widgetData

 DESCRIPTION:
      realize the editor - window.
	The editor-window is displayed on the screen - the plot-preview is
	drawn in the drawing-widget

 INPUTS:
      aBase	 	-> the base-widget
	widgetData	-> the widgetData-structure

 KEYWORDS:
      _extra keywords go to widget_control.

 CALLING SEQUENCE:
      papco_panel_Realize, panel_base, widgetData

 MODIFICATION HISTORY:
      september 1995, written by A.Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:820)

papco_panel_Refresh

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE: papco_panel_Refresh, widgetData,  ALL=ALL, $
                         SELECT_PLOT_STYLE=SELECT_PLOT_STYLE, $
                         SCATTER_TYPE=SCATTER_TYPE, PLOT_STYLE=PLOT_STYLE

 DESCRIPTION:
      update the paneleditor-display. This procedure is called on some of the 
   events handled in this file.  The colorbars, symbol styles, etc are redrawn.

 INPUTS:
      widgetData, struct,	the panel editor's widget data

 KEYWORDS:
   ALL, keyw, refresh everything
   ADD_FILE, keyw, AddFile_widgets
   SELECT_PLOT_STYLE, keyw, description
   SCATTER_TYPE, keyw, description
   PLOT_STYLE, keyw, description
   FILL_STYLE, keyw, description
   COLOR_PSYM_SELECT, keyw, description
   COLBAR_STYLE, keyw, description
   YSCALE, keyw, description
   ZSCALE, keyw, description
   DESCR, keyw, description
   UNITS, keyw, AddUnits
   VAR_SEL, keyw, AddVar_Sel
   VAR_AVE, keyw, AddVar_Ave
   MAG_COORD, keyw, description
   COORDSYS, keyw, description

 CALLING SEQUENCE:
      called from papco_panel_Event

 MODIFICATION HISTORY:
      september 1995, written by A.Keese
      march 1996, Haje Korth, user symbols added
      july 1997, Haje Korth, Thick and Linestyle added
      october 1997, Reiner Friedel, Add File added
      March, 2003, reiner Freidel, Add Var_Sel added

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:2237)

papco_panel_returnData

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: papco_panel_returnData, widgetData

 DESCRIPTION:
      Creates a structure containing all tags in widgetData that should
      be returned from a panel-editor, depending on the widgets
      chosen by the user!

 INPUTS:
      widgetData        a structure containing the editor's widget-data.

 OUTPUT:
      a structure with the neccessary tag-fields

 CALLING SEQUENCE:
      returnData={typeVector:plotinfo.typeVector}
      additionalRData=papco_panel_ReturnData(widgetData)
      return, create_struct(ReturnData, additionalRData)

 MODIFICATION HISTORY:
      september 1995, written by A.Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:371)

papco_panel_setup_draw_style

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: PAPCO_PANEL_SETUP_DRAW_STYLE
 DESCRIPTION: get the plot keywords from PANELWIDGETDATA.
 INPUTS:   
   PANELWIDGETDATA, type, description
 KEYWORDS:
 OUTPUTS:
   PSYM, int, description
   THICK, float, description
   COLOR, int, description
   SYMSIZE, float, description
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.60 $
 CURATOR: Jeremy Faden
 HISTORY:  
   22-Apr-2005, 1.25, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco/papco_panel.pro:2021)

papco_papco_have_utility

 [Previous Routine] [Next Routine] [List of Routines] 
 function:     papco_papco_have_utility

 description:  checks if a given system utility program is
               available.

 inputs:       exec_name - string, name of the command

 output:   1 if it exisits, 0 if not

 author:       R. Friedel, October 1998

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:1064)

papco_pickfile

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      papco_pickfile, papco_pickfile_event, papco_pickfile_refresh

 DESCRIPTION:
      Wrapper to the idl routine DIALOG_PICKFILE that extends the
      functionailty of the file handling to allow creation/deletion of
      directories and creation/deletion of files, and links to a simple
      editor for text files, or links to a simple file explorer for idl
      saveset files.. Incorporates some PAPCO niceties
      for always forcing a given file extension.

 KEYWORDS: same as DIALOG_PICKFILE, see idl help

 INPUTS:
      none

 OUTPUT:
      none

 CALLING SEQUENCE:
      result=papco_pickfile(same keywords as for DIALOG_PICKFILE)

(See /home/jbf/ct/papco/working/papco/papco/papco_files.pro:45)

papco_pitch_bin

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_pitch_bin

 DESCRIPTION:  a routine to make pitch angle bins centered on 90 deg

 KEYWORDS:     pa_idx : returns an array of 1 degree pitch angle
               mapings to the index of the corresponding pitch
               angle bin. This is used in binning pitch angles into
               the chosen pitch angle ranges - much faster!

 INPUTS:       pa_bin    -  center pitch angle bin width

 OUTPUT:       array of start / end of pa bins

 HISTORY:      written July 2002, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_math.pro:1069)

papco_plot

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_plot
 DESCRIPTION:  simply draws plot axes for overplotting.  Conventionally, a simple
   papco 12 module will call this, then overplot the data, then call this again so
   that the data doesn't clobber the axes.
 KEYWORDS:
   [XYZ]SCALE, fltarr(3), [ min, max, log ] to control the axis.
   TIMERANGE, { papco_timerange }, the xaxis time range
   PANEL, intarr(3), papco panel vector, indicating the plot is a panel and
      the plot's should be positioned accordingly.  The routine will
      set up the Y, and Z axes for the panel editor settings.  The module 
      must provide a default (or auto) range via the yrange and zrange keywords.  
      And will set up the X timeaxis to be [ 0,width_seconds ], and will
      set the plotted common block.
    PLOTS_ATTHISPOSITION, int, number of plots already plotted, so shift the title down.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.8 $
 CURATOR: NAME
 HISTORY:  
   Nov 17, 2005, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_plot.pro:86)

papco_plot_colorspec[4]

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_plot_colorspec
 DESCRIPTION: Plots a colorplot of data.  Z data must be stored in a 2D array,
   with columns correponding to intervals in x and rows corresponding
   to intervals in y.
 INPUTS:   
   ZMAT_IN, fltarr[M,N], zvalues to be color-encoded
   XARR_IN, fltarr[M]|fltarr[2,N], x tags for ZMAT
      if xarr=fltarr(n,2) then pairs are start and end of column.
      if xarr=fltarr(n)   then each is start of column with no gaps,
                           and the last column is not shown.
   YARR_IN, fltarr[N]|fltarr[2,N], y tags for each ZMAT row
      same format as xarr. fltarr(m,2) or fltarr(m)
 KEYWORDS:
   YLOG, keyw, y axis should be type log. (Note xlog not supported)
   DX, float, explicitly specify the bin size for x and y, otherwise
      the binsize is the greatest common divisor, within pixel
      precision of the x and y values.
   DY, float, see DY
   RESX, float, explicitly specify the required accuracy of the x and y
      bins, otherwise the device pixel resolution sets these.
   RESY, float, see RESX
   ZLOG, keyw, z axis should be type log.
   ZRANGE, fltarr(2), [zmin,zmax] range to plot.
   _EXTRA, extra keywords are passed to plot.
   SPECIAL_COLORS, fltarr(2,n), can be used to insert special colors,
      e.g. saturation.  It is an array of pairs, each pair is (value,color). 
      Where value is found in zmat, use display color.
   NODATA, float, specifies the fill value should be plotted in grey and omitted
     from averaging.
   SAMPLE, keyw, do not average zmat if device resolution is not sufficient,
     instead display samples from zmat.
   XFILLED, keyw, assume data in X is filled.
   VERBOSE, keyw, verbose messages
   COLORTBL, intarr(2), specifies the range of colors to use for the colorbar. 
       if not specified, then the following algorithm is used:
       if n_elements(papco_color) gt 0 then use PAPCO color scheme.
       otherwise, use [0,!d.n_colors]
 SIDE EFFECTS: 
       affects plot device state
 EXCEPTIONS:
 NOTES: 
   No averaging is done on columns (y).
   Averaging will clobber special color values.
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: lib.plotting
 CVSTAG: 
   $Name:  $
   $Revision: 1.7 $
 CURATOR: NAME
 HISTORY:  
   Written, Jeremy Faden, November 1997.

(See /home/jbf/ct/papco/working/papco/papco_lib/color_plot/papco_plot_colorspec.pro:241)

papco_Printer

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      FUNCTION papco_Printer, aPrinterInfo, $
		 GROUP=GROUP, SELECT_DEFAULT=SELECT_DEFAULT

 DESCRIPTION:
      open the printer-selection-dialog.

	In this dialog, the user may select if output shall be done to a
	printer or to a file. If output is done to a file, the file-format
	can be defined (PNG or PS)

	If the dialog is called for a default-printer, a printer AND a file-
	name may be selected. Else, either a filename or a printer may be
	be selected.

	If a file is selected, the user may decide, if the filename shall be
	obtained by opening a file-selection-box, or if it shall be obtained
	by substituting the abbreviations in the file-name-template.
      See $PAPCO_BASE/papco/help/papco_printer.help for possible
      template formats.


 INPUTS:
      aPrinterInfo	an instance of papco_PRINTER_INFO-structure
			the settings in this instance are used as initial
			settings for this dialog

 KEYWORDS:
 	GROUP		a widget-base
			if set, this will be used as GROUP-Leade for this
			window

	SELECT_DEFAULT	a boolean (non-existent or 1)
			if set, the dialog will be opened for selecting the
			default-printer. In this case, a printer as well
			as a filename may be chosen.

			If it isn't set, either a printer or a filename
			can be selected.

 OUTPUT:
      the widget-data is returned.

 CALLING SEQUENCE:
  ;---selecting a default-printer
      default_printer=papco_getPrinterInfoStruct()
	;....lots of code...
	tmp=papco_Printer(default, /SELECT_DEFAULT)
	if not tmp.canceled then begin
	   default_printer.usePrinter=printer.usePrinter
	   default_printer.printer=printer.printer
	   default_printer.askForFileName=printer.askForFileName
	   default_printer.fileType=printer.fileType
	   default_printer.fileName_tmpl=printer.fileName_tmpl
	endif

  ;---selecting a non-default-printer
	printer=papco_Printer(papco_GetPrinterInfoStruct())
	if not printer.canceled then begin
	   if tmp.usePrinter then begin
	      output_toPrinter, tmp.printer
	   endif else begin
            if tmp.askForFileName then begin
		 fileName=pickfile()
		 output_toFile, fileName
            endif else begin
		 ; first, substitute the abbreviations:
		 fileName=substitute_templates(tmp.fileName)
		 output_toFile, fileName
	      endelse
	   endelse
	endif

 MODIFICATION HISTORY:
      september 1995, written by A.Keese
      february 1996, Haje Korth
      December 2000, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_printer.pro:563)

papco_PrinterDescription

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      FUNCTION papco_PrinterDescription, printerInfo, $
					   PRINTER=PRINTER, FILE=FILE

 DESCRIPTION:
      A description for the printerInfo is returned. This string is used
	to label the print-buttons and by the papco_printPlots-routine that
	is contained in papco_draw.pro

	If printerInfo describes a file, or if the keyword /FILE is set,
	The data in COMMON PLOT_COMPOSER, widgetData is used to substitute the
	patterns which might be contained in the printerInfo.fileName_tmpl
	patterns :
		       $     -> is substituted by the product name
		       %     -> is substituted by the orbit-number
		       <     -> substituted by the widgetData.startTime
		       >     -> substituted by the widgetData.endTime
             &     -> substituted by start date only, yyyymmdd

 INPUTS:
      printerInfo	an instance of the papco_PRINTER_INFO-structure
			the returned description describes this printer

 KEYWORDS:
 	PRINTER		if not specified, the returned name is the name of
	FILE		a printer if printerInfo.usePrinter EQ 1. If the
			keyword PRINTER is specified, the returned string is
			the name of the printer contained in printerInfo.
			If FILE is specified, the returned string is the name
			of the file contained in printerInfo
  OUTPUT    return the output file name (*.txt, *.cdf, ... )

 OUTPUT:
      a string is returned.
	this is either the name of a printer or the name of a file

 CALLING SEQUENCE:
	name=papco_printerDescription(aPrinter)
	name=papco_printerDescription(aPrinter, /PRINTER)
	name=papco_printerDescription(aPrinter, /FILE)

 MODIFICATION HISTORY:
     written august and september 1995, Andreas Keese
     february 1996, Haje Korth

(See /home/jbf/ct/papco/working/papco/papco/papco_printer.pro:152)

papco_Printer_Event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_Printer_Event, Event

 DESCRIPTION:
      Process an XMANAGER-Event

 INPUTS:
      Event	 an XMANAGER-Event

 KEYWORDS:
      none

 CALLING SEQUENCE:
      called by XMANAGER

 MODIFICATION HISTORY:
      september 1995, written by A.Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_printer.pro:376)

papco_Printer_Refresh

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_Printer_Refresh

 DESCRIPTION:
      update the display of the printer-selection-window

 INPUTS:
      none

 KEYWORDS:
      none

 MODIFICATION HISTORY:
      september 1995, written by A.Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_printer.pro:294)

papco_PrintMenu_event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_PrintMenu_event, event

 DESCRIPTION:
      Handles events that are invoked, when the user selects an entry
      from the printer-menu.

 INPUTS:
      Event       a string indicating the caller.
                  'papco' if caller is papco main
                  'slice' if caller is a slice.

 KEYWORDS:
  none

 CALLING SEQUENCE:
  papco_PrintMenu_event, anXManagerEvent
  Called by papco_main_Event only.

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_event.pro:23)

papco_PrintPlots

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_PrintPlots, printerInfo, PRINTER=PRINTER, FILE=FILE

 DESCRIPTION:
	this procedure is called, when the panels shall be drawn to a
      printer or a file.

 INPUTS:
	printerInfo	a papco_PRINTER_INFO-structure instance
			this is the description of the printer or file
			to which the plots are to be made.

 KEYWORDS:
 	PRINTER		use the printer that is specified by printerInfo
	FILE		print to the file that is specified by printerInfo
			If printerInfo is a default-printer, you have to
			set one of these keywords.
      SLICE           indicates caller is slice and contains plot call
                      for slice
      SLICE_CALLS     strarr of procedure calls to to implement the slice
      ZBUFFER         put drawing in zbuffer, no file output. Used
                      for output data option.
      OUTPUTNAME      returns the name of the file written to.

 CALLING SEQUENCE:
	papco_PrintPlots, userSelectedPrinter
	papco_PrintPlots, defaultPrinterInfo, /PRINTER

 MODIFICATION HISTORY:
     written august and september 1995, Andreas Keese
     february 1996, Haje Korth
     november 1997, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_draw.pro:240)

papco_print_control_info

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:    papco_print_control_info

 DESCRIPTION:  Prints verbose description of control structure for module.

 KEYWORDS:     WRITE     also output info to file

 INPUTS:       control structure

 OUTPUT:       none, prints info to stout or file

 HISTORY:      written October 2004, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:2181)

papco_props_add

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_props_add
 DESCRIPTION:  add a property to a property set
 INPUTS:   
   PROPS, struct, papco props structure
   NAME, string, identifier string for property
   DEFAULT, value, the default value of the property
 KEYWORDS:
   DIRECTORY, keyw, property must be a valid directory (may not exist)
   FILENAME, keyw, must be a filename (may not exist)
   URL, keyw, must be a URL
   ENUMERATION, strarr, must be one of the specified elements.  Note elements cannot contain '::'
   LISTINDEX, strarr, index into the array of strings.  Much like enum, but an index instead.
   STRARR, keyw, property is a string array that can be edited.
   STRING, keyw, property is a string
   INTEGER, keyw, property is an int.
   FLOAT, keyw, property is a float.
   BOOLEAN, keyw, prop is a bool (1=checked, 0=not checked)
   NBOOLEAN, keyw, prop is a negated boolean ( 0=checked, 1=not checked )
   RADIO, keyw, use a radio instead of droplist
   DROPLIST, keyw, explicitly use a droplist (the default)
   WIDGETLIST, keyw, use a widget list
   WIDGET_KW, struct,  a structure of keywords to pass to the widget when it's created.
   LABEL, string, less concise label for widgets (20-80 chars)
   INFO, string, concise label for widgets (5-30 chars)
   DIMENSION, keyw, property is a dimension (width by height).
   EDITOR, string, function to call to get the editor.  A button "edit" appears next to the value.
   IGNOREIF, string, evaluate this string, and if true, then this value is not used
   DOC, strarr, verbose documentation (2-5 lines)
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.13 $
 CURATOR: Jeremy Faden
 HISTORY:  
   26 Oct 2005, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_props_editor.pro:71)

papco_props_create

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_props_create
 DESCRIPTION: generic set of properties and editor to modify them.
 INPUTS:   
   NAME, string, identifier string for properties set.
 KEYWORDS:
   PACKROWS, keyw, put the property editor next to the label
 RETURNS: 
   struct, an empty papco properties struct, with meta data in props__meta tag.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.13 $
 CURATOR: Jeremy Faden
 HISTORY:  
   Oct 23, 2005, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_props_editor.pro:21)

papco_radial_spectrogram

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_radial_spectrogram    
 DESCRIPTION: draw a spectrogram of the dataset on a polar plot.  The interpolation used
   to go from the rectilinear to polar space is cached so that successive calls can be 
   done rapidly.  (For example, slicers that draw at animation-interactive rate.)
 INPUTS:   
   DS, papco dataset, rank 2 dataset with angles as one of the tags
 KEYWORDS:
   ANGLE_TAG, string, name of the tag from which the polar angles are found.  If tag 
     units are 'deg' then the data is degrees, radians otherwise.
   RADIAL_TAG, string, name of the tag from which the radial positions are found.  
   ZRANGE, fltarr(2), colorbar range
   ZSCALE, fltarr(3), colorbar range and scale type.  [ min, max, scale ]
   RADSCALE, fltarr(3), [ min, max, scale ].  min is radius zero, max is the outer ring.
   RTICKV, fltarr, explicitly specify locations of the ring location.
   ATICKV, fltarr, explicitly specify locations of the angle rays.
   WEDGES, boolean, paint wedges instead of interpolating data
   RESET, boolean, reset internal state
   FORCE_RECYCLE, boolean, force reuse of cache, even when the cache appears to be invalid.
   OVERPLOT, boolean, overplot the data onto existing axes.
 SIDE EFFECTS: 
   A common block is used to cache the interpolation.
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.11 $
 CURATOR: Jeremy Faden
 HISTORY:  
   12-Sept-2005, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_radial_spectrogram.pro:87)

papco_readDefaultSettings

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_readDefaultSettings, FONT_ONLY=FONT_ONLY

 DESCRIPTION:
      At program-start, this procedure reads the default-settings.
  These are the default printer and the default write/read-paths.
  All defaults are written at program-end to the file
      'papco_user/papco_default.dat' by papco_writeDefaultSettings

 INPUTS:
  none

 KEYWORDS:
  TAGID       if set, return TAGID only

 CALLING SEQUENCE:
  papco_readDefaultSettings, TAGID=TAGID

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese
     modified october 1996, Reiner Friedel
     generalized Februaty 2000, Reiner Friedel, for easy expandability.

(See /home/jbf/ct/papco/working/papco/papco/papco_files.pro:698)

papco_readOrbitInfo

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      papco_readOrbitInfo

 DESCRIPTION:
      read an Array of orbit-infos.
      The read orbits are cached in the variable 'readOrbits'.

 INPUTS:
      SCraft          : name of space_craft
      orbitInfo	: the Variable, in which the orbits are to be read

 OUTPUT:
      if reading was succesful, the string 'OK' is returned
		           and the parameter orbitInfo will
			   contain an array of orbitInfos
      if reading failed, a string containing the error-message
	                   is returned, and the parameter
    			   orbitInfo will have undefined
			   value.

 CALLING SEQUENCE:
      result=papco_readOrbitInfo(SCraft, orbits)
	IF result NE 'OK' THEN BEGIN
         print, 'error:' + result
	   return
       ENDIF ELSE $
         doWhateverYouWantWith, orbits

 MODIFICATION HISTORY:
     october 1996, written by R. Friedel
     july 1997, Haje Korth

(See /home/jbf/ct/papco/working/papco/papco/papco_orbitinfo.pro:242)

papco_readPrinterConfig

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_readPrinterConfig

 DESCRIPTION:
      At program-start, this procedure reads the available printer
      from 'papco_user/papco_printer_config.dat'

 INPUTS:
  none

 KEYWORDS:
  none

 CALLING SEQUENCE:
  papco_readPrinterConfig, printerData

 MODIFICATION HISTORY:
      written February 1996, Haje Korth
      updated June 2001, Reiner friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_files.pro:633)

papco_read_batch

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_read_batch, fName

 DESCRIPTION:
      This procedure reads an entry from a batch file and sets the time
      accordingly. The entry number is set by widgetData.batch_count
  The batch file has this format:
  -> empty lines or lines starting with '#' are ignored
  -> it contains one orbit and/or time-description per line
  -> a line has this format (in BNF) :
        line=orbit [, time-range] | time-range
        orbit = aNumber
        time-range= t90-time "-" t90-time
        t90-time=date [" " time]
        date = doy"/"year | day_om"."month"."year | month"/"day_om"/"year
        (doy=aNumber, year=aNumber, day_om=aNumber, month=aNumber)
        time = hour":"minutes[":"seconds]
        (time=aNumber, minutes=aNumber, seconds=aNumber)

 INPUTS:
      fName    the file-name including the path

 KEYWORDS:
      ALL      read all the times in file into time_str

 MODIFICATION HISTORY:
      April 1999, written by R. Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_files.pro:914)

papco_read_struct

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_read_struct, filename, structname, struct

 DESCRIPTION:  a routine to read an IDL structure from a text file

 INPUTS:       filename - file to read structure from, string
               structname - a string name for the structure
               struct - the structure to save. Tags may be any
                        variable, a structure or a pointer to a
                        structure.

 KEYWORDS:     TAGID
               UNIT     read struct from this unit number / file
               VERBOSE  print out info
               FOLD_TAG_DEFAULT  default_X is treated the same as
                   default.X, to support old papco_defaults.dat files.
               logger, papco_logger, send debugging messages
               lineCount, int, current line counter

 OUTPUT:       two element results structure:
                {error - 0 no error, 1 error
                 text  - '' or string array if keyword ARRAY set
               lineCount is updated

 KEYWORDS:     ARRAY - do not write to file, return string array

 HISTORY:      written February 2000, Reiner Friedel
               modified May 2003 to read contents of Pointers (as
               part of structur, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:629)

papco_reconfigure

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_reconfigure

 DESCRIPTION:
      Once PAPCO has been started, this routine allows the user to
      add or delete modules from PAPCo without needing to restart IDL.

 INPUTS:
      none

 KEYWORDS:
      none

 MODIFICATION HISTORY:
     written August 1999, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_configure.pro:1589)

papco_refresh

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_refresh, TIME=TIME, LIST=LIST, NEW_TIMERANGE=NEW_TIMERANGE,
             ALL=ALL, PRINTER=PRINTER,SELECT_TIME_METHOD=SELECT_TIME_METHOD
                         NEED_READ=NEED_READ
 DESCRIPTION:
      Refresh the screen to display the contents of the actual
  widgetdata

 INPUTS:
  none

 KEYWORDS:
  TIME          if set, the time-entry-fields and the time-
                   sliders are updated
  LIST          if set, the list containing the plot-descriptions
                   is updated
  ORBIT         if set, the displayed orbit is updated.
                   Specifying ORBIT implicitly specifies TIME
  PRINTER       the printer-menus are updated to display the
                   default-printer and default-print-file
  SLICE         the mouse does window is updated according to
                   the last set option
  wget          wget status (online/offline)
  files         recently selected files and current file
  ALL           everything will be updated, when ALL is set.

 CALLING SEQUENCE:
  e.g.: papco_Refresh, /LIST

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese
     updated for SLICE, May 1997, Reiner Friedel
     updated for NEED_READ, Oct 1997, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_refresh.pro:35)

papco_RefreshList

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_RefreshList

 DESCRIPTION:
      Refresh the listbox to display the currently selected plots

 INPUTS:
  none

 KEYWORDS:
  LIST  =  if set to 2, then also reset total panels.

 CALLING SEQUENCE:
  papco_RefreshList

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_refresh_list.pro:19)

papco_Release_SubTable

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_Release_SubTable

 DESCRIPTION:
	Sets the chosen suntable as being unused: allows reassignment with
      a new color table.
      Default is to do nothing: needs keywords.

 INPUTS:
	none

 KEYWORDS:
      TABLE    if set, mark that subtable as unused (1,2,3)
      ALL      if set, mark all user definable subtables as unused

 CALLING SEQUENCE:
	papco_Release_SubTable

 MODIFICATION HISTORY:
     february 1997, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_color.pro:444)

papco_replace_name

 [Previous Routine] [Next Routine] [List of Routines] 
 Procedure:    papco_replace_name

 description:  Goes through the whole 'path' tree replacing all
               occurences of one string with another. Uses a perl call
               ONLY works for UNIX!

 inputs:       path       -  path to start with
               old, new   -  original and new string.

 keywords      filename   -  change occurrence in filename too!

 output:   none

 author:       R. Friedel, October 1997

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:68)

papco_resetslots

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_resetslots
 DESCRIPTION: Action performed by Reform->"reset all", reset all panels to height 1
 INPUTS:   
 KEYWORDS:
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.10 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco/papco_editslots.pro:167)

papco_ResetState

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_ResetState

 DESCRIPTION:
      ResetState resets papco - i.e. it clears all plots.

 INPUTS:
  none

 KEYWORDS:
  none

 CALLING SEQUENCE:
  papco_ResetState

 MODIFICATION HISTORY:
      written August 1995, Andreas Keese
      modified October 1998, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_files.pro:586)

papco_resortslots

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_resortslots
 DESCRIPTION: Action performed by Reform->"resort all", resort the panels ascending order
 INPUTS:   
 KEYWORDS:
   NOREFRESH, type, description
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.10 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco/papco_editslots.pro:200)

papco_RevalidatePlot

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_RevalidatePlot, plotNumber

 DESCRIPTION:
      Attempt to revalidate an existing PlotInfo, for example after
  a state file is loaded or the module is reset.  This calls a module's _revalidate.pro 
  if available.

 INPUTS:
	PLOTNUMBER, int,  the index of the plot in widgetData.plotInfos.  0<=plotNumber<=widgetData.numberOfPlots
			
 KEYWORDS:
 	none

 CALLING SEQUENCE:
	papco_revalidatePlot, PLOTNUMBER

 MODIFICATION HISTORY:
     written July 2005, Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco/papco_plotedit.pro:196)

papco_routine_header[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 This file is part of the PAPCO software package. 

 PAPCO is a free IDL package to combine data plots written by A. Keese and
 R. Friedel, maintained by R. Friedel
                                                           
    For more information, check the papco home page at     
    http://leadbelly/ccr/software/papco/papco.html       
    for online Manual and downloadble latest version.      
                                                           
 Comments and questions can be directed to friedel@lanl.gov  
  
 You are free to modify and distribute this file. However, any changes not 
 communicated to R. Friedel will not become part of the next release of PAPCO.

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_routine_header.pro:15)

papco_routine_header[2]

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
     papco_routine_header

 PURPOSE:
     Tell what your routine does here.  I like to start with the words:
     "This function (or procedure) ..."
     Try to use the active, present tense.

 CATEGORY:
     Put a category (or categories) here.  For example:
     Widgets.

 CALLING SEQUENCE:
     Write the calling sequence here. Include only positional parameters
     (i.e., NO KEYWORDS). For procedures, use the form:

     routine_name, Parameter1, Parameter2, Foobar

     Note that the routine name is ALL lowercase and arguments have Initial
     Caps.  For functions, use the form:
 
     Result = function_name(Parameter1, Parameter2, Foobar)

     Always use the "Result = " part to begin. This makes it super-obvious
     to the user that this routine is a function!

 INPUTS:
     Parm1:  Describe the positional input parameters here. Note again
     	      that positional parameters are shown with Initial Caps.

 OPTIONAL INPUTS:
     Parm2:  Describe optional inputs here. If you don't have any, just
     	      delete this section.
     
 KEYWORD PARAMETERS:
     INFO:     Calls doc_library to display this header documentation.
               1: print to terminal, 2: print to default printer

     VERBOSE:  If set, output informational messages to console.

     KEY1:     Document keyword parameters like this. Note that the keyword
     	        is shown in ALL CAPS!

     KEY2:     Yet another keyword. Try to use the active, present tense
               when describing your keywords.  For example, if this keyword
               is just a set or unset flag, say something like:
               "Set this keyword to use foobar subfloatation. The default
               is foobar superfloatation."

 OUTPUTS:
     Describe any outputs here.  For example, "This function returns the
     foobar superflimpt version of the input array."  This is where you
     should also document the return value for functions.

 OPTIONAL OUTPUTS:
     Describe optional outputs here.  If the routine doesn't have any, 
     just delete this section.

 COMMON BLOCKS:
     PLOT_COMPOSER: contains the main papco structure
                    
     BLOCK1:	Describe any common blocks here. If there are no COMMON
               blocks, just delete this entry.

 SIDE EFFECTS:
     Describe "side effects" here.  There aren't any?  Well, just delete
     this entry.

 RESTRICTIONS:
     Describe any "restrictions" here.  Delete this section if there are
     no important restrictions.

 PROCEDURE:
     You can describe the foobar superfloatation method being used here.
     You might not need this section for your routine.

 EXAMPLE:
     Please provide a simple example here. An example from the PICKFILE
     documentation is shown below. Please try to include examples that
     do not rely on variables or data files that are not defined in
     the example code. Your example should run properly if typed
     in at the IDL command line with no other preparation.

     Create a PICKFILE widget that lets users select only files with 
     the extensions 'pro' and 'dat'.  Use the 'Select File to Read' title 
     and store the name of the selected file in the variable F.  Enter:

	  F = pickfile(/READ, FILTER = ['pro', 'dat'])

 NAMING CONVENTION:
     All routines that are part of the papco core should be lower
     case and start with 'papco_'

 MODIFICATION HISTORY:
     Written by:    Your name here, Date.
     July, 1994     Any additional mods get described here.  Remember to
                    change the stuff above if you add a new keyword or
                    something!
     January, 2003  This example routine header written for papco,
                    R. Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_routine_header.pro:117)

papco_routine_info

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:    papco_routine_info

 DESCRIPTION:  prints out routine header information

 INPUTS:       file    name of file containing routine
               name    name of routine

 OUTPUT:       prints out the routine header for the routine specified

 KEYWORDS:     ROOT_DIR  start search from this root directory
               WRITE     also output info to file

 HISTORY:      written August 1999, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:255)

papco_rs_lbl

 [Previous Routine] [Next Routine] [List of Routines] 
  NAME:        papco_rs_lbl

  DESCRIPTION: Puts a label to mark a panel to the right of the panel.
               calculates position form system variable !p.position
               Does "correct" new line with enough space
               Can attempt to shrink label into available space.

  INPUT:       panel : 3 element vector for position of panel
               label : string used as label, IDL Format.

  KEYWORDS     ROT90 : rotates output string by 90 degrees, used for plots
                       with papco_colorbar
            NOCOLBAR : assumes no color bar, can use more space
            CLEARBUF : clears the label buffer for the panel
               NOBUF : don't accumulate multiple labels
               AUTO  : 0 no scaling
                       1 attempt to scale into space.
               LINE  : add a line and plot the current linestyle there
               _extra: extra keywords to be passed to xyouts procedure

  OUTPUT:      plots on current plotting device

  DATE:        July 2003

  AUTOR:       R. Friedel

  SIDEEFFECTS: -

  MODIFICATIONS: rewrite using buffers for overplots.

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_panel_label.pro:310)

papco_r_eph.pro

 [Previous Routine] [Next Routine] [List of Routines] 
 FILE:
	papco_r_eph.pro

 DESCRIPTION:
	Generic routine to read ephemeris information.

 INPUTS: name - string of ephemeris module, e.g. 'polar_eph'
         files - string array of fielnames to read, full path
         dates - string array of dates to read
         plotinfo - plot's plotinfo struct 

 OUTPUTS: in common block

 KEYWORDS:
 	VERBOSE  integer     be verbose or not

 MODIFICATION HISTORY:
	written  July 2004, R. Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_add_mag.pro:338)

papco_r_eph_onefile.pro

 [Previous Routine] [Next Routine] [List of Routines] 
 FILE:
	papco_r_eph_onefile.pro

 DESCRIPTION:
	Generic routine to read ephemeris one file. Incorporates
      magnetic field model addition/reading.

 INPUTS: name - string of ephemeris module, e.g. 'polar_eph'
         file - string of filename to read, full path
         date - string of date to read
         plotinfo - plot's plotinfo struct 

 OUTPUTS: in common block

 KEYWORDS:
 	VERBOSE  integer     be verbose or not

 MODIFICATION HISTORY:
	written  July 2004, R. Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_add_mag.pro:403)

papco_r_mag

 [Previous Routine] [Next Routine] [List of Routines] 
  PROCEDURE:   papco_r_mag

  DESCRIPTION: reads an ephemeris files containing model mag coords.
               reads the "eph_struct.idl" file and ensures that
               returned data structures have same tags as eph_struct to 
               ensure successfull concatination.

  INPUT:       

  OUTPUT:      data is in common blocks, error common block set too

  DATE:        July 2005

  AUTHOR:      R. Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_add_mag.pro:653)

papco_sat_conj.pro

 [Previous Routine] [Next Routine] [List of Routines] 
  NAME:        papco_sat_conj.pro

  DESCRIPTION: Routine to find magnetic conjunction between satellites.
               Implemented to work between the following satellites: 
                  POLAR  HEO



  INPUT:       sats array of satellite(s) for conjunctions

  OUTPUT:      none (writes conjunctions file)

  KEYWORDS:    VERBOSE  -  enables print comments, save/restore comments
               L_RNG,MLT_RNG,MLAT_RNG - definition for conjunctions
               INTMOD, EXTMOD - mag model to use
               DATE_1=DATE_1, DATE_2=DATE_2 - range of time to cover
               ADOPT_MJDT - if set, use current time from papco
               NEWLOG - if set, start new log, otherwise append old
               LOGFLN - if set, use as file name for log
               SAVE - collect all interpolated L, MLT, MLAT into a file.
               LOAD - use saved interp arrays


  DATE:        May 2002

  AUTOR:       R. Friedel

  CHANGES:

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_sat_conj.pro:30)

papco_saveState

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_saveState

 DESCRIPTION:
      Save the plot product to a file.
  This procedure lets the user pick a filename, to which the info
  are written, or writes to a user supplied fiel name.

  The format of the written file is determined by the
  papco_getPlotInfoStruct. So, this routine should suffice even if
  you extend the plotInfo-structure.

      This routine makes use of the general papco_write_struct function.

 INPUTS:
  none

 KEYWORDS:
  FILENAME    if set, don't enquire for name but use filename

 CALLING SEQUENCE:
  papco_saveState

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese
     modified November 1995, R Friedel: to include filename in widgetData
                             add keyword FILE to pickfile
                             to "remember" previously used filename
              November 2000 to use papco_write_struct, R Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_files.pro:193)

papco_save_compiled

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      papco_save_compiled

 DESCRIPTION:
      saves the current status of all compiled routines for quick startup

 INPUTS:
      none

 OUTPUT:
      none

 CALLING SEQUENCE:
      papco_save_compiled

(See /home/jbf/ct/papco/working/papco/papco/papco_files.pro:1788)

papco_save_current_state[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      papco_save_current_state

 DESCRIPTION:
      saves the previous state of the panel editor to file. Panel Editor
      state files are the same as papco product files.
      Naming convention: state_00001.papco, etc, stored in the users
      papco_user/papco_products directory.

   windowId-- allows for multiple threads of state, that follow for example,
      draw windows.

 INPUTS:
      none

 OUTPUT:
      none

 CALLING SEQUENCE:
      papco_save_current_state

(See /home/jbf/ct/papco/working/papco/papco/papco_files.pro:1900)

papco_save_current_state[2]

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      papco_save_current_state

 DESCRIPTION:
      loads the state pointed to by the state pointer, if it exists.  Otherwise,
   does nothing.

   windowId-- allows for multiple threads of state, that follow for example,
      draw windows.

 INPUTS:
      none

 KEYWORDS:
     /noErase     don't erase the screen since the loaded state doesn't
                            make the screen invalid.

 OUTPUT:
      none

 CALLING SEQUENCE:
      papco_load_current_state

(See /home/jbf/ct/papco/working/papco/papco/papco_files.pro:1956)

papco_selectedOrbits_refresh

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      papco_selectedOrbits_refresh

 DESCRIPTION:
      updates the display using the data found in 'infoStruct'

 INPUTS:
      none    All parameters passed in common block papco_selectorbit

 OUTPUT:
      none

 CALLING SEQUENCE:
	papco_selectOrbits_refresh

 MODIFICATION HISTORY:
     March 1997, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_orbitinfo.pro:409)

papco_selectOrbit

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      papco_selectOrbit, group

 DESCRIPTION:
	Display a window containing a list of orbit descriptions. When the user
 	selects one, its orbitInfo is returned.

 INPUTS:
	none

 KEYWORDS:
      group	the widget-group of the window

 OUTPUT:
      if the user exits using the 'CHOOSE'-button:
         a POLAR_ORBIT_INFO-structure. Its fields are explained in the file
	   'papco_orbitinfo.pro'
	if the user exits using the 'CANCEL'-button:
	   -1

 CALLING SEQUENCE:
	orbInfo=papco_selectOrbit()

 MODIFICATION HISTORY:
     March 1997, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_orbitinfo.pro:695)

papco_selectOrbits_calcBounds

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      papco_selectOrbits_calcBounds, infoStruct, newDay, newYear, $
				       NEWMAX, NEWMIN

 DESCRIPTION:
      when the user enters a new upper or lower bound for the data to be
	displayed, this procedure is used to calculate the corresponding
	index-range in the list  of orbit-descriptions. Furthermore, the bounds
	are checked: the bound won't be set before  the day of the first known
	orbit or after the day of the last known index. The lower bound won't
	be higher than the upper bound.

 INPUTS:
      infoStruct	this is a structure containing the data to be shown on
			the screen. It is the same data that is kept in the
			first widget of the Window. For its description see
			the function 'papco_selectOrbit() at the end of this
			file.
      newDay		An integer: the newDay of the new bound.
	newYear		An integer: its year. If year < 100 then 1900 is added.

 KEYWORDS:
 	NEWMAX		if set, the upper bound is calculated
	NEWMIN		if set, the lower bound is calculated

 OUTPUT:
      -

 CALLING SEQUENCE:
      for displaying data from the 201st day of 1990:
	  papco_selectOrbits_calcBounds, infoStruct, 201, 1990, /NEWMIN

      for displaying data to the 201st day of 1991:
	  papco_selectOrbits_calcBounds, infoStruct, 201, 1991, /NEWMAX

 MODIFICATION HISTORY:
     March 1997, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_orbitinfo.pro:489)

papco_selectOrbits_Event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      papco_selectOrbits_Event, Event

 DESCRIPTION:
      this routine handles Events

 INPUTS:
      Event	 the event to be handled

 OUTPUT:
      -

 CALLING SEQUENCE:
	Called by XMANAGER only !

 MODIFICATION HISTORY:
     March 1997, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_orbitinfo.pro:567)

papco_sepdir

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: PAPCO_SEPDIR, fname, path, file, ext
 DESCRIPTION: seperates a filename string into directory and filename 
 INPUTS:   
   FNAME, string, input filename
 OUTPUT:
   PATH, string, directory of file
   FILE, string, filename, without the extension.
   EXT, string, extension including period (.dat).
 KEYWORDS:
   OS, string, use this OS family (e.g. for testing).
 SIDE EFFECTS:
 EXCEPTIONS:
    'papco does not yet support...'  indicates the OS is not supported.
 EXAMPLES:
    filename= 'c:\data\mydata.dat'
    papco_sepdir, filename, path, file, ext
    help, filename, path, file, ext
    FILENAME        STRING    = 'c:\data\mydata.dat'
    PATH            STRING    = 'c:\data\'
    FILE            STRING    = 'mydata'
    EXT             STRING    = '.dat'
 UNIT TEST: test_papco_opsys.pro
 CATEGORY: opsys
 CVSTAG: 
   $Name:  $
   $Revision: 1.47 $
 CURATOR: NAME
 HISTORY:  
   written R. Friedel, October 1997
   R. Friedel, updated December 2000 to include extension

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:273)

papco_SetColorTable

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_SetColorTable

 DESCRIPTION:
	Set the default color-table for the plot-widget, widgetData.dw_draw
      papco internally supports a maximum of four simultaneous color tables.
      They are made by partitioning the existing single 255 color table.
      The X-windows system uses some of these colors, the remaining
      number is used by papco.
      The top 16 colors are hardwired to some nice primary colors for
      coloring line plots, the remainder subdivided into four tables.
      The papco default table (rainbow) is loaded into the bottom of the
      four subtables, and is the color table used unless the user
      specifies another color table.
      The remaining three slots are filled with further pre-defined
      color tables. It is these that the user may change and substitute
      with his own.

 INPUTS:
	none

 KEYWORDS:
 	none

 CALLING SEQUENCE:
	papco_SetColorTable

 MODIFICATION HISTORY:
     february 1997, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_color.pro:134)

papco_setenv

 [Previous Routine] [Next Routine] [List of Routines] 
 Procedure:    papco_setenv

 description:  sets an environmental variable, but also dereferences $HOME for
               unix, and converts paths to os.  Expects the input
               string to be in the UNIX format:
               'ENV_VAR_NAME=env_var_value'

 inputs:       setstr : name and value of the env. var. in above format

 output:       none

 keywords:     FS    - file stystem variable, check for correct naming.

 author:       R. Friedel, October 1997

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:533)

papco_setorbit

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      FUNCTION papco_setorbit, anOrbitNr

 DESCRIPTION:
      Set the orbit.
	This function is invoked, when the user enters an orbit number in
	the orbit-entry-field.
	The new orbitInfo is read and the display is refreshed.

 INPUTS:
	anOrbitNr	an Integer
			containing the number of the orbit

 OUTPUTS:
	a Boolean	0 : the orbit could not be read
			1 : all o.k

 KEYWORDS:
 	none

 CALLING SEQUENCE:
	IF NOT papco_SetOrbit(anInt) THEN print, 'error !'

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_settime.pro:62)

papco_setPlotData

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_setPlotData, aPanelResult, atPosition

 DESCRIPTION:
	This procedure copies the data from a structure that contains some
      or all of the tags that are contained in a PLOTInfo-structure to the
	plot at position 'atPosition', i.e. widgetData.plotInfos(atPosition)

 INPUTS:
	aPanelResult	a structure.
			This structure must contain all fields, that
			the papco_PLOTINFO-structure contains. It MAY contain
 			additional fields.

	atPosition	a non-negative integer
			0<=atPosition<=N_ELEMENTS(widgetData.plotInfos)
			the index of 'widgetData.plotInfos', in which the
			fields of aPanelResult are to be copied.

 KEYWORDS:
 	none

 CALLING SEQUENCE:
	papco_setPlotData, aStructure, anInt

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_plotedit.pro:148)

papco_setTime

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      papco_setTime, newTime, STARTTIME=starttime, ENDTIME=endtime

 DESCRIPTION:
      Whenever the user changes the start- or the endtime using the
	time-sliders or the time-entry-fields, this procedure is invoked
	to calculate the new effectively set time.
	This routine guarantees, that the starttime will be earlier than
	the endtime, and it guarantees, that both values lie in the range
	of the orbit-times.

 INPUTS:
	newTime 	a long
			the new time in seconds.

 KEYWORDS:
 	STARTIME	when set, the newTime-variable specifies the new
			starttime.
	ENDTIME		when set, the newTime specifies the new endtime.

 CALLING SEQUENCE:
	PAPCO_SetTime, seconds, /STARTIME

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_settime.pro:346)

papco_settime[3]

 [Previous Routine] [Next Routine] [List of Routines] 

apco_set_timerange   set timerange for papco widget

(See /home/jbf/ct/papco/working/papco/papco/papco_settime.pro:307)

papco_set_default_widget_font

 [Previous Routine] [Next Routine] [List of Routines] 
 procedure:    papco_set_default_widget_font

 description:  creates a widget for the user to choose a default font
               for all widgets.

 inputs:       none

 output:       none

 keywords:     none

 author:       R. Friedel, May 2003

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco/papco_files.pro:2217)

papco_set_module_defaults

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_set_module_defaults, config_data

 DESCRIPTION:
      Sets all environmental variables in config_data

 INPUTS:
      config_data   configuration data to write

 KEYWORDS:
  none

 OUTPUT:
      none

 MODIFICATION HISTORY:
      written February 2005, R. Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_module_configure.pro:460)

papco_set_module_env_var

 [Previous Routine] [Next Routine] [List of Routines] 
 CALL (papco_set_module_env_var):
     PRO papco_set_module_env_var

 DESCRIPTION:
     This procedure runs through all the module default files and sets the
     required environmntal variables. Useful if you want to be in the PAPCO
     environment without starting the PAPCO widget (which normally does
     this).

 INPUTS:
     none

 KEYWORDS:
     VERBOSE   allows informative output or not
     INFO      prints papco info for this routine

 CALLING SEQUENCE:
     papco_set_module_env_var

 MODIFICATION HISTORY:
     written October 1997, Reiner Friedel
*****************************************************************************

(See /home/jbf/ct/papco/working/papco/papco/papco_set_module_env_var.pro:24)

papco_set_plot

 [Previous Routine] [Next Routine] [List of Routines] 
 procedure:    papco_set_plot

 description:  sets the plot device to the appropriate device for
               the operating system.

 inputs:       device, a string like 'X' or 'PS'

 output:       none.

 keywords:     none.

 author:       Jeremy Faden

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:923)

papco_Set_SubTable

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_Set_SubTable

 DESCRIPTION:
	Sets the internal papco sub colortable to be used for plotting.

 INPUTS:
	c_idx    the index of the papco internal subtable. Allowed Values
                 are 1,2,3. 0 is reserved for to papco default table abd
                 cannot be changed.

 KEYWORDS:
      none

 CALLING SEQUENCE:
	papco_Set_SubTable,c_idx

 MODIFICATION HISTORY:
     february 1997, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_color.pro:409)

papco_set_timerange

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_set_timerange
 DESCRIPTION:  official method for setting the papco timerange.  Both the inner and outter times are changed.
 INPUTS:   
   TIMERANGE, , the new timerange.
 KEYWORDS: none
 SIDE EFFECTS: modifies widgetData.timerange, widgetData.startTime, widgetData.minTime and others.
 EXCEPTIONS:
 EXAMPLES: papco_set_timerange, papco_new_timerange( '2005-017' )
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.91 $
 CURATOR: Jeremy Faden
 HISTORY:  
   Apr 7, 2005, 1.39, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco/papco.pro:530)

papco_show_widgetdata

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
   pro papco_show_widgetdata

 DESCRIPTION:
   Outputs verbose description of the contents of the main
   widgetdata structure that can be overwritten on the papco command
   line by using a keyword equal to the tag name.

 INPUTS: none

 KEYWORDS: none

 CALLING SEQUENCE:
   papco_show_widgetdata
   Called by papco only. May be called from anywhere in PAPCO environment.

 MODIFICATION HISTORY:
   written January 2001, R. Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco.pro:337)

papco_ShrinkMe

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ShrinkMe
 DESCRIPTION: reduce the selected panels' height.  papco_stripemptyslots is
   called after to remove the new gaps between panels.  This is the 
   "Absolute size, Decrease" button's action.
 INPUTS:   
 KEYWORDS:
   NOSTRIP, keyw, don't call papco_stripemptyslots
   ALONE, keyw, affect just the selected panel.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.10 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco/papco_editslots.pro:624)

papco_ShrinkOthers

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_ShrinkOthers
 DESCRIPTION: shrinks the size of other panels relative to the current
   one.  This is "Relative Size, Increase" button's action.
   This is done in two ways:
      a) if the other panel are larger than height "1", their height
         is reduced.
      b) if one of the other panel is of height "1", the current panel is
         enlarged by "1". 
   Care is taken of overplots. ALL overplots that overlap at the
   current position are treated the same way as the panel at the
   current position.
 INPUTS:   
 KEYWORDS:
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.10 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco/papco_editslots.pro:444)

papco_sizeBytesOf

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_sizeBytesOf 
 DESCRIPTION: returns the size of an IDL value, recursing through tags of a structure.
 INPUTS: 
   V, idl value, the value to estimate the size of
 KEYWORDS: none
 RETURNS: 
   long, size of the value in bytes.
 EXAMPLES:
   print, papco_sizeBytesOf( papco_ds_testDs(0) )
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.25 $
 CURATOR: Jeremy Faden
 HISTORY:  
   Feb 9, 2006, 1.10, found on the web and integrated by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_cache.pro:525)

papco_slices[1]

 [Previous Routine] [Next Routine] [List of Routines] 
  redraw using the slice_calls.
  seconds=  reset the seconds to be new value

(See /home/jbf/ct/papco/working/papco/papco/papco_slices.pro:252)

papco_slices[3]

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION
      papco_multiple_slice

 DESCRIPTION:
	Sets up widget to choose multiple slices

 INPUTS:
	slice_name    string array of slice name

 OUTPUTS:
      result        bytearray of slices set
 KEYWORDS:
 	none

 CALLING SEQUENCE:
	result=papco_multiple_slice(slice_name)

 MODIFICATION HISTORY:
     written march 20007, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_slices.pro:1314)

papco_slice_get_slices

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      FUNCTION  papco_slice_get_slices

 DESCRIPTION:
                   reads available slices for a module

 INPUTS:
	module       name of the module for which the slices are to be found.

 KEYWORDS:
 	none

 OUTPUT:           list of available slices from header of module_slice.pro

 MODIFICATION HISTORY:
     November 2000, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/slice_thumbs/papco_slice_panel.pro:55)

papco_slice_names

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      papco_slice_names

 DESCRIPTION:
	Returns a strarr of the loaded slice types

 INPUTS:
	none

 KEYWORDS:
 	none

 CALLING SEQUENCE:
	result=papco_slice_names()

 MODIFICATION HISTORY:
     written October 2005, Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco/papco_cursor.pro:1653)

papco_slice_panel[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      FUNCTION  papco_slice_panel, plotinfo, GROUP=group, ACTION=ACTION

 DESCRIPTION:
	Open an editor for a slice panelplot.
	Its window is constructed using the methods defined in the file
	$PAPCO_PATH/papco_panel.pro
	When the user presses the 'Done'- or the 'Cancel'-Button, the values
	changed by the event-methods of papco_panel.pro are returned.
	The returned value is a structure containing those values and a flag,
	'canceled', which the caller may read out to check, whether the
	window was closed using the 'Cancel' or the 'Done'-Button.

 INPUTS:
	plotinfo	a structure of the PAPCO_PLOTINFO-type
			this structure is edited in the window.

 KEYWORDS:
 	GROUP		a WIDGET_BASE
			when specified, this is used as GROUP_LEADER
	ACTION		a string
			when specified, the 'Done'-Button is labeled with it
		        if not specified, the 'Done'-Button is labeled 'Done'
      MODULE          the name of the module that called this routine.

 OUTPUT:
      a default-structure of type PAPCO_PANEL_EDITOR_RETURN. Though this
	type is nowhere defined, I like to think of it as virtually existing
	data-type.
	All the functions in $PAPCO_PATH/papco.pro that edit plots or add new
	ones, expect the opened editor-windows to return a structure containing
	at last some fields. Those fields might make up a structure, but as no
	program defines the structure-type PAPCO_PANEL_EDITOR_RETURN, this
	poor structure is not alive but only virtual.
	The return-values of plot-editors have to expand this structure - I
	like to think, that they inherit from that structure - and contain at
	least those fields:
   		{$
			canceled:1, $
	    		panelHeight:1, $
	    		channel:0, $
	    		typeVector:[0,0,0,0], $
	    		manualYScaling:0 $
	    		yScaleMin:LONG(1), $
	    		yScaleMax:LONG(1), $
	    		panelKind:'some string'}

      Additionally, some Panel-editors may return these fields in
      structure:
               {$
		        color:1, $
			plotStyle:1}

      For an enhanced description read $PAPCO_PATH/papco_variables.text

 CALLING SEQUENCE:
	plotinfoStruct=PAPCO_getPlotInfoStruct()

(See /home/jbf/ct/papco/working/papco/papco_lib/slice_thumbs/papco_slice_panel.pro:165)

papco_slice_panel_event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_slice_panel_event, event

 DESCRIPTION:
	This processes events from the XMANAGER.
	As this example does not extend the basic functionality of plot-
	editors, it directly calls the default-handler, PAPCO_PANEL_Event

 INPUTS:
	event		an XManager event

 KEYWORDS:
 	none

 CALLING SEQUENCE:
	called by XMANAGER

(See /home/jbf/ct/papco/working/papco/papco_lib/slice_thumbs/papco_slice_panel.pro:344)

papco_slice_time_list

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_slice_time_list

(See /home/jbf/ct/papco/working/papco/papco_lib/slice_thumbs/papco_slice_panel.pro:732)

papco_slice_value

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      papco_slice_value

 DESCRIPTION:
	Returns the slice value assigned to slice_name. If slice_name
      is not uniquely found, 0 is returned.

 INPUTS:
	SLICE_NAME, string, the slice name

 RETURNS:
      int, the code (2**k) flagging this slice type.

 KEYWORDS:
 	none

 EXAMPLES:
   slice_assigned_value_1=papco_slice_value('USER 3DD Slice')
   slice_assigned_value_3=papco_slice_value('USER Cluster 4SC 3D view')
   slice_type = slice_assigned_value_1+slice_assigned_value_3

 CALLING SEQUENCE:
	result=papco_slice_value(slice_name)

 MODIFICATION HISTORY:
     written october 1997, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_cursor.pro:1689)

papco_smooth[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_smooth

 DESCRIPTION:  wrapper to the IDL function smooth, but extended
               functionality to preserve bad data flags.

 KEYWORDS:     NODATA - bad data flag, default is -99.0

 INPUTS:       same as IDL function smooth

 OUTPUT:       smoothed array

 HISTORY:      written June 2003, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_math.pro:570)

papco_smooth[2]

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_smooth

 DESCRIPTION:  wrapper to the IDL function smooth, but extended
               functionality to preserve bad data flags.

 KEYWORDS:     NODATA - bad data flag, default is -99.0

 INPUTS:       same as IDL function smooth

 OUTPUT:       smoothed array

 HISTORY:      written June 2003, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:1258)

papco_spawn

 [Previous Routine] [Next Routine] [List of Routines] 
 Procedure:    papco_spawn, cmdline, result

 description:  Runs operating system commands. Only works for the
               list of commands "known" here. The cmdline passed in is
               parsed for a set of "known" commands, and the correct
               command for the os is inserted. The arguments are NOT
               checked.

 inputs:       cmdline : command line string, needed
               result  : if passed in, pass out output of spawn in it.

 output:       none

 keywords:     none

 author:       R. Friedel, October 1997

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:767)

papco_spectrogram

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_spectrogram 
 DESCRIPTION:  draw a spectrogram of a rank 2 dataset
 INPUTS:   
   DS, papco dataset, rank 2 papco dataset
 KEYWORDS:
   OVERPLOT, boolean, overplot on the existing axes.
   [XYZ]SCALE, fltarr(3), [min,max,log]
   TIMERANGE, { papco_timerange }, the xaxis time range
   PANEL, intarr(3), papco panel vector, indicating the spectrogram is a panel.
   DRAW_COLORBAR, boolean, draw a colorbar alongside.
   OUTPUT, output the data instead of plotting it.
   _EXTRA keywords are sent to papco_plotcolor
 RETURNS: 
   type, description
 SIDE EFFECTS:
   messages are sent to the developer logger 
   plot axes are modified.
 EXCEPTIONS:
   This is based an old code with lots of kludges and failure modes.  
 EXAMPLES:
 UNIT TEST: test_papco_ds_grid
 CVSTAG: 
   $Name:  $
   $Revision: 1.18 $
 CURATOR: Jeremy Faden
 HISTORY:  
   Sept 2005, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_spectrogram.pro:29)

papco_spectrogram2

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE: papco_spectrogram2, DS
 DESCRIPTION: spectrogram routine based on dataset operations.  It's much 
   simpler than the legacy spectrogram, and much faster.
 INPUTS:   
   DS, papco dataset, a rank 2 papco dataset.
 KEYWORDS:
   _EXTRA, extra keywords are passed on to papco_plot.
 SIDE EFFECTS: plot coordinates are affected
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: test_papco_ds_spectrogram2
 CVSTAG: 
   $Name:  $
   $Revision: 1.2 $
 CURATOR: Jeremy Faden
 HISTORY:  
   19-March-2007, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_spectrogram2.pro:165)

papco_spectrogram_get_pixel_ds

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_spectrogram_get_pixel_ds    
 DESCRIPTION: return a tags dataset with pixel cadence 
 INPUTS:   
   AXIS, int, 0=xaxis, 1=yaxis
 KEYWORDS:
   _EXTRA, additional keywords are added to the dataset
 RETURNS: 
   papco dataset, a rank 1 tags dataset for the axis.
 KEYWORDS RETURN:
   DPOS, intarr[2], the device position.  PS resolution is limited to screen resolution
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.2 $
 CURATOR: Jeremy Faden
 HISTORY:  
   19-March-2007, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_spectrogram2.pro:24)

papco_spec_fit

 [Previous Routine] [Next Routine] [List of Routines] 
 Function: papco_spec_fit
 
 Description: Generalized routine to fit a selected function to
              experimental data 
 
 Inputs:   
           energy - 1 (central energy) or 2 (start and end energies)
                    dimensional array. Dimension: (1/2,flux_vals)
                    
           flux   - array of measured flux at given energies (energy
                    bins) Dimension: flux_vals
                    
           err    - array of measurement errors, Dimensions:
                    flux_vals
        
           output - array of energies for which fitted fluxes should
                    be returned
 
 Outputs:  Structure with fit Parameters and description

 Keywords: FITFUN - string, or array of strings giving function to
                     use for fit (MAXWELLIAN, KAPPAFUN, SINGEXP, DBLEXP, GAUSSIAN,POWER)
           FITSEP -  separation between different fits. Must have one
                    less elements than FITFUN (or none if FITFUN has
                    only one element) 
           FITLIM - the absolute limits for the fit in energy 
           PLOT -   plot the flux and fit
           ONECOUNT - array of one count levels to plot
           INITIND - indices to use for start parameter calculations

           NOWINDOW - plot into exisiting window, use existing scaling
           REM_NEG -remove negative values in the flux

 Modification History: 
           Written by Arne Aasnes at LANL, Jan. 2004

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_spec_fit.pro:38)

papco_stripEmptySlots

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_stripEmptySlots
 DESCRIPTION: Action performed by Reform->"remove gaps", strip all empty slots
 INPUTS:   
 KEYWORDS:
   NOREFRESH, type, description
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.10 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_editslots.pro:98)

papco_struct_combine

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_struct_combine
 DESCRIPTION: returns the union of the two structures.  This is a wrapper for create_struct,
    but allows for a null argument.  This cleans up code greatly. 
 INPUTS:   
   STRUCT1, struct, a structure.  Undefined is okay too.
   STRUCT2, struct, a second structure.  Undefined is okay too.
 KEYWORDS:
   NAME, string, a name for the new structure
 RETURNS: 
   struct, the new structure
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.6 $
 CURATOR: Jeremy Faden
 HISTORY:  
   10-Aug-2006, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_util.pro:88)

papco_struct_extract

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_struct_extract  
 DESCRIPTION: Extract a set of tags from struct.  
 INPUTS:   
   STRUCT, struct, the structure from which tags are extracted
   TAGS, strarr, strarr of the tags to keep, can be regular expressions
 KEYWORDS:
   DEPEND, strarr, automatically add depend tags.
   ADDNAMES, strarr, used with ADDVALUES to add additional tags to new struct.
      Empty tag names are ignored.
   ADDVALUES, ptrarr, used with ADDNAMES to add additional tags to new struct
 RETURNS: 
   struct, struct of extracted tags
 SIDE EFFECTS: calls heap_gc
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: test_papco_struct_extract
 CVSTAG: 
   $Name:  $
   $Revision: 1.6 $
 CURATOR: Jeremy Faden
 HISTORY:  
   10-Aug-2006, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_util.pro:185)

papco_struct_form

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_struct_form
 DESCRIPTION: create a structure from an array of strings and an array of pointers.  
   This was introduced when support for the runtime environment was introduced,
   because it avoids the use of execute.  Note this recurses (calls itsself) when 
   more than 8 tags are used.
 INPUTS: 
   TAGS, strarr, array of tag names.  empty tag names are ignored.
   VALUES, ptrarr, array of pointers to the tag values.
 KEYWORDS:
   NAME, string, name the structure so it can be used in other name structures.
 RETURNS: 
   struct, the new structure
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.6 $
 CURATOR: Jeremy Faden
 HISTORY:  
   10-Aug-2006, 1.1, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_util.pro:28)

papco_struct_shadow

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:  papco_struct_shadow   
 DESCRIPTION:  combines the two structures, but where both structures contain the same tag
   the value from the second is used.  This allows str2 values to override values
   from str1.
 INPUTS:   
   STR1, struct, the first struct
   STR2, struct, the second struct.  
 KEYWORDS:
   NAME, string, name the new structure.
 RETURNS: 
   type, description
 SIDE EFFECTS: heap_gc is called.
 EXCEPTIONS:
 EXAMPLES:
   default_pparm= { color:1, xtitle:'x', xlabel='the label' }
   my_pparm= { color:0, xlog:1 }
   pparm= papco_struct_shadow( default_pparm, my_pparm )
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.6 $
 CURATOR: Jeremy Faden
 HISTORY:  
   05-Mar-2007, 1.4, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_ds_util.pro:124)

papco_subtable_editor

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_subtable_editor

 DESCRIPTION:
	Widget to interactively modify PAPCO color sub-tables

 INPUTS:
      

 KEYWORDS:
      

 OUTPUT:
      

 CALLING SEQUENCE:
	

 MODIFICATION HISTORY:
     August 1999, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_subtable_editor.pro:76)

papco_subtable_editor_refresh

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_subtable_editor_refresh

 DESCRIPTION:
	Referesh routine for papco_subtable_editor

 INPUTS:
      

 KEYWORDS:
      

 OUTPUT:
      

 CALLING SEQUENCE:
	

 MODIFICATION HISTORY:
     August 1999, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_subtable_editor.pro:22)

papco_SubTable_used

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      FUNCTION papco_SubTable_used

 DESCRIPTION:
	Test if the specified subtable is currently in use.

 INPUTS:
	c_idx    the index of the papco internal subtable. Allowed Values
                 are 1,2,3. 0 is reserved for to papco default table

 KEYWORDS:
      none

 CALLING SEQUENCE:
	res = papco_SubTable_used(c_idx)

 MODIFICATION HISTORY:
     february 1997, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_color.pro:480)

papco_s_module_init

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_s_module_init

 DESCRIPTION:
      Writes the file papco_module_init.pro needed to compile modules.  This script
  includes all the init_module.pro files found on the path.

 INPUTS:
  none

 KEYWORDS:
  EMPTY:   Writes an empty file (used in no modules are configured)
      FILE:    Used this file name as output file name

 CALLING SEQUENCE:
  papco_s_module_init

 MODIFICATION HISTORY:
      written March 1998, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_configure.pro:1802)

papco_thumb_plot

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_thumb_plot

 DESCRIPTION:
      Plots a series of thumb plots into a standard papco panel.
      Does the positioning of thumbs in the panel, and calls an
	external routine for the actial plot.
	Basics come from J. Faden, extended here to work with slices. 
	
	
 KEYWORDS:
 	SLICE_CALL  the name of the module's slice routine to be called
      PANEL_NR the Panel nr. to be associated with the slice.

(See /home/jbf/ct/papco/working/papco/papco_lib/slice_thumbs/papco_thumb_plot.pro:16)

papco_timerange::timeshift

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_timerange::timeshift
 DESCRIPTION: creates a new timerange object that is SELF shifted by SHIFTOBJ, a time offset. 
 INPUTS:   
   SHIFTOBJ, papco_timeOffset::, the amount to shift
 KEYWORDS:
 RETURNS: 
   papco_timerange::, the new timerange, which will have the same length.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
   timeRange= papco_new_timeRange( '2001-001' )
   pprint, timeRange->timeShift( papco_new_timeOffset( '12 hours' ) )
   ; this prints "1/1/2001 12:00 - 1/2/2001 12:00"
 UNIT TEST: 
 CVSTAG: 
   $Name: $
   $Revision: $
 CURATOR: Arne Asnes
 HISTORY:  
   02-May-2007, 1.23, written by Arne Asnes

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_timerange.pro:664)

papco_timeticks[1]

 [Previous Routine] [Next Routine] [List of Routines] 
e: all time labeling routines return two lines, the first being
 time of day, the second the date. Dates are only printed if they
nge from the previous tick mark.

(See /home/jbf/ct/papco/working/papco/papco_lib/axis_label/papco_timeticks.pro:5)

papco_timeticks[2]

 [Previous Routine] [Next Routine] [List of Routines] 
t_yyyymmmdd returns dates as mjdt_ddmmmyyyy, eg. 27Nov1987

(See /home/jbf/ct/papco/working/papco/papco_lib/axis_label/papco_timeticks.pro:8)

papco_timeticks[3]

 [Previous Routine] [Next Routine] [List of Routines] 
t_hhmm returns dates as hh:mm, eg 16:40.  parameter "t"
ould be in seconds since the midnight before mjdt_start.

(See /home/jbf/ct/papco/working/papco/papco_lib/axis_label/papco_timeticks.pro:54)

papco_timeticks[4]

 [Previous Routine] [Next Routine] [List of Routines] 
t_date_sec returns dates as hh:mm !C ss.mss

(See /home/jbf/ct/papco/working/papco/papco_lib/axis_label/papco_timeticks.pro:85)

papco_timeticks[5]

 [Previous Routine] [Next Routine] [List of Routines] 
t_date_ms returns dates as ss.mss
                  modified from Friedel's mjdt_date_4
                  by Doug Rowland

(See /home/jbf/ct/papco/working/papco/papco_lib/axis_label/papco_timeticks.pro:121)

papco_timeticks[6]

 [Previous Routine] [Next Routine] [List of Routines] 
 function find_timeticksmjd
 takes starttime,endtime in time in seconds
 since the start of the first Modified Julian day
 loaded into PAPCO (PAPCO standard)
 spits out "nice" ticks
 formatstring is the routine that should be used to label the ticks

(See /home/jbf/ct/papco/working/papco/papco_lib/axis_label/papco_timeticks.pro:258)

papco_time_adjust

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_time_adjust

 DESCRIPTION:
      This procedure is called when time needs to auto adjusted according
      to what is set in default_adjust_time

 INPUTS:
	none

 KEYWORDS:
 	none

 CALLING SEQUENCE:
	papco_time_adjust

 MODIFICATION HISTORY:
      written march 2000, Reiner Friedel
      check for invalid time ranges, revert to no adjust.  Jeremy Faden 2006 Nov 7

(See /home/jbf/ct/papco/working/papco/papco/papco_settime.pro:512)

papco_time_average

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:    papco_time_average, t, y

 DESCRIPTION:  performs time averageing of data onto fixed time intervals

 KEYWORDS:     

 INPUTS:       

 OUTPUT:       

 HISTORY:      written February 2007, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:2699)

papco_trim

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_trim
 DESCRIPTION:  
 INPUTS:   
   ARRAY, type, description
 KEYWORDS:
   EXCLUDE, type, description
   NODATA, type, description
 RETURNS: 
   type, description
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CATEGORY: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.14 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_math.pro:792)

papco_unilib_exe

 [Previous Routine] [Next Routine] [List of Routines] 
 function:     papco_unilib_exe

 description:  returns the correct path to the UNILIB .so file for
               the current operating system.

 inputs:       none

 output:       path string

 keywords:     none

 author:       R. Friedel, June 2003

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:1096)

papco_unzip

 [Previous Routine] [Next Routine] [List of Routines] 
 Procedure:    papco_unzip, cmdline, result

 description:  Runs operating system command for unzipping files
               Uses unzip on UNIX / MAC OS10
               Uses the command line version of WINZIP 8.1 on Windows WZUNZIP
               No support for other MAC OS or VMS yet.
               Action: unzips files PRESERVING origimal zipped file.


 inputs:       cmdline : command line string, needed
               result  : if passed in, pass out output of spawn in it.

 output:       result

 keywords:     VERBOSE - print cmdline before executing

 author:       R. Friedel, July 2003

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco/papco_opsys.pro:596)

papco_usage

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_usage

 PURPOSE: routine the source file for a given routine

 CATEGORY:

 CALLING SEQUENCE: papco_usage, routine

 INPUTS:
   routine,  string that is the name of the routine (no .pro)

 KEYWORD PARAMETERS:

 OUTPUTS:
   prints the a short statement about the usage of the routine.

 SIDE EFFECTS:
   automatically compiles the routine if it is not compiled.

 RESTRICTIONS:
   calls and parses the output of "help, source."  IDL discourages
   this practice and reserves the right to make changes to the help
   output format.  This may cause this code to fail in future
   revisions of IDL.

   Also, the filename and paths may contain spaces, and the code can
   handle this!

   Does not work under IDL 4.0

 PROCEDURE:
   call "help, /routine", and parse output.

 EXAMPLE:
   papco_usage, 'which'

 SEE ALSO: ROUTINE_INFO, which provides much of this functionality

 MODIFICATION HISTORY:
   written, Jeremy Faden, January, 2002.  University of Iowa

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_usage.pro:44)

papco_util[10]

 [Previous Routine] [Next Routine] [List of Routines] 
 New general method to make L-spec based on flux v. time and L
 v. time data. Needs lbin and ltav set in control structure.

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:2847)

papco_util[4]

 [Previous Routine] [Next Routine] [List of Routines] 
 papco_total

 DESCRIPTION Wrapper routine to IDL total, do be able to check for
 nodata

 KEYWORDS: NODATA - bad data flag, default is -99.0
           CUMULATIVE -

 INPUTS: arr - array to sum
         dim - dimension to sum over

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:1617)

papco_util[5]

 [Previous Routine] [Next Routine] [List of Routines] 
 r = v(perp)/w = mv(perp) /(|q|B)
 E - particle energy, in keV
 B - mag field, in nT
 alpha - particle pitch angle
 species - 0 elec, 1 ion, 2 oxygen

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:1914)

papco_util[7]

 [Previous Routine] [Next Routine] [List of Routines] 

apco_plot_state

aves, restores and resets current idl plot state
/reset_colors
/reset_axes

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:2243)

papco_util[8]

 [Previous Routine] [Next Routine] [List of Routines] 
 Function to substitute into a path/file the year/date given by
 the input papco time

 Keywords: START_MJDT  - use current PAPCO start time
           TEMPLATE    - substitute current template string
           VERSION     - check for version numbers in file "_vXX" or
                         "_VXX" replace XX by wildcards
           /GLOB       - put the glob chars in instead of the YYYY, etc
           /CLUSTER_C1 - replace "c[1-4]_" with "c?_"
*****************************************************************************

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:2444)

papco_util[9]

 [Previous Routine] [Next Routine] [List of Routines] 
 routine to check keywords and set default value
 used as a wrapper to much used code like

 IF keyword_set(VERBOSE) THEN verbose = VERBOSE ELSE verbose=0

 Any number of keywords can be checked and set at once. Keywords are
 all collected into _extra and passed to the routine.

 defaults is a structure of corresponding default values in a 1-to-1
 correspondence.

           Author: R. Friedel at LANL, February 2006

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:2571)

papco_valid_average[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      papco_valid_average, x, iny,outy, outystruc,nodata,PASS_AVE=PASS_AVE

 DESCRIPTION:
      This procedure outputs average of valid (non-nodata)
      across time period where data is valid

 INPUTS:
      x,iny     arrays to be plotted
      nodata  bad data flag value

 KEYWORDS:
      PASS_AVE, array of data of same dimensions as iny where 1's
        represent period of 'x' in which average must be calculated. This was
        made for time where one requires the average value during a satellite
        pass thru and L range, but data coverage was not full (ie data gaps
        requested so and average during hte time period requested ignoring
        datagaps is needed)


 OUTPUTS:
      outy     averaged data values
      outystruc, structure containing average, skew etc from idl
      moment function , along with std_dev and min max values
      of averaged array
 CALLING SEQUENCE:
      papco_valid_average, x, iny,outy, outystruc,nodata,PASS_AVE=PASS_AVE

 MODIFICATION HISTORY:
     written August 2003 by MATT 'I pity da fool' TAYLOR

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_math.pro:62)

papco_valid_average[2]

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      papco_valid_average, x, iny,outy, outystruc,nodata,PASS_AVE=PASS_AVE

 DESCRIPTION:
      This procedure outputs average of valid (non-nodata)
      across time period where data is valid

 INPUTS:
      x,iny     arrays to be plotted
      nodata  bad data flag value

 KEYWORDS:
      PASS_AVE, array of data of same dimensions as iny where 1's
        represent period of 'x' in which average must be calculated. This was
        made for time where one requires the average value during a satellite
        pass thru and L range, but data coverage was not full (ie data gaps
        requested so and average during hte time period requested ignoring
        datagaps is needed)


 OUTPUTS:
      outy     averaged data values
      outystruc, structure containing average, skew etc from idl
      moment function , along with std_dev and min max values
      of averaged array
 CALLING SEQUENCE:
      papco_valid_average, x, iny,outy, outystruc,nodata,PASS_AVE=PASS_AVE

 MODIFICATION HISTORY:
     written August 2003 by MATT 'I pity da fool' TAYLOR

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:1720)

papco_version[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 This file is part of the PAPCO software package.

 PAPCO is a free IDL package to combine data plots written and
 maintained by A. Keese and R. Friedel.

    For more information, check the papco home page at
    http://leadbelly/ccr/software/papco/papco.html
    for online Manual and downloadble latest version.

 Comments and questions can be directed to friedel@lanl.gov

 You are free to modify and distribute this file. However, and
 changes not communicated to R. Friedel will not become part of the
 next release of PAPCO.

(See /home/jbf/ct/papco/working/papco/papco/papco_version.pro:16)

papco_version[2]

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
     papco_version

 PURPOSE:
     This function returns a string containing the current version of PAPCO.
     It is used to label the main-window and is included in the first
     line of papco-save-files. Date MUST be of format "dd mmm yyyy"
     and MUST come at end of string.

 CATEGORY:
     Documentation

 CALLING SEQUENCE:
     Result = papco_version()

 INPUTS:
     none

 KEYWORD PARAMETERS:
     INFO:   Calls doc_library to display this header documentation.
             1: print to terminal, 2: print to default printer
     /release_tag  return the cvs release tag instead of the version string.
     /interface_version  modules can check this to support earlier versions
         of papco.  This is a number that will increase with papco versions.
 OUTPUTS:
     This function returns a string of the PAPCO version information.

 MODIFICATION HISTORY:
     Written by:  Reiner Friedel, May 1998
     Modified:    Each time a new version is released

(See /home/jbf/ct/papco/working/papco/papco/papco_version.pro:48)

papco_vert_slice

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_vert_slice, panelNr, seconds, yValue, CLOSE=CLOSE

 DESCRIPTION:
	The slice-window displays a slice through the data,
	when the user clicks in the drawing-widget.
	This procedure opens that window and calls other routines, that draw
	the slice.

 INPUTS:
	panelNr	 	an integer
			the number of the panel for which the slice is to be
			drawn
	seconds		a float
	yvalue		a float
			the time and the y-value, for that the slice shall
			be drawn

 KEYWORDS:
 	CLOSE		   when specified, the window is destroyed
  sliced_panel   this was the panel that generated the slice
  overplot       0=first panel, 1=second, etc. or panel_count
  panel_count    number of panels to come

 CALLING SEQUENCE:
	papco_vert_slice, aPanel, convert_tzero_to_t90(3600, 1, 1990), 42.42
	papco_vert_slice, /CLOSE

 MODIFICATION HISTORY:
     written august and september 1995, Andreas Keese
     modified for modules may 1996, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_slices.pro:826)

papco_vert_slice_Event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_vert_slice_Event, Event

 DESCRIPTION:
	The slice-window displays a slice through the data,
	when the user clicks in the drawing-widget.
	This procedure handles events for that window.
 INPUTS:
	Event	 	an XMANAGER-event

 KEYWORDS:
 	none

 CALLING SEQUENCE:
	called by XMANAGER

 MODIFICATION HISTORY:
     written august and september 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco/papco_slices.pro:524)

papco_vert_slice_generic

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: papco_vert_slice_generic 

 PROCEDURE:
      PRO papco_vert_slice_generic, panelNr, seconds, yValue

 DESCRIPTION:
      Automatic slicer for papco datasets.  This should work as long as
      papco_set_plotted_dataset, dataset  as used in the plotter, and the
      where dataset is a conventional papco12 dataset.  (See papco_ds.pro)

 INPUTS:
      panelNr     an integer, the number of the panel for which the slice
                  is to be drawn
      seconds     time of mouse click, a float
      yvalue      y-value of mouse click, a float

 KEYWORDS:
      none
      papco12 compliant

 CALLING SEQUENCE:
      called by papco_DrawSLice (in $papco_PATH/papco_cursor.pro)

 MODIFICATION HISTORY:
      December 1995, written by R.Friedel at Goddard
      Feb 2006, Jeremy Faden generic version

(See /home/jbf/ct/papco/working/papco/papco_lib/dataset/papco_vert_slice_generic.pro:28)

papco_wget[1]

 [Previous Routine] [Next Routine] [List of Routines] 

apco_wget_credentials_check

ttempt to connect to server

eturns:
0  successful at checking credentials
499 bad_login
!=0 some other error, indeterminate

(See /home/jbf/ct/papco/working/papco/papco/papco_wget.pro:183)

papco_wget[2]

 [Previous Routine] [Next Routine] [List of Routines] 
 Procedure:    papco_wget

 description:  Downloads data file from remote system using Wget utility.


 inputs:       url, e.g. ftp://user.pwd@nis-ftp.lanl.gov/omni/omni2_1997.idl
               logfile is complete path and name of log file

 output:       pid is process identifier for wget subprocess

 keywords:     
               block   wait until download is complete before returning
               timeout_seconds   timeout for connection
               monitor     progress monitor object (currently ignored)
               status      returns 0 if okay, see table above (only set
                           if /block is used)
               /credentials_check  we're really just wanting to check
                           credentials, so only return valid status
                           =499 or =0.

 author:       J. Roeder, November 2003

 changes:      Jeremy Faden, September 2004.  pid is the pid of the
                  wget process, not the unix shell

(See /home/jbf/ct/papco/working/papco/papco/papco_wget.pro:276)

papco_wget_listing

 [Previous Routine] [Next Routine] [List of Routines] 
 Procedure:    papco_wget_listing

 description:  Downloads listing of a remote directory.

 inputs:       url ie ftp://user:password@nis-ftp.lanl.gov/omni/

 output:       strarr of the files.

 keywords:
    monitor   optional object that implements papco_monitor
    status    =0 success, !=0 wget failure (see papco_wget)
    isFolderArr  intarr for each name.  =1 indicates folder, =0 indicates file
    error_message=  returns human-consumable error message from wget

 author:       Jeremy Faden, September 2004

 notes:    see papco_web_filesystem for more complex filesystems, as
           it supports caching results and checks for ls-lLR files.

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco/papco_remote_filesystem.pro:88)

papco_wget_log_check

 [Previous Routine] [Next Routine] [List of Routines] 
 Procedure:    papco_wget_log_check

 description:  checks contents of wget logfile to determine status.
               Knows how to look in the log file of each wget
               version and derive failure information

 returns:      1 if status is determinable
               0 indeterminable

 output:       status=0  success
               status=401
               status=498 unable to connect
               status=499 bad credentials
               status=493 file not found

 keywords:
    /done      wget is done, so give a definitive answer
    /credentials_only   only check if credentials are okay
    progress_percent=p  progress as a percentage

(See /home/jbf/ct/papco/working/papco/papco/papco_wget.pro:35)

papco_widget_base

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION: PAPCO_WIDGET_BASE
 DESCRIPTION: wrapper for WIDGET_BASE. Behaves the same way.  
 INPUTS:   
 KEYWORDS:
   MODAL, boolean, widget should be modal
   GROUP_LEADER, long, use this widget as the leader
   _EXTRA, extra keywords are passed to widget_base
 RETURNS: 
   long, widget base
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.7 $
 CURATOR: R. Friedel
 HISTORY:  
   Written R. Friedel, January 1998

(See /home/jbf/ct/papco/working/papco/papco/papco_idlver.pro:51)

papco_writeDefaultSettings

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_writeDefaultSettings

 DESCRIPTION:
      At program-end, this procedure writes all the default-settings
      and other "remembered" settings.
  Defaults file:  $PAPCO_USER/papco_default.dat
      At program-start, they are read by papco_readDefaultSettings

      All common paramters for PAPCO are stored in the structure and
      common block:

        common plot_composer, widgetdata

      Here we store all tags of the structure whose name contain
      any of the the following strings:string "default" in a text file.

         default - all the varibales from the papco defaults widget
         keep    - any variables that need to be "remembered" for
                   the next PAPCO session.

      We write to file the name of the variable, followed by the IDL_SIZE
      structure for that variable, followed by the variable contents.

 INPUTS:   none

 KEYWORDS: none

 CALLING SEQUENCE:
  papco_writeDefaultSettings

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese
     modified october 1996, Reiner Friedel
     generalized Februaty 2000, Reiner Friedel, for easy expandability.

(See /home/jbf/ct/papco/working/papco/papco/papco_files.pro:796)

papco_writeOrbitInfo

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      papco_writeOrbitInfo

 DESCRIPTION:
      the orbit-infos are written.

 INPUTS:
      SCraft:      Name of space craft
      orbitInfo :  an array containing instances of the
                   ORBIT_INFO-structure

 OUTPUT:
      a string. If writing was succesful, the string is 'OK'.
      If not, it contains the error message

 CALLING SEQUENCE:
	result=papco_writeOrbitInfo(SCraft, anOrbitInfoArray)
	IF result NE 'OK' THEN BEGIN
         print, 'error:' + result
	   return
      ENDIF

 MODIFICATION HISTORY:
     october 1996, written by R. Friedel
     july 1997, Haje Korth

(See /home/jbf/ct/papco/working/papco/papco/papco_orbitinfo.pro:174)

papco_write_batch

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
   PRO papco_write_batch, fileName, batch_times

 DESCRIPTION:
   wirites the contents of batch_times to a papco bacth file.

 MODIFICATION HISTORY:
   January 2001, written by R. Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_files.pro:868)

papco_write_data

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE: papco_write_data, time, data

 DESCRIPTION:
	writes the calling modules' panel plot data to file. The
	filename is constructed using the time range of the plot and the
	product name if set.

 INPUTS:
      time            the time array of the data (dimension n)
	data            the data array (dimension [n*ch] or [ch])
                        where n is the number of points of the time array,
                        and ch is the number of data channels.

 OUTPUTS:
      none

 KEYWORDS:
 	DESCRIPTION   a string or string array describing the data
      TIME_LABEL    a string decribing the x-axis format if it is time
                    if empty or unknown format, use time as is
                    known formats:  'TAI'   -   int. atomic time
                                    'DMJD'  -   dec. mod. Julian day
                                    'DY'    -   decimal year
                                    'T90'   -   sec since 1/1/1990
                                    'SSD'   -   sec from start day
                                    'YDD    -   year and decimal day
      SLICE         a string containg the time of the data for slice
      CHANNELS      an (ch,2) array giving the channel start/end
      X_LABEL       a string with the x-axis label
      Y_LABEL       a string with the y-axis label
      Z_LABEL       a string with the z-axis label
      RS_LABEL      a string with the righ-side label of the plot
      NODATA        contains the no data flag value.
      ONECOUNT      an (ch) array giving the one count level
      FORMAT        a string for the file output format:
                       'TXT'   - ASCII flat text file
                       'CDF'   - common data format (binary)
                       'IDL'   - IDL save/restore set (binary)
                       'MEM'   - put data in common block for
                                 scratch pad
                       'PUM'   - PAPCO utility module / S. Bourdarie
      FILE          if setm use this string as filename.

 CALLING SEQUENCE:
	called from the user modules' plot routine.

 MODIFICATION HISTORY:
     written May 1998, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_output.pro:115)

papco_write_paneldata

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_write_paneldata, panelNr, seconds, yValue, CLOSE=CLOSE

 DESCRIPTION:
	The slice-window displays panelinfo, when the user clicks
	in the drawing-widget.
	This procedure opens that window and displays data about the position
      clicked, it x/y coordinates. A user-defined rountine can be called for
      auxilliary info, e.g. the ephemeris info.

 INPUTS:
	panelNr	 	an integer
			the number of the panel for which the slice is to be
			drawn
	seconds		a float
	yvalue		a float
			the time and the y-value, for the slice

 KEYWORDS:
 	CLOSE		when specified, the window is destroyed

 CALLING SEQUENCE:
	papco_write_paneldata, aPanel, sometime, 42.42
	papco_write_paneldata, /CLOSE

 MODIFICATION HISTORY:
     written october 1996, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_slices.pro:107)

papco_write_paneldata_Event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO papco_write_paneldata_Event, Event

 DESCRIPTION:
	The slice-window displays a slice through the data,
	when the user clicks in the drawing-widget.
	This procedure handles events for that window.
 INPUTS:
	Event	 	an XMANAGER-event

 KEYWORDS:
 	none

 CALLING SEQUENCE:
	called by XMANAGER

 MODIFICATION HISTORY:
     written May 1997, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_slices.pro:20)

papco_write_png

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:    papco_write_png, fName, image

 DESCRIPTION:  a wrapper to write_png
               outputs individual panels als png files if needed

 INPUTS:       fName, image, r_papco, g_papco, b_papco

 OUTPUT:       none, files get written

 KEYWORDS:   
    aafact=1.0    image was antialiased and device coords must be corrected

 HISTORY:      written November 2000, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:876)

papco_write_struct

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:     papco_write_struct, filename, struct_name, struct, $
                                   ARRAY=ARRAY, APPEND=APPEND

 DESCRIPTION:  a routine to write an IDL structure to a text file

 INPUTS:       filename

 OUTPUT:       two element results structure:
                {error - 0 no error, 1 error
                 text  - '' or string array if keyword ARRAY set

 KEYWORDS:     ARRAY  - do not write to file, return string array
               APPEND - append to file_name
               TAGID  - only save tags that contain TAGID
               UNIT   -

 HISTORY:      written February 2000, Reiner Friedel
               modified May 2003 to write contents of Pointers

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_util.pro:478)

papco_xdisplayfile

 [Previous Routine] [Next Routine] [List of Routines] 
 procedure:    papco_xdisplayfile, filename, _EXTRA=E

 description:  wrapper for XDISPLAYFILE. Behaves the same way.

 inputs:       _EXTRA - any keywords set

 output:       none

 author:       R. Friedel, November 1998

 changes:      -

(See /home/jbf/ct/papco/working/papco/papco/papco_idlver.pro:99)

papco_xmanager

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: PAPCO_XMANAGER
 DESCRIPTION: wrapper for XMANAGER. Behaves the same way. 
 INPUTS:   
   NAME, string, passed to xmanager
   ID, long, passed to xmanager
 KEYWORDS:
   _EXTRA, extra keywords are passed to xmanager
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.7 $
 CURATOR: R. Friedel
 HISTORY:  
   written by R. Friedel, January 1998

(See /home/jbf/ct/papco/working/papco/papco/papco_idlver.pro:82)

papco_ylim

 [Previous Routine] [Next Routine] [List of Routines] 
 finds limits any 1D data array - used for automatic scaling the
                                  y-axis

(See /home/jbf/ct/papco/working/papco/papco_lib/autoscaling/papco_ylim.pro:66)

papco_y_label[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 This file is part of the PAPCO software package. 

 PAPCO is a free IDL package to combine data plots written by A. Keese and
 R. Friedel, maintained by R. Friedel
                                                           
    For more information, check the papco home page at     
    http://leadbelly/ccr/software/papco/papco.html       
    for online Manual and downloadble latest version.      
                                                           
 Comments and questions can be directed to friedel@lanl.gov  
  
 You are free to modify and distribute this file. However, any changes not 
 communicated to R. Friedel will not become part of the next release of PAPCO.

(See /home/jbf/ct/papco/working/papco/papco_lib/axis_label/papco_y_label.pro:15)

papco_y_label[2]

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
     papco_y_label

 PURPOSE:
     Attempt to give "nice" y-labels given the range for a plot. 

 CATEGORY:
     Plotting.

 CALLING SEQUENCE:
     papco_y_label, Yst, Yen

 INPUTS:
     Yst:    Start value of Y-axis
     Yen:    End  value of Y-axis

 KEYWORD PARAMETERS:
     INFO:     Calls doc_library to display this header documentation.
               1: print to terminal, 2: print to default printer

     VERBOSE:  If set, output informational IF verbose then s to console.

     LOG:      Do for log, full powers of 10 only. Default is for linear.

 OUTPUTS:
     Describe any outputs here.  For example, "This function returns the
     foobar superflimpt version of the input array."  This is where you
     should also document the return value for functions.

 COMMON BLOCKS:
     PLOT_COMPOSER: contains the main papco structure
                    
 SIDE EFFECTS:
     Alters IDL system variables for plotting:
     !Y.MINOR, !Y.TICKV, !Y.TICKS  

 RESTRICTIONS:
     Routine exits with !Y.MINOR, !Y.TICKV, !Y.TICKS all set to zero
     if !Y.TICKS is set to zero (defaults to IDL's internal automatic
     y-axis labeling)

 MODIFICATION HISTORY:
     Written by:    R. Friedel, February 2000.

(See /home/jbf/ct/papco/working/papco/papco_lib/axis_label/papco_y_label.pro:60)

plot_clr

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PLOT_CLR,XARR,YMINARR,YMAXARR,ZARR,ZMIN,ZMAX,linlogbit [,azimbit,smbit]

 DESCRIPTION:
  plot a two-dimensional representation of three-dimensional data

 RESTRICTIONS:
      The x-coordinates are expected to be linear.
      The y-coordinates can be linear or logarithmic, but the exact
      y-field boundaries must be specified and be the same for all x.

      If the output-device is not the screen or a printer with scalable pixel
  sizes, the routine 'PLOT_CLR_ALT' is used, which is extreme slow !

 HOW DOES THIS PROCEDURE DO ITS WORK - AND WHY ?
      Instead of plotting the data to the screen using the POLYFILL-Routines,
  the data is plotted into a two-dimensional data-array, 'image', which
  is output to the current device afterwards.
  Therefore, the dimension of 'image' is the effective resolution the data
  is plotted with. As the available RAM is finite, and because the dimension
      of image are almost proportional to the size of created Postscript-files,
      image can't have the size XResolution X YResolution.
  The height of 'image' is calculated by the function 'crres_calculate_Height'.
  The width of 'image' is

 INPUTS:
      XARR     FLTARR(xdim) x-coordinates
      YMINARR  FLTARR(ydim) lower y-boundaries of color-fields
      YMAXARR  FLTARR(ydim) upper y-boundaries of color-fields
               the y-coordinates must be the same for all x.
               YMINARR and YMAXARR can be unsorted.
      ZARR     FLTARR(xdim,ydim) data-values for each field
      ZMIN     float bottom value of color axis
      ZMAX     float top value of color axis
               linlogbit =0: linear z-scaling
                         =1: logarithmic z-scaling

 OPTIONAL INPUTS:
      azimbit   =0: color values ranging from 0-255(def)
                =1: color values ranging from 0-224
  smbit     =0: no smoothing
        =1: smoothing (default)

 KEYWORDS:
      USEOLD    when specified, the old routine is used.
        e.g.: PLOT_CLR,..., /USEOLD

 OUTPUT:
      a color-coded plot of ZARR on the current
      viewport (limits taken from !x.crange,!y.crange).
      Axes are drawn depending on the current
      value of the !type-variable. Usually x- and y-axes
      should be generated by the AXIS- or LOGAXIS-procedures,
      the z-axis by the papco_colorbar-procedure.
      Color density is influenced by the last parameter
      in POLYFILLS (25 for PHASERPS).
      Additionally the ZARR is smoothed and interpolated in
      y-direction. (the variable ZARR is not changed)
  This feature can be turned off by calling with smbit=0


 MODIFICATION HISTORY:
  january 1992, M.Fraenz and N.Krupp
                    wrote the routine 'plot_clr_alt' at the end of this
            file
      august 1995,  written by A.Keese, based on 'plot_clr_alt'
            performance-enhancement by using the TV-Routine instead
            of the polyfill-routine
      18th august 95, A.Keese
                corrected the calculation of the vertical resolution
      21st august 95, A.Keese
            corrected the calculation of the horiz resolution
            corrected rounding error while calculating width
                    of color-bars
      february 1997, R.Friedel
                    to work with papco internal color table scheme

(See /home/jbf/ct/papco/working/papco/papco_lib/color_plot/plot_clr.pro:168)

pprint

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: PPRINT
 DESCRIPTION: return a human-comsumable string that is a concise representation of the
    IDL value.  This is for debugging only, and not for machine consumption!!!  For
    example a indgen(50) is printed like "fltarr(50)[0,1,2,3,4,...]".  papco_objects
    toString function is called, etc.
 INPUTS:
    VAR, expr, any IDL expression. 
 OUTPUT KEYWORDS:
    out, string, the formated value.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.15 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/string_functions.pro:511)

PROCEDURE papco_defaults

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PROCEDURE papco_defaults

 DESCRIPTION:
      A window containing a entry field and buttons is displayed modally.

 INPUTS:
	none

 KEYWORDS:
      SIZE_ONLY  returns size info of widget only. Used to determine
                 scrolling

 OUTPUT:
      mone

 CALLING EXAMPLE:
      papco_defaults

(See /home/jbf/ct/papco/working/papco/papco/papco_defaults.pro:181)

process_active

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      FUNCTION process_active

 DESCRIPTION:
      checks, if a special process is running

 INPUTS:
      c_command   string which contains the execution command of the
                  process
      c_url       string contains the url currently being accessed. This is
                  needed for the uniqueness of the get command being used.

 OUTPUT: Function returns:
      1   if process containing c_command and c_url exist
      0   otherwise

 KEYWORDS:
  none

 MODIFICATION HISTORY:
     written September 1997, Torsten Heise

(See /home/jbf/ct/papco/working/papco/papco/papco_get_remote_data.pro:84)

PROpapco_subtable_editor_event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PROpapco_subtable_editor_event

 DESCRIPTION:
	Event handler for Widget to interactively modify PAPCO color sub-tables

 INPUTS:
      

 KEYWORDS:
      

 OUTPUT:
      

 CALLING SEQUENCE:
	

 MODIFICATION HISTORY:
     August 1999, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_subtable_editor.pro:198)

ps

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     : SOHO - CDS

 Name        : 
	PS
 Purpose     : 
	Sets graphics device to PostScript file.
 Explanation : 
	This procedure sets the system variables needed to write PostScript
	printer plot files.  The default configuration is landscape mode.
	Alternate modes are (TeX-compatible) encapsulated mode, portrait mode
	using all of the paper, and color mode (either landscape or portrait)
	which is compatible with the color printer.

	SETPLOT is called to save and set the system variables.  If a new file
	is to be opened, then DEVICE is called to set the plot window size and
	orientation, and to open the file.

	If the plot file is already open, then calling PS without any
	parameters or keywords allows the user to write into the already opened
	file, in the same mode as before.

 Use         : 
	PS  [, FILENAME ]

	PS				;Open PostScript plot file
	   ... plotting commands ...	;Create plot
	PSPLOT				;Close & plot file, reset to prev. dev.
	   or
	PSCLOSE				;Close w/o printing,  "    "   "    "

 Inputs      : 
	None required unless /ENCAPSULATED switch set.  See FILENAME below.
 Opt. Inputs : 
	FILENAME - Name of postscript file to be opened.  If not passed, and no
		   filename was previously passed, "idl.ps" is assumed.  If the
		   /ENCAPSULATED switch is passed, then a filename must be
		   passed.
 Outputs     : 
	A message is printed to the screen.
 Opt. Outputs: 
	None.
 Keywords    : 
	The following keywords are listed in the order of precedence.

	ENCAPSULATED = If set, then the plot is done in encapsulated landscape
		       mode.  This is compatible with TeX/LaTeX.
	TEX	     = A synonym for ENCAPSULATED.
	PORTRAIT     = If set, then the plot is done in portrait mode, using
		       all of the paper.
	LANDSCAPE    = If set, then the plot is done in landscape mode, using
		       all of the paper.  This is the default mode.

	In addition, the following keyword can be used with any of the others.

	COLOR	     = If set, then a color plot is made.
	COPY	     = If set, (together with /COLOR) then the current color
		       table is copied to the PostScript device.  Also, unless
		       INTERPOLATE is also set, the SETFLAG routine is called
		       to set TOP equal to the number of colors.  Also makes
		       sure that !P.COLOR does not exceed the TOP color.
		       Requires the SERTS image display software.
	INTERPOLATE  = If set, (together with /COLOR and /COPY) then the
		       current color table is interpolated to the PostScript
		       device.

 Calls       : 
	SETPLOT, FORM_FILENAME
 Common      : 
	PS_FILE which contains PS_FILENAME, the name of the plotting file,
	LAST_DEVICE, which is the name of the previous graphics device, and
	various parameters used to keep track of which configuration is being
	used.

	Also calls SETPLOT, which uses common block PLOTFILE.

 Restrictions: 
	Only the routines PSPLOT and PSCLOSE can be used to close the
	PostScript file.  It is best if the routines TEK, REGIS, etc. (i.e.
	those routines that use SETPLOT) are used to change the plotting
	device.

	In general, the SERTS graphics devices routines use the special system
	variables !BCOLOR and !ASPECT.  These system variables are defined in
	the procedure DEVICELIB.  It is suggested that the command DEVICELIB be
	placed in the user's IDL_STARTUP file.

 Side effects: 
	If the filename, or one of the configuration keywords (ENCAPSULATED,
	COLOR, PORTRAIT, or LANDSCAPE) are passed, then DEVICE is called to
	open a new file.  Any previously opened PostScript file would be
	closed.

	If a new file has to be opened, and if none of the configuration
	keywords are passed, then the default configuration (LANDSCAPE) is
	used.  This is true even if the last PostScript file was in a different
	configuration.

	If not the first time this routine is called, then system variables
	that affect plotting are reset to previous values.  If it is the first 
	time the routine is called, !FANCY is set to 1.

	In UNIX, if a new file is opened with the same name as an existing
	file, then the old file is lost.

 Category    : 
	Utilities, Devices.
 Prev. Hist. : 
	W.T.T., Nov. 1989.
	W.T.T., Aug. 1990, added LAST_DEVICE to common block.
	W.T.T., Feb. 1991, added keywords LANDSCAPE, PORTRAIT, TEX, COLOR.
	W.T.T., June 1992, fixed bug where CUR_CONFIG was not stored.
	W.T.T., Nov. 1992, added !P.POSITION to common block.
 Written     : 
	William Thompson, GSFC, November 1989.
 Modified    : 
	Version 1, William Thompson, GSFC, 27 April 1993.
		Incorporated into CDS library.
	Version 2, William Thompson, GSFC, 11 November 1993.
		Added ENCAPSULATED keyword.  Relegated TEX to a synonym.
	Version 3, William Thompson, GSFC, 14 September 1994
		Added COPY keyword.
	Version 4, William Thompson, GSFC, 21 June 1995
		Added INTERPOLATE keyword.
 Version     : 
	Version 4, 21 June 1995

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/system/ps.pro:130)

refactory[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 replace each instance of FIND_IN with REPLACEWITH in
 file FILE.

 Parameters:
   FILE, string, the name of the file to modify.  This file is
      overwritten
   FIND_IN, string, look for this string.  This is case-insensitive 
      when SMARTCASE is used.
   REPLACEWITH, string, replace with this string.  The case is
      ignored when SMARTCASE is used.

 Keywords:
   SMARTCASE, keyword_set, preserve case when replacing.

(See /home/jbf/ct/papco/working/papco/papco_lib/refactory.pro:226)

refactory[2]

 [Previous Routine] [Next Routine] [List of Routines] 
 Return the names of procedures that use this routine.  Presently, this is slow, and depends on
 grep.  Note that for Windows, cygwin or similar must provide grep.  Also note that call_procedure,
 call_function and execute all subvert this method.  A future version of this
 might contain a proper language syntax model and call graph.  One thought is to maintain a
 database of calls, and have a trace-monitored instance of papco to modify the call graph

 exclude=''    exclude if this string matches
 /print           print the source code lines

(See /home/jbf/ct/papco/working/papco/papco_lib/refactory.pro:532)

reset

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     : SOHO - CDS

 Name        : 
	RESET
 Purpose     : 
	Resets system variables to their default values.
 Explanation : 
	Resets the system variables for the currently selected device, and
	sets the following system variables to their default settings:

		!LINETYPE	!PSYM		!NOERAS
		!X.TITLE	!Y.TITLE	!P.TITLE
		!XTICKS		!YTICKS

	The routine SETPLOT is called to reinitialize the relevant system 
	parameters for the selected device.  Then the above mentioned system
	variables are set to their defaults.

 Use         : 
	RESET
 Inputs      : 
	None.
 Opt. Inputs : 
	None.
 Outputs     : 
	None.
 Opt. Outputs: 
	None.
 Keywords    : 
	None.
 Calls       : 
	SETPLOT
 Common      : 
	None, but this routine calls SETPLOT which uses the PLOTFILE common 
	block.
 Restrictions: 
	In general, the SERTS graphics devices routines use the special system
	variables !BCOLOR and !ASPECT.  These system variables are defined in
	the procedure DEVICELIB.  It is suggested that the command DEVICELIB be
	placed in the user's IDL_STARTUP file.

 Side effects: 
	None.
 Category    : 
	Utilities, Devices.
 Prev. Hist. : 
	William Thompson, January 23, 1989.
	William Thompson, January 1993, changed to use current system variable
		names.
 Written     : 
	William Thompson, GSFC, 23 January 1989.
 Modified    : 
	Version 1, William Thompson, GSFC, 27 April 1993.
		Incorporated into CDS library.
 Version     : 
	Version 1, 27 April 1993.

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/system/reset.pro:59)

returns best available local file.

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: returns best available local file.    
 DESCRIPTION:  
 INPUTS:   
   MDJT1, , the time to look for.
 OUTPUT KEYWORDS:
   VERSION, float, version found
   FILESYSTEM, , filesystem containing.
 RETURNS: 
   string, the file id (name within the filesystem).
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST:
 NOTES: TODO: check
    validity for secondary caches.  This logic should probably be
    only implemented when externalized file name is returned. 
 CVSTAG: 
   $Name:  $
   $Revision: 1.57 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_data_cache.pro:683)

right_side_label

 [Previous Routine] [Next Routine] [List of Routines] 
  NAME:  right_side_label

  DESCRIPTION: Puts a label to mark a panel to the right of the panel.
               calculates position form system variable !p.position
               Does "correct" new line with enough space
               Can attempt to autoscale label into available space.

  INPUT:       
     PANEL, intarr[3], vector for position of panel
     LABEL, string, string to be used as label

  KEYWORDS:    
     ROT90, keyw, rotates output string by 90 degrees, used for plots with papco_colorbar
     POS, int, indicates position. 
               0 (default) aligned with top of panel 
               1  aligned with bottom of panel
     AUTO, keyw, attempts to scale string into space.
     NOEXTEND, keyw, inhibit extend label over multiple panels
     _EXTRA, extra keywords to be passed to xyouts procedure

  DATE:        August 1995

  AUTHOR:       R. Friedel

  SIDE EFFECTS: 
      Plots on current plotting device.  Some branches may affect !p.position.

  MODIFICATIONS: Jan 1997 -  made charsize controlled by !P.CHARSIZE
                             system variable R. Friedel
                 Oct 1997 -  Better New Line spacing added
                 Jan 1999 -  Keyword POS added
                 Feb 1999 -  Keyword AUTO added.
                 Feb 2006    Use existing plot coordinates, don't rely on !p.position

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_panel_label.pro:614)

r_module_config

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO r_module_config, module, config_data, msg

 DESCRIPTION:
      Reads configuration file

 INPUTS:
      module   module name

 KEYWORDS:
      defaults= defaults  use these defaults if the value is not
        specified.  (This introduces a mechanism to allow for a
        module to add new parameters into existing user config
      changed (output) =1 indicates a new variable was introduced
        and the config should be saved
 OUTPUT:
      config_data   configuration data for the module
      msg           status message

 MODIFICATION HISTORY:
     written July 1997, Haje Korth
     check of path separtors, revised Nov 2003, Jim Roeder

(See /home/jbf/ct/papco/working/papco/papco/papco_module_configure.pro:250)

r_module_default

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO r_module_default, fln, config_data, msg

 DESCRIPTION:
      Read default configuration from module path.

 INPUTS:
      fln      file name for default file
      module   module name

 KEYWORDS:
      none

 OUTPUT:
      config_data   default configuration data for the module
      msg           status message

 MODIFICATION HISTORY:
     written July 1997, Haje Korth
     check of path separtors, revised Nov 2003, Jim Roeder

(See /home/jbf/ct/papco/working/papco/papco/papco_module_configure.pro:340)

r_papco_include_addins

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO r_papco_include_addins

 DESCRIPTION:
      reads papco_include_addins.pro file

 INPUTS:
      none

 KEYWORDS:
      none

 MODIFICATION HISTORY:
      written December 1998, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_configure.pro:94)

r_papco_include_modules

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO r_papco_include_modules

      Writes papco_include_modules.pro to dir pointed at by PAPCO_CONFIG

 DESCRIPTION:
      Reads previous papco_include_modules.pro if exists

 INPUTS:
      none. All passed in common block papco_configure

 OUTPUT:
      none

 MODIFICATION HISTORY:
      written July 1997, Haje Korth
      modified January 2002, Reiner Friedel for multiple configs

(See /home/jbf/ct/papco/working/papco/papco/papco_configure.pro:290)

r_papco_output

 [Previous Routine] [Next Routine] [List of Routines] 
 Procedure:
      r_papco_output

 DESCRIPTION:
      reads files produced by the PAPCO output function

 INPUTS:
      filename       full path of the papco output file

 KEYWORDS:
      FILE_FORMAT    a string of either 'ASCII', 'IDL', 'CDF'
                     default is 'IDL', 'CDF' is not implemented yet
      VERBOSE        if set, be verbose.

 OUTPUT:
      none
      data read is returned in a common block papco_output

 CALLING SEQUENCE:
      r_papco_output, fln

 MODIFICATION HISTORY:
      written May 1999, R. Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_output.pro:620)

sec2utc

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     : SOHO - CDS     
                   
 Name        : SEC2UTC()
               
 Purpose     : Converts seconds since MJD=0 to CDS UTC time format.
               
 Explanation : Used in the UTPLOT programs, this function converts elapsed
               seconds since the zero time of MJD to CDS internal UTC format.
               It takes no account of leap seconds.  For more information on
		various time formats, see file aaareadme.txt.
               
 Use         : IDL>  str = sec2utc(tsec)
    
 Inputs      : tsec  -  variable with number of elapsed seconds
               
 Opt. Inputs : None
               
 Outputs     : Function returns structure with .mjd and .time tags.
               
 Opt. Outputs: None
               
 Keywords    : ERRMSG  =  If defined and passed, then any error messages 
                          will be returned to the user in this parameter 
                          rather than being handled by the IDL MESSAGE 
                          utility.  If no errors are encountered, then a null 
                          string is returned.  In order to use this feature, 
                          the string ERRMSG must be defined first, e.g.,

                            ERRMSG = ''
                            UTC = SEC2UTC( TSEC, ERRMSG=ERRMSG )
                            IF ERRMSG NE '' THEN ...

 Calls       : None

 Common      : None
               
 Restrictions: No account of leap seconds.
               
 Side effects: If an error is encountered and the ERRMSG keyword is set, 
		SEC2UTC returns a structure of value {mjd:0L,time:0L}.
               
 Category    : Util, time
               
 Prev. Hist. : None

 Written     : C D Pike, RAL, 20-Apr-94
               
 Modified    :	Version 1, C.D. Pike, RAL, 20 April 1994
		Version 2, Donald G. Luttermoser, GSFC/ARC, 28 December 1994
                       Added the keyword ERRMSG.  Added IDL ON_ERROR utility.
			Note that there are no internally called procedures
			that use the ERRMSG keyword.
		Version 3, Donald G. Luttermoser, GSFC/ARC, 30 January 1995
			Made error handling procedure more robust.  Note that
			this routine can handle both vectors and scalars as
			input.
               Version 4, CDP, 5-Dec-95 Made output structure of type
                                        CDS_INT_TIME

 Version     :	Version 4, 05-Dec-95

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/sec2utc.pro:62)

setenv

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     :	SOHO - CDS

 Name        :	SETENV

 Purpose     :	Emulates the SETENV routine in VMS.

 Explanation :	Converts the SETENV syntax used in Unix and Microsoft Windows
		to the equivalent SETLOG statement in VMS.

 Use         :	SETENV, EXPRESSION

		SETENV, 'ZDBASE=SYS$USER1:[CDS.DATA.PLAN.DATABASE]'

 Inputs      :	EXPRESSION = A scalar string containing the name of the
			     environment variable to be defined, followed by
			     the equals "=" character, and the value to set
			     this environment variable to.

 Opt. Inputs :	None.

 Outputs     :	None.

 Opt. Outputs:	None.

 Keywords    :	None.

 Calls       :	DATATYPE

 Common      :	None.

 Restrictions:	VMS-only.  In Unix and Microsoft Windows, the built-in SETENV
		routine is used instead.

 Side effects:	None.

 Category    :	Utilities, Operating_system.

 Prev. Hist. :	None.

 Written     :	William Thompson, GSFC, 27 March 1995

 Modified    :	Version 1, William Thompson, 27 March 1995

 Version     :	Version 1, 27 March 1995

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/system/setenv.pro:47)

setplot[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     : SOHO - CDS

 Name        : 
	SETPLOT
 Purpose     : 
	Switch between plotting devices with memory about each.
 Explanation : 
	Switches among the various available plotting devices.	The plotting
	variables for each device are saved in a common block so that the user
	retains the ability to reset to a previously used device and do over-
	plots, even if plots were produced on another device in the meantime.

	Calling SETPLOT with the name of the currently selected device resets
	the system variables to either default values, or those from the last
	time SETPLOT was called.

	The !BCOLOR and !ASPECT system variables are also saved.

 Use         : 
	SETPLOT, DEVICE
 Inputs      : 
	DEVICE	- Name of the plotting device one is changing to.
 Opt. Inputs : 
	None.
 Outputs     : 
	None.
 Opt. Outputs: 
	None.
 Keywords    : 
	COPY = If set, then the current color table is copied to the new
	       graphics device.  Also, the SETFLAG routine is called to set TOP
	       equal to the number of colors.  Also makes sure that !P.COLOR
	       does not exceed the TOP color.  Requires the SERTS image display
	       software.
 Calls       : 
	ADD_DEVICE, SETSCALE
 Common      : 
	PLOTFILE - Saves system variables for later retrieval.  Not to be used 
	by other routines.
 Restrictions: 
	The procedure will not work correctly unless it is used exclusively to 
	change the plotting device.

	In general, the SERTS graphics devices routines use the special system
	variables !BCOLOR and !ASPECT.  These system variables are defined in
	the procedure DEVICELIB.  It is suggested that the command DEVICELIB be
	placed in the user's IDL_STARTUP file.

 Side effects: 
	Many system variables are manipulated by this routine--in particular
	!P.CHARSIZE and !P.FONT.

	The first time the routine is called for a particular graphics device,
	certain plot parameters may be set to default values.

	Any SETSCALE settings will be lost.

 Category    : 
	Utilities, Devices.
 Prev. Hist. : 
	W.T.T., Sept. 1987.
	William Thompson, February, 1990.
	William Thompson, October, 1991, added !ASPECT system variable.
	William Thompson, November 1992, changed to save !P.NOERASE and
					 !Z.THICK.
 Written     : 
	William Thompson, GSFC, September 1987.
 Modified    : 
	Version 1, William Thompson, GSFC, 27 April 1993.
		Incorporated into CDS library.
	Version 2, William Thompson, GSFC, 14 September 1994
		Added COPY keyword.
	Version 3, William Thompson, GSFC, 21 June 1995
		Added INTERPOLATE keyword.
 Version     : 
	Version 3, 21 June 1995

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/system/setplot.pro:78)

setplot[2]

 [Previous Routine] [Next Routine] [List of Routines] 
  ****    ****    ****    ****    ****    ****    ****    ****    ****    ****

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/system/setplot.pro:82)

setplot[3]

 [Previous Routine] [Next Routine] [List of Routines] 
  ****    ****    ****    ****    ****    ****    ****    ****    ****    ****

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/system/setplot.pro:127)

setplot[4]

 [Previous Routine] [Next Routine] [List of Routines] 
  ****    ****    ****    ****    ****    ****    ****    ****    ****    ****

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/system/setplot.pro:171)

set_device

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
       pro set_device

 DESCRIPTION:
       used by papco system. Reads the common widgetData.land_port to see
       if landscape or portrait mode is chosen. Sets gif size and print font
       size from defaults in widgetdata.

       reads the IDL graphics variable !d.name which is set by the
       routine set_plot from the IDL prompt. set_plot='x', the
       default when starting IDL, selects and X-window
       display. set_plot='ps' selects postscript output.
       Here display and plot window size are set.

 INPUTS:
	plfl    :   Plot output filename

 KEYWORDS:
	SLICE   ;  indicates plot is from a slice window, needs
                 different siizing
  ASPECT=   float number for aspect ratio.  1.5 means rise(Y) is 1.5 taller than run(X)
  antiAliasFactor:   float indicator indicated oversized Z buffer use to create antiAliasedGraphics

 OUTPUT:
      none

 CALLING EXAMPLE:
      set_device,plfl

 MODIFICATION HISTORY:
      April 1998, written by R. Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/set_device.pro:33)

set_manual_time

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      FUNCTION SET_MANUAL_TIME, MAXTIME=MAXTIME, MINTIME=MINTIME, $
                                DAYTIME=DAYTIME

 DESCRIPTION:
      this function is connected with the fields for manual entering
      the time-range. It is called from the papco_Event-function when
	one presses enter in this fields.

 INPUTS:
      none

 KEYWORDS:
 	MAXTIME		the return-key was pressed in the ef_maxTime-field
	MINTIME		enter was pressed in the ef_minTime-field
  DAYTIME         enter was pressed in the efDayTime-field
  timerange   parse the timerange string in widgetData.gui.ef_DayTime

 OUTPUT:
      0	 	the time was entered in an invalid format
	1		the entered time has correct format

 CALLING SEQUENCE:
      if SET_MANUAL_TIME(/maxtime) then .....

 MODIFICATION HISTORY:
      september 1995, written by A.Keese
      modified to add DAYTIME, may 1996, R. Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_settime.pro:163)

str2utc

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     :	SOHO - CDS

 Name        :	STR2UTC()

 Purpose     :	Parses UTC time strings.

 Explanation :	This procedure parses UTC time strings to extract the date and
		time.

 Use         :	Result = STR2UTC( UTC )
		Result = STR2UTC( UTC, /EXTERNAL )

 Inputs      :	UTC	= A character string containing the date and time.  The
			  target format is the CCSDS ASCII Calendar Segmented
			  Time Code format (ISO 8601), e.g.

				"1988-01-18T17:20:43.123Z"

			  The "Z" is optional.  The month and day can be
			  replaced with the day-of-year, e.g.

				"1988-018T17:20:43.123Z"

			  Other variations include

				"1988-01-18T17:20:43.12345"
				"1988-01-18T17:20:43"
				"1988-01-18"
				"17:20:43.123"

			  Also, the "T" can be replaced by a blank, and the
			  dashes "-" can be replaced by a slash "/".  This is
			  the format used by the SOHO ECS.

			  In addition this routine can parse dates where only
			  two digits of the year is given--the year is assumed
			  to be between 1950 and 2049.

			  Character string months, e.g. "JAN" or "January", can
			  be used instead of the number.  In that case, it
			  assumes that the date is either in day-month-year or
			  month-day-year format, e.g. "18-JAN-1988" or
			  "Jan-18-1988".  However, if the first parameter is
			  four digits, then year-month-day is assumed, e.g.
			  "1988-Jan-18".

			  Dates in a different order than year-month-day are
			  supported, but unless the month is given as a
			  character string, then these are only supported
			  through the /MDY and /DMY keywords.

 Opt. Inputs :	None.

 Outputs     :	The result of the function is a structure containing the (long
		integer) tags:

			MJD:	The Modified Julian Day number.
			TIME:	The time of day, in milliseconds since the
				beginning of the day.

		Alternatively, if the EXTERNAL keyword is set, then the result
		is a structure with the elements YEAR, MONTH, DAY, HOUR,
		MINUTE, SECOND, and MILLISECOND.

		Any elements not found in the input character string will be
		set to zero.		

 Opt. Outputs:	None.

 Keywords    :	EXTERNAL = If set, then the output is in CDS external format,
			   as described above.
		DMY	 = Normally the date is in the order year-month-day.
			   However, if DMY is set then the order is
			   day-month-year.
		MDY	 = If set, then the date is in the order
			   month-day-year.
		YMD	 = If set, then the date is in the order
			   year-month-day.
		ERRMSG	 = If defined and passed, then any error messages 
			   will be returned to the user in this parameter 
			   rather than being handled by the IDL MESSAGE 
			   utility.  If no errors are encountered, then a null 
			   string is returned.  In order to use this feature, 
			   the string ERRMSG must be defined first, e.g.,

				ERRMSG = ''
				RESULT = STR2UTC( UTC, ERRMSG=ERRMSG )
				IF ERRMSG NE '' THEN ...

 Calls       :	DATATYPE, DATE2MJD, UTC2INT, MJD2DATE, VALID_NUM

 Common      :	None.

 Restrictions:	The components of the time must be separated by the colon ":"
		character, except between the seconds and fractional seconds
		parts, where the separator is the period "." character.

		The components of the date must be separated by either the dash
		"-" or slash "/" character.

		The only spaces allowed are at the beginning or end of the
		string, or between the date and the time.

		This routine does not check to see if the dates entered are
		valid.  For example, it would not object to the date
		"1993-February-31", even though there is no such date.

 Side effects:	If an error is encountered and the ERRMSG keyword is set, 
		STR2UTC returns an integer scalar equal to -1.

 Category    :	Utilities, Time.

 Prev. Hist. :	Part of the logic of this routine is taken from TIMSTR2EX by M.
		Morrison, LPARL.  However, the behavior of this routine is
		different from the Yohkoh routine.  Also, the concept of
		"internal" and "external" time is based in part on the Yohkoh
		software by M. Morrison and G. Linford, LPARL.

 Written     :	William Thompson, GSFC, 13 September 1993.

 Modified    :	Version 1, William Thompson, GSFC, 21 September 1993.
		Version 2, William Thompson, GSFC, 28 September 1993.
			Expanded the capabilities of this routine based on
  			TIMSTR2EX.
		Version 3, William Thompson, GSFC, 20 October 1993.
			Corrected small bug when the time string contains
			fractional milliseconds, as suggested by Mark Hadfield,
			NIWA Oceanographic.
		Version 4, William Thompson, GSFC, 18 April 1994.
			Corrected bugs involved with passing arrays as
			input--routine was not calling itself reiteratively
			correctly.
		Version 5, Donald G. Luttermoser, GSFC/ARC, 28 December 1994
			Added the keyword ERRMSG.
		Version 6, William Thompson, GSFC, 25 January 1995
			Changed to call intrinsic ROUND instead of NINT.  The
			version of NINT in the Astronomy User's Library doesn't
			automatically select between short and long integers as
			the CDS version does.
		Version 7, William Thompson, GSFC, 26 January 1995
			Modified to support VMS-style format.
			Made error-handling more robust.
		Version 8, Donald G. Luttermoser, GSFC/ARC, 30 January 1995
			Added ERRMSG keyword to internally called procedures.
			Note that this routine can handle both scalars and
			vectors as input.
		Version 9, William Thompson, GSFC, 2 February 1995
			Fixed bug with years input with two-digits.
		Version 10, William Thompson, GSFC, 22 March 1995
			Fixed bug when date string contains OCT in capital
			letters.
		Version 11, William Thompson, GSFC, 15 June 1995
			Modified so that the default behavior is different when
			the month is given as a character string.  In that
			case, it now assumes that the year is the *last*
			parameter in the string unless given with all four
			digits.
		Version 12, William Thompson, GSFC, 19 June 1995
			Made logic used in version 11 more robust.  Added
			keyword YMD.
		Version 13, William Thompson, GSFC, 6 October 1995
			Added ability to recognize strings that end in either
			AM or PM.
		Version 14, William Thompson, GSFC, 15 January 1996
			Extended bug fix of version 10 to "SEPT" and "AUGUST".

 Version     :	Version 14, 15 January 1996

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/str2utc.pro:171)

strCenter

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: strCenter

 DESCRIPTION:
	returns the string ASTRING expanded or cut to length LEN by
      filling with blanks or cutting of its right, so that the ASTRING
      is centered in the new string.

 INPUTS:
	ASTRING, string, the string to center
	LENGTH, int, the result string's length

 OUTPUT:
	string, of length LEN containing the centered string ASTRING.

 CALLING EXAMPLES:
	a1=strcenter('*', 5)     ---> a1=='  *  '
      a1=strcenter('**, 5)     ---> a1==' **  '
	a1=strcenter('   aaa',5) ---> a1==' aaa '
      a1=strcenter('1234567', 3) -> at=='123'

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco_lib/string_functions.pro:184)

strchminus

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: STRCHMINUS
 DESCRIPTION:  replace all minus signs ('-') with underscores ('_')
 INPUTS:   
   STRING, string, string to search, not modified.
 KEYWORDS:
 RETURNS: 
   string, string with underscores ('_') where there were once minus signs ('-').
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.15 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/string_functions.pro:275)

strdel

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: STRDEL
 DESCRIPTION: return the string but with all instances of FIND in STRING removed. 
 INPUTS:   
   STRING, string, the string to search.  It is not modied.
   FIND, string, look for and remove instances of this string in result.
 KEYWORDS:
 RETURNS: 
   string, a copy of STRING, but with each FIND removed.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.15 $
 CURATOR: Reiner Friedel
 HISTORY:  
   04_Nov-2004, 1.1, written by Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/string_functions.pro:413)

strFormat

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      FUNCTION strFormat, aString, len, CENTER=CENTER, LEFT=LEFT, $
                                        RIGHT=RIGHT

 DESCRIPTION:
	returns the centered, left- or right-formatted string 'aString'
      expanded or reduced to length 'len' by filling with blanks or
      by cutting of a part of it.

 INPUTS:
	string	a String
	length  an Integer

 OUTPUT:
	a String

 CALLING EXAMPLES:
	a1=strformat('*', 5, /LEFT)        ---> a1=='*    '
      a1=strformat('**, 5, /RIGHT)       ---> a1=='   **'

	a1=strformat('*', 5, /CENTER)      ---> a1=='  *  '
      a1=strformat('**, 5, /CENTER)      ---> a1==' **  '
	a1=strformat('   aaa', 5, /CENTER) ---> a1==' aaa '

	a1=strformat('12345', 2, /CENTER)  ---> a1=='12'

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco_lib/string_functions.pro:147)

string_functions[3]

 [Previous Routine] [Next Routine] [List of Routines] 

UNCTION:
    FUNCTION strfrom, string, from

ESCRIPTION:
    return the right part of the string starting from position 'from'.

NPUTS:
    string       a string
    from         an integer (0,...)

UTPUT:
    a string

ALLING SEQUENCE:
    a=strfrom('12345', 1)  ;=> a EQ '2345'
    a=strfrom('12345', 5)  ;=> a EQ ''
    a=strfrom('12345', 0)  ;=> a EQ '12345'

ODIFICATION HISTORY:
    september 1995, written by A.Keese

(See /home/jbf/ct/papco/working/papco/papco_lib/string_functions.pro:61)

strleft

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      strleft, string, length

 DESCRIPTION:
	returns a the leftmost 'length' bytes of 'string'

 INPUTS:
	string	a String
	length  an Integer

 OUTPUT:
	a String

 CALLING EXAMPLES:
	find=strright('find outer otter', 4)
      empty=strleft('the lazy fox does not jump', 0) ;=> empty EQ ''

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco_lib/string_functions.pro:112)

strright

 [Previous Routine] [Next Routine] [List of Routines] 
 FUNCTION:
      strright, string, length

 DESCRIPTION:
	returns a the rightmost 'length' bytes of 'string'

 INPUTS:
	string	a String
	length  an Integer (0,...)

 OUTPUT:
	a String

 CALLING EXAMPLES:
	otter=strright('find outer otter', 5) ;=> otter EQ 'otter'
      empty=strright('the lazy fox does not jump', 0) ;=> empty EQ ''

 MODIFICATION HISTORY:
     written august 1995, Andreas Keese

(See /home/jbf/ct/papco/working/papco/papco_lib/string_functions.pro:86)

strsubst

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: STRSUBST
 DESCRIPTION: put the string NEW where ever FIND is found in STRING.  STRING is copied, so this can cause a 
    lot of heap garbage collecting.  (See string_replace_in_situ, which modifies STRING)  NEW and FIND must be the same length.
 INPUTS:   
   STRING, string, the string to search.  It is not modified.
   FIND, string, look for this string.  e.g. '\'
   NEW, string, replace with this string e.g. '/'
 KEYWORDS:
 RETURNS: 
   string, description
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.15 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/string_functions.pro:381)

struct widgetData.defaults

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: struct widgetData.defaults
 DESCRIPTION: structure for storing all of papco's default settings. 
 TAGS:   
   CLASSIC_PANELLIST, int=0,  use the classic panel list as opposed to papco 12.
   INFO, int=0, enable plot info file generation
   REDRAW, int=1, enable redraw logic
   VERT_SLICE_SIZE, intarr[2]=[ 500, 500 ], vertical slice draw window size
   ASK_WGET, int=1, 0=ask confirmation before wget
   DISABLE_DATA_VERSIONING, int=0,  0=suppress version checks for data.
   RAM_CACHE_SIZE, int=256, size of the ram cache in megabytes.
   RAM_CACHE_COUNT_LIMIT, int=50,  number of each dataset allowed.  1 means minimal caching (for batch), 50 is no limit.
   RAM_CACHE_AUTO_RESET, int=0, 0= none, 1=before plot cycle; 2=after each panel draw
   WGET_PASSIVE_FTP, int=1,  1= use passive ftp by default
   SCROLL, int=0, 1=disable scrolling inside papco windows
   SAVE_BITMAP, int=1, enable saving of bitmap
   INPUT_ENABLE, int=1, allow disable of widgets
   DO_PLOTS, int=1, do plots or just do read of data
   PRINTERNO, long=1, actual number of printers loaded
   STATES, int=0, 0 turns on papco_state files, 1 turns off, 2 follows draw_windows
   PNG_FORMAT, int=0, description
   RIGHT_LABEL, int=0, description
   SLICE_RELOAD, int=1, description
   MULTIPLE_SLICE, intarr[16], description
   DRAW_ON_STEP, int=1, draw on time step or not
   ADJUST_TIME, float=0.0, hours to add to ends of time range
   NUMBERING, int=1, 1=disable numbering, 0=draw number labels
   SATELLITE, int=0, description
   TRAP, int=1, set to trap user routine errors
   WGET, int=1, set to enable remote get
   WEB_TIMEOUT_SECONDS, float=3.0, number of seconds to time out
   PRINT_CHOICE, int=1, description
   USEPRINTER, int=1, description
   PRINTER, int=0, description
   ASKFORFILENAME, int=0, description
   FILETYPE, int=1, description
   FILENAME_TMPL, string=#.png, description
   RECENTPAPCOFILES, strarr[5], names of recently opened papco files for file menu
   SAVESESSION, int=0, description
   PAPCOFILE, string='default.papco', current papco product file name
   BATCHFILE, string, current batch file name
   ORBITINFO,  structarr[*], description
   LAYOUT, int=0, description
   VERBOSE, int=0, sets verbose flag in get_error common flag for diag
   ERROR_BOX, int=1, draw error box
   CHARFONT, int=3, default font for drawing
   FONT, string, system font name for widgets.
   CHARSIZE, float=1.0,  default char size  for screen
   CHARTHICK, float=1.0, default char thick for screen
   OUTPUT_FORMAT, string='TXT', description
   US_EUROPE, int=1, used to set US/Europe defaults
   PLOT_SIZE, floatarr[*]=[ 100, 100 ], default plot scaling of full size
   GIF_SIZE, intarr[*]=[ 800, 800 ], default output gif size
   GIF_AA_FACTOR, int=1,  factor to antialias image output.  1=no aa, 4 = full aa.
   DRAW_SIZE, intarr[*]=[ 700, 500 ], default draw window size
   DRAW_AA_FACTOR, int=1, will not be implemented until 24-bit support
   PS_MULT, float=1.0, scaling fonts to ps factor
   PS_EPS, int=0, encapsulated postscript = 1
   DRAW_IDENT, int=1, description
   BCKG_COLOR, int=200, background grey value. 255=white.
   FORG_COLOR, int=0, foreground grey value. 255=white.
   RESET_PLOTSTATE, int=0, reset plot params and color table after drawing.
   TICKLEN, float=-0.0150000, description
   XTICKS, int=6, description
   XLINES, int=2, description
   XSTYLE, int=1, description
   XMINOR, int=10, description
 CVSTAG: 
   $Name:  $
   $Revision: 1.91 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco/papco.pro:770)

str_replace_in_situ

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: STR_REPLACE_IN_SITU
 DESCRIPTION: replace all FIND in STRING with NEW efficiently.  
   This is used, for example, to replace \ with / in filenames. 
 INPUTS:   
   STRING, string, string to search.  It is modified!
   FIND, string, look for this string
   NEW, string, and replace with this string.  Must be same length as FIND.
 KEYWORDS:
 RETURNS: 
   string, reference to STRING for convenience.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.15 $
 CURATOR: Jeremy Faden
 HISTORY:  
   2004, REV, written by Jeremy Faden

(See /home/jbf/ct/papco/working/papco/papco_lib/string_functions.pro:621)

str_sep

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
    STR_SEP

 PURPOSE:
    This routine cuts a string into pieces which are separated by the 
    separator string.
 CATEGORY:
    String processing.
 CALLING SEQUENCE:
    arr = STR_SEP(string, separator)

 INPUTS:
    str - The string to be separated.
    sep - The separator.

 KEYWORDS:
    None.

 OUTPUT: 
    An array of strings as function value.

 COMMON BLOCKS:
    None

 SIDE EFFECTS:
    No known side effects.

 RESTRICTIONS:
    None.

 EXAMPLE:
    array = STR_SEP ("ulib.usca.test", ".")

 MODIFICATION HISTORY:
	July 1992, AH,	CreaSo		Created.

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/cdsxtra/str_sep.pro:42)

substrcnt

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: SUBSTRCNT
 DESCRIPTION: Count the occurrences of a substring in a string  
 INPUTS:   
   STRING, string, string to search
   FIND, string, look for this string
 KEYWORDS:
 RETURNS: 
   int, number of occurances of FIND in STRING.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES: 
    print, substrcnt( 'foofoo', 'oo' )  ; prints '2'
    print, substrcnt( 'foooo', 'oo' )  ; prints '2'
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.15 $
 CURATOR: Arne Asnes
 HISTORY:  
   07-July-2005, 1.4, written by Arne Asnes

(See /home/jbf/ct/papco/working/papco/papco_lib/string_functions.pro:345)

s_module_config

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO s_module_config, module, config_data

 DESCRIPTION:
      Writes configuration file.

 INPUTS:
      module        module name
      config_data   configuration data to write

 KEYWORDS:
  none

 OUTPUT:
      none

 MODIFICATION HISTORY:
     written July 1997, Haje Korth

(See /home/jbf/ct/papco/working/papco/papco/papco_module_configure.pro:421)

s_papco_include_addins

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
     PRO s_papco_include_addins

 DESCRIPTION:
     writes new papco_include_addins file to location PAPCO_CONFIG

 INPUTS:
     none

 KEYWORDS:
     FILE      if set, save to this addins file name

 MODIFICATION HISTORY:
     written December 1998, Reiner Friedel
     modified January 2002, reiner Friedel, allow multiple conf's

(See /home/jbf/ct/papco/working/papco/papco/papco_configure.pro:17)

s_papco_include_modules

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO s_papco_include_modules

 DESCRIPTION:
      Writes papco_include_modules.pro to dir pointed at by PAPCO_CONFIG

 INPUTS:
      none

 COMMON papco_configure, papcocfgWidgetData, config_data, $
    modules, standardModules, userModules
      readonly  config_data.config_dir
      readonly  config_data.active
      readonly  userModules(i).name
      readonly  userModules(i).path
      readonly  standardModules

 ENVIRONVARS
    PAPCO_MODULES
    PAPCO_CONFIG

 KEYWORDS:
      FILE   if set use this as the filename instead of
             papco_include_modules.pro - to load configuration files

 MODIFICATION HISTORY:
      written July 1997, Haje Korth
      modified January 2002, Reiner Friedel, allows multiple conf's

(See /home/jbf/ct/papco/working/papco/papco/papco_configure.pro:486)

tag_exist

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     : SOHO - CDS     
                   
 Name        : TAG_EXIST()
               
 Purpose     : To test whether a tag name exists in a structure.
               
 Explanation : Routine obtains a list of tagnames and tests whether the
               requested one exists or not. The search is recursive so 
               if any tag names in the structure are themselves structures
               the search drops down to that level.  (However, see the keyword
		TOP_LEVEL).
               
 Use         : IDL>  status = tag_exist(str, tag)
    
 Inputs      : str  -  structure variable to search
               tag  -  tag name to search for
               
 Opt. Inputs : None
               
 Outputs     : Function returns 1 if tag name exists or 0 if it does not.
               
 Opt. Outputs: None
               
 Keywords    : INDEX	  = Index of matching tag

		TOP_LEVEL = If set, then only the top level of the structure is
			    searched.

 Calls       : None

 Common      : None
               
 Restrictions: None
               
 Side effects: None
               
 Category    : Util, structure
               
 Prev. Hist. : None

 Written     : C D Pike, RAL, 18-May-94
               
 Modified    : Version 1.1, D Zarro, ARC/GSFC, 27-Jan-95
               Passed out index of matching tag
		Version 2, William Thompson, GSFC, 6 March 1996
			Added keyword TOP_LEVEL
               Version 2.1, Zarro, GSFC, 1 August 1996
                       Added call to help 

 Version     : Version 2.1 1 Aug 1996

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/util/tag_exist.pro:52)

tai2utc

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: TAI2UTC
 DESCRIPTION: Converts TAI time in seconds to UTC calendar time. 
 INPUTS:   
   TAI, dblarr, The time in seconds from midnight, 1 January 1958.
 KEYWORDS:
   EXTERNAL, keyw, result is a structure containing the integer tags
				   YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, and
				   MILLISECOND. 
   CCSDS, keyw, "1988-01-18T17:20:43.123Z"
   ECS, keyw, "1988/01/18 17:20:43.123"
   VMS, keyw, "18-JAN-1988 17:20:43.123"
   STIME, keyw, "18-JAN-1988 17:20:43.12"
   TRUNCATE, keyw, truncate to 1 second resolution
   DATE_ONLY, keyw, only return date
   TIME_ONLY, keyw, only return time
   UPPERCASE, keyw, return month in uppercase.
   ERRMSG, keyw, return errmsg in same keyword.
 OUTPUT KEYWORDS:
   ERRMSG, string, error message, '' if no error occurred.
 RETURNS: 
   structarr|stringarr, output based on keywords.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 NOTES: more verbose documentation is available in tai2utc.pro
 CVSTAG: 
   $Name:  $
   $Revision: 1.3 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/tai2utc.pro:34)

The color sequence is (and must be) linear

 [Previous Routine] [Next Routine] [List of Routines] 
 CALL (papco_color_bar):
      papco_color_bar, XPOS=XPOS, WIDTH=WIDTH, TITLEPOS=TITLEPOS, $
                       _EXTRA=extra_par

 DESCRIPTION:
      Plots a papco_color_bar on the right side of the screen

 INPUTS:
      none.    Expects keywords only.

 CALLING SEQUENCE:
      papco_color_bar, _extra=extra_plotPar

 KEYWORDS:
      uses _extra structure and expects at least the following keywords:
                  extra_Par={zrange:[zmin,zmax], $
                             zlog:zscl(panel(0),3), $
                             ztitle:uztit, $
                             ztickformat:'papco_color_bar_log_ticks' }
      XPOS   normal coords position seperation from plot
      WIDTH  normal coords width of color bar
      INFO   print out header of routine
      /nopanelset   don't do the panel set, use existing !p.position

 PROCEDURE:  The color sequence is (and must be) linear, even for
	       logarithmic z-scaling.
             Axes are drawn using the AXIS- and LOGAXIS-procedures.
             Viewport and data-screen relation are restored at the end.

 MODIFICATION HISTORY:
       written June 1999, Reiner Friedel
*****************************************************************************

(See /home/jbf/ct/papco/working/papco/papco_lib/color_plot/papco_color_bar.pro:34)

top_side_label

 [Previous Routine] [Next Routine] [List of Routines] 
  NAME:         top_side_label

  DESCRIPTION:  Puts a label at top of plot.
                calculates position from system variable !p.position

  INPUT:        label : string to be used as label 

  OUTPUT:       -

  DATE:         Jan 1997

  AUTOR:        R. Friedel

  SIDEEFFECTS:  -

  MODIFICATIONS: ;****************************************************************************

(See /home/jbf/ct/papco/working/papco/papco_lib/top_side_label.pro:18)

to_display_size

 [Previous Routine] [Next Routine] [List of Routines] 
 
 PROCEDURE:     
      to_display_size,t90,ymat,newt90,newymat
 
 DESCRIPTION:  
      This function resizes a data array to fit the actual diaplay pixels
 	available. It is used before calling the color spectrogram plot
      routines in order to speed up plotting by only plotting what would 
      actually be seen on the plot. Only the x-dimension is rescaled.

 INPUTS:       
      t90,ymat	: x-axis array and plot matrix
 
 OUTPUT:	 
      newt90,newymat  : resized x-axis array and plot matrix

 CALLING SEQUENCE:
      to_display_size,t90,ymat,newt90,newymat
      
 MODIFICATION HISTORY:       
      august 1996, written by R.Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/color_plot/to_display_size.pro:24)

trim

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     : SOHO - CDS

 Name        : 
	TRIM()
 Purpose     : 
	Converts numbers to strings, without trailing zeros.
 Explanation : 
	Converts numbers into a string representation, and trims off leading
	and/or trailing blanks.  Differs from STRTRIM in that trailing zeros
	after the period are also trimmed off, unless NUMBER is already a
	string, or an explicit format is passed.
 Use         : 
	Result = TRIM( NUMBER  [, FORMAT ]  [, FLAG ] )
 Inputs      : 
	NUMBER	= Scaler variable or constant.  May be of any ordinary type,
		  including string.  However, structures are not allowed.
 Opt. Inputs : 
	FORMAT	- Format specification for STRING function.  Must be a string
		  variable, start with the "(" character, end with the ")"
		  character, and be a valid FORTRAN format specification.  If
		  NUMBER is complex, then FORMAT will be applied separately to
		  the real and imaginary parts.

	FLAG	- Flag passed to STRTRIM to control the type of trimming:

			FLAG = 0	Trim trailing blanks.
			FLAG = 1	Trim leading blanks.
			FLAG = 2	Trim both leading and trailing blanks.

		  The default value is 2.  If NUMBER is complex, then FORMAT
		  will be applied separately to the real and imaginary parts.

 Outputs     : 
	Function returns as a string variable representing the value NUMBER.
 Opt. Outputs: 
	None.
 Keywords    : 
	None.
 Calls       : 
	None.
 Common      : 
	None.
 Restrictions: 
	NUMBER must not be an array.  NUMBER must not be a structure.
	FORMAT must be a valid format specification, and must not be passed
		if NUMBER is of type string.
	FLAG must not be of string type, or an array.
 Side effects: 
	None.
 Category    : 
	Utilities, Strings.
 Prev. Hist. : 
	William Thompson	Applied Research Corporation
	May, 1987		8201 Corporate Drive
				Landover, MD  20785

	William Thompson, Feb. 1992, added support for complex numbers, and
				     fixed Unix problem with lowercase "e".
 Written     : 
	William Thompson, GSFC, May 1987.
 Modified    : 
	Version 1, William Thompson, GSFC, 9 April 1993.
		Incorporated into CDS library.
	Version 2, Zarro (SAC/GSFC), 3-Jun-98
		Added check for undefined input
       Version 3, Zarro (SM&A/GSFC), 1-Dec-99
               Returned invalid input as blank string
               to avoid downstream problems.
 Version     : 
	Version 3

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/util/trim.pro:73)

USER_3DD_Slice

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO USER_3DD_Slice, plotinfo

 DESCRIPTION:
      Draw the generic slice widget window for USER_3DD_Slice type slices
      This routine is called by the modules' USER_3DD_Slice routines.

 INPUTS:
      panelNr     an integer, the number of the panel for which the slice
                  is to be drawn
      seconds     time of mouse click, a float
      yvalue      y-value of mouse click, a float

 KEYWORDS:
      OVERPLOT  endables oberplot into same slice window. Lineplots only.
      READDATA  set to indicate data needs reading
      NOWIDGET  produce the plot only, no widget! Used forslice_thumb panel.
                if set to 2, draw color bar, otherwise inhibit.

 CALLING SEQUENCE:
      called by papco_DrawSLice (in $papco_PATH/papco_cursor.pro)

 MODIFICATION HISTORY:
      November 2000, written by R.Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_slices.pro:1492)

USER_3DD_Slice_Event

 [Previous Routine] [Next Routine] [List of Routines] 
 PROCEDURE:
      PRO USER_3DD_Slice_Event, Event

 DESCRIPTION:
	This slice displays a 3DD slice through the data, when the user clicks
      in the drawing-widget. This procedure handles events for that window.

 INPUTS:
	Event	 	an XMANAGER-event

 KEYWORDS:
 	none

 CALLING SEQUENCE:
	called by XMANAGER

 MODIFICATION HISTORY:
     written November 2000, Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco/papco_slices.pro:1665)

utc2dow

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     :	SOHO - CDS

 Name        :	UTC2DOW()

 Purpose     :	Calculates the day of the week from CDS UTC date/time.

 Explanation :	This procedure takes any of the UTC date/time formats, and
		calculates the appropriate day of the week.  This is returned
		as either a number between 0-6 (Sunday-Saturday), or as a three
		letter character string (e.g. "Mon") or as a longer character
		string (e.g. "Monday").

 Use         :	Result = UTC2DOW( UTC )
		Result = UTC2DOW( UTC, /STRING )
		Result = UTC2DOW( UTC, /ABBREVIATED )
		Result = STRUPCASE( UTC2DOW( UTC, /ABBREVIATED ))

 Inputs      :	UTC	= Coordinated Universal Time, in one of the following
			  formats:

			Internal:  A structure containing the tags:

				MJD:	The Modified Julian Day number.
				TIME:	The time of day, in milliseconds since
					the beginning of the day.

				   Both are long integers.

			External:  A structure containing the integer tags
				   YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, and
				   MILLISECOND.

			CCSDS:	   An ASCII string containing the UTC time to
				   millisecond accuracy in the format
				   recommended by the Consultative Committee
				   for Space Data Systems (ISO 8601), e.g.

					"1988-01-18T17:20:43.123Z"

				   or one of its variants--see STR2UTC for
				   more details.

 Opt. Inputs :	None.

 Outputs     :	The result of the function is the day of the week in one of the
		following formats:

			     Default	String	    Abbreviated

				0	Sunday		Sun
				1	Monday		Mon
				2	Tuesday		Tue
				3	Wednesday	Wed
				4	Thursday	Thu
				5	Friday		Fri
				6	Saturday	Sat

 Opt. Outputs:	None.

 Keywords    :	STRING	    = If set, then the result of the function is a
			      character string containing the full name of the
			      day of the week, e.g. "Monday".

		ABBREVIATED = If set, then the result of the function is a
			      three-letter abbreviation for the day of the
			      week, e.g. "Mon".  If all uppercase letters are
			      desired, e.g. "TUE", then simply combine this
			      function with the STRUPCASE function.

		ERRMSG	    = If defined and passed, then any error messages 
			      will be returned to the user in this parameter 
			      rather than being handled by the IDL MESSAGE 
			      utility.  If no errors are encountered, then a 
			      null string is returned.  In order to use this 
			      feature, the string ERRMSG must be defined 
			      first, e.g.,

				ERRMSG = ''
				RESULT = UTC2DOW( UTC, ERRMSG=ERRMSG )
				IF ERRMSG NE '' THEN ...

 Calls       :	STR2UTC, UTC2INT

 Common      :	None.

 Restrictions:	None.

 Side effects:	If an error is encountered and the ERRMSG keyword is set, 
		UTC2DOW returns an integer scalar equal to -1.

 Category    :	Utilities, Time.

 Prev. Hist. :	None.

 Written     :	William Thompson, GSFC, 27 September 1993.

 Modified    :	Version 1, William Thompson, GSFC, 27 September 1993.
		Version 2, William Thompson, GSFC, 14 November 1994.
			Changed .DAY to .MJD
		Version 3, Donald G. Luttermoser, GSFC/ARC, 28 December 1994.
			Added the keyword ERRMSG.
		Version 4, Donald G. Luttermoser, GSFC/ARC, 30 January 1995.
			Added ERRMSG keyword to internally called procedures.
			Made the error handling routine more robust.  Note 
			that this procedure can handle both scalars and
			vectors as input.

 Version     :	Version 4, 30 January 1995

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/utc2dow.pro:112)

utc2doy

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     :	SOHO - CDS

 Name        :	UTC2DOY()

 Purpose     :	Calculates the day of the year from CDS UTC date/time.

 Explanation :	This procedure takes any of the UTC date/time formats, and
		calculates the appropriate day of the year, starting with the
		1st of January as day 1.

		See file aaareadme.txt for a listing of the proper UTC
		date/time formats.

 Use         :	Result = UTC2DOY( UTC )

 Inputs      :	UTC	= Coordinated Universal Time, in one of the following
			  formats:

			Internal:  A structure containing the tags:

				MJD:	The Modified Julian Day number.
				TIME:	The time of day, in milliseconds since
					the beginning of the day.

				   Both are long integers.

			External:  A structure containing the integer tags
				   YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, and
				   MILLISECOND.

			CCSDS:	   An ASCII string containing the UTC time to
				   millisecond accuracy in the format
				   recommended by the Consultative Committee
				   for Space Data Systems (ISO 8601), e.g.

					"1988-01-18T17:20:43.123Z"

				   or one of its variants--see STR2UTC for
				   more details.

 Opt. Inputs :	None.

 Outputs     :	The result of the function is the day of the year.

 Opt. Outputs:	None.

 Keywords    :	ERRMSG       =	If defined and passed, then any error messages 
				will be returned to the user in this parameter 
				rather than being handled by the IDL MESSAGE 
				utility.  If no errors are encountered, then a 
				null string is returned.  In order to use this 
				feature, the string ERRMSG must be defined 
				first, e.g.,

					ERRMSG = ''
					RESULT = UTC2DOY( UTC, ERRMSG=ERRMSG )
					IF ERRMSG NE '' THEN ...

 Calls       :	STR2UTC, UTC2INT

 Common      :	None.

 Restrictions:	None.

 Side effects:	If an error is encountered and the ERRMSG keyword is set, 
		UTC2DOY returns an integer scalar equal to -1.

 Category    :	Utilities, Time.

 Prev. Hist. :	None.

 Written     :	William Thompson, GSFC, 27 September 1993.

 Modified    :	Version 1, William Thompson, GSFC, 27 September 1993.
		Version 2, William Thompson, GSFC, 14 November 1994
			Changed .DAY to .MJD
		Version 3, Donald G. Luttermoser, GSFC/ARC, 28 December 1994
			Added the keyword ERRMSG.  Added a check to see
			whether the calculated DOY is valid.
		Version 4, Donald G. Luttermoser, GSFC/ARC, 3 January 1995
			Fixed bug introduced in version 3 which did not allow
			for arrays to be sent/returned.
		Version 5, Donald G. Luttermoser, GSFC/ARC, 30 January 1995
			Added ERRMSG keyword to internally called procedures.
			Madec the error handling routine more robust.  Note
			that this procedure can handle both scalars and 
			vectors as input.

 Version     :	Version 5, 30 January 1995

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/utc2doy.pro:92)

utc2int

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     :	SOHO - CDS

 Name        :	UTC2INT()

 Purpose     :	Converts CCSDS calendar time to internal format.

 Explanation :	This procedure converts Coordinated Universal Time (UTC)
		calendar time, as either a seven element structure variable, or
		in the CCSDS/ISO 8601 ASCII calendar format, into CDS internal
		format.  For notes on various time formats, see file 
		aaareadme.txt.

 Use         :	Result = UTC2INT( UTC )

 Inputs      :	UTC	= This can either be a structure with the tags YEAR,
			  MONTH, DAY, HOUR, MINUTE, SECOND, MILLISECOND, or a
			  character string in CCSDS/ISO 8601 format, e.g.

				"1988-01-18T17:20:43.123Z"

			  or one of it's variants--see STR2UTC for more
			  details.

 Opt. Inputs :	None.

 Outputs     :	The result of the function is a structure with the tags:

			MJD	= The Modified Julian Day number
			TIME	= The time of day, in milliseconds since the
				  start of the day.

 Opt. Outputs:	None.

 Keywords    :	ERRMSG       =	If defined and passed, then any error messages 
				will be returned to the user in this parameter 
				rather than being handled by the IDL MESSAGE 
				utility.  If no errors are encountered, then a 
				null string is returned.  In order to use this 
				feature, the string ERRMSG must be defined 
				first, e.g.,

					ERRMSG = ''
					RESULT = UTC2INT( UTC, ERRMSG=ERRMSG )
					IF ERRMSG NE '' THEN ...

 Calls       :	DATATYPE, DATE2MJD, STR2UTC

 Common      :	None.

 Restrictions:	None.

 Side effects:	If an error is encountered and the ERRMSG keyword is set, 
		UTC2INT returns an integer scalar equal to -1.

 Category    :	None.

 Prev. Hist. :	None.  However, the concept of "internal" and "external" time
		is based in part on the Yohkoh software by M. Morrison and G.
		Linford, LPARL.

 Written     :	William Thompson, GSFC, 13 September 1993.

 Modified    :	Version 1, William Thompson, GSFC, 21 September 1993.
		Version 2, William Thompson, GSFC, 14 November 1994
			Changed .DAY to .MJD
		Version 3, Donald G. Luttermoser, GSFC/ARC, 3 January 1995
			Added the keyword ERRMSG.  Check to see if the input
			structure (if sent) has 2 or 7 tags.  If 2 tags (MJD &
			TIME), this procedure returns the input variable with 
			no changes (i.e., already in CDS internal format).
		Version 4, Donald G. Luttermoser, GSFC/ARC, 30 January 1995
			Added ERRMSG keyword to internally called procedures.
			Made error handling routine more robust.  Note that 
			this procedure allows both scalars and vectors as
			input.

 Version     :	Version 4, 30 January 1995

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/utc2int.pro:80)

utc2sec

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     : SOHO - CDS     
                   
 Name        : UTC2SEC()
               
 Purpose     : Converts CDS UTC time format to seconds since MJD=0.
               
 Explanation : Used in the UTPLOT programs, this function converts CDS 
               internal UTC format to seconds since MJD=0.
               It takes no account of leap seconds.
		For notes on various time formats, see file aaareadme.txt.
               
 Use         : IDL>  sec = utc2sec(str)
    
 Inputs      : str  - structure variable containing UTC time format
               
 Opt. Inputs : None
               
 Outputs     : Function returns seconds elapsed since MJD=0.
               
 Opt. Outputs: None
               
 Keywords    : ERRMSG       =	If defined and passed, then any error messages 
				will be returned to the user in this parameter 
				rather than being handled by the IDL MESSAGE 
				utility.  If no errors are encountered, then a 
				null string is returned.  In order to use this 
				feature, the string ERRMSG must be defined 
				first, e.g.,

					ERRMSG = ''
					RESULT = UTC2SEC( STR, ERRMSG=ERRMSG )
					IF ERRMSG NE '' THEN ...

 Calls       : None

 Common      : None
               
 Restrictions: No account is taken of leap seconds.
               
 Side effects: If an error is encountered and the ERRMSG keyword is set, 
		UTC2SEC returns an integer scalar equal to -1.
               
 Category    : Util, time
               
 Prev. Hist. : None

 Written     :	C D Pike, RAL, 20-Apr-94
               
 Modified    :	Version 1, C D Pike, RAL, 20-Apr-94
		Version 2, William Thompson, GSFC, 14 November 1994
			Changed .DAY to .MJD
		Version 3, Donald G. Luttermoser, GSFC/ARC, 3 January 1995
			Added the keyword ERRMSG.  Added ON_ERROR,2 flag.
			Allow for input of EXTERNAL format of UTC.
		Version 4, Donald G. Luttermoser, GSFC/ARC, 30 January 1995
			Added ERRMSG keyword to internally called procedures.
			Made the error handling routine more robust.  Note 
			that this routine can handle both scalars and vectors
			as input.

 Version     :	Version 4, 30 January 1995

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/utc2sec.pro:63)

utc2str

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     :	SOHO - CDS

 Name        :	UTC2STR()

 Purpose     :	Converts CDS external time in UTC to string format.

 Explanation :	This procedure takes the UTC time in "internal" or "external"
		format, and converts it to a calendar string.  The default
		format is the Consultative Committee on Space Data Systems
		(CCSDS) ASCII Calendar Segmented Time Code format (ISO 8601),
		but other formats are also supported.  For notes on various 
		time formats, see file aaareadme.txt.

 Use         :	Result = UTC2STR( UTC )
		Result = UTC2STR( UTC ,/ECS )

 Inputs      :	UTC	= The UTC date/time as a data structure with the
			  elements YEAR, MONTH, DAY, HOUR, MINUTE, SECOND,
			  and MILLISECOND.

 Opt. Inputs :	None.

 Outputs     :	The result of the function will be an ASCII string containing
		the UTC time to millisecond accuracy in CCSDS format, e.g.

			"1988-01-18T17:20:43.123Z"

		However, if the ECS keyword is set, then the following format
		will be used instead.

			"1988/01/18 17:20:43.123"

		Note that this isn't exactly the ECS string format, because the
		ECS does not use fractional seconds.  However, if /ECS is
		combined with /TRUNCATE, then the following output will result

			"1988/01/18 17:20:43"

		which matches what the ECS expects to see.

		Using the keyword /VMS writes out the time in a format similar
		to that used by the VMS operating system, e.g.

			"18-Jan-1988 17:20:43.123"

		A variation of this is obtained with the /STIME keyword, which
		emulates the value of !STIME in IDL.  It is the same as using
		/VMS except that the time is only output to 0.01 second
		accuracy, e.g.

			"18-Jan-1988 17:20:43.12"

		The keywords /DATE_ONLY and TIME_ONLY can be used to extract
		either the date or time part of the string.

 Opt. Outputs:	None.

 Keywords    :	ECS	  = If set, then the output will be in ECS format, as
			    described above.

		VMS	  = If set, then the output will be in VMS format, as
			    described above.

		STIME	  = If set, then the output will be in STIME format, as
			    described above.

		Only one of the above keywords can be set.  If none of them are
		set, then the output is in CCSDS format.

		TRUNCATE  = If set, then the time will be truncated to 1 second
			    accuracy.  Note that this is not the same thing as
			    rounding off to the nearest second, but is a
			    rounding down.

		DATE_ONLY = If set, then only the date part of the string is
			    returned.

		TIME_ONLY = If set, then only the time part of the string is
			    returned.

		UPPERCASE = If set, then the month field in either the VMS or
			    STIME format is returned as uppercase.

		ERRMSG    = If defined and passed, then any error messages 
			    will be returned to the user in this parameter 
			    rather than being handled by the IDL MESSAGE 
			    utility.  If no errors are encountered, then a 
			    null string is returned.  In order to use this 
			    feature, the string ERRMSG must be defined 
			    first, e.g.,

				ERRMSG = ''
				RESULT = UTC2STR( UTC, ERRMSG=ERRMSG )
				IF ERRMSG NE '' THEN ...

 Calls       :	DATATYPE

 Common      :	None.

 Restrictions:	None.

 Side effects:	If an error is encountered and the ERRMSG keyword is set, 
		UTC2STR returns an string scalar equal to '-1'.

 Category    :	Utilities, Time.

 Prev. Hist. :	None.  However, the concept of "internal" and "external" time
		is based in part on the Yohkoh software by M. Morrison and G.
		Linford, LPARL.

 Written     :	William Thompson, GSFC, 20 September 1993.

 Modified    :	Version 1, William Thompson, GSFC, 21 September 1993.
		Version 2, William Thompson, GSFC, 21 October 1993.
			Modified to overcome IDL formatted string limitation
			when processing more than 1024 values, based in part on
			a suggestion by Mark Hadfield, NIWA Oceanographic.
		Version 3, William Thompson, GSFC, 20 December 1994
			Added keywords TRUNCATE, DATE_ONLY, TIME_ONLY
		Version 4, Donald G. Luttermoser, GSFC/ARC, 3 January 1995
			Added the keyword ERRMSG.
		Version 5, Donald G. Luttermoser, GSFC/ARC, 30 January 1995
			Added ERRMSG to the internally called procedures.
			Made the error handling routine more robust.  Note 
			that this routine can handle both scalars and vectors
			as input.
		Version 6, William Thompson, GSFC, 14 March 1995
			Added keywords VMS, STIME, UPPERCASE
               Version 7  CDP, RAL  15-Mar-95.  Fixed typo in Version 6

 Version     :	Version 7, 15 March 1995

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/utc2str.pro:136)

utc2tai

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: UTC2TAI
 DESCRIPTION:  
 INPUTS:   
   UTC, string|struct, Coordinated Universal Time, in one of the following formats described in tai2utc.
 KEYWORDS:
   ERRMSG, keyw, return errmsg in same keyword.
 OUTPUT KEYWORDS:
   ERRMSG, string, error message, '' if no error occurred.
 RETURNS: 
   double, in seconds from midnight on 1 January 1958.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 NOTES: more verbose documentation is available in utc2tai.pro
 CVSTAG: 
   $Name:  $
   $Revision: 1.2 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/utc2tai.pro:23)

valid_num[1]

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     : SOHO - CDS     
                   
 Name        : VALID_NUM()
               
 Purpose     : Check if a string is a valid number representation.
               
 Explanation : The input string is parsed for characters that may possibly
               form a valid number.  It is more robust than simply checking
               for an IDL conversion error because that allows strings such
               as '22.3qwert' to be returned as the valid number 22.3
               See also the original NUM_CHK which returns the status in 
               the opposite sense.

 Use         : IDL> status = valid_num(string  [,value]  [,/integer])
    
 Inputs      : string  -  the string to be tested
               
 Opt. Inputs : None
               
 Outputs     : The function returns 1 for valid, 0 for invalid number
               
 Opt. Outputs: value	- The value the string decodes to.  This will be
			  returned as a double precision number unless /INTEGER
			  is present, in which case a long integer is returned.
               
 Keywords    : Integer   -  if present code checks specfically for an integer.

 Calls       : None
               
 Restrictions: None
               
 Side effects: None
               
 Category    : Utilities, Numerical
               
 Prev. Hist. : Small changes from NUM_CHK by Andrew Bowen, 
                                             Tessella Support Services, 8/3/93

 Written     : CDS version by C D Pike, RAL, 24-May-93
               
 Modified    : Version 1, C D Pike, RAL, 24-May-93
		Version 2, William Thompson, GSFC, 14 October 1994
			Added optional output parameter VALUE to allow
			VALID_NUM to replace STRNUMBER in FITS routines.

 Version     : Version 1  24-May-93

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/util/valid_num.pro:48)

valid_time()

 [Previous Routine] [Next Routine] [List of Routines] 
 PROJECT:
       SOHO - CDS

 NAME:	
       VALID_TIME()

 PURPOSE:
       To test if the given time has the valid format

 EXPLANATION:
       
 CALLING SEQUENCE: 
       Result = valid_time(time [, err])

 INPUTS:
       time - Any date/time format

 OPTIONAL INPUTS: 
       None.

 OUTPUTS:
       Result - 1 if the time format is valid, 0 otherwise

 OPTIONAL OUTPUTS:
       ERROR  - A string scalar containing error message. If the time format
                is correct, ERROR will be a null string

 KEYWORD PARAMETERS: 
       None.

 CALLS:
       ANYTIM2UTC

 COMMON BLOCKS:
       None.

 RESTRICTIONS: 
       None.

 SIDE EFFECTS:
       None.

 CATEGORY:
       
 PREVIOUS HISTORY:
       Written May 5, 1995, Liyun Wang, GSFC/ARC

 MODIFICATION HISTORY:
       Version 1, created, Liyun Wang, GSFC/ARC, May 5, 1995

 VERSION:
       Version 1, May 5, 1995

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/time/valid_time.pro:62)

varprt

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: VARPRT
 DESCRIPTION: format any variable or expression as a string.  Machine consumption okay, unless /DEBUG
    keyword is used. 
 INPUTS:   
   VAR, expr, any idl expression.
 KEYWORDS:
   LEN, int, pad to this length with spaces
   FIXED, boolean, use format="(g10.4)" to print.
   DEBUG, boolean, debug mode for use with pprint.  Indicates that the result is only
      for human consumption, so backwards-compatibility is not an
      issue.
   ADD0, pad string with zeros if a specific LEN is requested
 RETURNS: 
   string, formatted result.
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.15 $
 CURATOR: NAME
 HISTORY:  
   DATE, REV, written by NAME

(See /home/jbf/ct/papco/working/papco/papco_lib/string_functions.pro:451)

win

 [Previous Routine] [Next Routine] [List of Routines] 
 Project     : SOHO - CDS

 Name        : WIN

 Purpose     : Switch to Microsoft Windows mode.

 Explanation : SETPLOT is called to save and set the system variables.

 Use         : WIN

 Inputs      : None.

 Opt. Inputs : None.

 Outputs     : A message is printed to the screen.

 Opt. Outputs: None.

 Keywords    : None.

 Calls       : SETPLOT

 Common      : None.  But calls SETPLOT, which uses common block PLOTFILE.

 Restrictions: It is best if the routines TEK, REGIS, etc. (i.e.  those
		routines that use SETPLOT) are used to change the plotting
		device.

		In general, the SERTS graphics devices routines use the special
		system variables !BCOLOR and !ASPECT.  These system variables
		are defined in the procedure DEVICELIB.  It is suggested that
		the command DEVICELIB be placed in the user's IDL_STARTUP file.

 Side effects: If not the first time this routine is called, then system
		variables that affect plotting are reset to previous values.

 Category    : Utilities, Devices.

 Prev. Hist. : None.

 Written     : William Thompson, GSFC, 15 June 1993.

 Modified    : Version 1, William Thompson, GSFC, 15 June 1993.

 Version     : Version 1, 15 June 1993.

(See /home/jbf/ct/papco/working/papco/papco_lib/cdssw/system/win.pro:48)

x_side_label

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME: X_SIDE_LABEL
 DESCRIPTION: program to draw a label next to the right side end of the x-axis labels
    used for annotation with multiple x-axis
    This routine needs to know the x-axis ticklength to position the label.
    default for most plots is 0.015, use the keyword XTICKLEN to change this. 
 INPUTS:   
     PANEL, intarr[3], vector for position of panel
     LABEL, string, string to be used as label
 KEYWORDS:
   XTICKLEN, float, (default=0.015)
 SIDE EFFECTS:
 EXCEPTIONS:
 EXAMPLES:
 UNIT TEST: 
 CVSTAG: 
   $Name:  $
   $Revision: 1.22 $
 CURATOR: Reiner Friedel
 HISTORY:  
   2003, 1.1, written by Reiner Friedel

(See /home/jbf/ct/papco/working/papco/papco_lib/papco_panel_label.pro:1089)

yres

 [Previous Routine] [List of Routines] 
 FUNCTION:
      yres,binSizes

 DESCRIPTION:
      Works out the lowest comon denominator for all binsizes, so that
      each binszie is a multiple therof to an accuracy of 75%.

 READ THIS !
      When you experience PROBLEMS IN THE RESOLUTION on the y-axis, this
  routine is probably the bad guy. Just increase the % accuracy
      required. Warning: this may drastically increase your filesizes for
      printing, and slow down plotting to screen.

 INPUTS:
      binSizes    : array containing the binsizes of the data bins.

 OUTPUT:
      an Integer

 CALLING SEQUENCE:
      res=yres(binSizes)

 MODIFICATION HISTORY:
      December 1995, written by R.Friedel at Goddard

(See /home/jbf/ct/papco/working/papco/papco_lib/color_plot/plot_clr.pro:26)