Help for routines in public IDL libraries used by the tasclib.idl library

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

     ? mk_html_help

at the IDL command line prompt.

Last modified: Tue Aug 23 14:22:35 2011.


List of Routines


Routine Descriptions

ABGRAD

[Next Routine] [List of Routines]
 NAME:
		ABGRAD
 VERSION:
		4.0
 PURPOSE:
		Calculates the absolute value of the gradient of a function represented
		as an array of values.  Works for 1-7 dimensions.
 CATEGORY:
		Array Manipulation.
 CALLING SEQUENCE:
		Result = ABGRAD( ARR [, DELTA])
 INPUTS:
	ARR
		Array, numeric, number of dimensions can be 1 through 7.
 OPTIONAL INPUT PARAMETERS:
	DELTA
		Size of step used to calculate the numeric derivatives.  The approx.
		partial derivative in the i-th direction is calculated as
		(ARR(...,I + DELTA,...) - ARR(...,I - DELTA,...))/(2*DELTA).
		The default value of DELTA is 1l.  If provided, it is rounded to a long
		integer on input.
 KEYWORD PARAMETERS:
		None.
 OUTPUTS:
		Returns the absolute value of the gradient as an array of the same size
		and type as ARR.  If ARR is not an array, returns 0.
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		Due to current limitations of the MAKE_ARRAY system routine, 8
		dimensions are not allowed.
 PROCEDURE:
		Creates an 7-dimensional array, with dummy leading dimensions,
		containing the original array.  Generates the differences using the
		SHIFT system routine and strips the dummy dimensions at the end.
		Uses the functions DEFAULT and FPU_FIX from MIDL.
 MODIFICATION HISTORY:
		Created 15-NOV-1991 by Mati Meron.
		Modified 30-AUG-1998 by Mati Meron.  Underflow filtering added.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\abgrad.pro)


ABS_MM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		ABS_MM
 VERSION:
		4.0
 PURPOSE:
		Calculates absolute values.  A temporary fix needed since the IDL ABS
		function fails with very large or very small complex numbers.
 CATEGORY:
		Mathematical, general.
 CALLING SEQUENCE:
		Result = ABS_MM (X)
 INPUTS:
	X
		Numerical, otherwise arbitrary.
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
		None.
 OUTPUTS:
		Returns the absolute value of the input.
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		None.
 PROCEDURE:
		Straightforward.  Calling FPU_FIX and ISNUM from MIDL.
 MODIFICATION HISTORY:
		Created 15-MAR-1996 by Mati Meron as M_ABS.
		Modified 30-AUG-1998 by Mati Meron.  Underflow filtering added.
		Renamed 25-SEP-1999 by Mati Meron, to ABS_MM.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\abs_mm.pro)


ACOSD

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

 PURPOSE:
       Return the inverse cosine of a value, in degrees rather then radians.

 CALLING SEQUENCE:
       deg = acosd(x)

 INPUTS:
       value      cosine of angle 

 OPTIONAL INPUTS:

 OUTPUTS:
       Angle in degrees returned.

 PROCEDURE

 COMMON BLOCKS:
       None.

 NOTES

 REFERENCES
 
 AUTHOR and DATE:
     Jeff Hicke     Earth Space Research Group, UCSB  12/07/93

 MODIFICATION HISTORY:

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\acosd.pro_)


ADC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		ADC
 VERSION:
		4.3
 PURPOSE:
		Interface to HISTOGRAM, simulating an Analog to Digital Converter.
 CATEGORY:
		Mathematical.
 CALLING SEQUENCE:
		Result = ADC( ARR [, keywords] )
 INPUTS:
	ARR
		Array, numeric, otherwise arbitrary.
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
	MASK
		Provision for optional data mask.  Needs to be an array of the same
		as ARR.  If given, only data (in ARR) corresponding to locations of
		non-zero elements of MASK is considered.  Equivalent to replacing
		ARR by ARR[ where(mask ne 0)].
	BINSIZE
		Specifies the size of the BIN, same as in HISTOGRAM.  Defaults to full
		range (i.e. a single channel).
	N_CHANNELS
		Number of channels to use in the binning.  If BINSIZE is provided,
		N_CHANNELS is ignored.
	MIN
		The minimal value to consider.  Same as in HISTOGRAM.  The default
		value is min(ARR).
	MAX
		The maximal value to consider.  Same as in HISTOGRAM.  The default
		value is max(ARR).
	/LEFT
		Switch.  If set, the elements within each bin are associated with the
		left bin boundary (i.e. with the minimum of the interval).
	/CENTER
		Switch.  If set, the elements within each bin are associated with the
		center of the bin (i.e. with the middle of the interval).  This is the
		default.
	/RIGHT
		Switch.  If set, the elements within each bin are associated with the
		right bin boundary (i.e. with the maximum of the interval).

		NOTE!!!:  Only one of the switches LEFT, CENTER, RIGHT may be set.

	/ROUND
		Switch.  If set, the upper and lower boundaries are rounded (up and
		down, respectively) to the nearest bin.
	/EXTEND
		Switch.  If set, the upper and lower boundaries are extended (up and
		down, respectively) by half a bin.

		NOTE:  If BINSIZE is not set, ROUND and EXTEND are ignored.

	/TOP_ADJUST
		Switch.  If set, adjusts for the possibility of the uppermost element
		of ARR being counted in a separate channel.
	/NORMALIZE
		Switch.  If set, the output is normalized to a total sum of 1.
	OMIN
		Optional output.  See below.
	OMAX
		Optional output.  See below.
	VALUES
		Optional output.  See below.
 OUTPUTS:
		Returns a histogram of the original array, with either binsize provided
		by BIN or number of channels provided by N_CHANNELS.
 OPTIONAL OUTPUT PARAMETERS:
	OMIN
		Name of a variable to receive the value of MIN used internally.  Same
		as in HISTOGRAM.
	OMAX
		Name of a variable to receive the value of MAX used internally.  Same
		as in HISTOGRAM.
	VALUES
		Returns a vector of the nominal values associated with the bins
		(LEFT, CENTER or RIGHT, according to the keywords).
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		ARR must be numeric and BIN must be a positive scalar.  No other
		restrictions.
 PROCEDURE:
		Straightforward.  Calls the IDL function HISTOGRAM.  Also calls ARREQ,
		CAST, DEFAULT, FPU_FIX, ISNUM and ONE_OF from MIDL.
 MODIFICATION HISTORY:
		Created 15-MAY-1996 by Mati Meron.
		Modified 25-JUN-2000 by Mati Meron.  Internal changes only.
		Modified 1-AUG-2001 by Mati Meron.  Checked compatibility with Windows
		and added keywords MASK and ROUND.
		Modified 5-JAN-2002 by Mati Meron.  Added keyword EXTEND and improved
		internal consistency.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\adc.pro)


ADD2HISTORY

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

 PURPOSE:
	This procedure adds information to the history of an ICG structure.

 CATEGORY:
	DATAFILES

 CALLING SEQUENCE:
	add2history, icg_struc [,text]

 INPUTS:
	icg_struc: Name of the ICG structure

 OPTIONAL INPUTS:
	text: String scalar or array which will be added to the history.

 OUTPUTS:
	This procedure writes information to the history of an ICG structure.
	The entry is as follows:
		   []

 EXAMPLE:
	icgs = read_ncdf('S:\links\idl_source\idl_work\fh_lib\examples\sfpo_oh.nc')
	icgs.time.param = icgs.time.param - 7200.D
	add2history, icgs, 'Subtracted 7200 sec from time data to convert from MESZ to UTC.'
	PRINT, TRANSPOSE(STR_SEP(icgs.!global.history, '!C'))

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 19.11.1999
	22.11.1999:	Changed format of history string (no leading blanks anymore)
	17.03.2000:	Added version information to history entry
					Changed code to new version of add_tag

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\add2history.pro)


ADDPATH

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:  addpath

 PURPOSE:  

 USEAGE:   addpath,pathname,cut=cut

 INPUT:    
   pathname   Name of new path to add to this session's directory path.
              if pathname is already present in !path no action is taken.
              This last feature allows addpath to be repeatedly executed
              (e.g., within a script) without affecting !path after the
              first invocation.

 KEYWORD INPUT:

  cut         If set and pathname is set, the element of !path that
              matches pathname is removed. If pathname is not
              specified, the last element of !path is removed.

 OUTPUT:

 DISCUSSION:

 LIMITATIONS:

 COMMON BLOCKS:

 SIDE EFFECTS:
  
 EXAMPLES:  
           addpath,'/home/paul/idl'            ; add a path

           addpath,'/local/idl/lib/wided',/cut ; remove a specific path

           addpath,/cut                        ; remove last path element 

           addpath                             ; view !path

 AUTHOR:   Paul Ricchiazzi                        04 Nov 97
           Institute for Computational Earth System Science
           University of California, Santa Barbara
           paul@icess.ucsb.edu

 REVISIONS:

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\addpath.pro)


ADD_COMMENT

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

 PURPOSE:
	This procedure adds a comment to an ICG structure.

 CATEGORY:
	ICG_STRUCT

 CALLING SEQUENCE:
	add_comment, icg_struc, text

 INPUTS:
	icg_struc: Name of the ICG structure
	text: Comment to be added to the ICG structure (scalar).

 KEYWORD PARAMETERS:
	/OVERWRITE: If set an alread existing comment will be overwritten

 OUTPUTS:
	This procedure adds the (or updates an alread existing) 'COMMENT' tag
	which is part of the '!GLOBAL' tag of an ICG structure.

 EXAMPLE:
	icgs = read_ncdf('S:\links\idl_source\idl_work\fh_lib\examples\sfpo_oh.nc')
	icgs.time.param = icgs.time.param - 7200.D
	add_comment, icgs, 'Subtracted 7200 sec from time data to convert from MESZ to UTC.'
	PRINT, icgs.!global.comment

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 13.03.2000

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\add_comment.pro)


ADD_MARGIN

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ADD_MARGIN
 PURPOSE:
       Add space to left margin and top of a text file.
 CATEGORY:
 CALLING SEQUENCE:
       add_margin, in, out, n_left, [n_top]
 INPUTS:
       in = Input file.                                    in
       n_left = Number of spaces to add to left margin.    in
       n_top = number of blank lines to add to top.        in
 KEYWORD PARAMETERS:
 OUTPUTS:
       out = Output file.                                  out
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       Written by R. Sterner, 3 Mar, 1988.
       Johns Hopkins University Applied Physics Laboratory.

 Copyright (C) 1988, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\add_margin.pro)


ADD_QUALITY

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

 PURPOSE:
   This function adds the QUALITY flag and array to a given structure of type INHALT

 CATEGORY:
   PROG_TOOLS/STRUCTURES

 CALLING SEQUENCE:
   Result=add_quality(structure)

 INPUTS:
   inhalt: the by ncdf_gr defined structure

 OUTPUTS:
   A structure type INHALT with a quality field and flag added

 EXAMPLE:
  inhalt=add_quality(inhalt)

 MODIFICATION HISTORY:
 	Written by:	R.Bauer (ICG-1), 1998-Jun-13
   1999-Nov-06 help added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\add_quality.pro)


ADD_TAG

[Previous Routine] [Next Routine] [List of Routines]
 USERLEVEL:
   TOPLEVEL

 NAME:
    add_tag

 PURPOSE:
   This functions adds a tag on an arbitrary level of a structure.

 CATEGORY:
   PROG_TOOLS/STRUCTURES

 CALLING SEQUENCE:
   result = add_tag(struct, tagname, tagvalue [, sub_structure = sub_structure])

 INPUTS:
   struct  : the structure to which the tag will be added
   tagname : the name of the new tag
   tagvalue: the value of the new tag

 KEYWORD PARAMETERS:
   sub_structure: to define the sub structure where the tag should be added.
		If not given the tag will be added on the main level of the structure (see examples)

 OUTPUT:
   This function returns a structure with a new tag added to it.

 EXAMPLE:

   d = {A: 1, B: {B1: 0, B2: 1}, C: {B1: 0, B2: 1}}

   help,d,/str
   ** Structure <1331608>, 3 tags, length=10, refs=1
   A               INT              1
   B               STRUCT    ->  Array[1]
   C               STRUCT    ->  Array[1]

   result = add_tag(d,'ASA',11)
   HELP, result, /STR
   ** Structure <10530e8>, 4 tags, length=12, refs=1:
   A               INT              1
   B               STRUCT    ->  Array[1]
   C               STRUCT    ->  Array[1]
   ASA             INT             11

   result = add_tag(d, 'ASA', 11, sub = 'B')
   HELP, result.b, /STR
   ** Structure <133ce88>, 3 tags, length=6, refs=1
   B1              INT              0
   B2              INT              1
   ASA             INT             11

   result = add_tag(d, 'BSB', {C11: INDGEN(3)}, sub = 'B.B3')
   HELP, result.b, /STR
   ** Structure <1357758>, 3 tags, length=10, refs=2:
   B1              INT              0
   B2              INT              1
   B3              STRUCT    ->  Array[1]

   result = add_tag(d, 'BSB', {C11: INDGEN(3)}, sub = ['B','C'])
   help,result.b,/str
   ** Structure <1055618>, 3 tags, length=10, refs=2:
   B1              INT              0
   B2              INT              1
   BSB             STRUCT    ->  Array[1]

   help,result.c,/str
   ** Structure <1056968>, 3 tags, length=10, refs=2:
   B1              INT              0
   B2              INT              1
   BSB             STRUCT    ->  Array[1]


   result = add_tag(d, 'BSB', {C11: INDGEN(3)}, sub = ['B.C1','C'])
   help,result.b,/str
   ** Structure <1056168>, 3 tags, length=10, refs=2:
   B1              INT              0
   B2              INT              1
   C1              STRUCT    ->  Array[1]

   result = add_tag(d, 'BSB', {C11: INDGEN(3)}, sub = 'F')
   help,result,/str
   ** Structure <10550f8>, 4 tags, length=16, refs=1:
   A               INT              1
   B               STRUCT    ->  Array[1]
   C               STRUCT    ->  Array[1]
   F               STRUCT    ->  Array[1]

 MODIFICATION HISTORY:
       Written by:     R.Bauer (ICG-1), 2000-Jan-05
       14.03.2000: Header edited

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\add_tag.pro)


ADD_TAG2

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

 PURPOSE:
	This function adds a tag to a given structure.
	Both, structure and values can be arrays.

 CATEGORY:
	PROG_TOOLS/STRUCTURES

 CALLING SEQUENCE:
	x = add_tag2(str, tag, value [, status])

 INPUTS:
	str: variable name of structure or array of structures
	tag: name of tag to be added (STRING)
		 if tag already exists in str its deleted
	value: value of tag (scalar or array)

 KEYWORD PARAMETERS:
	/EXPAND_VALUES: IF set, the last dimension of value is expanded along the dimension of str
	/FIRST:	The new tag is inserted at the beginning of str
	NAME: A unique name for the new structure.

 OPTIONAL OUTPUTS:
	status: Status information 	=0: every thing worked fine;
								=1: something went wrong (see messages on screen)

 SIDE EFFECTS:
	If an array of anonymous structures is passed into the routine an array
	of named structures is returned.

 EXAMPLE:
	as = {Bsp1, a:0, b:'asd'}
	bs = add_tag2(as, 'c', 0.46D00, /FIRST, NAME = 'Bsp2')
	HELP, bs, /STR :
		** Structure BSP2, 3 tags, length=24:
		   C               DOUBLE          0.46000000
		   A               INT              0
		   B               STRING    'asd'

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 09. Mar. 98.
	This program is based on the procedure add_tag.pro but provides additional features
	27.05.98 - Type of loop variable in FOR loop changed to LONG
	15.11.98:	call to debug deleted
	28.04.1999:	tag_defined exchanged by is_tag
	22.09.1999:	Random structure name will only be generated if a tag is added to an
					array of structures.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\add_tag2.pro)


ADD_TAG_FH

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

 PURPOSE:
	This function can be used to add tags to a substructure of a given structure

 CATEGORY:
	PROG_TOOLS/STRUCTURES

 CALLING SEQUENCE:
	result = add_tag_fh(struct, tag_name, value)

 INPUTS:
	struct: Input structure.
	tag_name: Name of new tag (STRING).
	value: Value of new tag.

 KEYWORD PARAMETERS:
	SUB_STR = sub_str: Name (scalar or array) of the substructure(s) under which the tag is added.
		(default: '' e.g. main level)

 OUTPUTS:
	This function returns a structure with the tag 'tag_name' added.

 EXAMPLE:
	s0 = {H2O: {param: 4, units: 'mbar'}, O3: {param: 17, units: 'ppb'}}

	s1 = add_tag_fh(s0, 'NO2', {param: 23.})
	s1 = add_tag_fh(s1, 'units', 'ppb', SUB_STR = 'NO2')
	HELP, s1, /STR

	s2 = add_tag_fh(s1, 'description', 'NONE', SUB_STR = ['NO2', 'H2O', 'O3'])
	HELP, s2, /STR

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 12.01.2000

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\add_tag_fh.pro)


ADJUSTPOSITION

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

 PURPOSE:

       This is a program for interactively adjusting the plot position
       coordinates. The result of the function is a four-element floating
       point array of normalized coordinates, suitable for passing to the
       POSITION keyword of most IDL graphics commands.

 AUTHOR:

       FANNING SOFTWARE CONSULTING
       David Fanning, Ph.D.
       1645 Sheely Drive
       Fort Collins, CO 80526 USA
       Phone: 970-221-0438
       E-mail: davidf@dfanning.com
       Coyote's Guide to IDL Programming: http://www.dfanning.com

 CATEGORY:

       Graphics

 CALLING SEQUENCE:

       position = AdjustPosition(startingPosition)

 OPTIONAL INPUTS:

       startingPosition - A four-element array of normalized coordinates
            of the form [x0, y0, x1, y1].

 OUTPUTS:

       position - The adjusted plot position. A four-element array of normalized coordinates.

 INPUT KEYWORDS:

       GROUP_LEADER - The group leader of this program. This keyword
            is required to ensure modal operation when calling from
            another widget program.

       TITLE - The title of the window. "Adjust Plot Position in Window..." by default.

       XOFFSET - The X offset of the program on the display. Calculated from the
            upper left-hand corner of the display.

       YOFFSET - The Y offset of the program on the display. Calculated from the
            upper left-hand corner of the display.

 OUTPUT KEYWORDS:

       CANCEL - Returns a 1 if the user selects the Cancel button. Returns 0 otherwise.
            Note that if the use cancels, the "position" parameter is set to the value of
            the "startingPosition" parameter.

 DEPENDENCIES:

       Reqires FSC_FIELD and FSC_PLOTWINDOW from the Coyote Library:

                     http://www.dfanning.com/programs/fsc_field.pro
                     http://www.dfanning.com/programs/fsc_plotwindow.pro

 MODIFICATION HISTORY:

       Written by David Fanning, March 2001.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\adjustposition.pro)


AFORMAT

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

 PURPOSE:
   This procedure is used by plotxy to set the axis-format.

 CATEGORY:
   PLOT/PLOTXY

 CALLING SEQUENCE:
   aformat,plot,xtickformat,ytickformat,xtype,ytype,i_xn,i_yn

 INPUTS:
   plot: plot-structure as defined by pl_init
   i_xn: position number for one of the used x axes
   i_yn: position number for one of the used y axes

 OPTIONAL INPUTS:
   x: name of a netCDF parameter-name containing the array of x values
   y: name of a netCDF parameter-name containing the array of y values


 OUTPUTS:
   xtickformat: string containing the name of the function later used to format xticks
   ytickformat: string containing the name of the function later used to format yticks
   xtype      : set to 1 if format emensch could be used
   ytype      : set to 1 if format emensch could be used

 EXAMPLE:
   aformat,plot,x='TIME',y='NO',xtickformat,ytickformat,xtype,ytype,0,0
   help,xtickformat,ytickformat,xtype,ytype
   XTICKFORMAT     STRING    = ''
   YTICKFORMAT     STRING    = 'emensch'
   XTYPE           INT       =        0
   yTYPE           INT       =        1

   MODIFICATION HISTORY:
   Written by: Franz Rohrer August 1997
   Modified  29.8.97 : plot.xtype und plot.ytype als Felder eingeführt
                       i_xn und i_yn im Prozeduraufruf eingeführt

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\aformat.pro)


AIRDENS (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        AIRDENS  (function)

 PURPOSE:
        Compute air mass density for a given pressure and 
        temperature. If the temperature is not provided, a
        temperature is estimated using the US Standard atmosphere.

 CATEGORY:
        Atmospheric Sciences

 CALLING SEQUENCE:
        idens = AIRDENS(p [,T])

 INPUTS:
        P  -> pressure in hPa (mbar)

        T  -> temperature in K

 KEYWORD PARAMETERS:
        HELP -> print help information

 OUTPUTS:
        The air mass density in molec/cm^3. The result type will 
        match the type and array dimensions of p unless p is a scalar
        and T an array.

 SUBROUTINES:

 REQUIREMENTS:
        Uses functions USSA_ALT and USSA_TEMP

 NOTES:

 EXAMPLE:
    print,airdens(1013.25,273.15)
    ; prints 2.69000e+19

    p = findgen(5)*100+500
    print,airdens(p,T)     ; T undefined !
    ; prints  1.44840e+19  1.67414e+19  1.89029e+19  2.10104e+19  2.30998e+19
    print,T
    ; prints      250.334      259.894      268.538      276.117      282.534

    print,airdens(800.,T)  ; T from previous calculation
    ; prints  2.31744e+19  2.23218e+19  2.16033e+19  2.10104e+19  2.05332e+19

 MODIFICATION HISTORY:
        mgs, 12 Nov 1998: VERSION 1.00
        mgs, 23 Aug 2000: - changed copyright to open source

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\airdens.pro)


AIRMASS

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:  airmass

 PURPOSE:  compute airmass as a function of angle, sza, including
           spherical earth effects

 USEAGE:   result=airmass(sza)

 INPUT:    
   sza     zenith angle   

 KEYWORD INPUT:

 OUTPUT:   relative airmass,
           by definition the relative airmass = 1 for sza=0.

 References:
   1) Kasten, F 1966: A new table and approximate formula for relative
      airmass. Arch. Meteor. Geophys. Bioklimatol. Ser. B, 14, 206-223

   2) Kasten and Young, 1989: Applied Optics, 28, 4735-4738
      recommended by Yankee Environmental Systems (MFRSR)
  
 EXAMPLE:  

    sza=findrng(0,89.,dx=.1)
    plot,sza,1./cos(sza*!dtor),yran=[1,30]
    plot,sza,cos(sza*!dtor)*airmass(sza)

 AUTHOR:   Paul Ricchiazzi                        09 Jan 97
           Institute for Computational Earth System Science
           University of California, Santa Barbara
           paul@icess.ucsb.edu

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\airmass.pro)


ALIGN

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ALIGN
 PURPOSE:
       Vector text justification (positioning).
 CATEGORY:
 CALLING SEQUENCE:
       align, x,y,txt
 INPUTS:
       x,y = Reference point.  in
       txt = Text string.
 KEYWORD PARAMETERS:
       Keywords:
         CHARSIZE=csz Character size.
         AX=ax    Alignment in X (fraction).
         AY=ax    Alignment in Y (fraction).
           AX=0, AY=0 is lower left corner of text.
           AX=1, AY=1 is upper right corner of text.
         /DEVICE  Means work in device coordinates.
         /DATA    Means work in data coordinates.
         /NORMAL  Means work in normalized coordinates.
         XOUT=xx  Output x position.
         YOUT=yy  Output x position.
           xyouts,xx,yy,txt,charsize=csz.
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
       Notes: Currently works only for horizontal text.
 MODIFICATION HISTORY:
       R. Sterner, 1994 Apr 4.

 Copyright (C) 1994, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\align.pro)


ALT_INHALT_DEF

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

 PURPOSE:
    This routine holds the definitons for the structure INHALT
    It's an alternative to inhalt_def

 CATEGORY:
  DATAFILES/NETCDF

 CALLING SEQUENCE:
	alt_inhalt_def,inhalt_def=inhalt_def,[array_de_descriprion=array_de_descriprion]


 OUTPUTS:
 inhalt_def=inhalt_def:                     an array defining ncdf and idl names

 OPTIONAL OUTPUTS:
 array_de_description=array_de_description: an array holding german expressions for additional parameters

 EXAMPLE:
 alt_inhalt_def,inhalt_def=inhalt_def

 MODIFICATION HISTORY:
 	Written by:	R. Bauer ICG-1 , May 1997
  R.Bauer 1997-Sep-16 debug added
  R.Bauer 1998-Mar-3 filter extended by using uppercase definitions
  R.Bauer 1998-Nov-16 added 4*s+o
  R.Bauer 1998-Nov-16 added user definitions for INHALT
  R.Bauer 1999-May-28 added time_description and time_de_description
  R.Bauer 1999-Sep-07 median added
  R.Bauer 2000-Jan-25 dataset_forecast_hours added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\alt_inhalt_def.pro)


AMES2ICGS

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

 PURPOSE:
   This functions reads the nasa Ames datafiles to the icg  data structure

 CATEGORY:
   DATAFILES/FILTER

 CALLING SEQUENCE:
   result=ames2icgs(file)

 INPUTS:
   file: name of the nasa ames file


 PROCEDURE:
  This routine uses the ames library interface

 EXAMPLE:
   struct=ames2icgs('al970626.ea1')
   write_ncdf,'al970626.nc',struct

 MODIFICATION HISTORY:
       Written by:     R.Bauer (ICG-1), 1999-Nov-30
       This routine is not quite finished at the moment.
       I will change the "cases" later on
       2000-01-18 Abfrage für das Einbinden von stdev erweitert.
       2000-01-21 useable fomats at the moment are: 1001, 1020, 2110
       2000-01-24 short_names for some files expanded
       2000-01-25 short_names for more files expanded (jug)
       2000-02-24 'ALTITUDE OF OBSERVATION' added
       2000-06-13 is_tag  auf 'time' added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\jug_lib\ames2icgs.pro)


ANGLE_INC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		ANGLE_INC
 VERSION:
		4.1
 PURPOSE:
		Calculates the angle increments between segments of a polygonal line.
 CATEGORY:
		Mathematical.
 CALLING SEQUENCE:
		Result = ANGLE_INC( X [, Y] [, keywords])
 INPUTS:
	X
		Numeric vector or [2,N] array.  In the first case:
			1)	If Y is given, X represents the X coordinates of the vertices.
			2)	If Y is not given, X represents the Y coordinates and the X
				coordinates are generated internally as [1, 2, ...N-1]
		In the second case X represents both X and Y coordinates and Y should
		not be given.
 OPTIONAL INPUT PARAMETERS:
	Y
		Numeric vector, optional when X given as vector, forbidden when X is a
		[2,N] array.  Represents the Y coordinates.
 KEYWORD PARAMETERS:
	/ABSOLUTE
		Switch.  If set the absolute values of the angles are calculated.
	/CLOSED
		Switch.  If set, the shape is closed prior to calculation (unless it
		is already closed.
	/TOTAL_ONLY
		Switch.  If set, only the sum of the angles is returned.
 OUTPUTS:
		Returns the N-2 (or N-1, for a closed curve) external angles generated
		by the vertices.  Note, the external angles are the angles by which
		each segment deviates from the previous one.
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		The value of N (the vector length) must be >=3.  Also, if both X and Y
		are given, they must be of same length.
 PROCEDURE:
		Straightforward from the geometric definitions.  Calls CAST, DIF,
		SIGN, SPLIT_XY and TYPE from MIDL.
 MODIFICATION HISTORY:
		Created 15-MAY-2001 by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\angle_inc.pro)


ANIMALS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ANIMALS
 PURPOSE:
       Return a string array of animals.
 CATEGORY:
 CALLING SEQUENCE:
       a = animals()
 INPUTS:
 KEYWORD PARAMETERS:
 OUTPUTS:
       a = string array of animals.   out
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 24 Jul, 1991

 Copyright (C) 1991, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\animals.pro)


APODIZE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       APODIZE
 PURPOSE:
       Weighting array for apodizing an image.  Cosine taper.
 CATEGORY:
 CALLING SEQUENCE:
       a = apodize(w, r)
 INPUTS:
       w = size of square array a to make.             in
       r = radius of flat top as a fraction 0 to 1.    in
 KEYWORD PARAMETERS:
 OUTPUTS:
       a = resulting array.                            out
 COMMON BLOCKS:
 NOTES:
       Notes: Output array is square.  To convert to rectangular
          use congrid to specify desired size and shape:
          b = congrid(a, 100,50)
 MODIFICATION HISTORY:
       Written by R. Sterner, 6 Dec, 1984.
       Johns Hopkins University Applied Physics Laboratory.

 Copyright (C) 1984, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\apodize.pro)


ARC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		ARC
 VERSION:
		4.0
 PURPOSE:
		Draws a circular arc in the currently defined plot area.
		Alternatively, a *SHAPE* representation (see SHAPE_VER for definition)
		of the arc may be returned through the SHAPEOUT keyword.  DATA
		coordinates are used.  The method of drawing depends on the number of
		input parameters provided (see details in CALLING SEQUENCE below).
 CATEGORY:
		General Graphics.
 CALLING SEQUENCE:
		There are two possible modes of operation, and accordingly two
		different calling sequences:
		Mode 1:
			ARC, R1, CENTER = CENT, ANGLE = ANG [, optional keywords]
		In this mode an arc with angular measure ANG is drawn around the point
		CENT, in the mathematical-positive direction, starting from point R1.
		Mode 2:
			ARC, R1, R2, {RADIUS = RAD, ANGLE = ANG} [, optional keywords]
		In this mode the arc is drawn in the mathematical-positive direction,
		from point R1 to point R2.  The arc is either drawn with radius RAD, or
		corresponding to an angle ANG (both RAD and ANG cannot be specified).
 INPUTS:
	R1, R2
		2-dimensional vectors in the [x,y] format, representing points in the
		plotting area.  R1 is mandatory.  The presence of R2 indicates that
		Mode 2 is being used.
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
	CENTER
		2 dimensional vector, arc center location, format [x,y].
		Mandatory in Mode 1, forbidden in Mode 2.
	RADIUS
		Scalar, the radius of the arc.			|
		Forbidden in Mode 1, allowed in Mode 2.	|  In Mode 2
	ANGLE										|  one and only one
		Scalar, the angle measure of the arc.	|  needs to be provided.
		Mandatory in Mode 1, allowed in Mode 2. |
	/DEGREES
		Switch.  Indicates that the angle ANG is given in degrees (default is
		radians).
	/BIGARC
		Switch.  When drawing in Mode 2, with the radius provided, there are two
		possible arcs that can be drawn, corresponding to angles smaller and
		bigger than 180 degrees (the sum of both angles is 360 degrees).  By
		default the smaller arc is drawn. Setting BIGARC selects the bigger arc.
	/SYMMETRIC
		Switch.  In Mode 1 causes the arc to be drawn symmetrically on both
		sides of R1.  Forbidden in Mode 2.
	/NO_SHOW
		Switch.  If set, no plotting is done, but the shape is generated and
		may be returned through SHAPEOUT.
	SHAPEOUT
		Optional output, see below.
	_EXTRA
		A formal keyword used to pass all plotting keywords.  Not to be used
		directly.
 OUTPUTS:
		None.
 OPTIONAL OUTPUT PARAMETERS:
	SHAPEOUT
		When provided with the name of a variable, on return the variable
		contains the *SHAPE* representation of the arc.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		The arc will appear as a true circular arc only if the aspect ratio of
		the X to Y axes is 1:1.
		The keywords passed through _EXTRA are transferred to the PLOTS
		routine.  No keyword verification is performed by ARC.
 PROCEDURE:
		Uses calls to ONE_OF and SHAPE_COCON from MIDL.
		Generates a (2,N) array containing a sufficient number of the arc
		points to yield a smooth curve.  N is variable, depending both on the
		arc size and on the pixel size of the current output device.
 MODIFICATION HISTORY:
		Created 15-DEC-1991 by Mati Meron.
		Modified 15-DEC-1993 by Mati Meron.  Now ARC takes advantage of the
		keyword inheritance property and accepts all PLOTS keywords.
		Modified 15-JUN-1995 by Mati Meron.  Removed the ALT_EXT keyword which
		is no longer needed (_EXTRA has been fixed).
		Modified 25-JUL-1999 by Mati Meron.  Added keywords NO_SHOW and
		SHAPEOUT.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\arc.pro)


ARCS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ARCS
 PURPOSE:
       Plot specified arcs or circles on the current plot device.
 CATEGORY:
 CALLING SEQUENCE:
       arcs, r, a1, a2, [x0, y0]
 INPUTS:
       r = radii of arcs to draw (data units).                  in
       [a1] = Start angle of arc (deg CCW from X axis, def=0).  in
       [a2] = End angle of arc (deg CCW from X axis, def=360).  in
       [x0, y0] = optional arc center (def=0,0).                in
 KEYWORD PARAMETERS:
       Keywords:
         /DEVICE means use device coordinates .
         /DATA means use data coordinates (default).
         /NORM means use normalized coordinates.
         /NOCLIP means do not clip arcs to the plot window.
         COLOR=c  plot color (scalar or array).
         LINESTYLE=l  linestyle (scalar or array).
         THICKNESS=t  line thickness (scalar or array).
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
       Note: all parameters may be scalars or arrays.
 MODIFICATION HISTORY:
       Written by R. Sterner, 12 July, 1988.
       Johns Hopkins University Applied Physics Laboratory.
       RES 15 Sep, 1989 --- converted to SUN.
       R. Sterner, 17 Jun, 1992 --- added coordinate systems, cleaned up.
       R. Sterner, 1997 Feb 24 --- Added THICKNESS keyword.

 Copyright (C) 1988, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\arcs.pro)


ARG_PRESENT[1]

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

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

 PURPOSE:
   Determine whether output parameter has been passed (IDL4 compatibility)

 CALLING SEQUENCE:
   PRESENT = ARG_PRESENT(ARG)

 DESCRIPTION: 

   ARG_PRESENT tests whether an argument to a function or procedure
   can be used as an output parameter.  The behavior of this function
   is identical to that of the built-in ARG_PRESENT function in IDL
   version 5 or greater, and is meant to give the same functionality
   to programs in IDL 4.

   An IDL procedure or function can use ARG_PRESENT to decide whether
   the value of a positional or keyword parameter will be returned to
   the calling procedure.  Generally, if the caller did not pass the
   parameter then there is no need to compute the value to be
   returned.

   To be a valid output parameter, the caller must have passed a
   named variable into which the result is stored.  If the caller
   passed the parameter by value (e.g., an expression or a
   subscripted array) the value cannot be returned and ARG_PRESENT
   returns 0.

 INPUTS:

   ARG - the parameter to be tested.  It can be either a positional
         or a keyword parameter.  Passing a normal local variable
         (i.e., not a passed parameter) will cause ARG_PRESENT to
         return zero.

 RETURNS:

   Returns a value of 1 if ARG is a valid output parameter, and a
   value of 0 otherwise.


 EXAMPLE:

   Consider the following procedure:
      PRO TESTARG, ARG1
        print, ARG_PRESENT(ARG1)
      END

   This procedure will print 1 when an ARG1 can be used as an output
   parameter.  Here are some examples of the results of TESTARG.

      IDL> testarg
             0
      IDL> testarg, x      
             1
      IDL> testarg, findgen(10)
             0
   
   In the first case, no argument is passed, so ARG1 cannot be a
   return variable.  In the second case, X is undefined, but it is
   still a legal named variable capable of receiving an output
   parameter.  In the third case, FINDGEN(10) is an expression which
   cannot receive an output parameter.

 SEE ALSO:

   ARG_PRESENT in IDL version 5

 MODIFICATION HISTORY:
   Written, CM, 13 May 2000
   Small documentation and bug fixes, CM, 04 Jul 2000

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\arg_present.pro)


ARG_PRESENT[2]

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

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

 PURPOSE:
   Determine whether output parameter has been passed (IDL4 compatibility)

 CALLING SEQUENCE:
   PRESENT = ARG_PRESENT(ARG)

 DESCRIPTION: 

   ARG_PRESENT tests whether an argument to a function or procedure
   can be used as an output parameter.  The behavior of this function
   is identical to that of the built-in ARG_PRESENT function in IDL
   version 5 or greater, and is meant to give the same functionality
   to programs in IDL 4.

   An IDL procedure or function can use ARG_PRESENT to decide whether
   the value of a positional or keyword parameter will be returned to
   the calling procedure.  Generally, if the caller did not pass the
   parameter then there is no need to compute the value to be
   returned.

   To be a valid output parameter, the caller must have passed a
   named variable into which the result is stored.  If the caller
   passed the parameter by value (e.g., an expression or a
   subscripted array) the value cannot be returned and ARG_PRESENT
   returns 0.

 INPUTS:

   ARG - the parameter to be tested.  It can be either a positional
         or a keyword parameter.  Passing a normal local variable
         (i.e., not a passed parameter) will cause ARG_PRESENT to
         return zero.

 RETURNS:

   Returns a value of 1 if ARG is a valid output parameter, and a
   value of 0 otherwise.


 EXAMPLE:

   Consider the following procedure:
      PRO TESTARG, ARG1
        print, ARG_PRESENT(ARG1)
      END

   This procedure will print 1 when an ARG1 can be used as an output
   parameter.  Here are some examples of the results of TESTARG.

      IDL> testarg
             0
      IDL> testarg, x      
             1
      IDL> testarg, findgen(10)
             0
   
   In the first case, no argument is passed, so ARG1 cannot be a
   return variable.  In the second case, X is undefined, but it is
   still a legal named variable capable of receiving an output
   parameter.  In the third case, FINDGEN(10) is an expression which
   cannot receive an output parameter.

 SEE ALSO:

   ARG_PRESENT in IDL version 5

 MODIFICATION HISTORY:
   Written, CM, 13 May 2000
   Small documentation and bug fixes, CM, 04 Jul 2000

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmarg_present.pro)


ARMBASETIME

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:  armbasetime

 PURPOSE: The base_time variable provided by ARM net_cdf files is the
          number of seconds since jan 1, 1970 00:00:00 UTC.  This
          procedure converts base_time to the current date in yymmdd
          format, and the number of hours since the most recent
          Grenich midnight (00:00:00 UTC).

 USEAGE:  armbasetime,base_time,time,yymmdd,file=file

 INPUT:    
   bt     number of seconds since jan 1, 1970 00:00:00 UTC.

 KEYWORD_INPUT

  file    name arm net_cdf file. If this quantity is set the value
          of bt is set from the value read from the file.


 OUTPUT:

  time    time since Grenich midnight of the current day
  yymmdd  date string in yymmdd format

  
 EXAMPLE: 
    file='/home/paul/arm/iop_97/mfrsr/sgpmfrsrC1.a1.970915.000000.cdf'
    armbasetime,file=file,bt,time,yymmdd
    print,bt,time,"   ",hms(3600*time)," ",yymmdd

 AUTHOR:   Paul Ricchiazzi                        05 Jun 98
           Institute for Computational Earth System Science
           University of California, Santa Barbara
           paul@icess.ucsb.edu

 REVISIONS:

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\armbasetime.pro)


ARR2STRING

[Previous Routine] [Next Routine] [List of Routines]
 USERLEVEL:
   TOPLEVEL

 NAME:
   arr2string

 PURPOSE:
   This function will combine elements of a stringarray; e.g. [' A ',' B ']->'A,B'

 CATEGORY:
   PROG_TOOLS/STRINGS

 CALLING SEQUENCE:
   result=arr2string(array)

 INPUT PARAMETERS:
   strarray

 KEYWORD PARAMETERS:
   sep  : separator, default:' '
   limit: string length limit (default 32767); longer strings will be put into a stringvector

 OUTPUTS:
   result: str-vector; combination of elements of the array separated by a separator
           undefined array will return result=''

 EXAMPLE:
   result=arr2string(['A','BCD','DCB'],sep=':')
   result:'A:BCD:DCB'

   result=arr2string()
   result:''

 MODIFICATION HISTORY:
   Written by Reimar Bauer, Franz Rohrer Aug 1998
   Modified 10.03.2000 Franz Rohrer : limit string length to 32765

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\arr2string.pro)


ARRAY2HTMLTABLE

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

 PURPOSE:
   This functions creates a table in html from an array of numbers or text

 CATEGORY:
   PROG_TOOLS/HTML

 CALLING SEQUENCE:
   Result = ARRAY2HTMLTABLE(Array)

 INPUTS:
   Array:  array of numbers or text

 KEYWORD PARAMETERS:
   MAX_ARRAY:  cuts the size of the output to max_array columns and rows
   MAX_COLS:   cuts the size of the output to max_cols columns
   MAX_ROWS:   cuts the size of the output to max_rows rows
   BORDER: if this keyword is set a border will be produced for each
           table entry
   CAPTION: if this keyword is set to a string this will be printed
           as a table caption
   COL_NUMBERS: if this keyword is set a column number is printed
   ROW_NUMBERS: if this keyword is set a row number is printed
   COL_TITLES: if an array of column title is provided they will be printed
           instead of numbers
   ROW_TITLES: see COL_TITLES
   CORNER_TITLE: if a string is provided it wil be set in the corner created
                   by row an col titles
   ALIGNMENT: Specifies the alignment of the caption text. An alignment
           of 0.0 (the default) aligns left, 1.0 right and 0.5 centered

   parsed to tab_i
   SMALL:      use small fonts for table entries
   FIXED:      use fixed fonts for table entries
   NOBREAK:    no line breaks in table entries

 OUTPUTS:
   This function returns a string array containing html-code for table
   which correponds to the content of an IDL array

 EXAMPLE:
   see also html_example.pro and html_example2.pro

   print, array2htmltable([[11,12],[21,22]])
       
11 12
21 22

print, array2htmltable([['11','12'],['21','22']], /BORDER)
11 12
21 22

MODIFICATION HISTORY: Written by: Theo Brauers, 1998-JAN-19 Modified 1998 Jul 29 new corner_title Corrected T.B. 1998 Aug 6 keyword_set for n_elements Modified 2000 Feb 1 new keyw HORIZOTAL_1D Modified 2000 Mar 13 new keyw max_array, max_rows, max_cols

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\array2htmltable.pro)


ARRAY2TEXTABLE

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

 PURPOSE:
   This functions creates a table in tex from an array of numbers or text

 CATEGORY:
   PROG_TOOLS/TEX

 CALLING SEQUENCE:
   Result = array2textable(array,[vspace=vspace],[format=format],[/table],[/grid])

 INPUTS:
   Array:  array of numbers or text

 OPTIONAL INPUTS:
   vspace:  a string holding the vertical space behind the table
   format:  the formatcode for the whole table without {}


 KEYWORD PARAMETERS:
  table : \table will be included before \begin {tabular}
  grid:  \grid will give hor and vertical lines

 OUTPUTS:
   This function returns a string array containing tex-code for table
   which correponds to the content of an IDL array

 EXAMPLE:
  test=sindgen(10,4)
  f=array2textable(test,/table)
  print,f

  \begin{table}
  \begin{tabular}{rrrrrrrrrr}
  0 & 1 & 2 & 3 & 4 & 5 & 6 & 7 & 8 & 9 \\
  10 & 11 & 12 & 13 & 14 & 15 & 16 & 17 & 18 & 19 \\
  20 & 21 & 22 & 23 & 24 & 25 & 26 & 27 & 28 & 29 \\
  30 & 31 & 32 & 33 & 34 & 35 & 36 & 37 & 38 & 39 \\
  \end{tabular}
  \end{table}


 MODIFICATION HISTORY:
   Written by: Reimar Bauer, 1998-Jun-29
   1998-Jul-05 format added
   1999-Nov-06 help added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\array2textable.pro)


ARRAY_LIST

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ARRAY_LIST
 PURPOSE:
       List an array in a form useful to cut and paste.
 CATEGORY:
 CALLING SEQUENCE:
       array_list, a
 INPUTS:
       a = array to list.       in
 KEYWORD PARAMETERS:
       Keywords:
         OUT=out Returned list in a text array.
         FRONT=frnt Text to add to front (def=none).
           Can space in and give a variable name: '  a = '
           Use spaces, not tabs, to get correct line length.
         INDENT=itxt Text string used to indent continued lines.
            Default is 10 spaces.
         /QUIET do not display list.
         MAXLEN=mx Max length before line continue (def=72).
           May be one longer for continued lines.
         FORMAT=fmt Format for values (def=none).
         /TRIM means trim leading and trailing 0s (and spaces).
           Useful with FORMAT to get minimum strings.
         TYPE=typ  Name of data type function (def=none).
           Will apply to array.  Ex: uint([1,2,3])
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 1999 Nov 30

 Copyright (C) 1999, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\array_list.pro)


ARRDELETE

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

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

 PURPOSE:
   Remove a portion of an existing array.

 CALLING SEQUENCE:
   NEWARR = ARRDELETE(INIT, [AT=POSITION,] [LENGTH=NELEM])

 DESCRIPTION: 

   ARRDELETE will remove or excise a portion of an existing array,
   INIT, and return it as NEWARR.  The returned array will never be
   larger than the initial array.

   By using the keywords AT and LENGTH, which describe the position
   and number of elements to be excised respectively, any segment of
   interest can be removed.  By default the first element is removed.

 INPUTS:

   INIT - the initial array, which will have a portion deleted.  Any
          data type, including structures, is allowed.  Regardless of
          the dimensions of INIT, it is treated as a one-dimensional
          array.  If OVERWRITE is not set, then INIT itself is
          unmodified.

 KEYWORDS:

   AT - a long integer indicating the position of the sub-array to be
        deleted.  If AT is non-negative, then the deleted portion
        will be NEWARR[AT:AT+LENGTH-1].  If AT is negative, then it
        represents an index counting from then *end* of INIT,
        starting at -1L.
        Default: 0L (deletion begins with first element).

  LENGTH - a long integer indicating the number of elements to be
           removed.  

  OVERWRITE - if set, then INIT will be overwritten in the process of
              generating the new array.  Upon return, INIT will be
              undefined.

  COUNT - upon return, the number of elements in the resulting array.
          If all of INIT would have been deleted, then -1L is
          returned and COUNT is set to zero.

  EMPTY1 - if set, then INIT is assumed to be empty (i.e., to have
           zero elements).  The actual value passed as INIT is
           ignored.

 RETURNS:

   The new array, which is always one-dimensional.  If COUNT is zero,
   then the scalar -1L is returned.

 SEE ALSO:

   STORE_ARRAY in IDL Astronomy Library

 MODIFICATION HISTORY:
   Written, CM, 02 Mar 2000
   Added OVERWRITE and EMPTY1 keyword, CM 04 Mar 2000

  $Id: arrdelete.pro,v 1.2 2001/03/25 18:10:41 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\arrdelete.pro)


ARREQ

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		ARREQ
 VERSION:
		4.0
 PURPOSE:
		Compares arrays for equality.  The arrays qualify as equal if:
			1) They are of the same general type (num., char., or struct.).
			2) Number of dimensions is the same.
			3) Size of each dimension is the same.
			4) Respective elements are equal.
 CATEGORY:
		Mathematical Function (general).
 CALLING SEQUENCE:
		Result = ARREQ( ARR1, ARR2 [, keywords])
 INPUTS:
	ARR1, ARR2
		Arrays, type and number of dimensions arbitrary.
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
	/WARN
		Switch. If set, a warning message is issued for incompatible data types.
	/NOVALUE
		Switch.  If set, only number of elements and structure are compared.
 OUTPUTS:
		Returns 1 if the arrays are equal, 0 otherwise.
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		None.
 PROCEDURE:
		Uses the SIZE function and ISNUM from MIDL to obtain information about
		the arrays.  Compares, in order, number of dimensions, size of each
		dimension, data types, and (unless NOVALUE is set) individual elements.
 MODIFICATION HISTORY:
		Created 15-JUL-1991 by Mati Meron.
		Modified 30-AUG-1998 by Mati Meron.  Scope broadened to pointer arrays.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\arreq.pro)


ARREX (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ARREX  (function)

 PURPOSE:
        This function extracts a multi-dimensional subset
        of an array. For each dimension the start index,
        end index (or count), and stride can be specified - default 
        values are 0 (i.e. first start index), "all" (i.e. last end
        index), and 1 (i.e. every element). A negative stride
        causes reversion of the respective array dimension.

 CATEGORY:
        Array Tools

 CALLING SEQUENCE:
        Result = ARREX( Array [, Startindex=]  $
                              [, Endindex= | Count=]    $
                              [, Stride=]      $
                              [, /Reform] )

 INPUTS:
        ARRAY -> The parent array from which the extraction shall be made.
            Currently up to 6 dimensions are supported.

 KEYWORD PARAMETERS:
        STARTINDEX -> An array with starting indices. Each element of
            startindex corresponds to one dimension of ARRAY. If
            startindex has less elements than ARRAY dimensions, the
            remainder is assumed 0. 

        ENDINDEX -> An array with ending indices. Each element of
            endindex corresponds to one dimension of ARRAY. If
            endindex has less elements than ARRAY dimensions, the
            remainder is set to the maximum possible value for that
            dimension. Endindex cannot be use together with count.

        COUNT -> An array with the number of elements to be extracted
            along each dimension. Count values must be greater 0 and
            are automatically adjusted so that startindex +
            (count-1)*stride is a valid index for that
            dimension. Count and Endindex cannot be used together.
 
        STRIDE -> An array with stride values. A stride of 1 (default)
            signifies extraction of every element, 2 returns every 
            second element for that dimension, etc. Negative values
            cause the respective dimension to be reversed and are
            only allowed when the count keyword is not used.
            Each value of stride corresponds to one dimension of ARRAY. 
            If stride has less elements than ARRAY dimensions, the 
            remainder is assumed 1.

        /REFORM -> Set this keyword to eliminate unnecessary dimensions
            in the result.

 OUTPUTS:
        A subset of the original array. This will have the same 
        dimensionality as ARRAY unless the REFORM keyword is set.

 SUBROUTINES:
        Function arrex_ComputeInd

 REQUIREMENTS:
        Uses the reverse function from the IDL library

 NOTES:
        Created after discussion in newsgroup idl-pvwave.

 EXAMPLE:
        A = indgen(10,10)
        print,arrex(A,[2,1],-1,[2,4])
        ; yields  12  14  16  18
        ;         52  54  56  58
        ;         92  94  96  98
        print,arrex(A,[10,1],[1,10],[5,5])
        ; yields  19  15
        ;         69  65
        ; note that stride for dimension 1 is adjusted automatically.

 MODIFICATION HISTORY:
        mgs, 20 May 1999: VERSION 1.00
            - with a lot of input from L. Gumley, S. Vidar, and
              others
        mgs, 15 Aug 2000: VERSION 2.00
            - added DEBUG keyword and extended for up to 6
              dimensions.
            - changed from arguments to keywords.
            - added count keyword to enhance usability together with
              netcdf type access.
            - changed error behaviour. Now stops instead of returning
              the unchanged array.
            - changed copyright notice to Open Source.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\arrex.pro)


ARRINSERT

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

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

 PURPOSE:
   Insert one array into another

 CALLING SEQUENCE:
   NEWARR = ARRINSERT(INIT, INSERT, [AT=POSITION] )

 DESCRIPTION: 

   ARRINSERT inserts the contents of one array (INSERT) into
   another (INIT), and returns the new array (NEWARR).

   ARRINSERT will handle empty lists, which are represented as
   undefined variables.  If both input arrays are empty, then the
   scalar -1L is returned, and the keyword COUNT is set to 0L.

 INPUTS:

   INIT - the initial array, into which INSERT will be inserted.  Any
          data type, including structures, is allowed.  Regardless of
          the dimensions of INIT, it is treated as a one-dimensional
          array.  If OVERWRITE is not set, then INIT itself is
          unmodified.

   INSERT - the array to be inserted into INIT, which must be of the
            same or similar type to INIT.  If INSERT is empty, then
            INIT is returned unchanged.  Regardless of the dimensions
            of INSERT, it is treated as a one-dimensional array.

 KEYWORDS:

    AT - a long integer indicating the position of the newly inserted
         sub-array.  If AT is non-negative, then INSERT will appear
         at NEWARR[AT].  If AT is negative, then INSERT will appear
         at NEWARR[AT + (N+1)] where N is the number of elements in
         INIT, which is to say if AT is negative, it indexes from the
         end side of the array rather than the beginning.

         Default: 0L (INSERT appears at beginning of INIT)

   OVERWRITE - if set, then the initial array INIT will be
               overwritten by the new array.  Upon exit INIT becomes
               undefined.

   COUNT - upon return, the number of elements in the resulting
           array.

  EMPTY1, EMPTY2 - if set, then INIT (for EMPTY1) or INSERT (for
                   EMPTY2) are assumed to be empty (i.e., to have
                   zero elements).  The actual values passed as INIT
                   or INSERT are then ignored.

 RETURNS:

   The new array, which is always one-dimensional.  If COUNT is zero,
   then the scalar -1L is returned.

 SEE ALSO:

   ARRDELETE, STORE_ARRAY in IDL Astronomy Library

 MODIFICATION HISTORY:
   Written, CM, 02 Mar 2000
   Added OVERWRITE and EMPTY keywords, CM, 04 Mar 2000
   Improved internal docs, and AT keyword docs, CM, 28 Sep 2000
   Doc clarifications, CM, 29 Sep 2001

  $Id: arrinsert.pro,v 1.3 2001/09/30 03:17:06 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\arrinsert.pro)


ARRLOC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		ARRLOC
 VERSION:
		4.0
 PURPOSE:
		Converts array indices from expanded (multi dimensional) form to
		contracted (one dimensional) form and vice versa.
 CATEGORY:
		Array Function.
 CALLING SEQUENCE:
		Result = ARRLOC( INDS, SIZ [, keywords])
 INPUTS:
	INDS
		Numeric, converted to long integer on input.  Structure depends on
		usage mode (EXPAND versus CONTRACT) and on the input parameter SIZ, as
		follows:
			EXPAND mode  :  INDS can be a scalar or a vector (1-dim array).
			CONTRACT mode:  If SIZ(0) = 0 then INDS arbitrary.  Else INDS can
			be a scalar, vector or a 2-dim array, subject to the following
			restrictions:
			INDS is scalar:  SIZ(0) must be 1.
			INDS is vector:  SIZ(0) must equal the length of INDS.
			INDS is M*N array:  SIZ(0) must equal M (first array dimension).
	SIZ
		Vector in the form of the standard output of the system function SIZE.
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
	/EXPAND
		Switch, specifies expansion mode.  This is the default.
	/CONTRACT
		Switch, specifies contraction mode.
 OUTPUTS:
		Depending on mode, as follows:
		EXPAND mode:  Returns an M*N array, where M is the number of dimensions
			of the object charactarized by SIZ (i.e. SIZ(0)) and N is the
			number of elements in INDS.  For example, if S = [2,3,8,4,24]
			(corresponding to a 3*8 real array) then ARRLOC(5,S) will return
			the vector [2,1] (the indices of the 5th element) while
			ARRLOC([2,5,22]) will return:	2	0
											2	1
											1	7
		CONTRACT mode:  Reverses the action of expand.  When fed an array in
			the form of the output of ARRLOC with EXPAND, returns a vector of
			1-dimensional indices.  For example a call to ARRLOC using S and
			the output array from the example above will return:	2
																	5
																	22
		In either mode, if any of the resulting indices is out of bounds for
		the array specified by SIZ, it is replaced by -1.
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		None other than those specified in the description of INDS, above.
 PROCEDURE:
		Straightforward.  Calls ONE_OF from MIDL.
 MODIFICATION HISTORY:
		Created 30-MARCH-1994 by Mati Meron.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\arrloc.pro)


ARRO.

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		ARRO.
 VERSION:
		4.0
 PURPOSE:
		Draws an arrow in the current plot area, from the FROM to the TO
		location.  DATA coordinates are used, unless one of the keywords
		/DEVICE or /NORMAL is set.
 CATEGORY:
		General Graphics.
 CALLING SEQUENCE:
		ARRO, FROM = tail, TO = head [, keywords]
 INPUTS:
		None.
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
	FROM
		Two dimensional vector, start location, mandatory.
	TO
		Two dimensional vector, end location, mandatory.
	SIZE
		Scalar, specifies size of head [and tail], default is 1.
	/TAIL
		Switch.  Puts a tail on the arrow.
	/TWOSIDED
		Switch.  Draws a twosided arrow (heads on both ends).
	/DEVICE
		Standard IDL plotting interpretation.
	/NORMAL
		Ditto.
	_EXTRA
		A formal keyword used to pass all plotting keywords.  Not to be used
		directly.
 OUTPUTS:
		None.
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		The keywords passed through _EXTRA are transferred to the PLOTS
		routine.  No keyword verification is performed by ARRO.
 PROCEDURE:
		Uses DEFAULT, ONE_OF, SHAPE_COCON, SHAPE_TRANS and WHERINSTRUCT
		from MIDL.  All the coordinates are converted to DEVICE coordinates for
		shape generation and plotting purposes.
 MODIFICATION HISTORY:
		Created 15-JUL-1991 by Mati Meron.
		Modified 15-DEC-1991 by Mati Meron.  Added keywords COLOR and TWOSIDED.
		Modified 15-DEC-1993 by Mati Meron.  Now ARROW takes advantage of the
		keyword inheritance property and accepts all IDL plotting keywords.
		Modified 5-OCT-1994 by Mati Meron.  Name changed to ARRO to avoid
		conflicts with library routines.
		Modified 15-JUN-1995 by Mati Meron.  Utilizes WHERINSTRUCT for improved
		keyword inheritance.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\arro.pro)


ARROW

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ARROW
 PURPOSE:
       Draw arrows on screen.
 CATEGORY:
 CALLING SEQUENCE:
       arrow, xt, yt, xh, yh
 INPUTS:
       xt, yt = x,y of arrow tail.     in
       xh, yh = x,y of arrow head.     in
 KEYWORD PARAMETERS:
       Keywords:
         /DATA means use data coordinates (def).
         /NORM means use normalized coordinates.
         /DEVICE means use device coordinates.
         COLOR=c arrow outline color (def=255).
           Make same as FILL for no outline.
         THICK=t arrow outline thickness (def=0).
         LINESTYLE=s arrow outline line style (def=0).
         FILL=f set arrow fill color (0-255, def = -1 = no fill).
         LENGTH=l  Arrow head length in % plot width (def = 3).
         WIDTH=w  Arrow head width in % plot width (def = 2).
         SHAFT=s  Arrow shaft width in % plot width (def = 1).
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 21 Sep, 1990

 Copyright (C) 1990, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\arrow.pro)


ARROW2

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ARROW2
 PURPOSE:
       Draw arrows on screen.
 CATEGORY:
 CALLING SEQUENCE:
       arrow2, xt, yt, xh, yh
 INPUTS:
       xt, yt = x,y of arrow tail.     in
       xh, yh = x,y of arrow head.     in
 KEYWORD PARAMETERS:
       Keywords:
         /DATA means use data coordinates (def).
         /NORM means use normalized coordinates.
         /DEVICE means use device coordinates.
         COLOR=c arrow outline color (def=255).
           Make same as FILL for no outline.
         THICK=t arrow outline thickness (def=0).
         LINESTYLE=s arrow outline line style (def=0).
         FILL=f set arrow fill color (0-255, def = -1 = no fill).
         LENGTH=l  Arrow head length in % plot width (def = 3).
         WIDTH=w  Arrow head width in % plot width (def = 2).
         SHAFT=s  Arrow shaft width in % plot width (def = 1).
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 21 Sep, 1990
       R. Sterner, 11 Nov, 1993 --- renamed from arrow.

 Copyright (C) 1990, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\arrow2.pro)


ARR_EQUAL

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

 PURPOSE:
       This function returns always an array with the founded multiple values

 CATEGORY:
       MATH

 CALLING SEQUENCE:
       Result=arr_equal(array,[/sort])

 INPUTS:
       array: the input array

 KEYWORD PARAMETERS:
       sort:   sorts the array

 OUTPUTS:
       This function returns an array with the equal values

 EXAMPLE:
       a=['1','2','2']
       print,arr_equal(a)
       2
       help,arr_equal(a)   STRING    = Array(1)



 MODIFICATION HISTORY:
 	Written by:	R.Bauer (ICG-1), June 20, 1997
   2000-Feb-18 help changed to call_help

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\arr_equal.pro)


ASC2NCDF

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

 PURPOSE:
   will translate ascii data with the icg-1 experimental header into netCDF Files

 CATEGORY:
   DATAFILES/FILTER


 CALLING SEQUENCE:
   asc2ncdf,inpath, outpath, filename, [data_sep=data_sep],[kritererium=kriterium],[inhalt=inhalt],[param_zeile=param_zeile]

 INPUTS:
	inpath:   Path where the data is
   outpath:  Path where the netCDF File will be saved
   filename: The filename of the ascii file which should be translated

 OPTIONAL INPUTS:
   data_sep: separator sign for the data
   kriterium: will give the posibility whith an input listfile
              to translate only logical parameters into netCDF
              kriterium='trans.fish.t'

 OPTIONAL OUTPUTS:
 inhalt:      the structure inhalt for the last parameter
 param_zeile: the whole Array field of the Ascii File

 PROCEDURE
 Examples of the two kinds of headers will be found at:
 http://ich313.ich.kfa-juelich.de/netcdf/icg1_header_datum.html
 and
 http://ich313.ich.kfa-juelich.de/netcdf/icg1_header_sekunden.html

 EXAMPLE:
  asc2ncdf,'/home1/icg105/data/','/home1/icg105/data/','test.dat'

 MODIFICATION HISTORY:
 	Written by:	R. Bauer , June, 13 , 1997
                       R.Bauer , Aug, 21 1997  data_sep added to choose column separator
                       R.Bauer,1997-9-16 debug added
 R.Bauer 1998-08-29 ncdf_ws mehtod changed to ncdf_w
   1999-Nov-06 help added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\asc2ncdf.pro)


ASCII2HTML

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

 PURPOSE:
   This functions creates html code for a given string array input

 CATEGORY:
   PROG_TOOLS/HTML

 CALLING SEQUENCE:
   Result = ASCII2HTML(string, [/SMALL] ,[/FIXED])

 INPUTS:
   string:   array

 KEYWORD PARAMETERS:
   SMALL:      use small fonts for table entries
   FIXED:      use fixed fonts for table entries

 OUTPUTS:
   String array

 EXAMPLE:
   see html_example.pro and html_example2.pro

 MODIFICATION HISTORY:
   Written by: Theo Brauers, 1998
   Modified T.B. Apr 2000 caption keyword

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\ascii2html.pro)


ASD_MEAN

[Previous Routine] [Next Routine] [List of Routines]
 usage:        asd_mean, tag,wvl,spec,sigma,view=view
 keyword input:
    tag        string used to match a certain subset of scan files listed
               an index file, 'asd_scan_list', which is read from the current
               working directory.

               Each record in 'asd_scan_list' consists of three fields
               separated by white space: the name of an asd scan file, 
               the utc time in hours, and the tag name, for example:

               spectrum.001   15.003 scan1
               spectrum.002   15.102 scan1
               spectrum.003   15.233 scan2
               spectrum.004   15.312 scan2

               setting tag to 'scan1' whould select spectrum.001 and
               spectrum.002, setting tag to ' ' or 'scan' would select
               all four files.  Since tag is compared to the whole record
               you can also select a single file by setting tag to a 
               particular file name or time.

    view       make a plot of the scan
               view=f makes an overplot with color=f*(!d.n_colors-1)

 output:
    wvl        wavelength values
    spec       averaged spectra
    sigma      standard deviation of spectral scans (same size as spec)

 example:
;;
 w8x11
 !p.multi=[0,2,2]
 asd_mean,tag='60_NE',wvl,s60ne
 asd_mean,tag='zenith',wvl,s0
 asd_mean,tag='60_SW',wvl,s60sw
 plot,wvl,s0
 oplot,wvl,s60ne
 oplot,wvl,s60sw

;; dont know tag name, use menu to find the one you want

 asd_mean,wvl,s00

;;

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\asd_mean.pro)


ASIND

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

 PURPOSE:
       Return the inverse sine of a value, in degrees rather then radians.

 CALLING SEQUENCE:
       deg = asind(x)

 INPUTS:
       value      sine of angle 

 OPTIONAL INPUTS:

 OUTPUTS:
       Angle in degrees returned.

 PROCEDURE

 COMMON BLOCKS:
       None.

 NOTES

 REFERENCES
 
 AUTHOR and DATE:
     Jeff Hicke     Earth Space Research Group, UCSB  12/07/93

 MODIFICATION HISTORY:

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\asind.pro_)


ASPECT

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

 PURPOSE:

  This function calculates and returns the normalized position
  coordinates necessary to put a plot with a specified aspect ratio
  into the currently active graphics window. It works on the display
  output window as well as in a PostScript output window.

 AUTHOR:

   FANNING SOFTWARE CONSULTING
   David Fanning, Ph.D.
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: davidf@dfanning.com
   Coyote's Guide to IDL Programming: http://www.dfanning.com/

 CATEGORY:

  Graphics

 CALLING SEQUENCE:

  position = ASPECT(aspectRatio)

 INPUTS:

  aspectRatio: A floating point value that is the desired aspect
     ratio (ratio of heigth to width) of the plot in the current
     graphics output window. If this parameter is missing, an aspect
     ratio of 1.0 (a square plot) is assumed.

 KEYWORD PARAMETERS:

  MARGIN:  The margin around the edges of the plot. The value must be
     a floating point value between 0.0 and 0.5. It is expressed in
     normalized coordinate units. The default margin is 0.15.

  WINDOWASPECT: The aspect ratio of the target window. If not provided,
     the value is obtained from the current graphics window.

 OUTPUTS:

  position: A four-element floating array of normalized coordinates.
     The order of the elements is [x0, y0, x1, y1], similar to the
     !P.POSITION system variable or the POSITION keyword on any IDL
     graphic command.

 EXAMPLE:

  To create a plot with an aspect ratio of 1:2 and a margin of
  0.10 around the edge of the output window, do this:

     plotPosition = ASPECT(0.5, Margin=0.10)
     PLOT, Findgen(11), POSITION=plotPosition

  Notice this can be done in a single IDL command, like this:

     PLOT, Findgen(11), POSITION=ASPECT(0.5, Margin=0.10)

 MODIFICATION HISTORY:

  Written by: David Fanning, November 1996.
       Added better error checking, 18 Feb 1997, DWF.
       Added WindowAspect keyword. 10 Feb 2000. DWF
       Added double precision tolerance for aspectRatio. 9 NOV 2001 BT

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\aspect.pro)


ASP_CORR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		ASP_CORR
 VERSION:
		4.0
 PURPOSE:
		Corrects the aspect ratio of a 2-dimensional shape, in order to make up
		for for different scaling in the x and y dimensions.
 CATEGORY:
		Array Manipulation /General Graphics.
 CALLING SEQUENCE:
		Result = ASP_CORR( SHAPE, REFERENCE = reflin)
 INPUTS:
	SHAPE
		(2,*) numeric array, mandatory.
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
	REFERENCE
		Defines the scaling procedure, according to the provided character
		value.  Accepts one of the following six values (only the first two
		characters matter):
			'XLO' :  Scale x, keeping lowest x-value constant.
			'XCEN':  Scale x, keeping center x-value constant.
			'XHI' :  Scale x, keeping highest x-value constant.
			'YLO' :  Scale y, keeping lowest y-value constant.
			'YCEN':  Scale y, keeping center y-value constant.
			'YHI' :  Scale y, keeping highest y-value constant.
 OUTPUTS:
		0 in case of failure (bad or missing shape or keyword value), otherwise
		the transformed shape is returned as a floating array (double if the
		input is of type double).
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		Three dimensional shapes aren't currently accepted.
 PROCEDURE:
		Uses calls to CAST, DEFAULT, SHAPE_VER and STRMATCH_MM from MIDL.  The
		scaling is done using the sizes of the plotting area in device
		coordinates, provided by the system variables !d.x_vsize and
		!d.y_vsize.  Therefore the scaling is always proper for the current
		output device.
 MODIFICATION HISTORY:
		Created 15-JUL-1991 by Mati Meron.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\asp_corr.pro)


AUTORANGE

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:    autorange

 PURPOSE:    given a range of values find a good tick mark interval
             and return a properly formatted tick label.  This routine
             can be used with the axis procedure to add additional
             axis which are not linearly related to the original 
             axis (see example)

 USEAGE:     autorange,range,ntick,tickv,tickl,ntickmax=ntickmax,$
                       cv=cv,log=log,colors=colors

 INPUT:      

   range     array of values

 keyword input

   ntickmax  maximum allowed number of tick marks (default=10)

   cv       if present and non-zero, the tick values will cover a bit
            less than the full range.  Otherwise tick values cover a
            bit more than the full range.  Set CV when you want exactly
            NTICK contour levels to appear on a contour plot.

 OUTPUT:

   ntick     number of tick marks
   tickv     array of tick values
   tickl     formatted tick labels   

 KEYWORD OUTPUT
   colors    vector of color values covering full color range and having
             one less element than ntick

; EXAMPLE:

   autorange,[.011,.022],ntick,tickv,tickl & print,tickl
   0.010 0.012 0.014 0.016 0.018 0.020

; plot solar spectrum with wavenumber on the lower x axis
; and wavelength on the upper x-axis
          
   solar,wn,f
   plot,wn,f,xstyle=5,xrange=[10000,40000],ymargin=[4,4]
   axis,xaxis=0,xstyle=1,xtitle='Wavenumber (cm-1)'
   autorange,1.e7/!x.crange,ntick,tickv,tickl 
   axis,xaxis=1,xticks=ntick-1,xtitle='Wavelength (nm)',$
               xtickv=1.e7/tickv,xtickname=tickl
          
          
 REVISIONS:

  author:  Paul Ricchiazzi                            mar94
           Institute for Computational Earth System Science
           University of California, Santa Barbara

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\autorange.pro)


AVERAGE

[Previous Routine] [Next Routine] [List of Routines]
 FUNCTION: This procedure computes the AVERAGE of a the nk 
           fields stored in the array tab (nbcol,nblign,nk).

 INPUTS  : tab  --> 3 dimensional array (nbcol x nblign x nk)

 OUTPUTS : moy  --> average of the fields (nbcol x nblign)
           stdv --> standard deviation (nbcol x nblign)
           nb   --> number of points used in the average

 USE     : vertaver, array1, array2, outaver,outstdc,outelmts

 CONTACT : Didier JOURDAN   didier@esrg.ucsb.edu

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\average.pro)


AXGAP

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:  axgap,pos

 PURPOSE:  draw a "gap symbol" to indicate a gap in the axis number scale.

 USEAGE:   axgap,pos

 INPUT:    
   pos     two element vector indicating x,y data coordinates of the
           axis break

 KEYWORD INPUT:
   one     gap symbol drawn on one axis only

   size    size of gap symbol (default = 1, which corresponds to size
           of default minor tick marks)

   skew    control skewness of gap symbol (default 0)

   gap     controls gap size (default 1)

 OUTPUT:
   none

 DISCUSSION:
   

 LIMITATIONS:

 COMMON BLOCKS:

 SIDE EFFECTS:
  
 EXAMPLE: 

   y=smooth(randomn(iseed,100),5)
   plot,y,xticks=5,xtickn=['1','2','3','4','5','20']
   axgap

 AUTHOR:   Paul Ricchiazzi                        31 Aug 95
           Institute for Computational Earth System Science
           University of California, Santa Barbara
           paul@icess.ucsb.edu

 REVISIONS:

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\axgap.pro)


AXIS_2C

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

 PURPOSE:
	This procedure plots an axis and its title in different colors

 CATEGORY:
	PLOT

 CALLING SEQUENCE:
	axis_2c [[[, x], y], z]

 OPTIONAL INPUTS:
	x, y, z: Scalars giving the starting coordinates of the new axis.
		For details see the IDL AXIS routine.

 KEYWORD PARAMETERS:
	AXIS_TITLE = axis_title: Title of the axis
	COLOR = color: Color of the axis.
	TCOLOR = tcolor: Color of the title.

	Any other keyword parameters which are accepted by the IDL AXIS procedure.

 EXAMPLE:
	def_color_sysv
	PLOT, EXP(FINDGEN(10)), /YLOG
	axis_2c, YAXIS = 0, TCOLOR = !F.red, AXIS_TITLE = 'Y title'
	axis_2c, XAXIS = 0, TCOLOR = !F.green, AXIS_TITLE = 'X title'

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 27.10.1999

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\axis_2c.pro)


AXLABEL

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

 PURPOSE:
        Put previously calculated axis labels onto the screen
        at proper position. This routine was designed to work 
        together with LOGLEVELS to produce fancy log plots.
        It involves several coordinate transformations in order
        to be device independent and take into account the 
        character size. The user can specify a label format
        and use 'external' formatting functions similar to
        the [XYZ]TICKFORMAT keyword of PLOT.

 CATEGORY:
        General Graphics

 CALLING SEQUENCE:
        AXLABEL,Value [,/XAxis] [,keywords]

 INPUTS:
        VALUE -> A vector with the values to be labelled on the 
             axis.

 KEYWORD PARAMETERS:
        /XAxis -> If set, the labels are placed on the X achis
             rather than on the Y axis

        /YAxis -> Place the labels on the Y axis (this is the default,
             and this keyword is there for purely aesthetic reasons)

        CHARSIZE -> The character size of the label

        FORMAT -> An IDL format string (used as argument to the
              STRING function) or the name of a function that returns
              formatted labels. This function must accept three
              arguments, the third of which is the current value
              (see the online help to [XYZ]TICKFORMAT for more details).
              AXLABEL always passes 0 to the first two arguments.

        _EXTRA  keywords are passed on to XYOUTS (e.g. COLOR or
              ORIENTATION). Note that the ALIGN keyword value is 
              determined automatically.

 OUTPUTS:
        Axis labels without fuss.

 SUBROUTINES:
        None.

 REQUIREMENTS:
        A DATA coordinate system must be established by a previous
        PLOT command.

 NOTES:
        AXLABEL currently operates only on the left and bottom axes.

 EXAMPLE:
          xrange = [0.3,3.0]   ; define axis range
          yrange = [0.3,3.0]
          plot,[1],xr=xrange,yr=yrange, $   ; do the plot
          	title='Logarithmic X axis, Logarithmic Y axis',$
          	xtickf='(a1)',ytickf='(a1)', /ylog,/xlog
          ; important: turn the tick labeling off with ?tickformat='(A1)'
          xlblv = loglevels(xrange)   ; get nice label values (0.5, 1., 2.)
          ylblv = loglevels(yrange)
          axlabel,xlblv, /xaxis       ; plot the labels
          axlabel,ylblv, /yaxis

 MODIFICATION HISTORY:
        mgs, 10 Sep 1999: VERSION 1.00
        mgs, 23 Sep 1999: - bug fix for log-log plots
        mgs, 23 Aug 2000: - changed copyright to open source

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\axlabel.pro)


AXVAL

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       AXVAL
 PURPOSE:
       Find nice axis values.
 CATEGORY:
 CALLING SEQUENCE:
       v = axval(x1,x2,n)
 INPUTS:
       x1 = Range minimum.                           in
       x2 = Range maximum.                           in
       n = Suggested number of divisions (def=5).    in
 KEYWORD PARAMETERS:
 OUTPUTS:
       v = array of labeled tick positions.          out
 COMMON BLOCKS:
 NOTES:
       Notes: Useful when exact axis and number of ticks
         are both specified.  For this case IDL forces
         labeled ticks to start and end at the axis ends,
         which in general gives poor tick spacing.
 MODIFICATION HISTORY:
       R. Sterner, 1994 Feb 8

 Copyright (C) 1994, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\axval.pro)


AZIMUTH

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:          azimuth

 PURPOSE:          given a smoothly varying 2d field, AZIMUTH
                   computes the angle between the gradient direction
                   of the field and the y direction (angle measured
                   clockwise).  This is is useful for computing the
                   satellite or solar azimuth angle when all you know
                   are the satellite or solar zenith angles.  For
                   example the relative azimuth at each point in a
                   satellite image is given by

                    relaz=abs(azimuth(satzen,1,1)-azimuth(-sunzen,1,1))

                   which is the angle between the satellite unit
                   vector and the solar ray vector, both projected
                   onto the surface.

 CALLING SEQUENCE:
                   result=azimuth(image,dx,dy)
 INPUT:
    image          smoothly varying image quantity (e.g., solar zenith angle)
    dx             pixel spacing, x direction
    dy             pixel spacing, y direction

 OUTPUT:
    result         angle between grad(image) and downward direction
                   (angle increases clockwise) 
 
 LIMITATION:       the image is fit by a quadratic function of x and y
                   which is analytically differentiated to find the
                   gradient directions.  An image which is not well
                   approximated by a quadratic function may produce
                   weird results.


 EXAMPLE:
   f=cmplxgen(400,400,/center)
   tvim,f,/scale
   f=abs(f)^2      ; should be perfectly fit by a quadratic function
   a=azimuth(f,1,1)
   loadct,5
   tvim,a,scale=2,range=[-180,180,45]

  author:  Paul Ricchiazzi                            apr94
           Institute for Computational Earth System Science
           University of California, Santa Barbara


(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\azimuth.pro)


A_AND_B

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

 PURPOSE:
	This function applies the boolean AND operator to two vectors.
	It returns a vector with those elements which occur in both vectors.

 CATEGORY:
	MATH

 CALLING SEQUENCE:
	Result = a_and_b(vec1, vec2)

 INPUTS:
	vec1, vec2: The two vectors to which the AND operation should be applied.

 KEYWORD PARAMETERS:
	/NO_SORT: If set the returned vector is not sorted. However, in that case
		multiple instances of single elements in the shorter of the two input
		vectors will show up in the output vector.

 OUTPUTS:
	This function returns a vector with those elements which occur in both input vectors.
	In the case of an empty output vector, -1 is returned. The elements are sorted in
	increasing order.

 RESTRICTIONS:
	Repeated elements in the input vectors are returned only once in the output vector
	(see example).

 EXAMPLE:
	A = [1, 2, 2, 2, 3, 4, 13, 6, 7, 8, 9, 14, 20]
	B = [0, 2, 2, 4, 6, 10, 12, 13]
	C = a_and_b(A, B) = [2, 4, 6, 13]

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 02.12.97
	History:	29.10.98:	FOR i = 0, ... changed to FOR i = 0L, ...
								debug statement removed
	25.02.2000:	New keyword parameter /NO_SORT

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\a_and_b.pro)


A_NOT_B

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

 PURPOSE:
	This function applies the negation of the boolean AND operator to two vectors.
	It returns a vector with those elements which occur in the first but not in the second vector.

 CATEGORY:
	MATH

 CALLING SEQUENCE:
	Result = a_not_b(vec1, vec2)

 INPUTS:
	vec1, vec2: The two vectors to which the negation of the AND operation should be applied.

 OUTPUTS:
	It returns a vector with those elements which occur in the first but not in the second vector.
	In the case of an empty output vector, -1 is returned.

 RESTRICTIONS:
	Repeated elements in the input vectors are returned only once in the output vector
	(see example).

 EXAMPLE:
	A = [1, 2, 2, 2, 3, 4, 13, 6, 7, 8, 9, 14, 20]
	B = [0, 2, 2, 4, 6, 10, 12, 13]
	C = a_not_b(A, B) = [1, 3, 7, 8, 9, 14, 20]

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 02.12.97
	History:	29.10.98:	FOR i = 0, ... changed to FOR i = 0L, ...
								debug statement removed

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\a_not_b.pro)


A_OR_B

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

 PURPOSE:
	This function applies the boolean OR operator to two vectors.
	It returns a vector with those elements which occur in one or the other vector.

 CATEGORY:
	MATH

 CALLING SEQUENCE:
	Result = a_or_b(vec1, vec2)

 INPUTS:
	vec1, vec2: The two vectors to which the OR operation should be applied.

 OUTPUTS:
	It returns a vector with those elements which occur in one or the other vector.
	In the case of an empty output vector, -1 is returned.

 RESTRICTIONS:
	Repeated elements in the input vectors are returned only once in the output vector
	(see example).

 EXAMPLE:
	A = [1, 2, 2, 2, 3, 4, 13, 6, 7, 8, 9, 14, 20]
	B = [0, 2, 2, 4, 6, 10, 12, 13]
	C = a_or_b(A, B) = [0, 1, 2, 3, 2, 6, 7, 8, 9, 10, 12, 13, 14, 20]

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 02.12.97
	History:	29.10.98:	debug statement removed

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\a_or_b.pro)


A_XOR_B

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

 PURPOSE:
	This function applies the boolean XOR operator to two vectors.
	It returns a vector with those elements which occur in one or the other vector
	but not in both.

 CATEGORY:
	MATH

 CALLING SEQUENCE:
	Result = a_xor_b(vec1, vec2)

 INPUTS:
	vec1, vec2: The two vectors to which the XOR operation should be applied.

 OUTPUTS:
	It returns a vector with those elements which occur in one or the other vector
	but not in both.
	In the case of an empty output vector, -1 is returned.

 RESTRICTIONS:
	Repeated elements in the input vectors are returned only once in the output vector
	(see example).

 EXAMPLE:
	A = [1, 2, 2, 2, 3, 4, 13, 6, 7, 8, 9, 14, 20]
	B = [0, 2, 2, 4, 6, 10, 12, 13]
	C = a_xor_b(A, B) = [0, 1, 3, 7, 8, 9, 10, 12, 14, 20]

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 02.12.97
	History:	29.10.98:	debug statement removed

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\a_xor_b.pro)


BALLOON_DRAG

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:   balloon_drag 

 PURPOSE:   compute drag on shere

 USEAGE:    result=balloon_drag(r,rho,v,cd)

 KEYWORD INPUT:    
   r        balloon radius in meters      (default=1.0 m)
   v        wind velocity (mph)           (default=5 m/s)
   rho      air density                   (default=1.29 kg/m3)
   cd       drag coefficient              (default=0.2)

 NOTE:      1 m/s = 3.60 km/hr = 2.23 mph = 1.94 knots

 OUTPUT:   
 
 result     drag force in newtons 

            
 SOURCE:    Steve Robinson
            NASA/MIT
            stever@space.mit.edu

            Drag on sphere = .5 * Cd * rho * v^2 * pi * r^2

            Cd = function of sphere Reynolds number 
                 (V*2*r)/(kinematic viscosity),
                 but 0.2 should be close.
            
 EXAMPLE:
            r=1. & v=10. & cd=.2
            rho=rhoz(p0=1013.,t0=273.,z=1.,lr=7.)
            print,balloon_drag(r,rho,v,cd)
            
  author:  Paul Ricchiazzi                            jan94
           Institute for Computational Earth System Science
           University of California, Santa Barbara

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\balloon_drag.pro)


BALLOON_LIFT

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:   balloon_lift 

 PURPOSE:   compute and print lifting capacity of a helium balloon in kg

 USEAGE:    balloon_lift,r=r,volume=volume,alt=alt,pres=pres,temp=temp,lr=lr

 KEYWORD INPUT:    
   r        balloon radius in meters              (default=1.0 m)
   volume   ignor r and use this value for volume (default=4.18 m3)
   alt      altitude in km                        (default=1 km)
   pres     pressure in mb                        (default=1013 mb)
   temp     surface temperature in K              (default=273 K)
   brho     balloon mass density (kg/m2)          (default=0.35 kg/m2)
   bwt      balloon weight (kg)                   (default=10 kg)
   trho     tether mass density (kg/km)           (default=6.25 kg/km, dacron)
   kevlar   if set use kevlar tether at 2.1kg/kg

            rubberized polyvinyl 0.35 kg/m2
            for dacron, 2.4 mm diam, trho=6.25kg/km, 260 lb pull
            for kevlar, 1.5 mm diam, trho=2.1kg/km,  750 lb pull

   english  if set all the above inputs are
            in units of feet or pounds (pounds/sq in for pressure)

 EXAMPLE:   lifting capacity of a 1 m radius helium balloon at an 
            altitude of 1 km. 
      
            rho=rhoz(p0=1013.,t0=273.,z=1.,lr=7.)
            print,balloon_lift(1.,rho)

 EXAMPLE:   lifting capacity of a non-stretching 1 m radius helium
            balloon at an altitude of 1 km.  To prevent the balloon
            from bursting at high altitude the balloon should not be
            filled to full capacity with helium at sealevel. Assume
            the helium retains its sealevel temperature (maybe less
            than ambient).

 balloon_lift,r=1,alt=1

  author:  Paul Ricchiazzi                            jan94
           Institute for Computational Earth System Science
           University of California, Santa Barbara

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\balloon_lift.pro)


BARGRAPH

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

 PURPOSE:
        Creates a bar graph from a vector of data points

 CATEGORY:
        2D Graphics

 CALLING SEQUENCE:
        BARGRAPH, DATA, BASELINE [,keywords]

 INPUTS
        DATA -> Vector of data points to be plotted as a bargraph
 
        BASELINE -> Vector of points to be used as a baseline for DATA
             (i.e. Y(I) = DATA(I) + BASELINE(I)).  If BASELINE
             is not specified, its default value will be an
             array of zeroes.

 KEYWORD PARAMETERS:
        OVERPLOT -> /OVERPLOT will not cause the current plot window
             to be erased.  This is useful for producing
             stacked bar plots with successive calls to BARGRAPH.
 
        BARWIDTH -> The width of the bars.  If BARWIDTH is not
            specified, its default value will be 1.0.

        BARCOLOR -> a value or an array containing the colorindex for
            all boxes or each box, respectively. If a single value
            is given, *all* boxes will have this color. If an array 
            is passed that has less elements than there are groups to 
            plot, the remaining colors will be filled with 15 (grey 
            in MYCT standard-scheme).  

        BARLABELS -> A string array of labels to be plotted above each
            bar.  If BARLEVELS may be originally set equal to the
            DATA vector, and it will be converted to the string 
            representation of DATA, using the FORMAT statement 
            contained in L_FORMAT.

        COLOR -> Color index for the plot axes and labels.  Default
            is 1 (which is BLACK for a MYCT color table).

        L_FORMAT -> The FORMAT statement used to convert BARLABELS
            from a numeric array to a string array.

        NO_LABELS -> /NO_LABELS will suppress printing the labels
            contained in the BARLABELS atop each bar.  This is
            useful for producing stacked bar plots.

        XLABELS -> X-axis labels corresponding to each bar.

        YRANGE -> YRANGE keyword for the PLOT command.  If YRANGE is
            not specified then YRANGE will be computed based on the 
            maximum value of the DATA array.  For stacked plots, it 
            is useful to compute YRANGE in the calling program and 
            pass it to BARGRAPH.

        _EXTRA=e -> Passes extra keywords to plot

 OUTPUTS:
        None

 SUBROUTINES:
        None
        
 REQUIREMENTS:
        None

 NOTES:
        (1) This routine has been modified to be more general and 
            more robust than the original version in the IDL 5.0 User's
            Guide (p. 170).

        (2) IDL 5.x array notation [] is now used.

 EXAMPLE:
        (1) Create a simple bar graph with bars of 3 different colors,
            using a baseline of zero.

        BARGRAPH, Data=[1,2,3], BarWidth=1.0, BarColor=[10,11,12]
           XLabels=['Bart', 'Lisa', 'Maggie']

        (2) Use successive calls to BARGRAPH to create a "stacked" bar
            graph with two different data vectors.  The first vector is
            used as the baseline for the second.  The BARLABELS array
            is created from the actual data values.

        Data   = [2,3.5,6,7,2,1]
        Data2  = 0.0*DATA + 2

        BARGRAPH, Data, Xlabels=['A','B','C','D','E','F'], 
        XStyle=1, BarWidth=0.8

        BARGRAPH, Data2, Data, BarWidth=0.8 ,/OverPlot, $
           BarColor=2, BarLabels=Data+Data2, L_Format='(F8.2)'             

 MODIFICATION HISTORY:
        bmy, 18 Nov 1997: VERSION 1.00
        bmy, 19 Nov 1997: VERSION 1.01
        bmy, 29 Apr 1999: VERSION 1.10
                          - added COLOR keyword
                          - eliminated help screen 
                          - enhanced readability & updated comments

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\bargraph.pro)


BARPLOT

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:  barplot

 PURPOSE:  produce a bar plot

 USEAGE:   barplot

 INPUT:  
   y       bar values fltarr(n)  

 KEYWORD INPUT:
   nbar    number of barplot overlays. Should only be set on the first
           call to BARPLOT

   over    if set, overplot new bar values.  

   dx      width of a bar (default=1).  An individual bar is sized to
           fill a fraction .5*DX/nn of the total plot width, where nn
           is the number of elements in y. Setting DX=2 eliminates
           blank space between adjacent bars.

   xinc    How far to move overplot bars to the left or right of the
           previous bar position (in units of the bar width).  Use
           with NBAR and XOFF to control degree to which overplot
           bars overlap previous bars. A positive value causes latter
           overplots to overlap bars starting from the left and
           finishing on the right. A negative value does the
           opposite.  (default = 0.6666)

   xoff    offset of bar with respect to labeled points on x-axis
           (default=0).  XOFF should be in the argument list and assigned
           to a named variable if NBAR, DX and XINC are used to control 
           bar overlap in multiplots.

           The xaxis labels are located at data coordinates 
           xlab=findgen(nn)+.5, where nn =n_elements(y)

   color   color index used to fill bars

   xtitle  string, x title of plot

   ytitle  string, y title of plot

   title   string, title of plot

   xlabels vector of strings used to label bar groups 

   xlabvec vector of x values at which to put XLABELS.
           if XLABVEC is not set, XLABELS are ploted at points
           .5+findgen(n_elements(xlabels))
           range of XLABVEC 0-1

   grid    if set, draw a y axis grid.  The numerical value of grid 
           is used to set the grid style (1=dotted line)

   yrange  a two element vector specifying the y axis range

   ynozero if set, y range may not include zero if all y values are
           are positive.

   xmargin two element vector specifies left and right margin around plot
           frame in units of character width.  (default = !x.margin)

   ymargin two element vector specifies bottom and top margin around plot
           frame in units of character height.  (default = !y.margin)


 OUTPUT:


 DISCUSSION:
   For best results try to arrange the order of overplots so that larger
   values of y are ploted first. See examples.

 LIMITATIONS:

 COMMON BLOCKS:

 SIDE EFFECTS:
  
 EXAMPLE:  

  loadct,5
  y=randomu(iseed,6)
  color=[.8,.6,.3]*!d.n_colors
  dx=.6
  barplot,y,dx=dx,xlabels=1990+indgen(6),title='test',xtitle='Year',$
      ytitle='power (Watts)',color=color(0),/grid,xoff=xoff,nbar=3
  barplot,y^2,dx=dx,color=color(1),/over,xoff=xoff
  barplot,y^3,dx=dx,color=color(2),/over,xoff=xoff

; A fancier example

  y=randomu(iseed,5) & y=y(sort(y))
  xlabels=['January','February','March','April','May']
  color=[.2,.4,.6,.8]*!d.n_colors
  dx=.32
  barplot,y,dx=dx,xtitle='---- Month ----',$
        ytitle='power (Watts)',color=color(3),yrange=[0,1.],ymargin=[5,7],$
        /grid,xlabels=xlabels,charsize=1.5 ,xoff=xoff,nbar=4
  barplot,y^2,dx=dx,color=color(2),/over,   xoff=xoff
  barplot,y^3,dx=dx,color=color(1),/over,   xoff=xoff
  barplot,y^4,dx=dx,color=color(0),/over,   xoff=xoff
  x_axis,findgen(5)+.5,1.,xtickn=(y+y^2+y^3+y^4)/4,yspace=-1.5,$
         xtitle='----- Cumulative Average -----'
  x_axis,findgen(5)+.5,[1,4],xtitle='Plot Title',yspace=-.5,charsize=1.2,/ext
  legend,'.cSensor\\AVHRR 1\AVHRR 2\GTR-200\PSP',color=color,$
          /clrbox,bg=0,/box,pos=[0.06,0.57,0.23,0.98]

; use with histogram to make nicer histogram plots

  y=randomn(iseed,2000)
  yy=histogram(y,binsize=.5,min=-3)
  yy=yy(0:11)
  xlabel=string(f='(f3.0)',findrng(-3,3,12))
  ;plot,findrng(-3,3,12),yy,/xsty,psym=10  ; compare to this
  barplot,yy,dx=2,color=20,xlabel=['-3','-2','-1','0','1','2','3']
  
 AUTHOR:   Paul Ricchiazzi                        31 Aug 95
           Institute for Computational Earth System Science
           University of California, Santa Barbara
           paul@icess.ucsb.edu

 REVISIONS:

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\barplot.pro)


BASECON

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       BASECON
 PURPOSE:
       Convert a number from one base to another.
 CATEGORY:
 CALLING SEQUENCE:
       out = basecon(in)
 INPUTS:
       in = input number as a text string.         in
 KEYWORD PARAMETERS:
       Keywords:
         FROM=n1    Original number base (def=10).
           From 2 to 36.
         TO=n2      Resulting number base (def=10).
           From 2 to 36.
         DIGITS=n   Minimum number of digits in output.
           If result has fewer then 0s are placed on left.
         GROUP=g    Number of digits to group together (def=all).
           Spaces will be placed between groups.  Useful for
           showing bytes or words for example.
         ERROR=err  error flag:
           0 = ok
           1 = input digit not 0-9 or A-Z.
           2 = FROM base not in the range 2-36.
           3 = TO base not in the range 2-36.
           4 = input digit too big for FROM base.
           5 = input number too big to handle.
 OUTPUTS:
       out = converted number as a text string.    out
         If an error occurs a null string is returned.
 COMMON BLOCKS:
 NOTES:
       Notes: maximum number base is 36.  Example:
         out = basecon('1010',from=2,to=16) gives out='A'.
         May give an array of input values.
 MODIFICATION HISTORY:
       R. Sterner, 5 Mar, 1993
       R. Sterner, 30 Sep, 1993 --- Added DIGITS keyword.
       R. Sterner, 1999 Jun 3 --- Added GROUP keyword.

 Copyright (C) 1993, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\basecon.pro)


BC

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

 PURPOSE:
        wall to wall cross hairs to help read numbers off of plot
        axis. The graphics function is set to 6 for eXclusive OR.
        This allows the cross hairs to be drawn and erased without
        disturbing the contents of the window.  Hit RMB to exit

 CALLING SEQUENCE:
        bc

 INPUTS/OUTPUTS: none

 RESTRICTIONS:
        Works only with window system drivers.

 CATEGORY:
        Interactive graphics.


 author   Paul Ricchiazzi      April, 1993

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\bc.pro)


BELL

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       BELL
 PURPOSE:
       Ring terminal bell.
 CATEGORY:
 CALLING SEQUENCE:
       bell, [n]
 INPUTS:
       n = number of rings (def=1).  in
 KEYWORD PARAMETERS:
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 20 Oct, 1989.

 Copyright (C) 1989, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\bell.pro)


BESELK_MM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		BESELK_MM
 VERSION:
		4.0
 PURPOSE:
		Calculates an approximation to Bessel K functions or their integrals.
 CATEGORY:
		Mathemetical Function (General).
 CALLING SEQUENCE:
		Result = BESELK_MM (X, NI [, /INTEGRAL ])
 INPUTS:
	X
		Numerical, otherwise arbitrary.
	NI
		Scalar, the order of the function.
 OPTIONAL INPUT PARAMETERS:
	EPS
		Allowed relative error.  Default is machine precision.
 KEYWORD PARAMETERS:
	/INTEGRAL
		Switch, if set the integral of the K function from X to infinity is
		calculated.
 OUTPUTS:
		Returns the value(s) of K_ni(X) or, if INTEGRAL is set, of the integral
		of K_ni(t) from X to infinity.
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		None.
 PROCEDURE:
		Uses the Kostroun approximation, see NIM 172, 371-374 (1980).
		Calls CAST, DEFAULT, FPU_FIX, ISNUM and TOLER from MIDL.
 MODIFICATION HISTORY:
		Created 1-MARCH-1993 by Mati Meron as BESELK.
		Modified 15-SEP-1998 by Mati Meron.  Underflow filtering added.
		Renamed 25-SEP-1999 by Mati Meron, to BESELK_MM.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\beselk_mm.pro)


BEST_FFT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       BEST_FFT
 PURPOSE:
       Attempts to find size of fastest FFT from given choices.
 CATEGORY:
 CALLING SEQUENCE:
       m = best_fft(n)
 INPUTS:
       n = proposed FFT size.                         in
 KEYWORD PARAMETERS:
       Keywords:
         DELTA=d  The range to search in samples or percent.
           Default = +/-1.
         /PERCENT means DELTA is in percent of n.
         /DOWN  Search from n down to n-DELTA.
 OUTPUTS:
       m = Predicted fastest FFT size within range.   out
 COMMON BLOCKS:
 NOTES:
       Notes: the selection is made based on the prime factors
         of the possible values.  The largest prime factor of
         each candidate is determined and the value with the
         smallest max prime factor is considered the best to use.
         For multiple matches the one with the smallest sum
         of the prime factors is selected.
 MODIFICATION HISTORY:
       R. Sterner, 8 Feb, 1993

 Copyright (C) 1993, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\best_fft.pro)


BINARY (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   binary (function)
 PURPOSE:
   This function returns the binary representation
   of a number. Numbers are converted to LONG integers
   if necessary.
 CATEGORY:
   General Programming
 EXAMPLE:
   Binary representation of 11B:
     IDL> print, binary(11B)                                           
     0 0 0 0 1 0 1 1
   If data extraction is used instead of conversion ->
   Binary representation of pi (little endian IEEE representation):
     IDL> print, format='(z9.8,5x,4(1x,8a1))', long(!pi,0), binary(!pi)
     40490fdb      01000000 01001001 00001111 11011011
 AUTHOR:
      Kevin Ivory                           Tel: +49 5556 979 434
      Max-Planck-Institut fuer Aeronomie    Fax: +49 5556 979 240
      Max-Planck-Str. 2                     mailto:Kevin.Ivory@linmpi.mpg.de
      D-37191 Katlenburg-Lindau, GERMANY

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\binary.pro)


BINBOUND

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       BINBOUND
 PURPOSE:
       For binary image return array with boundary points set to 1.
 CATEGORY:
 CALLING SEQUENCE:
       b = binbound(bin_image)
 INPUTS:
       bin_image = byte binary image (only 0 or 1).   in
 KEYWORD PARAMETERS:
 OUTPUTS:
       b = array with boundary points set to 1.       out
 COMMON BLOCKS:
 NOTES:
       Notes: The boundary of a binary image is the set of points
         in the image that are 1 and also touch a 0.
         A binary image may be made using logical operators.
         For example, if an image has both positive and negative
         values the boundary between them may be found as
         b = binbound(img gt 0). To put this boundary into
         another image, A, do:
         w = where(b eq 1) & a(w) = 255.
 MODIFICATION HISTORY:
       R. Sterner.  24 June, 1987.
       R. Sterner, 4 Dec, 1989 --- Converted to Sun.
	R. Sterner, 21 Nov, 1991 --- removed a multiply.
       Johns Hopkins University Applied Physics Laboratory.

 Copyright (C) 1987, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\binbound.pro)


BIN_DATA

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

 PURPOSE:
		This function returns the density function (histogram) of an array
		together with the lower bound values of the single bins.

 CATEGORY:
		MATH

 CALLING SEQUENCE:
		Result = bin_data(Array)

 INPUTS:
		Array:  Data for which the density function will be calculated.

 OPTIONAL INPUTS:
		B_WIDTH = bw:	Set the bin width of the density function. (Default = 1)
		B_MIN = bmin:	Set the lower bound of the first bin. (Default = MIN(array))
		B_MAX = bmax:	Maximum value to consider. (Default = MAX(array))

		see also IDL HISTOGRAM Function

 KEYWORD PARAMETERS:
		/PLOT:	Set this keyword to display a plot of the histogram.

 OUTPUTS:
		The return value of this funktion is a structure of arrays where the
		array dimension n is equal to the number of bins in the density function:
		result.bin	: 		Array with lower bound values of the single bins.
		result.freq	:		Array with frequency of occurrence.
		result.bin_width:	Bin width used to calculate the frequency distribution (scalar).
		In the case that B_MIN > MAX(array) the number -1 is returned.

 OPTIONAL OUTPUTS:
		REV_INDEX = ri:	Set this keyword to a named variable to return the
			reverse index vector of the density function.
		ERROR = err:		Set this keyword to a named variable to return the
			error status of the routine (err = 0: no error; otherwise: err = 1).

 EXAMPLE:
		A = [0.5, 1.5, 1.6, 2.0, 2.3, 2.5, 2.7, 2.9, 3.2, 5.1, 5.6, 5.7, 6.0]
		Result = bin_data(A, B_WIDTH = 2.0, B_MIN = 0.0, /PLOT)

		- The histogram should be plotted

		- HELP, result, /STR
			** Structure <5a844c8>, 3 tags, length=36, refs=1:
			   BIN             FLOAT     Array[4]
			   FREQ            LONG      Array[4]
			   BIN_WIDTH       FLOAT           2.00000

		- PRINT, Result.bin :
		     0.000000      2.00000      4.00000      6.00000		- lower bound of bins
		- PRINT, Result.freq :
    		         3            6            3            1		- frequency of occurrence

 MODIFICATION HISTORY:
		Written by:	F. Holland (ICG-3), 22.09.97.
		Revised: 	F. Holland, 01.06.99.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\bin_data.pro)


BIN_STAT

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

 PURPOSE:
		This function returns the statistics of a binned data set where the
		partitition of the data set into the different bins is determined by the
		reverse index vector of a preceding call to the IDL HISTOGRAM function.

 CATEGORY:
		MATH

 CALLING SEQUENCE:
       Result = BIN_STAT(Array, Riv, Nobs)

 INPUTS:
		Array:  Data for which the statistical parameters should be calculated.
		Riv:	Reverse Index Vektor from the Functions BIN_DATA or HISTOGRAM
		Nobs:	Number of bins which correspond to the Riv.

 OUTPUTS:
		The return value of this funktion is a structure of arrays where the
		array dimension n is equal to the number of bins in the density function.
		For each bin the statistical parameters mean, stdev, sterr, n, and
		median are returned (tag names: mean, stdev, sterr, n, median).
		If a quantity is not defined (e.g. stdev for only one point in the bin),
		the value !VALUES.F_NAN is returned.

 EXAMPLE:
		A = [0.5, 1.3, 1.5, 1.6, 2.0, 2.5, 2.9, 3.2, 5.1, 5.6, 5.7, 6.0]
		B = [3.1, 2.0, 4.1, 8.2, 1.0, 0.0, 2.2, 5.3, 5.5, 0.7, 7.8, 5.1]
		Result = bin_data(A, B_WIDTH = 2.0, B_MIN = 0.0, REV_INDEX = Riv)
		nobs = N_ELEMENTS(Result.bin(*))
		stat = bin_stat(B, Riv, Nobs)

		HELP, stat, /STR
		** Structure <1855a28>, 7 tags, length=112, refs=1:
			MEAN            FLOAT     Array[4]
			STDEV           FLOAT     Array[4]
			STERR           FLOAT     Array[4]
			N               LONG      Array[4]
			MEDIAN          FLOAT     Array[4]
			MIN             FLOAT     Array[4]
			MAX             FLOAT     Array[4]

		PRINT, stat.mean
			4.35000      2.12500      4.66667      5.10000
		PRINT, stat.stdev
			2.70617      2.29982      3.62261          NAN
		PRINT, stat.n
			4            4            3            1
		PRINT, stat.min
			2.00000      0.000000     0.700000     5.10000

 MODIFICATION HISTORY:
		Written: F. Holland (ICG-3), 22.09.97.
		Revised: F. Holland (ICG-3), 01.06.99.
		14.06.1999:	Function returns now also min and max of dataset.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\bin_stat.pro)


BLEND

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       BLEND
 PURPOSE:
       Sets up weighting array for blending arrays together.
 CATEGORY:
 CALLING SEQUENCE:
       WT = BLEND(N,I1,I2)
 INPUTS:
       N = size of array to make.				  in
       I1, I2 = indices of first and last values to blend.   in
 KEYWORD PARAMETERS:
 OUTPUTS:
       WT = weighting array.                                 out
          WT(0:I1) = 0
          WT(I1:I2) = cosine shaped weighting from 0 to 1.
          WT(I2:*) = 1
 COMMON BLOCKS:
 NOTES:
       Notes: to blend arrays A and B: A*(1-WT) + B*WT
         starts with pure A and ends with pure B.
 MODIFICATION HISTORY:
       Written by R. Sterner  6 Jan, 1986.
       Johns Hopkins University Applied Physics Laboratory.

 Copyright (C) 1986, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\blend.pro)


BMP_DEFINITIONS

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

 PURPOSE:
  This function returns the widget_button symbol array

 CATEGORY:
   PLOT

 CALLING SEQUENCE:
   Result=bmp_definitions(name)

 EXAMPLE:
   result=bmp_definitions('play')


 MODIFICATION HISTORY:
   Written by: R.Bauer (ICG-1), 1999, June 11

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\bmp_definitions.pro)


BOOTSTRAP_MPFITFUN

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

 PURPOSE:
   This function does a bootstrap simulation of a (non-linear) fit of
   a given function to a set of data using the mpfitfun function
   (MPFIT, MPFITFUN were provided by Craig Markwardt)

 CATEGORY:
   MATH

 CALLING SEQUENCE:
   Result = BOOTSTRAP_MPFITFUN(MYFUNCT, X, Y, ERR, start_params, ...)

 INPUTS:

   (text copied from from mpfitfun)
   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.  It should be declared in
             the following way:

             FUNCTION MYFUNCT, X, parms, dparms
               ; X are the independent variable values
               ; parms are the parameter values
               ; dparms - analytical derivative matrix - NOT REQUIRED
               YMOD   = ...
               IF N_PARAMS() EQ 3 THEN $
                 DPARMS = ...  ;; compute derivatives - NOT REQUIRED
               RETURN, YMOD
             END

             The returned array YMOD should be of the same size and
             dimensions as the "measured" Y values.

             See the discussion of AUTODERIVATIVE and MYFUNCT in
             MPFIT.PRO if you wish to compute your derivatives for
             yourself.  AUTODERIVATIVE is accepted by MPFITFUN and
             passed directly to MPFIT.

   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.

 OUTPUTS:

   Returns a structure array containing the best-fit parameters of
   each bootstrap replication.


 KEYWORD PARAMETERS:

   all input keyword parameters of MPFITFUN are parsed via _EXTRA

   NBOOTSTRAP: number of bootstrap replications (def =10)
   VERBOSE:    if set a message is printed before any call of mpfit
   KEEP_INITIAL:   start every new call of mpfit with the same set
                   of starting values (def: use the result of the
                   last fit, which is normally faster)

 DESCRIPTION:

   The description of MPFITFUN is given in the header of these functions.
   Basically BOOTSTRAP_MPFITFUN repeatatively calls MPFITFUN using a
   bootstrap resanpled input data set and fit a user-supplied model to
   easch set of the user-supplied data.

   The idea of bootstrap is to evaluate errors of the estimated parameters
   when the erros of y are not know precisely or when the model  which
   is fitted does not represent a full description of the dependence
   of y on x. A discussion of bootstrap estimates is givern in the
   references (see below)

 EXAMPLE:

   (text modified from from mpfitfun)

   FUNCTION gauss2, x, p & RETURN, gauss1(x,p[0:2])+p[3] & END
   ;  First, generate some synthetic data
   npts = 200
   x  = dindgen(npts) * 0.1 - 10.                  ; Independent variable
   yi = gauss1(x, [2.2D, 1.4, 3000.]) + 1000.      ; "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., 1234.]                           ; Initial guess
   r = bootstrap_mpfitfun('GAUSS2', x, y, sy, p0, NBOOT = 50)
                                                   ; Fit and replicate 50 times
   HELP, /STR, r
   ; compare all
   PLOT, x, y, PSYM=1
   FOR i=1,50 DO OPLOT, x, GAUSS2(x,r[i].p), COLOR=2
   OPLOT, x, GAUSS2(x,r[0].p), COLOR=3

   FOR i=0,3 DO PRINT, r[0].perror[i], STDDEV(r[1:*].p[i])


   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.

 REFERENCES:

   For details on bootstrap methods see:
       A.C.Davison and D.V.Hinkley
       Bootstrap methods and their applications
       Cambridge series in statistical  and probabilistical Mathematics
       Cambridge, UK, 1997
   and references therein

   For details on MPFIT see:
   http://cow.physics.wisc.edu/~craigm/idl/fitting.html

 REVISION HISTORY:
       Written         Theo Brauers, Mar 2000
       Corrected
       Revised
       Modified

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\bootstrap_mpfitfun.pro)


BOX

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		BOX
 VERSION:
		4.0
 PURPOSE:
		Creates an empty plot area, with boundaries defined by XLIMS and YLIMS.
 CATEGORY:
		General Graphics.
 CALLING SEQUENCE:
		BOX, XLIMS, YLIMS [, keywords]
 INPUTS:
	XLIMS, YLIMS
		2 dimensional vectors, format: [xmin,xmax] and [ymin,ymax] respectively.
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
	/BORDER
		Switch.  Draws a border around the plot area.  Default - no border.
	/OVER
		Switch.  Creates the plot area over an existing plot.  Default - new
		plot area.
	TRUASP
		Corrects the XLIMS or YLIMS values to yield a 1:1 aspect ratio.
		Accepts six possible character values (only first 2 characters matter):
			'XLO' :  Scale x, keeping lowest x-value constant.
			'XCEN':  Scale x, keeping center x-value constant.
			'XHI' :  Scale x, keeping highest x-value constant.
			'YLO' :  Scale y, keeping lowest y-value constant.
			'YCEN':  Scale y, keeping center y-value constant.
			'YHI' :  Scale y, keeping highest y-value constant.
	/UPDATE_LIMS
		Switch.  If set, XLIMS and YLIMS are updated to the values used in
		plotting.
	_EXTRA
		A formal keyword used to pass all plotting keywords.  Not to be used
		directly.  See comment in RESTRICTIONS.
 OUTPUTS:
		None.
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		If UPDATE_LIMS is set, the values of XLIMS, YLIMS may change.
 RESTRICTIONS:
		The keywords passed through _EXTRA are transferred to the PLOTS
		routine.  No keyword verification is performed by BOX.
 PROCEDURE:
		Uses calls to CAST, and STRMATCH_MM from MIDL.  The scaling is done
		using the sizes of the plotting area in device coordinates, provided by
		the  system variables !d.x_vsize and !d.y_vsize.  Therefore the scaling
		is always proper for the current output device.
 MODIFICATION HISTORY:
		Created 15-JUL-1991 by Mati Meron.
		Modified 15-DEC-1991 by Mati Meron.  Added keyword COLOR.
		Modified 15-DEC-1993 by Mati Meron.  Now BOX takes advantage of the
		keyword inheritance property and accepts all IDL plotting keywords.
		Modified 1-MAY-1995 by Mati Meron.  Improved aspect ratio correction.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\box.pro)


BOX1

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       BOX1
 PURPOSE:
       Single mouse button interactive box on image display.
 CATEGORY:
 CALLING SEQUENCE:
       box1, x, y, dx, dy
 INPUTS:
 KEYWORD PARAMETERS:
       Keywords:
         /DEVICE         Work in device coordinates (default).
         /NORMAL         Work in normalized coordinates.
         /DATA           Work in data coordinates.
         COLOR=clr       Box color.  -2 for dotted box.
         DXRANGE=dxr     X size range [min, max].
         DYRANGE=dyr     Y size range [min, max].
         SHAPE=shp       If given box shape is locked: Shape=dy/dx.
         /NOSTATUS       Inhibits status display widget.
         TEXT=txt        Text array to display in status widget.
         MENU=txtarr     Text array with exit menu options.
           Def=['OK','Abort','Continue'].  'Continue is added.'
         /NOMENU         Inhibits exit menu.
         EXITCODE=code.  0=normal exit, 1=alternate exit.
           If MENU is given then code is option index.
         SETSTAT=st      May use the same status display widget on
           each call to box1 (stays in same position).
           On first call: the status widget structure is returned.
           Following calls: send st.  Must use with /KEEP.
           To delete status display widget after last box1 call: 
             widget_control,st.top,/dest (or drop /KEEP)
         /KEEP           Do not delete status widget on exit.
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 1994 Jan 10
       R. Sterner, 1995 Mar 22 --- Added /NOMENU option.

 Copyright (C) 1994, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\box1.pro)


BOX2B

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       BOX2B
 PURPOSE:
       Simple two mouse button interactive box on image display.
 CATEGORY:
 CALLING SEQUENCE:
       box2b, x1, x2, y1, y2
 INPUTS:
 KEYWORD PARAMETERS:
       Keywords:
         /STATUS  means display box size and position.
         MENU=txtarr     Text array with exit menu options.
           Def=['OK','Abort','Continue'].  'Continue is added.'
         /NOMENU         Inhibits exit menu.
         EXITCODE=code.  0=normal exit, 1=alternate exit.
           If MENU is given then code is option index.
         /YREVERSE makes y=0 be the top line.
 OUTPUTS:
       x1, x2 = min and max X.   out
       y1, y2 = min and max Y.   out
 COMMON BLOCKS:
 NOTES:
       Notes: Works in device coordinates.
         Drag open a new box.  Corners or sides may be dragged.
         Box may be dragged by clicking inside.
         Click any other button to exit.
         A returned value of -1 means box undefined.
 MODIFICATION HISTORY:
       R. Sterner, 1997 Nov 10
       R. Sterner, 1998 Feb  5 --- Fixed first erase box problem.
       Better but not perfect.
       R. Sterner, 1998 Jul 21 --- Added List Box Position.
       R. Sterner, 1999 Mar 15 --- Added /YREVERSE keyword.

 Copyright (C) 1997, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\box2b.pro)


BOXAREA

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       BOXAREA
 PURPOSE:
       Select an area with a box.
 CATEGORY:
 CALLING SEQUENCE:
       boxarea, x1, y1, x2, y2
 INPUTS:
 KEYWORD PARAMETERS:
       Keywords:
         FLAG=flg  Exit flag: 0=ok, 1=abort.
 OUTPUTS:
       x1,y1 = first box point.   out
       x2,y2 = second box point.  out
 COMMON BLOCKS:
 NOTES:
       Notes: Open a box by dragging with left mouse button.
         Repeat to get desired box.
         Accept box with middle button.
         Reject box with right button.
         All coordinates are device coordinates.
 MODIFICATION HISTORY:
       R. Sterner, 1995 Oct 31

 Copyright (C) 1995, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\boxarea.pro)


BOXAREA2

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

 PURPOSE:
       Select an area with a box.

 CATEGORY:
 PROG_TOOLS/WIDGETS

 CALLING SEQUENCE:
       boxarea2, x_1, y_1, x_2, y_2 ,[/flag],[/js],[color=color]

 KEYWORD PARAMETERS:
         FLAG  Exit flag: 0=ok, 1=abort.
         JS  Means X axis is time in Julian seconds. Example:
           x=maken(-2e8,-1.9e8,200) & y=maken(20,30,200)
           z=bytscl(makez(200,200))
           izoom,x,y,z,/js
           boxarea2,/js

 OUTPUTS:
       x_1,y_1 = first box point.   out
       x_2,y_2 = second box point.  out


 PROCEDURE:
       Notes: Open a box by dragging with left mouse button.
              Return by right button
         All coordinates are device coordinates.

 MODIFICATION HISTORY:
       R. Sterner, 1995 Oct 31
       R. Bauer, 1996, April 1   changed for data coordinates


 Copyright (C) 1995, 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.
1998-Mar-11 return variables changed
   1999-Nov-06 help added
 2000-Mar-13 color keyword added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\boxarea2.pro)


BOXONMAP

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:
   BOXONMAP, derived from IDL User Library Procedure BOX_CURSOR

 PURPOSE:
   Emulate the operation of a variable-sized box cursor (also known as
   a "marquee" selector).

 CATEGORY:
   Interactive graphics.

 CALLING SEQUENCE:
   BOXONMAP, wx0, wy0, wx1, wy1 [, INIT = init] [, FIXED_SIZE = fixed_size]

 INPUTS:
  No required input parameters.

 OPTIONAL INPUT PARAMETERS:
 wx0, wy0, wx1, and wy1 give the initial location of the lower left
       (wx0, wy0) and upper right (wnx, wny) corners of the box if the
 keyword INIT is set.  Otherwise, the box is initially drawn in the
 center of the screen.  Both input and output parameters are in
       Longitude (X) and Latitude (Y).

 KEYWORD PARAMETERS:
 INIT:  If this keyword is set, wx0, wy0, wx1, and wy1 contain the
       initial parameters for the box.

 FIXED_SIZE:  If this keyword is set, the initial parameters fix the
 size of the box.  This size may not be changed by the user.

 MESSAGE:  If this keyword is set, print a short message describing
 operation of the cursor.

 OUTPUTS:
 wx0:  X value (Lon) of lower left corner of box.
 wy0:  Y value (Lat) of lower left corner of box.
 wx1:  X value (Lon) of upper right corner of box.
 wy1:  Y value (Lat) of upper right corner of box.

 The box is also constrained to lie entirely within the window.

 COMMON BLOCKS:
 None.

 SIDE EFFECTS:
 A box is drawn in the currently active window.  It is erased
 on exit.
       A window for display of numeric latitude and longitude is created.
       It is destroyed on exit.

 RESTRICTIONS:
 Works only with window system drivers.

 PROCEDURE:
 The graphics function is set to 6 for eXclusive OR.  This
 allows the box to be drawn and erased without disturbing the
 contents of the window.

 Operation is as follows:
 Left mouse button:   Move the box by dragging.
 Middle mouse button: Resize the box by dragging.  The corner
  nearest the initial mouse position is moved.
 Right mouse button:  Exit this procedure, returning the
        current box parameters.

 MODIFICATION HISTORY:
 DMS, April, 1990.
 DMS, April, 1992.  Made dragging more intutitive.
 NFH, March, 1993,  Warp box & use map coordinates,
                          display Lat & Lon in text box.
 PJR/ESRG, March, 1994, display lat & lon in xmessage window

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\boxonmap.pro)


BOXPLOT

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

 PURPOSE:
        This procedure produces a box and whisker plot of a data
        vector and provides many options to customize the appearance
        of the plots. The data can be supplied as one vector and the
        statistics will be computed according to the group
        index. Alternatively, the data can be supplied as
        precalculated percentile values if the Is_Percentile flag is
        set. Boxes may be plotted staggered along the x axis or the y
        axis.

 CATEGORY:
        2D Graphics

 CALLING SEQUENCE:
        BOXPLOT, DATA [,GROUP=] [,MINGROUP=]  $
                 [,MAXGROUP=] [,LABEL=]       $
                 [,COLOR=] [,BOXCOLOR=]      $
                 [,BOXWIDTH=] [,BOXPOSITION=]      $
                 [,MEDIANCOLOR=] [,MEDIANTHICK=]$
                 [,MEANSYMBOL=]    $
                 [,MEANCOLOR=] [,FILLCOLOR=] $
                 [,MISSING=] [,MIN_VALID=]         $
                 [,MAX_VALID=] [,PRINTN=]           $
                 [,CHARSIZE=] [,OVERPLOT=]          $
                 [,VERTICAL=]                              $
                 [,ORIENTATION=] [,IS_PERCENTILE=]  $
                 [,PERCVAL=] [,QUIET=]

 INPUTS:
        DATA  --> The data vector. This can be an array of 
           any dimensions but is always treated as 1-dimensional
           vector. If the Is_Percentiles keyword is set, data must be
           an array of dimensions 5,N, where the first dimension
           denotes the percentile values.

 KEYWORD PARAMETERS:
        GROUP --> array of the same dimension as DATA which
           contains grouping information. One box is plotted for
           each group. If MINGROUP or MAXGROUP are given, boxes and
           whiskers are only plotted for group values within this
           range. Group can also be a string array. In this case
           MINGROUP and MAXGROUP make no sense of course.
           If GROUP contains more than 28 values, the major tick
           marks will no longer be aligned with the groups and a
           warning message is printed.

        MINGROUP --> the minimum group value for which a box
           shall be plotted.

        MAXGROUP --> the maximum group value for which a box
           shall be plotted

        LABEL --> Label values for different *groups*.
           NOTE: The user must take care that one label is passed for
           each group to be plotted. If label is not specified, the
           group values will be used as axis labels. Note that
           group itself can be a string array.

        COLOR --> plotting color for axis (default: !P.Color).

        BOXCOLOR --> color of the boxes (frames). Default
           is the COLOR value, i.e. !P.COlor if not specified. This
           color will also be used as default for MEDIANCOLOR and
           MEANCOLOR. Set BoxColor to a negative value to suppress
           the box outlines. In this case the default for MEDIANCOLOR
           and MEANCOLOR will be the COLOR value.

        BOXWIDTH --> Width of boxes relative to major tick
           marks (default: 0.8). 

        BOXPOSITION --> Position of boxex relative to tick
           marks on x axis (default: 0.). This parameter is useful
           together with the OVERPLOT keyword in order to plot
           multiple groups of boxes in one graph. 

        MEDIANCOLOR --> a color value for the median bar
           (default: value of BOXCOLOR)

        MEDIANTHICK -> thickness of the median line

        MEANSYMBOL --> symbol to be used for mean values. If no
           symbol is given, no mean values will be drawn.

        MEANCOLOR --> color for mean symbols (default:
           value of BOXCOLOR) 

        FILLCOLOR --> a value or an array containing the
           colorindex for all boxes or each box, respectively. If a
           single value is given, *all* boxes will be filled with
           this color. If an array is passed that has less elements
           than there are groups to plot, the remaining colors will
           be filled with the default background color (!P.background). 
           If no FILLCOLOR is specified, the boxes will not be filled
           at all. 

        MISSING --> a value that represents missing data. If
           given, any data with a value of missing will be filtered
           out before plotting. 

        MIN_VALID -> any data below this value will be ignored
           from the analysis.

        MAX_VALID -> any data above this value will be ignored
           from the analysis.

        PRINTN --> print number of elements on top of each
           box/whisker. 

        CHARSIZE --> character size of the PRINTN labels
           (default: 0.8) 

        OVERPLOT --> do not draw a new coordinate system but
           overlay new data. For 2 sets of data it is recommended to
           use BOXWIDTH=0.4 and BOXPOSITION=-0.25 and 0.25,
           respectively. 

        ORIENTATION -> orientation for axis labels (see XYOUTS
           procedure) 

        VERTICAL -> Set this keyword to have boxes staggered
           along y axis (i.e. boxes are horizontal).

        IS_PERCENTILE --> data are already processed
           percentiles. In this case data must be an array with
           dimensions 5,N. The GROUP keyword is ignored, and each set
           of the N percentiles will be treated as one group.

        PERCVAL --> percentile values (default: 0.05, 0.25,
           0.5, 0.75, 0.95). See the percentiles function for
           deatils. This keyword has only effect if Is_Percentile is
           not set. 

        QUIET -> suppress printing of statistics for each
           group.

        _EXTRA keywords are passed to the PLOT routine and can be used
        to determine the appearance of the plot (e.g. XTITLE,YTITLE,
        YSTYLE,YRANGE,/YLOG,COLOR,THICK,FONT)

 OUTPUTS:

 SUBROUTINES:
        xboxplot : produces plot with groups along x axis
        yboxplot : produces plot with boxes along y axis

 REQUIREMENTS:
        function PERCENTILES is called and must either be compiled
        or located in the IDL_PATH

 NOTES:

 EXAMPLE:
            o3 = data(where(header eq 'O3'),*)
            alt = data(where(header eq 'ALT'),*)
            ialt=2.*fix(alt/2.)
            boxplot,o3,group=ialt

         produces a boxplot with ozone percentiles in altitude bins of
         2 (km). Axis, box frames and labels will be plotted in the
         default color, boxes are not filled.

            boxplot,o3,group=ialt,fillc=15,meansym=sym(1),meancol=2, $
                 boxwidth=0.6,ytitle='O3',xtitle='alt. bin',  $
                 missing=-999.99,/printn

         produces boxes that are filled with color index 15 and have the
         frame and median line in the default color. The mean values
         are deonted by a circle filled with color index 2. 
         Titles are assigned to the x and y axis. The number of valid 
         observations is printed on top of each box. The boxes are
         reduced in size.

            co = data(where(header eq 'CO'),*)
            boxplot,o3,group=ialt,missing=-999.99,boxcol=4, $
                 boxwidth=0.4,boxpos=-0.25
            boxplot,co,group=ialt,missing=-999.99,boxcol=2, $
                 boxwidth=0.4,boxpos=+0.25,/overplot

         produces a plot with different colored box frames for ozone
         and CO data.
            

 MODIFICATION HISTORY:
        mgs, 30 Jul 1997: VERSION 1.00
        mgs, 03 Aug 1997: added template
        mgs, 27 Nov 1997: some revisions and suggested changes by T.Brauers:
             - better color handling (NOTE: meaning of BOXCOLOR has changed)
             - optional overlay of mean value
             - box frames
             - variable boxwidth
             - error fixing lower upper boundaries in log plots
             - bug fix with label keyword
             - added OVERPLOT and BOXPOSITION keywords
        mgs, 22 Jan 1998: added IS_PERCENTILE keyword to allow
               plotting of data that has been processed already
        mgs, 17 Apr 1998: 
             - x-axis handling improved (now uses axis command and xyouts)
             - orientation and medianthick keywords added
        mgs, 21 May 1998:
             - added percval keyword
        mgs, 24 Aug 2000:
             - changed copyright to open source
             - changed default colors to system values
             - improved documentation and modernized code
             - bug fix: n_elements instead of keyword_set
             - added min_valid, max_valid, and quiet keywords
             - added vertical keyword, thus yboxplot is obsolete
             - [] array notation throughout

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\boxplot.pro)


BOXPOS

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:   boxpos
 USEAGE:
            result=boxpos()
            result=boxpos(aspect=aspect,rmarg=rmarg,xpos=xpos,ypos=ypos,$
                         get=get,curbox=curbox,print=print)

 PURPOSE:   returns the 4 element position of a properly shaped data window.
            output is in normalized coordinates

 INPUT:

    none required

 keyword input:

    aspect       x/y aspect ratio of map (default = 1)

    rmarg        the amount of margin to leave on the right side of the
                 box.  The margin is specified in units of 10 character
                 widths, so merely setting the RMARG parameter provides
                 enough space for COLOR_KEY

    get          if set, retrieve the position information of the last
                 plot drawn. 
 
    xpos         two element vector specifying x position of a multi frame
                 plot,  the first element specifies the frame number, the
                 second element specifies the number of frames
                
    ypos         two element vector specifying y position of a multi frame
                 plot, the first element specifies the frame number, the
                 second element specifies the number of frames

    print        if set, print out the normal coordinates of the box
                 edges in format,
                                   pos=[x0,y0,x1,y1]

                 where (x0,y0) and (x1,y1) are the normal coordiates
                 of the lower left and upper right corners of the box
                 The default value of PRINT is 1 if the CURSOR keyword
                 is set.

                
 OUTPUT:
                 result=[x1,y1,x2,y2], 
                 where (x1,y1) and (x2,y2) are the lower left hand
                 and upper right hand corner of the new data window
                 in normalized coordinates.
                 
 EXAMPLE:        Draw a map over a TVIM image

     tvim,dist(200)
     map_set,0,0,/orth,/cont,/grid,pos=boxpos(/get),/noerase

                 Draw a map of the southern hemisphere with 2:1 aspect
                 ratio

     map_set,-90,0,/orth,/cont,/grid,pos=boxpos(aspect=2)
                  
                    now try a 1:1 aspect ratio

     map_set,-90,0,/orth,/cont,/grid,pos=boxpos(/aspect)

                  now allow room for color key, and draw color key

     map_set,-90,0,/orth,/cont,/grid,pos=boxpos(/aspect,/rmarg)
     color_key


                Draw a multframe plot 
 
     x=findgen(100)
     plot,x,x,pos=boxpos(aspect=1,ypos=[3,3])
     plot,x,x^2,pos=boxpos(aspect=1,ypos=[2,3]),/noerase
     plot,x,x^3,pos=boxpos(aspect=1,ypos=[1,3]),/noerase


;    NOTE: the XMULTI and YMULTI proceedures (in this directory) can
;          also be used to make multiframe plots and are more flexible
;          than BOXPOS for positioning the individual frames.

  author:  Paul Ricchiazzi                            25jan93
           Institute for Computational Earth System Science
           University of California, Santa Barbara

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\boxpos.pro)


BOX_SIZE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       BOX_SIZE
 PURPOSE:
       Used by MOVBOX to change box size using the cursor.
 CATEGORY:
 CALLING SEQUENCE:
       BOX_SIZE, x, y, dx, dy, showflag
 INPUTS:
       x,y = lower left corner device coordinates.    in
 KEYWORD PARAMETERS:
       Keywords:
         /POSITION prints box position and size on exit.
         XSIZE = factor.  Mouse changes Y size, computes X size.
         YSIZE = factor.  Mouse changes X size, computes Y size.
         /YREVERSE means y is 0 at screen top.
         XFACTOR=xf convsersion factor from device coordinates
           to scaled coordinates.
         YFACTOR=yf convsersion factor from device coordinates
           to scaled coordinates.
         DXMIN=dxmn  Minimum allowed box x size (def=1).
         DYMIN=dymn  Minimum allowed box y size (def=1).
         COLOR=clr  Box color (-2 for dotted box).
 OUTPUTS:
       dx, dy = box size.                             in, out
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner,  25 July, 1989.
       R. Sterner, 16 Mar, 1992 --- upgraded box list.
       R. Sterner,  7 Dec, 1993 --- Added min box size.
       R. Sterner, 1994 Nov 27 --- Switched !err to !mouse.button.

 Copyright (C) 1989, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\box_size.pro)


BREAK_LINES

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

 PURPOSE:
   This function breaks the linesin a string array into multiple records if the record is longer
   than the reclength parameter. By default, the break is always located at
   [' ','+','/','(',')','|'] charackters.

 CATEGORY:
   PROG_TOOLS/STRINGS

 CALLING SEQUENCE:
   Result=break_lines(Str, Reclength, [LIST=list] )

 INPUTS:
   Str       : array of (string) records
   Reclength : maximum recordlength allowed

 KEYWORD PARAMETERS:
   LIST:   a list of locations where a break might occur
           default: [' ','+','/','(',')','|']

 OUTPUTS:
   Result:  string array with string length of all elements less than revlength

 EXAMPLE:
   str_new=break_lines(['a=3+45+87/15;','b=3;'],10)
   print,transpose(str_new)
   gives :
   a=3+45+87
   /15;
   b=3;

 MODIFICATION HISTORY:
   Written by: Franz Rohrer 1998-Jan-15
   Modified:   Theo Brauers, 1999-Jan-7
               new keyword list

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\break_lines.pro)


BUILD_STRUCTURE

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

 PURPOSE:
	This routine accumulates values into a structure or concatinates two structures

 CATEGORY:
   PROG_TOOLS

 CALLING SEQUENCE:
   build_structure,structure,declaration,value,[name=name],[/random_structure_name],[/counted_structure_name]

 INPUTS:
   structure : if it's present the structure which will be accumulated to
   declaration: the tag which will be added to the structure
   value  : the value which will be added to the structure

 KEYWORD PARAMETERS:
    name: to set the Structure name
    random_structure_name: if set the structure name is performed by random_hex_name()
    counted_structure_name: if set the structure name is performed by count_name(name)

 OUTPUTS:
	structure: A structure holding value

 EXAMPLE:
   build_structure,def,'test',5
   help,test,/str
** Structure <117e2f8>, 1 tags, length=2, refs=1:
   TEST            INT              5
   build_structure,def,'AN',5
   help,def,/str
** Structure <117ec88>, 2 tags, length=4, refs=1:
   TEST            INT              5
   AN              INT              5


 MODIFICATION HISTORY:
 	Written by:	R.Bauer (ICG-1), 1998-Jun-27
   1999-02-23 Problem if tag is alread defined in structure by is_tag resolved
   1999-03-16 random_structure_name added
   1999-03-20 counted_structure_name added
   2000-Feb-18 help changed to call_help

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\build_structure.pro)


BUILD_VECTOR

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

 PURPOSE:
	This routine accumulates values into a vector

 CATEGORY:
   PROG_TOOLS

 CALLING SEQUENCE:
   build_vector,vector,value

 INPUTS:
   vector : if it's present the vector which will be accumulated to
   value  : the value which will be added to the vector

 OUTPUTS:
	vector: A vector holding value

 EXAMPLE:
   build_vector,test,5
   print,test
   5

 MODIFICATION HISTORY:
 	Written by:	R.Bauer (ICG-1), 1998-Jun-27

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\build_vector.pro)


BYT2STRARR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       BYT2STRARR
 PURPOSE:
       Unpack a string array from a byte array
 CATEGORY:
 CALLING SEQUENCE:
       byt2strarr, barr, tarr
 INPUTS:
       barr = byte array with text.   in
 KEYWORD PARAMETERS:
 OUTPUTS:
       tarr = text string array.      out
 COMMON BLOCKS:
 NOTES:
       Notes: The format of barr is:
         byte 0: NUM = Number of strings (255 max).
         byte 1: MAX = Length of longest string (255 max).
         byte 2: LEN1 = Length of 1st string.
         byte 3: C1_0 = 1st char of 1st string.
         byte 4: C1_1 = 2nd char of 1st string.
         byte 5: C1_2 = 3rd char of 1st string.
         . . .
         byte x1 (2+LEN1): C1_last = last char of 1st string.
         byte x1+1: LEN2 = Length of 2nd string.
         . . .
         To last char of last string in tarr.
         NUM, MAX, LEN1, C1, C2, ..., Clast, LEN2, C1, C2, ...
       
         Advantage: saves space, allows storing text arrays of
         various lengths.  See also strarr2byt, the inverse.
 MODIFICATION HISTORY:
       R. Sterner, 1996 May 29

 Copyright (C) 1996, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\byt2strarr.pro)


BYTARR_GET

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       BYTARR_GET
 PURPOSE:
       Extract a byte array from a byte buffer.
 CATEGORY:
 CALLING SEQUENCE:
       bytarr_get, buf, out
 INPUTS:
       buf = byte buffer to extract output from.  in
 KEYWORD PARAMETERS:
       Keywords:
         INDEX=indx  Index of byte array to extract:
           0=1st, 1=2nd, ...  Returned by bytarr_put
           array was inserted.  Out of range indices return
           a single 0 byte (no error).
         The inverse routine, bytarr_put, is used to insert
         arrays into the buffer.
         You must handle converting from byte to correct
         data type when extracting.
 OUTPUTS:
       out = byte array extracted from buffer.    out
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 1996 May 30

 Copyright (C) 1996, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\bytarr_get.pro)


BYTARR_PUT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       BYTARR_PUT
 PURPOSE:
       Insert a byte array into a byte buffer.
 CATEGORY:
 CALLING SEQUENCE:
       bytarr_put, buf, in
 INPUTS:
       in = byte array to add to buffer.   in
 KEYWORD PARAMETERS:
       Keywords:
         INDEX=indx  Returned index of inserted byte array:
           0=1st, 1=2nd, ...  Can be used with bytarr_get to
           retrieve a given array.
         ADDRESS=a  returned byte address into buffer for in.
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
       Notes: To start set input buffer b to 1 element:
         b = [0B] before using in bytarr_put.
         Can use this routine to build up an array of
         variable lengths arrays, or pack arrays of any data
         type together in a compact form.  Must convert input
         to a byte array first using field extraction.  Ex:
         a=indgen(10) & b=byte(a,0,2*n_elements(a)) will create
         an int array and convert it to a byte array.
         The inverse routine, bytarr_get, allows extraction by
         index number (1st input is 0, 2nd is 1, ...).
         You must handle converting from byte when extracting.
 MODIFICATION HISTORY:
       R. Sterner, 1996 May 30

 Copyright (C) 1996, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\bytarr_put.pro)


BYTES2STRARR

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

 PURPOSE:
   This function convertes a byte array to a string array
   cut at the LF character (10B), all CR (13B) are removed

 CATEGORY:
   PROG_TOOLS/STRINGS

 CALLING SEQUENCE:
   Result=BYTES2STRARR(Bytes)

 INPUTS:
   Bytes:  bytearray

 KEYWORD PARAMETERS:
   REMOVE_10B: if set 10b is removed

 OUTPUTS:
   an string array containing the text converted from bytearrary

 EXAMPLE:
   b=GET_FILE('....', /BYTE)
   s=BYTES2STRARR(b)

 REVISION HISTORY:
   Written         Theo Brauers, June 1997
   Modified by     R.Bauer, F.Rohrer, 1998-Nov-10 added REMOVE_10B

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\bytes2strarr.pro)


CACHE

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

 PURPOSE:
   This procedure is used to remember previously loaded data from file for the last plot;

 CATEGORY:
   PLOT/PLOT2D

 CALLING SEQUENCE:
   cache,plot,file,x,y,z,[i_xn=i_xn],[i_yn=i_yn]

 INPUTS:
   plot:    The by pl_init defined structure plot
   file:    The filename of the netCDF file
   x:       The name of parameter x
   y:       The name of parameter y
   z:       The name of parameter z

 OPTIONAL INPUTS:
   i_xn: number of x page position
   i_yn: number of y page position

 OUTPUTS:
   x:       Structure
   y:       Structure
   z:       Structure

  All structures of the same tag names:

  .name               : the name of the parameter
  .file               : the filename of the file
  .param              : the param field
  .valid              : the valid field
  .time               : the time field
  .param_long_name    : the long_name of the parameter
  .param_units        : the units of the parameter
  .time_long_name     : the long_name of the time
  .time_units         : the units of the time



 COMMON BLOCKS:
   plot_data
         pl_data: A structure holding parameters, names, titles and the file name of a loaded dataset


 EXAMPLE:
  cache,plot,file,x,y,z,i_xn=i_xn,i_yn=i_yn

 MODIFICATION HISTORY:
 	Written by:	R.Bauer (ICG-1), 5. Oct 1997
   1999-Nov-06 help added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\cache.pro)


CACHE_DEL

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

 PURPOSE:
   This procedure clears the common block plot_data variable pl_data

 CATEGORY:
   PLOT/PLOT2D

 CALLING SEQUENCE:
   cache_del


 COMMON BLOCKS:
   plot_data: This is the common block where file and data information for plot2d and plotxy are saved


 EXAMPLE:
   cache_del

 MODIFICATION HISTORY:
 	Written by:	R.Bauer (ICG-1), 5. Oct 1997

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\cache_del.pro)


CACHE_ENZ

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

 PURPOSE:
       Read-cache for enz-files

 CATEGORY:
       DATAFILES/ZCHN

 CALLING SEQUENCE:
       cache_enz,file,dvalue,ix,iy,fb,text,header,err

 INPUTS:
       file: name of enz-file

 KEYWORD PARAMETERS:
       js_time   : time values in julian seconds, calculated with appropriate dvalue-columns
       errmess   : error message text
       fill_value: fill value for non-existing data
       nocache   : to supress generation of *.sav-file

 OUTPUTS:
       dvalue: matrix of values, field[ix,iy]
       ix    : number of rows
       iy    : number of columns
       fb    : errorbar-flag for compatibility with zusammen-files, should be 0 for enz-files
       text  : array of headertext of columns
       header: raw header information
       err   : file read error flag

 SIDE EFFECTS:
       stores and restores information in the file filename.enz.sav

 EXAMPLE:
       cache_enz,'test.enz',dvalue,ix,iy,fb,text,header,err,js_time=js_time,fillvalue=-12345

 MODIFICATION HISTORY:
       Written         Franz Rohrer, May 1997
       Modified: 25.9.1998  renamed fillvalue in fill_value
                            included nocache
                 10.11.1998 FR file_info used to determine time difference
                 16.03.1999 FR file=file_in included
                 06.06.1999 FR if result2[0] eq '' and result1[0] ne '' then dt=10 else begin
                            damit das sav-file auch eingelesen wird, wenn kein Original vorhanden ist

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\cache_enz.pro)


CACHE_ZUS

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

 PURPOSE:
       Read-cache for zus-files

 CATEGORY:
       DATAFILES/ZCHN

 CALLING SEQUENCE:
       cache_zus,file,dvalue,ix,iy,fb,text,header,err

 INPUTS:
       file: name of zus-file

 KEYWORD PARAMETERS:
       js_time  : time values in julian seconds, calculated with appropriate dvalue-columns
       errmess  : error message text
       fillvalue: fill value for non existing data
       high_err : upper end of errorbar
       low_err  : lower end of errorbar

 OUTPUTS:
       dvalue: matrix of values, field[ix,iy], errorbars are taken out and stored in high_err and low_err
       ix    : number of rows
       iy    : number of columns
       fb    : errorbar-flag, should be 0 for enz-files
       text  : array of the headertext of columns
       header: raw header information
       err   : file read error flag

 SIDE EFFECTS:
       stores and restores information in file filename.zus.sav

 EXAMPLE:
       cache_zus,'test.zus',dvalue,ix,iy,fb,text,header,err,js_time=js_time,fillvalue=-12345,high_err=high_err,low_err=low_err

 MODIFICATION HISTORY:
       Written         Franz Rohrer, May 1997
       Corrected

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\cache_zus.pro)


CALCTYPE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		CALCTYPE
 VERSION:
		4.0
 PURPOSE:
		Identifies maximal (and, optionally) minimal data type for calculation.
 CATEGORY:
		Programming.
 CALLING SEQUENCE:
		Result = CALCTYPE( V_0 [,V_1, ... V_7] [, VALUE = VAL])
 INPUTS:
	V_0 through V_7
		Numeric, otherwise arbitrary, at least one should be given.  If the
		keyword /STRICT is set, unsigned integers of all lengths are not
		considered numerical.
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
	/TYPES
		Switch.  If set, the V_i parameters are taken to represent data types
		of inputs rather then the inputs themselves.
	/MAXTYP
		Switch.  If set, the numerically *highest* of the data types is
		returned.  This is the default, so there is really no need to set
		/MAXTYP, it is just provided for completeness.
	/MINTYP
		Switch.  If set, the numerically *lowest* of the data types is
		returned.
	DEFAULT
		Accepts an integer value to be used as default type for those input
		variables which happen to be undefined.  If not given, undefined
		inputs result in error.
	/EXACT
		Switch.  Disables the resetting of lower value to 4 and higher to 9
		when the inputs types are 5,6.  Has no impact in other cases.
	/STRICT
		Switch.  If set, unsigned integers are *NOT* considered numbers.
	/QUIET
		Switch.  Determines error handling.  See OUTPUTS below.
 OUTPUTS:
		If the data types of all inputs (or the inputs themself, when /TYPES
		is set) correspond to valid numeric types (excluding unsigned integers
		if /STRICT is set), CALCTYPE returns the numerically highest (or, if
		/MINTYP is set, numerically lowest) of the types present.  Note that
		the numeric order of the types is (excluding unsigned types):

				1, 2, 3, 14, 4, (5-6), 9

		As neither of (5,6) is equivalent or higher to the other, in case the
		inputs are of types 5 and 6, the return value is 9 (for higher) or 4
		(for lower) unless /EXACT is set.

		The types of unsigned integers (when accepted) are converted to these
		of signed ones of same length.

		The types of undefined inputs are converted to DEFAULT if given, else
		are left at 0 (which is *not* a valid numeric type).

		If some of the data types do not correspond to valid numeric types,
		the outcome depends on the /QUIET switch.  If /QUIET is set, the
		routine returns 0, else it stops with an error message.
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		All the V_i present have to be valid numeric inputs (or numeric data
		types) else an error results (unless /QUIET is set).
 PROCEDURE:
		Straightforward.  Using ISNUM and ONE_OF from MIDL.
 MODIFICATION HISTORY:
		Created 15-FEB-2001 by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\calctype.pro)


CALC_AV_RESIDUAL

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

 PURPOSE:
       calculate geometric average of residuals

 CATEGORY:
       MATH

 CALLING SEQUENCE:
       calc_av_residual,x,y,a,b

 INPUTS:
       x,y : x/y data dublets
       a,b : offset and slope of line

 OUTPUTS:
       returns geometric average of residuals =mean( sqrt(sum((y-a-b*x)^2)/n) )

 EXAMPLE:
       calc_av_residual,x,y,a,b

 MODIFICATION HISTORY:
       Written         Franz Rohrer, May 1997
       Corrected

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\calc_av_residual.pro)


CALC_BIN_AVERAGES

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

 PURPOSE:
   This function calculates averages of y-values for given x-intervals

 CATEGORY:
   MATH

 CALLING SEQUENCE:
   result=calc_bin_averages(x,y[,log=log][,number=number][,min=min][,max=max])

 INPUTS:
   x:vector of x-values
   y:vector of y-values

 OUTPUTS:
   result.occurrence   :number of occurrencies
         .mean         :mean of y-data inside bin-interval
         .stddev       :standard deviation of y-data inside bin-interval
         .position     :average x-position of bin-intervals
         .left         :left margins of bin-intervals
         .right        :right margins of bin-intervals
         .binposition  :average of left and right margins

 KEYWORD PARAMETERS:
   log   : make equidistant bins on a logarithmic scale
   number: number of bins, default=10
   min   : left margin,  default=MIN(x)
   max   : right margin, default=MAX(x)

 EXAMPLE:
   x=findgen(1000) & y=randomn(seed,1000)
   r=calc_bin_averages(x,y)
   print,r.position,r.mean,format='(10f12.7)'
   49.5000000 149.5000000 249.5000000 349.5000000 449.5000000 549.5000000 649.5000000 749.5000000 849.5000000 949.5000000
   -0.0238803   0.0346891  -0.0060972  -0.0419993   0.1417571  -0.0071263   0.0606227   0.1793810   0.0087501   0.0297610

 MODIFICATION HISTORY:
 	Written by:	F. Rohrer (ICG-3), 1998-Nov-19

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\calc_bin_averages.pro)


CALC_GEOMETRY

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

 PURPOSE:
   This function calculates the area and volume of a different geometrical
   figures which are stacked into/onto another.

 CATEGORY:
   MATH

 CALLING SEQUENCE:
   Result = CALC_GEOMETRY(X)

 INPUTS:
   X:  the thicknes of one layer of the figures, can be a single value, all
       layer are of the same thickness, or an array. The length of this array
       defines the size of the output structure array. If n_elements(x) ==1
       then the num_box keyword is tested.

 OPTIONAL INPUTS:
   Y:  see GEOMETRY keyword
   Z:  see GEOMETRY keyword

 KEYWORD PARAMETERS:

   KDIFF:    set this keyword to a number or array with same elements as X  the kd in
               all layers will be set to the number or array (default=0.0)

   GEOMETRY: possible options:

           'SPHERE':   concentric spheres
                       volume and area are calculated from the thickness input
                       only, Y and Z are disregarded

           'TUBE':     concentric cylinders, no length
                       volume and area are calculated from the thickness input
                       If Y is given it is taken as length of the tubes and
                       Z are disregarded

           'BARREL':   concentric barrels, length is total lenght if y is scalar
                       if Y is vector then these values are taken.
                       volume and area are calculated from the thickness and length
                       input, Z is disregarded

           'CUBE':     concentric cubes
                       volume and area are calculated from the thickness input
                       only, Y and Z are disregarded

           'COLUMN':   stacked boxes, if Y is area and volume, is calcualted

           'UNKNOWN':  Y and Z are area and volume, if not
                       provided they are set to 1.D0 in all boxes

   NUM_BOX:  number of boxes in a equal layer thickness model, if x is provided
             as a scalar value

 OUTPUTS:
   This function returns an array of structure which contains the thickness , the
   area, and the volume. Result.ar[k] is the area between layer k and k+1.
   Result.vl[k] is the volume of layer[k]

 EXAMPLES:
   In order to calculate the volume and area of a 4m cube surrounded by a
   4.2m cube one has to enter the following function call:

   IDL> x=calc_geometry([2.,.1 ], g='cube') & print, x & help, x,/str
   {       2.0000000       64.000000       96.000000    0.0000 }
   {      0.10000000       10.088000       105.84000    0.0000 }
   ** Structure <1062420>, 3 tags, length=24, refs=1:
      DH              DOUBLE           2.0000000
      VL              DOUBLE           64.000000
      AR              DOUBLE           96.000000

   A set of 10 concentric spheres of .05m layers is calculated

   IDL> x=calc_geometry(.05D, g='sphere', n=10) & print, x[0:1],  x[9]
   {     0.050000000   0.00052359879     0.031415927    0.010000 }
   {     0.050000000    0.0036651915      0.12566371    0.010000 }
   {     0.050000000      0.14189527       3.1415927    0.010000 }

   note that the diameter of the last sphere is 1m corresponding to
   a surface area of 3.1415..m


 MODIFICATION HISTORY:
   Written by: Theo Brauers, 1998-Feb-5
   Modified:   T.B.        1998-FEB-6
                           calc of cube/ tube / barrel corrected

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\calc_geometry.pro)


CALC_LINEAR_INTERPOL

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

 PURPOSE:
   This functions calls the linear interpolation for TIMES_SERIES_SYNC

 CATEGORY:
   MATH

 CALLING SEQUENCE:
   Result = CALC_LINEAR_INTERPOL(client_t, client_v, master_t)

 INPUTS:
   Client_t:   client time array
   Client_v:   client value array
   Master_t:   master time array

 KEYWORD PARAMETERS:
   FILL_VALUE:  value for missing entries in the output array
   ERROR:      if set to a named variable an error status is returned (0: OK)

 OUTPUTS:
   This function returns an array of the interpolated values

 EXAMPLE:
   see TIME_SERIES_SYNC

 MODIFICATION HISTORY:
   Written by: Theo Brauers, 1999-FEB-15

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\calc_linear_interpol.pro)


CALC_LINEAR_WITH_LIMIT

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

 PURPOSE:
   This functions performs the linear interpolation with time limits for TIMES_SERIES_SYNC

 CATEGORY:
   MATH

 CALLING SEQUENCE:
   Result = CALC_LINEAR_WITH_LIMIT(client_t, client_v, master_t, master_w)

 INPUTS:
   Client_t:   client time array
   Client_v:   client value array
   Master_t:   master time array

 KEYWORD PARAMETERS:
   FILL_VALUE:  value for missing entries in the output array
   ERROR:      if set to a named variable an error status is returned (0: OK)

 OUTPUTS:
   This function returns an array of the interpolated values

 EXAMPLE:
   see TIME_SERIES_SYNC

 MODIFICATION HISTORY:
   Written by: Theo Brauers, 1999-FEB-15

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\calc_linear_with_limit.pro)


CALC_NUMBER_FREQUENCY

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   calc_number_frequency
 PURPOSE:
   This function calculates the frequencies of the first digit of numbers
 CATEGORY:
   MATH
 CALLING SEQUENCE:
   result=calc_number_frequency(arr)
 INPUTS:
   arr: array of numbers
 OUTPUTS:
   result: frequency distribution of the first digits
 EXAMPLE:
   arr=[1.2,0.0122222,200]
   print,calc_number_frequency(arr),format='(f45.2)'
    0.00 0.67 0.33 0.00 0.00 0.00 0.00 0.00 0.00 0.00
 MODIFICATION HISTORY:
 	Written by:	F. Rohrer (ICG-3), 1998-Nov-17

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\calc_number_frequency.pro)


CALC_PROP_INTERPOL

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

 PURPOSE:
   This functions performs the proportional interpolation for TIMES_SERIES_SYNC

 CATEGORY:
   MATH

 CALLING SEQUENCE:
   Result = CALC_PROP_INTERPOL(client_t, client_v, master_t, master_v)

 INPUTS:
   Client_t:   client time array
   Client_v:   client value array
   Master_t:   master time array
   Master_v:   master value array

 KEYWORD PARAMETERS:
   FILL_VALUE:  value for missing entries in the output array
   ERROR:      if set to a named variable an error status is returned (0: OK)

 OUTPUTS:
   This function returns an array of the interpolated values

 EXAMPLE:
   see TIME_SERIES_SYNC

 MODIFICATION HISTORY:
   Written by: Theo Brauers, 1999-FEB-15

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\calc_prop_interpol.pro)


CALC_SOLAR_ZENITH_ANGLE

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

 PURPOSE:
   This function calcutes the solar zenith

 CATEGORY:
   TIME

 CALLING SEQUENCE:
   Result = calc_solar_zenith_angle(time, longitude, latitude)

 INPUTS:
   Time:       julian seconds or string [d.m.y h:m:s] or [yyyy-mm-dd hh:mm:ss]
               (Julian Sec =0 : 2000-JAN-1 0:00:00 UTC)
   Longitude:  eastern longitude
   Latitude:   northern latitude

 KEYWORD PARAMETERS
   STRUCTURE:  if set a structure with input and output params will be returned as structure

 OUTPUT:
   This functions returns an array of solar zenith angles or a structure
   including the input parameters

 PROCEDURE:
   This set of routines is based on Yoshio Kubo, Rep. of Hydrographic Res. No. 15 1980
   Sun position for 1970 - 2030 (see calc_sun_pos for details)

 REVISION HISTORY:
   Written     Theo Brauers, Nov 1998
   Modified    Theo Brauers, June 1999
               bugs removed !!!!

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\calc_solar_zenith_angle.pro)


CALC_SPLINE_INTERPOL

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

 PURPOSE:
   This functions call the spline interpolation for TIMES_SERIES_SYNC

 CATEGORY:
   MATH

 CALLING SEQUENCE:
   Result = CALC_SPLINE_INTERPOL(client_t, client_v, master_t)

 INPUTS:
   Client_t:   client time array
   Client_v:   client value array
   Master_t:   master time array

 KEYWORD PARAMETERS:
   FILL_VALUE:  value for missing entries in the output array
   ERROR:      if set to a named variable an error status is returned (0: OK)

 OUTPUTS:
   This function returns an array of the interpolated values

 EXAMPLE:
   see TIME_SERIES_SYNC

 MODIFICATION HISTORY:
   Written by: Theo Brauers, 1999-FEB-15

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\calc_spline_interpol.pro)


CALC_SUN_POS

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

 PURPOSE:
   This function calcutes the declination or right ascension of the sun

 CATEGORY:
   TIME

 CALLING SEQUENCE:
   Result = calc_sun_pos(jdf, [/RIGHT_ASCENSION] , [/DECLINATION])

 INPUTS:
   Jdf: julian day with fractions of day

 KEYWORD PARAMETERS:
   RIGHT_ASCENSION:    if set only right ascension will be returned
   DECLINATION:        if set only declination be returned

 OUTPUTS:
   Result:     sun positions given in degrees

 EXAMPLE:

 PROCEDURE:
   This set of routines is based on
   Yoshio Kubo, Rep. of Hydrographic Res. No. 15 1980
   Sun position for 1970 - 2030
   ( copied from MFC199m source code, GETMOON2.C, GETMOON.C, ..)
   typed by K. Pfeilsticker 13.9.1989)

 REVISION HISTORY:
   Written     Theo Brauers, Nov 1998

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\calc_sun_pos.pro)


CALC_UNIT

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

 PURPOSE:
 This function returns a structure with the result and other informations to calculate with units

 CATEGORY:
  MATH

 CALLING SEQUENCE:
   Result=calc_unit(value,inunit,outunit)

 INPUTS:
   value:   one or an array of values that should be transformed
   inunit:  The input unit of the value
   outunit: The output unit of the result

 EXAMPLE:
   result=calc_unit(5,'ppb','ppt')
   help,result,/str
   ** Structure <302d43bc>, 5 tags, length=32, refs=1:
      PARAM_UNITS_IN  STRING    'ppb'
      PARAM_UNITS_OUT STRING    'ppt'
      PARAM           INT              5
      RESULT          FLOAT           1000.00
      FUNC            STRING    '*1.e-09/1.e-12'

 MODIFICATION HISTORY:
  Written by:	R.Bauer (ICG-1), August , 12 1997
  1998-01-14  additional: seconds since 2000-01-01 00:00:00 UTC
   1999-Nov-06 help added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\calc_unit.pro)


CALC_WINDOW_AVERAGE

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

 PURPOSE:
   This functions performs the averaging over the provided tme windows for TIME_SERIES_SYNC

 CATEGORY:
   MATH

 CALLING SEQUENCE:
   Result = calc_window_average(client_t, client_v, master_t, master_w)

 INPUTS:
   Client_t:   client time array
   Client_v:   client value array
   Master_t:   master time array
   Master_w:   master window array

 KEYWORD PARAMETERS:
   FILL_VALUE:  value for missing entries in the output array
   ERROR:      if set to a named variable an error status is returned (0: OK)

 OUTPUTS:
   This function returns an array of the window averaged values

 EXAMPLE:
   see TIME_SERIES_SYNC

 MODIFICATION HISTORY:
   Written by: Theo Brauers, 1999-FEB-15

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\calc_window_average.pro)


CALC_ZENITH

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

 PURPOSE:
   This function calculates zenith and azimuth angle for a given location/time

 CATEGORY:
	MATH

 CALLING SEQUENCE:
   zenit=calc_zenith(js,long,lat,azimuth=azimuth)

 INPUTS:
       date:    the speciefied day; scalar string
       time:    the time in UT    ; scalar string
       long:    longitude of the geograhical position; scalar float
       lat:     latitude  of the geograhical position; scalar float

 OUTPUTS:
       zenith : zenith angle
       azimuth: azimuth angle

 PROCEDURE:
  This function is based on the publication by Sirri Aydinli,
  Fortschrittberichte der VDI-Zeitschriften (Fortschr.Ber. VDI-Z.), 1981, Reihe 6, Nr.79, p5-12,
  'Ueber die Berechnung der zur Verfuegung stehenden Solarenergie und des Tageslichtes'

 EXAMPLE:
   print,calc_zenith(str2js('12:00:00 08.11.1996'),6.35,50.92)
     67.9200

   print,calc_zenith(str2js('12:00:00 28.10.1997'),0.,0.)
     13.1800
     sollte 13.819 sein nach Ralf's astronomischen Tabellen

 MODIFICATION HISTORY:
 	Written by:	Franz Rohrer August 1998
   Modified  : 9.11.1998 FR, calc_zenit->calc_zenith,zenit->zenith,azimut->azimuth

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\calc_zenith.pro)


CALL_HELP

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

 PURPOSE:
	The result of this function is the text below CALLING SEQUENCE from a called routine

 CATEGORY:
   CASE_TOOLS

 CALLING SEQUENCE:
   result=call_help()

 EXAMPLE:
   message,call_help(),/info

 MODIFICATION HISTORY:
 	Written by	R.Bauer (ICG-1), 1999-Nov-06
   1999-Nov-06 help added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\call_help.pro)


CAPTION

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:  caption

 PURPOSE:  CAPTION can be used to print captions above or below a
           figures.  The character size is determined by the number
           of characters per line.  

 USEAGE:   caption,cap,xx,ybot=ybot,yt=ytop,nchar=nchar

 INPUT:    

   cap     string used for caption.  Normally all text within CAP 
           is line wrapped to produce a multiline caption. All
           white space within CAP is preserved in the caption.
           Within CAP the character "\" can be used to force a line
           break (i.e., to start a new line).  Extra white space
           following the "\" causes the text to be indented.

           t='this is a test \     junk test test'+$
             ' \     junk test \ \    junk: this is a test'

           caption,t

                             PRODUCES:

           this is a test
                junk test test
                junk test

                junk: this is a test

           Note that the backslash character must be surrounded by
           whitespace to be recognized

  
   xx      normal coordinates of left and right edge of caption
   

 KEYWORD INPUT:

   ytop       normal coordinates of top of caption
              (default=!y.window(0)-.15)

   nchar      number of characters per line

   vspace     vertical space factor, controls vertical space between
              lines (default = 1)

   bg_color   background color

   color      foreground color

   exdent     number of character positions to indent all lines except
              the first. (default=0)

   nowrap     if set do not line wrap the input text, instead use
              embedded backslash characters to control line breaks.

 KEYWORD OUTPUT:

   ybot       normal coordinates of bottom of caption. The value of
              of ybot can be used append more text with another call
              to CAPTION.

 DISCUSSION:

 LIMITATIONS:

 COMMON BLOCKS:

 SIDE EFFECTS:
  
 EXAMPLE:  

    t1='CAPTION can be used to print captions above or below a '+$
      'figures.  The character size is determined by the number '+$
      'of characters per line.   here is a list of items: \ '+$
      '     1. item 1 \ '+$
      '     2. item 2 \ '+$
      'END OF FIRST CAPTION
       
    t2='BEGINNING OF SECOND CAPTION \ HERE is more text to add to  '+$
      'the previous text. Note how the  '+$
      'text starts immediately below the last line of the previous  '+$
      'written text. The use of ybot allows concatenation of text with  '+$
      'different right and left margins'
       
    w8x11 & !p.multi=[0,1,2]
    plot,dist(10)
       
    caption,t1,nchar=80,ybot=yy
    xwid=.5*(!x.window(1)-!x.window(0))
    xmid=.5*(!x.window(0)+!x.window(1))
    caption,t2,xwid+.5*[-xwid,xwid],nchar=40,ytop=yy

;; FILL option

    t= 'HERE is more sample text to demonstrate the use of CAPTION''s, '+$
       '"fill" option.  Note how the text is stretched to fill the '+$
       'entire width of the line.  It is probably a good idea not '+$
       'to force linebreaks using the backslash symbol while in this '+$
       'mode.  The "fill" option works best when NCHAR is large'
        
    erase
    caption,t,[.1,.9],ytop=.9,/fill,nchar=80
       
;; CAPTION used with READ_TEXT 

   caption,read_text('caption.txt','Figure 1.'),nchar=60
  

 AUTHOR:   Paul Ricchiazzi                        12 Mar 96
           Institute for Computational Earth System Science
           University of California, Santa Barbara
           paul@icess.ucsb.edu

 REVISIONS:

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\caption.pro)


CAST

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		CAST
 VERSION:
		4.0
 PURPOSE:
		Generalized type casting.  Converts variables whose type code is out
		of the range [LO,HI] into this range.
 CATEGORY:
		Programming (type conversion).
 CALLING SEQUENCE:
		Result = CAST( X, [LO [,HI]])
 INPUTS:
	X
		Numerical, arbitrary (see /STRICT for possible limitations).
	LO
		Number representing a type code, range (1:15).  If out of this range,
		an error results.  If not given, it is set to 1.
 OPTIONAL INPUT PARAMETERS:
	HI
		Type code, same as LO.  Default value is 9 (note that, though higher
		number codes exist, 9 corresponds to the "numerically highest" type).
		If HI is provided and corresponds to a "numerically lower" type than
		LO, it is set to LO.
 KEYWORD PARAMETERS:
	/STRICT
		Switch.  If set, unsigned values are not accepted as numbers.
	/ROUND
		Switch.  If set AND the casting is to any integer type, rounding is
		performed prior to type casting.
	/FIX
		Switch.  If set, the output is filtered through FPU_FIX, eliminating
		floating underflow errors.
 OUTPUTS:
		If the type of X is < LO, CAST returns X converted to type LO.
		If the type of X is > HI, CAST returns X converted to type HI.
		Otherwise CAST returns X.
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		And attempt to call CAST with non-numerical input or with type codes
		not corresponding to known numerical codes, will yield an error.
 PROCEDURE:
		Identifies the type of X, and if out of the range given by [LO,HI]
		calls the proper conversion routine using the system routine
		CALL_FUNCTION.  The "range" follows the numerical order of types, i.e.

				1, 2, 3, 14, 4, (5-6), 9

		Unsigned types (Uint, Ulong, Ulong64) are either ignored (if /STRICT
		is set) or converted to the signed types of same length.

		CAST uses CALCTYPE, FPU_FIX and ISNUM from MIDL.
 MODIFICATION HISTORY:
		Created 25-DEC-1991 by Mati Meron.
		Modified 15-JUN-1995 by Mati Meron to accept the new DOUBLECOMPLEX type.
		Modified 25-SEP-1998 by Mati Meron.  Underflow filtering added.
		Modified 25-DEC-2000 by Mati Meron.  Added keyword ROUND.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
		Totally rewritten by Mati Meron, on 15-FEB-2001, to accomodate all new
		numeric types.  Added keyword STRICT.  Eliminated type conversion for
		CHARACTER type as it serves no useful purpose.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\cast.pro)


CATALOG

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

 PURPOSE:
   This procedure writes the html catalog files

 CATEGORY:
  CASE_TOOLS

 CALLING SEQUENCE:
   catalog,[path],[/no_examples],[/no_error],[/no_mail],[out_path=out_path],[/publish]

 EXAMPLE:
   catalog

 MODIFICATION HISTORY:
 Written by:     R.Bauer (ICG-1), 1997
 new version: 2000-Jan-25
 2000-Feb-08 get_template_one_value keywords added
 2000-Apr-02 examples now without dbase and example icon

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\catalog.pro)


CATALOG_DB

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

 PURPOSE:
   This procedure writes the html catalog database files and the tar and sav files of the routines

 CATEGORY:
  CASE_TOOLS

 CALLING SEQUENCE:
   catalog_db,[path],[out_path=out_path]

 INPUTS:
  path: the routine path to search routines

 PROCEDUE:
  idl_work and idl_model are the routine directories which will be scanned by resolve_dependencies.
  with the key /no_publish all our routine directories will be scanned


 MODIFICATION HISTORY:
 Written by:     R.Bauer (ICG-1), 1997
 new version: 2000-Jan-25
 2000-Feb-08 : get_template_one_value keywords added
 2000-Jun-18 : link files sampled in a script and this will executed at the end of the routine
 catalog_db,['j:/links/idl_source/idl_work','j:/links/idl_source/idl_model'],out_path='j:\links\idl_source\'
 catalog_db,['/usr/local/icg/icg/idl_test/idl_source/idl_work','/usr/local/icg/icg/idl_test/idl_source/idl_model'],out_path='/usr/local/icg/icg/idl_test/idl_source'

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\catalog_db.pro)


CBAR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CBAR
 PURPOSE:
       Make a color bar.
 CATEGORY:
 CALLING SEQUENCE:
       cbar
 INPUTS:
 KEYWORD PARAMETERS:
       Keywords:
         VMIN=vmn  Minimum value of color bar parameter (def=0).
         VMAX=vmx  Maximum value of color bar parameter (def=top).
         CMIN=cmn  Color that represents vmn (def=0).
         CMAX=cmx  Color that represents vmx (def=top).
           where top = !d.table_size-1.
         CCLIP=cc  Actual max color index allowed (def=!d.table_size-1)
         /HORIZONTAL Colors vary horizontally (def).
         /VERTICAL   Colors vary vertical.
         /BOTTOM   Horizontal axis on bottom (def).
         /TOP      Horizontal axis on top.
         /RIGHT    Vertical axis on right (def).
         /LEFT     Vertical axis on left.
         Plus all keywords accepted by PLOT.
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
       Notes: Bar is positioned using the POSITION keyword.
         To display a title use TITLE and so on.
 MODIFICATION HISTORY:
       R. Sterner, 13 Dec, 1993
       R. Sterner, 1994 Jul 5 --- Added axis positioning.
       R. Sterner, 1995 Dec 10 --- Allow position to be in device coords.
       R. Sterner, 1995 Dec 18 --- Fixed to not clobber current xy scaling.
       R. Sterner, 1996 Dec  9 --- Added CCLIP keyword.
       R. Sterner, 1998 Jan 23 --- Added charthick keyword.

 Copyright (C) 1993, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\cbar.pro)


CED1

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CED1
 PURPOSE:
       Simple widget to edit a single color table entry.
 CATEGORY:
 CALLING SEQUENCE:
       ced1, index
 INPUTS:
       index = color table index to edit.   in
 KEYWORD PARAMETERS:
       Keywords:
         TITLE=txt  Title text to display.
         /HSV  means work in Hue, Saturation, and Value
           coordinates (def=Red, Green, Blue).
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 29 Oct, 1993
       R. Sterner, 29 Oct, 1993

 Copyright (C) 1993, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\ced1.pro)


CENTERTLB

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

 PURPOSE:

       This is a utility routine to position a widget program
       on the display at an arbitrary location. By default the
       widget is centered on the display.

 AUTHOR:

       FANNING SOFTWARE CONSULTING
       David Fanning, Ph.D.
       1645 Sheely Drive
       Fort Collins, CO 80526 USA
       Phone: 970-221-0438
       E-mail: davidf@dfanning.com
       Coyote's Guide to IDL Programming: http://www.dfanning.com

 CATEGORY:

       Utilities

 CALLING SEQUENCE:

       CenterTLB, tlb, [x, y, /NOCENTER]

 REQUIRED INPUTS:

       tlb: The top-level base identifier of the widget program.

 OPTIONAL INPUTS:

       x:  Set this equal to a normalized position for the center
       of the widget as measured from the left-hand side of the screen.
       The default value is 0.5 (the center)  Setting this equal to 1.0
       places the widget at the far right-hand side of the screen.

       y:  Set this equal to a normalized position for the center
       of the widget as measured from the bottom of the screen.
       The default value is 0.5 (the center) Setting this equal to 1.0
       places the widget at the top of the screen.

 KEYWORDS:

      NOCENTER:  By default, the center of the widget is positioned at the
      location specified by the x and y parameters.  If NOCENTER is set
      to a non-zero value, then the upper left corner of the widget
      is postioned at the specifed location.

 PROCEDURE:

       The program should be called after all the widgets have
       been created, but just before the widget hierarchy is realized.
       It uses the top-level base geometry along with the display size
       to calculate offsets for the top-level base that will center the
       top-level base on the display.

 COMMENT:
       Regardless of the values set for x, y and NOCENTER, the widget
       is not permitted to run off the display.

 MODIFICATION HISTORY:

       Written by:  Dick Jackson, 12 Dec 98.
       Modified to use device-independent Get_Screen_Size
            function. 31 Jan 2000. DWF.
       Added x, y, NOCENTER and run-off protection. 26 Jan 2001. BT.

###########################################################################

 LICENSE

 This software is OSI Certified Open Source Software.
 OSI Certified is a certification mark of the Open Source Initiative.

 Copyright © 1998-2000 Fanning Software Consulting

 This software is provided "as-is", without any express or
 implied warranty. In no event will the authors be held liable
 for any damages arising from the use of this software.

 Permission is granted to anyone to use this software for any
 purpose, including commercial applications, and to alter it and
 redistribute it freely, subject to the following restrictions:

 1. The origin of this software must not be misrepresented; you must
    not claim you wrote the original software. If you use this software
    in a product, an acknowledgment in the product documentation
    would be appreciated, but is not required.

 2. Altered source versions must be plainly marked as such, and must
    not be misrepresented as being the original software.

 3. This notice may not be removed or altered from any source distribution.

 For more information on Open Source Software, visit the Open Source
 web site: http://www.opensource.org.

###########################################################################

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\centertlb.pro)


CGM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CGM
 PURPOSE:
       Toggles graphics redirection to a *.cgm file on or off.
 CATEGORY:
 CALLING SEQUENCE:
       cgm, [file]
 INPUTS:
       file = optional cgm file name.   in
         Default file name is seconds after midnight, like
         31412.cgm.
 KEYWORD PARAMETERS:
 OUTPUTS:
 COMMON BLOCKS:
       cgm
 NOTES:
       Notes: Computer Graphics Metafile (CGM) format files are
         useful because they may be imported into word processor
         documents.  An initial color table warning message appears
         to be harmless.
 MODIFICATION HISTORY:
       R. Sterner 2 Dec, 1992
       R. Sterner, 29 Jan, 1993 --- Revised.

 Copyright (C) 1992, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\cgm.pro)


CHEBCOEF

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

 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:
   Estimate Chebyshev polynomial coefficients of a function on an interval

 MAJOR TOPICS:
   Curve and Surface Fitting

 CALLING SEQUENCE:
   p = CHEBCOEF(FUNC, PRIVATE, FUNCTARGS=functargs, /DOUBLE, /EXPRESSION, $
                PRECISION=prec, ERROR=err, NMAX=nmax, INTERVAL=interval, $
                REDUCE_ALGORITHM=, STATUS=)

 DESCRIPTION:

   CHEBCOEF estimates the coefficients for a finite sum of Chebyshev
   polynomials approximating the function FUNC(x) over an interval.
   The user can choose the desired precision and maximum number of
   chebyshev coefficients.

   This routine is intended for functions which can be evaluated to
   full machine precision at arbitrary abcissae, and which are smooth
   enough to ensure that the coefficients are a decreasing sequence.
   For already-tabulated or potentially noisy data, the routines
   CHEBGRID or CHEBFIT should be used instead.

   The function to be approximated may either be the name of an IDL
   function (the default behavior), or an IDL expression (using the
   /EXPRESSION keyword).

   The procedure uses a modified form of the classic algorithm for
   determining the coefficients, which relies the orthogonality
   relation for Chebyshev polynomials.  The interval [a,b] is
   subdivided successively into sets of subintervals of length
   2^(-k)*(b-a),(k = 0,1,2...). After each subdivision the
   orthogonality properties of the Chebyshev polynomials with respect
   to summation over equally-spaced points are used to compute two
   sets of approximate values of the coefficients cj, one set
   computed using the end-points of the subintervals, and one set
   using the mid-points.  Certain convergence requirements must be
   met before terminating.  If the routine fails to converge with 64
   coefficents, then the current best-fitting coefficients are
   returned, along with an error estimate in the ERROR keyword.
   CHEBCOEF never returns more than 64 coefficients.

   The coefficients may be further refined.  If the keyword
   REDUCE_ALGORITHM is set to a value of 1, then any high order
   coefficients below a certain threshold are discarded.  If
   REDUCE_ALGORITHM is set to 2 (the default), then all coefficients
   below the threshold are discarded rather than just the high order
   ones.  The threshold is determined by the PRECISION keyword.

 INPUTS:

   FUNC - a scalar string, the name of the function to be
          approximated, or an IDL string containing an expression to
          be approximated (if /EXPRESSION is set).

  PRIVATE - any optional variable to be passed on to the function to
            be integrated.  For functions, PRIVATE is passed as the
            second positional parameter; for expressions, PRIVATE can
            be referenced by the variable 'P'.  CHEBCOEF does not
            examine or alter PRIVATE.

 RETURNS:

   An array of Chebyshev coefficients which can be passed to
   CHEBEVAL.  NOTE: the convention employed here is such that the
   constant term in the expansion is P(0)*T0(x) (i.e., the convention
   of Luke), and not P(0)/2 * T0(x).

 KEYWORD PARAMETERS:

   DOUBLE - if set, then computations are done in double precision
            rather than single precision.

   ERROR - upon return, this keyword contains an estimate of the
           maximum absolute error in the approximation.

   EXPRESSION - if set, then FUNC is an IDL expression to be
                approximated, rather than the name of a function.

   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.

   INTERVAL - a 2-element vector describing the interval over which
              the polynomial is to be evaluated.
              Default: [-1, 1]

   NMAX - a scalar, the maximum number of coefficients to be
          estimated.   This number may not exceed 64. 
          Default: 64

   PRECISION - a scalar, the requested precision in the
               approximation.  Any terms which do not contribute
               significantly, as defined by this threshold, are
               discarded.  If the function to be estimated is not
               well-behaved, then the precision is not guaranteed to
               reach the desired level.  Default: 1E-7

   REDUCE_ALGORITHM - a scalar integer, describes how insignificant
               terms are removed from the fit.  If 0, then all terms
               are kept, and none are dicarded.  If 1, then only
               trailing terms less than PRECISION are discarded.  If
               2, then both trailing and intermediate terms less than
               PRECISION are discarded.
               Default: 2

   STATUS - upon return, this keyword contains information about the
            status of the approximation.  A value of -1 indicates bad
            input values; a value of 0 indicates the required
            accuracy was not obtained; a value of 1 indicates
            success.

 EXAMPLE:

   x = dindgen(1000)/100     ; Range of 0 to 10
   p = chebcoef('COS(x)', /expr, interval=[0d, 10d])  ;; Compute coefs
   y = chebeval(x, p, interval=[0d,10d])              ;; Eval Cheby poly
   plot, x, y - cos(x)       ; Plot residuals

 REFERENCES:

   Abramowitz, M. & Stegun, I., 1965, *Handbook of Mathematical
     Functions*, 1965, U.S. Government Printing Office, Washington,
     D.C. (Applied Mathematical Series 55)
   CERN, 1995, CERN Program Library, Function E406
   Luke, Y. L., *The Special Functions and Their Approximations*,
     1969, Academic Press, New York

 MODIFICATION HISTORY:
   Written and documented, CM, June 2001
   Copyright license terms changed, CM, 30 Dec 2001
   Added usage message, CM, 20 Mar 2002
   Changed docs slightly, CM, 25 Mar 2002

  $Id: chebcoef.pro,v 1.6 2002/05/03 18:40:27 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\chebcoef.pro)


CHEBEVAL

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

 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:
   Evaluate a Chebyshev polynomial on an interval, given the coefficients

 MAJOR TOPICS:
   Curve and Surface Fitting

 CALLING SEQUENCE:
   y = CHEBEVAL(X, P, INTERVAL=interval, DERIVATIVE=deriv)

 DESCRIPTION:

   CHEBEVAL computes the values of a Chebyshev polynomial function at
   specified abcissae, over the interval [a,b].  The user must supply
   the abcissae and the polynomial coefficients.  The function is of
   the form:

               N
       y(x) = Sum p_n T_n(x*)     x in [a,b]
              i=0

   Where T_n(x*) are the orthogonal Chebyshev polynomials of the
   first kind, defined on the interval [-1,1] and p_n are the
   coefficients.  The scaled variable x* is defined on the [-1,1]
   interval such that (x*) = (2*x - a - b)/(b - a), and x is defined
   on the [a,b] interval.

   The derivative of the function may be computed simultaneously
   using the DERIVATIVE keyword.  

   The is some ambiguity about the definition of the first
   coefficient, p_0, namely, the use of p_0 vs. the use of p_0/2.
   The p_0 definition of Luke is used in this function.

 INPUTS:

   X - a numerical scalar or vector, the abcissae at which to
       evaluate the polynomial.  If INTERVAL is specified, then all
       values of X must lie within the interval.

   P - a vector, the Chebyshev polynomial coefficients, as returned
       by CHEBFIT or CHEBCOEF.

 RETURNS:

   An array of function values, evaluated at the abcissae.  The
   numeric precision is the greater of X or P.

 KEYWORD PARAMETERS:

   DERIVATIVE - upon return, a vector containing the derivative of
                the function at each abcissa is returned in this
                keyword.

   INTERVAL - a 2-element vector describing the interval over which
              the polynomial is to be evaluated.
              Default: [-1, 1]

 EXAMPLE:

   x = dindgen(1000)/100     ; Range of 0 to 10
   p = chebcoef('COS(x)', /expr, interval=[0d, 10d])  ;; Compute coefs
   y = chebeval(x, p, interval=[0d,10d])              ;; Eval Cheby poly
   plot, x, y - cos(x)       ; Plot residuals

 REFERENCES:

   Abramowitz, M. & Stegun, I., 1965, *Handbook of Mathematical
     Functions*, 1965, U.S. Government Printing Office, Washington,
     D.C. (Applied Mathematical Series 55)
   CERN, 1995, CERN Program Library, Function E407
   Luke, Y. L., *The Special Functions and Their Approximations*,
     1969, Academic Press, New York

 MODIFICATION HISTORY:
   Written and documented, CM, June 2001
   Copyright license terms changed, CM, 30 Dec 2001
   Added usage message, CM, 20 Mar 2002

  $Id: chebeval.pro,v 1.5 2002/03/25 06:42:50 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\chebeval.pro)


CHEBFIT

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

 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:
   Fit Chebyshev polynomial coefficients to a tabulated function

 MAJOR TOPICS:
   Curve and Surface Fitting

 CALLING SEQUENCE:
   p = CHEBFIT(X, Y, ERR, INTERVAL=interval, NMAX=nmax,
               PRECISION=prec, /EVEN, /ODD, REDUCE_ALGORITHM=)

 DESCRIPTION:

   CHEBFIT fits a series of Chebyshev polynomials to a set of
   tabulated and possibly noisy data points.  The functions MPFIT and
   CHEBEVAL, available from the above web page, must also be in your
   IDL path for this function to work properly.  The user can choose
   the desired precision and maximum number of chebyshev
   coefficients.

   This function is intended for use on already-tabulated data which
   are potentially noisy.  The user should never expect more than
   NPOINTS terms, where NPOINTS is the number of (x,y) pairs.  For
   functions which can be evaluated to full machine precision at
   arbitrary abcissae, the routine CHEBCOEF should be used instead.
   For exact data tabulated on a regular grid, the routine CHEBGRID
   should be tried.

   The user can also specify that the function is even or odd, using
   the keywords EVEN or ODD.  This saves computation time because
   certain terms in the expansion can be ignored.  For the purposes
   of this function even and odd refer to the symmetry about the
   center of the interval.

   The algorithm is employed in three steps.  In the first step, the
   coefficients are estimated at a crude level.  In the second step,
   it is determined whether certain coefficients are deemed
   "ignoreable", i.e., they do not contribute significantly to the
   function and are discarded.  The operation of this step is
   determined by the REDUCE_ALGORITHM keyword.  Finally, the
   remaining "good" coefficients are re-fitted to achieve the best
   fit.

 INPUTS:

   X, Y - the x- and y- tabulated values to be fitted.

   ERR - (optional) the y-error bar associated with each (x,y) pair.
         Default: 1

 RETURNS:

   An array of Chebyshev coefficients which can be passed to
   CHEBEVAL.  NOTE: the convention employed here is such that the
   constant term in the expansion is P(0)*T0(x) (i.e., the convention
   of Luke), and not P(0)/2 * T0(x).

 KEYWORD PARAMETERS:

   EVEN, ODD - if set, then the fitting routine assumes the function
               is even or odd, about the center of the interval.

   INTERVAL - a 2-element vector describing the interval over which
              the polynomial is to be evaluated.
              Default: [-1, 1]

   NMAX - a scalar, the maximum number of polynomial terms to be
          fitted at one time.
          Default: 16

   PRECISION - a scalar, the requested precision in the fit.  Any
               terms which do not contribute significantly, as
               defined by this threshold, are discarded.  If the
               function to be fitted is not well-behaved, then the
               precision is not guaranteed to reach the desired
               level.
               Default: 1E-7

   REDUCE_ALGORITHM - a scalar integer, describes how insignificant
               terms are removed from the fit.  If 0, then all terms
               are kept, and none are dicarded.  If 1, then only
               trailing terms less than PRECISION are discarded.  If
               2, then both trailing and intermediate terms less than
               PRECISION are discarded.
               Default: 2

 EXAMPLE:

   x = dindgen(1000)/100     ; Range of 0 to 10
   y = cos(x) + randomn(seed,1000)*0.01  ; Function with some noise
   p = chebfit(x, y, interval=[0d,10d])
   plot, x, y - chebeval(x,p, interval=[0d,10d])

 REFERENCES:

   Abramowitz, M. & Stegun, I., 1965, *Handbook of Mathematical
     Functions*, 1965, U.S. Government Printing Office, Washington,
     D.C. (Applied Mathematical Series 55)
   CERN, 1995, CERN Program Library, Function E407
   Luke, Y. L., *The Special Functions and Their Approximations*,
     1969, Academic Press, New York

 MODIFICATION HISTORY:
   Written and documented, CM, June 2001
   Copyright license terms changed, CM, 30 Dec 2001
   Added usage message, CM, 20 Mar 2002
   Slight docs change, CM, 25 Mar 2002

  $Id: chebfit.pro,v 1.6 2002/05/03 18:40:19 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\chebfit.pro)


CHEBGRID

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

 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:
   Estimate Chebyshev polynomial coefficients of a function on a grid

 MAJOR TOPICS:
   Curve and Surface Fitting

 CALLING SEQUENCE:
   p = CHEBGRID(T, X, [ DXDT, NPOINTS=, NPOLY=, NGRANULE= , $
                RMS=, DRMS=, RESIDUALS=, DRESIDUALS= , $
                XMATRIX=, DXMATRIX=, RESET=, 
                DERIV_WEIGHT= ] )

 DESCRIPTION:

   CHEBGRID estimates the coefficients for a finite sum of Chebyshev
   polynomials approximating a continuous tabulated function over an
   interval.  The function (and optionally its derivative) must be
   tabulated on a regularly sampled grid.  The implementation of this
   function is taken from a method described by X. X. Newhall, used
   in estimating coefficients for ephemerides in the solar system.

   The tabulated function is assumed to be continuous over the entire
   interval.  A Chebyshev series is fitted to the function over small
   segments, called granules.  The size of each granule, the number
   of points in each granule, and the number of Chebyshev polynomials
   are all configurable.

   Users may specify either the function alone, or the function and
   its first derivative.  By also giving the tabulated derivative, a
   more accurate Chebyshev polynomial can be developed.  Aside from
   the constraints mentioned in the next paragraph, the polynomial
   that is returned is the best-fit polynomial in a least-squares
   sense.

   Here is a definition of terms:

      GRANULE - a single continuous fitted segment.  The length of the
         granule, NGRANULE, is specified in units of the tabulated
         grid size.  Because of the continuity requirements developed
         below, granules will always overlap at their endpoints.
         Thus, then length of a granule should be a factor of
         N_ELEMENTS(X)-1.  For simple functions over short intervals,
         the granule size can be equal to N_ELEMENTS(X)-1

      NUMBER OF POINTS the number of points, NPOINTS, within a
         granule to be fitted to the polynomial, not necessarily
         equal to the granule size.  The greater the number of
         points, the more computation time and storage is required.
         This number *must* be a factor of NGRANULE.  Typically
         NPOINTS is a number between 8 and 12.  Because of the
         single-point overlap between granules (see below), the
         actual number of points per fit is NPOINTS+1.

      NUMBER OF POLYNOMIALS the number of Chebyshev polynomial terms,
         NPOLYNOMIAL, to be fitted per granule.  The greater the
         number of polynomial terms, the more computation time and
         storage is required, but also the greater the approximating
         precision of the fit.

   The particular set of Chebyshev polynomial coefficients developed
   by this function have some special properties.  If both the
   function and its derivative are specified, then the value and
   derivative of the interpolating polynomial at the granule
   endpoints will be exactly equal to the tabulated endpoint values.
   This feature allows many approximations to be strung together
   piecewise, and the function value and first derivative will be
   continuous across granule boundaries.

   If only the function value is specified, then only the function
   value will be continuous at the granule endpoints, and not the
   derivative.

   An extensive set of statistics are computed to assess the quality
   of the Chebyshev polynomial fit.  The keywords RESIDUALS and
   DRESIDUALS return the residuals of the fit after subtracting the
   interpolation.  The RMS and DRMS keywords return the root mean
   squared deviations between data and model.

   If the user does not know how many granules, points, or polynomial
   coefficients to use, then he or she should try several
   combinations and see which minimizes the r.m.s. value with the
   fewest number of coefficients.

   If the XMATRIX and DXMATRIX keywords are passed, then CHEBGRID
   attempts to avoid recomputing several of the matrices it uses in
   estimating the coefficients.  If multiple calls to CHEBGRID are to
   be made, some compution time savings can be made.  In the first
   call CHEBGRID the required matrices are computed and returned.  In
   subsequent calls, CHEBGRID detects the XMATRIX and DXMATRIX
   keyword values and uses those values if it can.

   The user can also estimate their own coefficients.  The matrices
   returned are (NPOINTS+1)x(NPOLYNOMIAL).  The coefficients from a
   NPOINTS+1 tabulation, X, are found by:

      PCHEB = XMATRIX ## X  +  DXMATRIX ## DXDT

   if derivative information is known, or

      PCHEB = XMATRIX ## X

   if no derivative information is known.  [ Note: the matrices are
   different, depending on whether derivative information is known or
   not. ]

   
 INPUTS:

   T - array of regularly sampled *independent* variables.  The number
       of elements in T should be a multiple of NGRANULE, plus one.

   X - array of regularly sampled *dependent* variables.  The number
       of elements in X should be equal to the number of elements in
       T.

   DXDT - optionally, a tabulated array of first derivatives of X
          with respect to T, at the same grid points.

 KEYWORD PARAMETERS:

   NGRANULE - size of a "granule", in grid intervals.  NGRANULE must
              be at least 2, and a factor of N_ELEMENTS(T)-1.
              Default: 8

   NPOINTS - number of points per granule that are fitted.  NPOINTS
             must be at least 2, and a factor of NGRANULE. 
             Default: NGRANULE

   NPOLYNOMIAL - number of Chebyshev polynomial terms per fit.
                 NPOLYNOMIAL must be at least 2 and less than
                 2*(NPOINTS+1), when derivative information is
                 specified; or less than NPOINTS+1, when no
                 derivative information is specified.
                 Default: 7

  RESIDUALS - upon return, an array of size N_ELEMENTS(T), with
              residuals of the tabulated function minus the
              interpolated function.

  DRESIDUALS - same as RESIDUALS, but for the function's first
               derivative.

  RMS - upon return, the root mean square of the function value
        residuals.

  DRMS - same as RMS, but for the function's first derivative.

  XMATRIX - upon return, the matrix used to compute Chebyshev
            polynomial coefficients from the function value.

            Upon input, CHEBGRID determines if XMATRIX will apply to
            the data, and if so, XMATRIX is reused rather than
            computed.  If XMATRIX cannot be reused, then it is
            computed afresh, and the new value is returned in the
            XMATRIX keyword.

            The user should not modify the contents of the is array.

  DXMATRIX - same as XMATRIX, but for the function's first
             derivative.

  RESET - if set, force a recomputation of XMATRIX and/or DXMATRIX.

  DERIV_WEIGHT - amount of weight to give to function derivative,
                 relative to the function value.
                 Default: 0.16d


 RETURNS:

   An array of coefficient values.  The dimensions of the array are
   NPOLYNOMIALxNSEGS, where NSEGS is the number of granules in the
   entire interval.


 EXAMPLE:

   ;; Estimate Chebyshev coefficients for the function SIN(X), on the
   ;; interval [-1,+1].  
   xx = dindgen(9)/4d - 1d   ;; Regular grid from -1 to 1 (9 points)
   yy = sin(xx)              ;; Function values, sin(x), ...
   dy = cos(xx)              ;; ... and derivatives

   ;; Estimate coefficients using CHEBGRID (single granule of 8 intervals)
   p = chebgrid(xx, yy, dy, npoints=8, ngranule=8, npoly=10)

   xxx = dindgen(1001)/500 - 1d   ;; New grid for testing
   res = sin(xxx) - chebeval(xxx, p)
   plot, xxx, res

   ;; Same as example above, except extended range to [-1, +15],
   using eight granules.
   xx2 = dindgen(65)/4d - 1
   yy2 = sin(xx2)
   dy2 = cos(xx2)
   p = chebgrid(xx2, yy2, dy2, ngranule=8, npoint=8, npoly=10)
   help, p
       P               DOUBLE    = Array[10, 8]
   ;; (i.e., 10 polynomial coefficients over 8 granules)


 REFERENCES:

   Abramowitz, M. & Stegun, I., 1965, *Handbook of Mathematical
     Functions*, 1965, U.S. Government Printing Office, Washington,
     D.C. (Applied Mathematical Series 55)
   Newhall, X. X. 1989, Celestial Mechanics, 45, p. 305-310

 MODIFICATION HISTORY:
   Written, CM, Feb 2002
   Documented, CM, 24 Mar 2002
   Corrected documentation, CM, 28 Apr 2002

  $Id: chebgrid.pro,v 1.3 2002/05/02 07:00:43 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\chebgrid.pro)


CHEBYSHEV_POL

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		CHEBYSHEV_POL
 VERSION:
		4.0
 PURPOSE:
		Calculates Chebyshev polynomials Tn and associated functions.
 CATEGORY:
		Mathematical function.
 CALLING SEQUENCE:
		Result = CHEBYSHEV_POL( X, N, [ /ASSOCIATED])
 INPUTS:
	X
		Numeric, absolute values must be <= 1, otherwise arbitrary.
	N
		Nonnegative scalar, rounded to integer on input.  Defaults to 0.
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
	/ASSOCIATED
		Switch.  When set, an associated function, SIN(N*ARCCOS(X)) is returned.
 OUTPUTS:
		Returns the values of the Chebyshev polynomial T(n,x), defined as
		COS(N*ARCCOS(X)) or (when ASSOCIATED is set), the values of the
		associated Chebyshev function, SIN(N*ARCCOS(X)).
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		None other then the restrictions on X, and N as mentioned above.
 PROCEDURE:
		Using the mathematical definition.  Calling DEFAULT and FPU_FIX from
		MIDL.
 MODIFICATION HISTORY:
		Created 20-DEC-1994 by Mati Meron.
		Modified 15-SEP-1998 by Mati Meron.  Underflow filtering added.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\chebyshev_pol.pro)


CHECK5

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CHECK5
 PURPOSE:
       Check if running IDL version 5 or greater.
 CATEGORY:
 CALLING SEQUENCE:
       flag = check5()
 INPUTS:
 KEYWORD PARAMETERS:
 OUTPUTS:
       flag = 0 if false, 1 if true.   out
 COMMON BLOCKS:
 NOTES:
       Notes: Useful to check if the current IDL version
       supports features from version 5 or greater.
 MODIFICATION HISTORY:
       R. Sterner, 1998 Jan 23

 Copyright (C) 1998, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\check5.pro)


CHECKER

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CHECKER
 PURPOSE:
       Return a checker board pattern array of 0 and 1.
 CATEGORY:
 CALLING SEQUENCE:
       checker, nx, ny, pat
 INPUTS:
       nx, ny = array size in x and y.     in
 KEYWORD PARAMETERS:
 OUTPUTS:
       pat = resulting array.              out
 COMMON BLOCKS:
 NOTES:
       Note: an example 4 x 4 array:
            0 1 0 1
            1 0 1 0
            0 1 0 1
            1 0 1 0
 MODIFICATION HISTORY:
       R. Sterner, 30 Dec, 1989

 Copyright (C) 1989, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\checker.pro)


CHGCOLOR

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

 PURPOSE:
       The purpose of this routine is to allow the user to change
       the color at a particular color index. The user is able to
       mix their own color by manipulating red, green, and blue
       sliders. This routine is ideal for changing axes or background
       colors of a plot, for example. The routine works on 8-bit,
       16-bit, and 24-bit displays.

 AUTHOR:
       FANNING SOFTWARE CONSULTING
       David Fanning, Ph.D.
       1645 Sheely Drive
       Fort Collins, CO 80526 USA
       Phone: 970-221-0438
       E-mail: davidf@dfanning.com
       Coyote's Guide to IDL Programming: http://www.dfanning.com

 CATEGORY:
       Widgets, Colors.

 CALLING SEQUENCE:
       CHGCOLOR, index

 REQUIRED INPUTS:
       INDEX: The color index to be changed. It must be a value
       between 0 and 255.

 KEYWORD PARAMETERS:

       LABEL: Text that goes next to the color window. The default is
       "Resulting Color".

       GROUP_LEADER: The group leader for this program. When the group leader
       is destroyed, this program will be destroyed.

       NOTIFYID: A a 2 column by n row array that contains the IDs of widgets
       that should be notified when CHGCOLOR changes a color. The first
       column of the array contains widgets that should be notified. The
       second column contains IDs of widgets that are at the top of the
       hierarch in which the corresponding widgets in the first column
       are located. (The purpose of the top widget IDs is to make it
       possible for the widget in the first column to get the "info"
       structure of the widget program.) An CHGCOLOR_LOAD event will be
       sent to the widget identified in the first column. The event
       structure is defined like this:

       event = {CHGCOLOR_LOAD, ID:0L, TOP:0L, HANDLER:0L, $
          r:(!D.N_COLORS < 256), g:(!D.N_COLORS < 256), b:(!D.N_COLORS < 256)}

       The ID field will be filled out with NOTIFYID(0, n) and the TOP
       field will be filled out with NOTIFYID(1, n).

       TITLE: This is the window title. It is "Modify Drawing Color" by
       default. The program is registered with the name "chgcolor " plus
       the TITLE string. The register name is checked before the widgets
       are defined. This gives you the opportunity to have multiple copies
       of CHGCOLOR operating simultaneously. (For example, one will change
       the background color and one will change the plotting color.)

       XOFFSET: This is the X offset of the program on the display. The
       program will be placed approximately in the middle of the display
       by default.

       YOFFSET: This is the Y offset of the program on the display. The
       program will be placed approximately in the middle of the display
       by default.

 COMMON BLOCKS:
       None.

 SIDE EFFECTS:
       Color at the specified index is changed. Events are sent to widgets
       if the NOTIFYID keyword is used.

 RESTRICTIONS:
       None.

 EXAMPLE:
       To change the background color of a plot, type:

       CHGCOLOR, !P.Background

       To see a more complete example, look at the program SLICE
       in the Coyote Software Library:

          ftp://ftp.frii.com/pub/dfanning/outgoing/idl_examples

 MODIFICATION HISTORY:
       Written by David Fanning, 23 April 97.
       12 May 97, Fixed a bug in the way colors were loaded when
          a tracking event occurred. DWF
       13 May 97, Added a JUST_REGISTER keyword and set it up for
          running in IDL 5.0 as a non-blocking widget.
       27 Sept 98. Fixed problems caused by IDL 5.1 color changes.
       27 Sept 98. Removed JUST_REGISTER keyword. Made widget non-blocking.
       03 Nov 98. Modified layout and added slider ganging. DWF.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\chgcolor.pro)


CHINIT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CHINIT
 PURPOSE:
       Initializes chart setup.  Good for viewgraphs.
 CATEGORY:
 CALLING SEQUENCE:
       chinit
 INPUTS:
 KEYWORD PARAMETERS:
       Keywords:
         /HARD means plot on postscript printer (else screen).
         /LAND means use landscape mode (else portrait mode).
         UNITS=u  Set plot units to 'inches' (def) or 'cm'.
         BPOSITION=p scalar or array giving list of outline
           offsets in UNITS from edge of page. Def=no outline.
         BTHICKNESS=t scalar or array giving outline thicknesses
           for each outline given in BPOS.  Def=1.
         XOFFSET=xoff  Set chart X offset in UNITS (def=0).
         YOFFSET=yoff  Set chart Y offset in UNITS (def=0).
         /MOVE means just move origin.  The only other keywords
           recognized with /MOVE are XOFFSET and YOFFSET.
           /MOVE should be used on the second and later calls to
           CHINIT to reposition the position of graphics.
         WINSIZE=sz Multiply default screen window size by this factor.
        Output keywords:
         LAST=lst Highest available plot color, returned.
         FONT=f "!17" for screen, null string for /HARD.
           Put in front of first string printed to make
           device independent.
         FACTOR=f text size factor. 1 for /HARD, 0.68 for screen.
           Multiply text size by this for device independence.
 OUTPUTS:
 COMMON BLOCKS:
       chinit_com
 NOTES:
       Notes: Also erases to white and sets default plot
         color to black.  All plot commands may then be
         given in units of inches or cm, whichever were set.
         Plot size:
           Portrait:  7.5 by 10 inches (360 by 480 on screen)
           Landscape: 9.5 by  7 inches (640 by 472 on screen)
         The screen view is not always close to the hard copy.
         Spaces are handled differently, and strings that fit
         for the hardcopy are sometimes too long on the screen.
 MODIFICATION HISTORY:
       R. Sterner, 17 Aug, 1991
       R. Sterner,  9 Jan, 1992 --- added /MOVE, also common.
       R. Sterner,  1 Sep, 1992 --- added WINSIZE

 Copyright (C) 1991, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\chinit.pro)


CHISQR

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

 PURPOSE:

	    Compute the Chi Square statistic of a function and a fit
	    to the function.  

 CALLING SEQUENCE:
 
	    Result=CHISQR(Y,SIGMA_Y,YFIT)
	    
 INPUTS:
	    Y - Input array.
	    
	    SIGMA_Y - Uncertainty in Y.
	    
	    YFIT - Fit to Y.

 PROCEDURE:
 
           CHISQR=TOTAL((Y-YFIT)^2/SIGMAY^2)

 MODIFICATION HISTORY:
 
    David L. Windt, Bell Labs, November 1989
    windt@bell-labs.com

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\windt\chisqr.pro)


CHKSTRU (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CHKSTRU  (function)

 PURPOSE:
        Check validity of a structure and test if necessary
        fields are contained. The result of this function will 
        be 0 if the argument is not a structure (this includes
        undefined values) or if the argument does not contain
        all the tags requested with the FIELDS argument.

 CATEGORY:
        General Programming

 CALLING SEQUENCE:
        res=CHKSTRU(STRUCTURE,FIELDS [,/VERBOSE]) 

 INPUTS:
        STRUCTURE --> the structure to be tested. If STRUCTURE is
             not of type structure, the function will return 0

        FIELDS --> a string or string array with field names to 
             be contained in STRUCTURE. CHKSTRU returns 1 (true)
             only if all field names are contained in STRUCTURE.
             The entries of FIELDS may be upper or lowercase.

 KEYWORD PARAMETERS:
        INDEX --> a named variable that will contain the indices of
             the required field names in the structure. They can then
             be assessed through structure.(index(i)) . Index will
             contain -1 for all fields entries that are not in the
             structure.

        /VERBOSE --> set this keyword to return an error message 
             in case of an error.

 OUTPUTS:
        CHKSTRU returns 1 if successful, otherwise 0.

 SUBROUTINES:

 REQUIREMENTS:

 NOTES:
        This routine should still work with IDL 5.0 or even 4.0

 EXAMPLE:
        test = { a:1, b:2, c:3 }
        required = ['a','c']
        if CHKSTRU(test,required) then print,'found a and c.'

 MODIFICATION HISTORY:
        mgs, 02 Mar 1998: VERSION 1.00
        mgs, 07 Apr 1998: - second parameter (FIELDS) now optional
        mgs, 23 Aug 2000: - changed copyright to open source
                          - changed array indices to [] and "emacsified"

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\chkstru.pro)


CHOICE

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

 PURPOSE:
        Allows user to choose interactively from several options

 CATEGORY:
        General Programming

 CALLING SEQUENCE:
        RESULT = CHOICE(VALUES [,options])

 INPUTS:
        VALUES  -> a string array containing the selectable options

 KEYWORD PARAMETERS:
        TITLE -> title to be displayed on top of the selection menu
        DEFAULT -> a default selection (to allow user to simply press enter)
        BY_INDEX  -> return selection index rather than value
        /NOABORT -> prevents addition of 'ABORT' to selection

 OUTPUTS:
        CHOICE returns a string containing the selected value or
            the index of the selection if keyword /BY_INDEX is set.

 SUBROUTINES:

 REQUIREMENTS:

 NOTES:
        CHOICE automatically adds 'ABORT' to the list of selections.
            If keyword BY_INDEX is set then ABORT will return -1
            (unless /NOABORT keyword is set)

 EXAMPLE:
        DIRNAMES = ['~my/dir/','~your/dir/','~any/dir']
        DIR = CHOICE(DIRNAMES,TITLE='Select Directory')

        IF (DIR ne 'ABORT') THEN BEGIN
            OPENR, U1, DIR+FILE, /GET_LUN
            READF, U1, DATA
            CLOSE, U1
            FREE_LUN,U1
        ENDIF ELSE PRINT,'ABORTED !'


 MODIFICATION HISTORY:
        mgs, 26 Sep 1997: VERSION 1.00
        mgs, 17 Nov 1998: - added DEFAULT and NOABORT keywords
        mgs, 23 Aug 2000: - changed copyright to open source

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\choice.pro)


CINDEX

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

 PURPOSE:
       This is a program for viewing the current colors in the
       colortable with their index numbers overlayed on each color.
       On 24-bit systems you must click the cursor in the graphics window
       to see the colors in the current color table.

 AUTHOR:
       FANNING SOFTWARE CONSULTING
       David Fanning, Ph.D.
       1645 Sheely Drive
       Fort Collins, CO 80526 USA
       Phone: 970-221-0438
       E-mail: davidf@dfanning.com
       Coyote's Guide to IDL Programming: http://www.dfanning.com

 CATEGORY: Graphics

 CALLING SEQUENCE:  CIndex

 INPUTS:   None.

 Optional Inputs:   None

 OUTPUTS:  None

 OPTIONAL OUTPUTS:  None

 KEYWORD Parameters:   None

 COMMON BLOCKS:  None

 SIDE EFFECTS:   None

 RESTRICTIONS:   Reqires XCOLORS and TVIMAGE from the Coyote Library:

                     http://www.dfanning.com/programs/xcolors.pro
                     http://www.dfanning.com/programs/xtvimage.pro

 PROCEDURE:

  Draws a 31x25 set of small rectangles in 256 different colors.
  Writes the color index number on top of each rectangle.

 MODIFICATION HISTORY:  Written by David Fanning, May 1995

  Widgetized and made it work in 24-bit color. Colors are
     updated by clicking in window. 22 Oct 98. DWF
  Replace POLYFILL with TV command to avoid underflow error in
     Z-buffer. 8 March 99. DWF
  Fixed a problem with 24-bit devices with color decomposition ON. 15 Feb 2000. DWF.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\cindex.pro)


CIRCLE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		CIRCLE
 VERSION:
		4.0
 PURPOSE:
		Draws a circle, around CENTER, with radius given by RADIUS, X_RADIUS,
		or Y_RADIUS.  The drawing is done in the currently defined plot area.
		One and ONLY ONE of the three radius values MUST be provided.  RADIUS
		and X_RADIUS are equivalent.  Alternatively, a *SHAPE* representation
		(see SHAPE_VER for definition) of the circle may be returned through
		the SHAPEOUT keyword.  DATA coordinates are used unless one of the
		keywords /DEVICE or /NORMAL is set.  The circle is drawn so as to
		appear visually as a circle, regardless of the coordinates used.
 CATEGORY:
		General Graphics.
 CALLING SEQUENCE:
		CIRCLE, CENTER = C, {RADIUS=R, X_RADIUS=XR, Y_RADIUS = YR} [, keywords]
 INPUTS:
		None.
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
	CENTER
		Two dimensional vector, circle center location, mandatory.
	RADIUS							|
		Scalar, value of radius (measured in the X direction).	| One
	X_RADIUS							| and only one
		Scalar, value of radius (measured in the X direction).	| must be
	Y_RADIUS							| provided.
		Scalar, value of radius (measured in the Y direction).	|
	/FILL
		Switch.  causes the circle to be filled with a solid pattern.
	/DEVICE
		Standard IDL plotting interpretation.
	/NORMAL
		Ditto.
	/NO_SHOW
		Switch.  If set, no plotting is done, but the shape is generated and
		may be returned through SHAPEOUT.
	SHAPEOUT
		Optional output, see below.
	_EXTRA
		A formal keyword used to pass all plotting keywords.  Not to be used
		directly.  See comment in RESTRICTIONS.
 OUTPUTS:
		None.
 OPTIONAL OUTPUT PARAMETERS:
	SHAPEOUT
		When provided with the name of a variable, on return the variable
		contains the *SHAPE* representation of the circle.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		While nominally all graphics keywords can be passed (through _EXTRA),
		care should be exercised to use only the applicable ones (ELLIPSE and
		PLOTS keywords usually, POLYFILL keywords when /FILL is used.
 PROCEDURE:
		Uses calls to COO_CONV, ONE_OF and SHAPE_COCON from MIDL.  Converts all
		parameters to device coordinates and calls ELLIPSE (also from MIDL)
		to do the actual plotting.
 MODIFICATION HISTORY:
		Created 15-JUL-1991 by Mati Meron.
		Modified 15-DEC-1993 by Mati Meron.  Now CIRCLE takes advantage of the
		keyword inheritance property and accepts all IDL plotting keywords.
		Modified 25-JUL-1999 by Mati Meron.  Added keywords NO_SHOW and
		SHAPEOUT.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\circle.pro)


CLASSIFY

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:         CLASSIFY

 FUNCTION:
            Display the physical locations of points selected on the
            basis of image quantities, xa and ya.  An interactive
            cursor box is used to select clusters of points from the
            2-d scatter plot of xa vs ya. These points are drawn on a
            satellite image to indicate their actual physical
            location.

 CALLING SEQUENCE:

       classify,xa,ya,class_out,image=image,class_in=class_in,select=select, $
              n_samples=n_samples,blow_up=blow_up,title=title,ytitle=ytitle, $
              xtitle=xtitle,ititle=ititle

 CATEGORY:
       Interactive graphics

 REQUIRED INPUTS:
       XA       First channel parameter, x-axis of scatter plot
       YA       Second channel parameter, y-axis of scatter plot

 OPTIONAL INPUTS (keyword parameters):
       IMAGE    Image of a particular satellite channel over which 
                points are ploted.  If not supplied points are ploted
                over blank plot

    CLASS_IN    (Byte array) Pixel color class initialization.  Each
                element corresponds to one pixel in the sample set
                (see n_samples, below). An initial run of CLASSIFY
                will generate the byte array, CLASS_OUT.  This can be
                used in a subsequent run of CLASSIFY with
                CLASS_IN=CLASS_OUT to restart CLASSIFY in its former
                state.  When set, CLASS_IN overrides the effect of
                SELECT and N_SAMPLES, below.

    N_SAMPLES   2 element vector specifying the number of samples in the
                x and y directions.  E.g., if N_SAMPLES=[100,150],
                then the scatter plot will consist of a 100x150
                element subset of the original image.  If N_SAMPLES
                is not set, a default number of samples in the x and
                y directions is used.
                
                
       SELECT   Vector of pre-selected indices (longword integers). 
                For example, SELECT=WHERE(XX LT 10) chooses only
                those sample points for which parameter xx
                is less than 10.

      BLOW_UP   Two element vector of specifying the image size blowup factor 

       TITLE    Title of scatter plot 
       XTITLE   Scatter plot x-axis label
       YTITLE   Scatter plot y-axis label
       ITITLE   Plot title of satellite image
       NO_COLOR don't use color, show points with unique symbols

 OUTPUTS
     CLASS_OUT  (Byte array) Color class of each sample point.  Values
                between 1 - 6 indicate different selected color
                classes.  Greater values indicate unselected points
                which can be selected with the cursor. CLASS_OUT can
                be used in another call to CLASSIFY, e.g.,
                CLASSIFY,XA,YA,CLASS_OUT ; followed by,
                CLASSIFY,XA,YA,CLASS_IN=CLASS_OUT


 COMMON BLOCKS:
       none

 SIDE EFFECTS:
       Two windows are created to contain the scatter plot (window 0) and
       the physical image (window 2).  Calls TVLCT to load a customized 
       color table with grey scale for byte values greater than 10 and
       discreet colors for byte values between 1 and 10.

 RESTRICTIONS:
       Works only on window system drivers

 PROCEDURE:
       Points which enter into the cursor box are hi-lighted and stored
       for plotting on the satellite image.  The left mouse button increases
       the size of the cursor box while the middle mouse button decreases it
       The right mouse button stops the selection process and displays a 
       pop-up menu with 4 options:

       (n) select a new selection class (assign a new color)
       (r) reset the selection set
       (d) display the selection set on the satellite image
       (p) save current plot to postscript file "plot.ps"
       (q) clean up displays and quit

  author:  Paul Ricchiazzi                            oct92 
           Institute for Computational Earth System Science
           University of California, Santa Barbara

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\classify.pro)


CLASSPLT

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:   classplt

 USEAGE:    classplt,xx

            classplt,xx,yy,alat,alon,$
                    [title=title,xtitle=xtitle,ytitle=ytitle,sym=sym]

 PURPOSE:   Draws two seperate plots to the graphics device:
            1. 2-d scatter plot of yy vs xx
            2. physical position of selected classes with respect
               to coastline features.
 
 INPUT:
     xx       index array of selected points for a class 
              (class definition mode)

     xx       2-D array, x quantity of scatter plot (ploting mode)
     yy       2-D array, y quantity of scatter plot     
     alat     latitude array
     alon     longitude array
     title    plot title (optional).  One or two element string array
              if two strings are specified the first string is used to
              title the scatter plot while the second titles the mapped
              plot
     xtitle   x title (optional)
     ytitle   y title (optional)
     sym      a vector of symbol index values.  Classes are assigned symbols
              in the sequence specified in SYM. (default=[1,4,7,5,6,2])
              (1=+, 2=*, 3=., 4=diamond, 5=triangle, 6=square, 7=x)


 PROCEDURE:   At least two steps are required to make plots with CLASSPLT: 

              1. In class definition mode CLASSPLT is called with a single 
                 argument one or more times to accumulate class definitions
                 to be used later in the ploting mode.
              2. In plotting mode CLASSPLT is called with at least 4 
                 arguments.  In this mode CLASSPLT produces a scatter 
                 plot and position plot of the previously defined classes.

 EXAMPLE:

 a4=congrid(avhrr4,40,30)                        ; reduce size of sample set
 a3=congrid(avhrr3,40,30)                        ;   could also use SUPERPIX

 classplt,inside(a4,a3-a4,[3,6,5,3],[4,3,5,4])   ; define classes
 classplt,where(a4 gt -6 and a3-a4 lt 8)         ;
 classplt,where(a4 gt -17 and a3-a4 gt 8)        ; 

 classplt,a4,a3-a4,alat,alon                     ; make the plot

 Here is a sequence of commands which uses the interactive graphics
 procedure, INSIDE, to simplify class specifcation.
 
 classplt,inside(a4,a3-a4)
 classplt,inside(a4,a3-a4)
 classplt,inside(a4,a3-a4)
 classplt,a4,a3-a4,alat,alon

 COMMON BLOCKS: classblk


  author:  Paul Ricchiazzi                            oct92 
           Institute for Computational Earth System Science
           University of California, Santa Barbara

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\classplt.pro)


CLIPBOARD

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

 PURPOSE:

       The purpose of this program is to copy the contents of a
       graphics window to the clipboard for subsequent pasting into
       applications such as Photoshop or Powerpoint.

 AUTHOR:

   FANNING SOFTWARE CONSULTING
   David Fanning, Ph.D.
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: davidf@dfanning.com
   Coyote's Guide to IDL Programming: http://www.dfanning.com/

 CATEGORY:

      Graphics.

 CALLING SEQUENCE:

      CLIPBOARD, window_index

 OPTIONAL INPUTS:

       window_index:    The window index number of the graphics window to
                        copy. If absent, the current graphics window is used
                        by default.

 OUTPUTS:
       None.

 COMMON BLOCKS:
       None.

 DEPENDENCIES:

       Uses the IDLgrClipboard object introduced in IDL 5.2(?).

 PROCEDURE:

       Copies the window contents to a clipboard object.

 EXAMPLE:

        IDL> Window
        IDL> Plot, Findgen(11)
        IDL> CLIPBOARD

 RESTRICTIONS:

       May not work for all applications. Applications tested successfully
       include: Framemaker, Powerpoint, Photoshop, Excel, Microsoft Word.
       Converts 24-bit images to 2D images with color tables.

 MODIFICATION HISTORY:

       Written by: David W. Fanning, 24 October 2001.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\clipboard.pro)


CLIPRANGE

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:    cliprange

 PURPOSE:    compute greyscale range for images, allowing for a fixed 
             percentage of the pixels to be within the greyscale range.

 USEAGE:     result=cliprange(qval,clip_top,clip_bot)

 INPUT:
   qval      image array
   clip_top  fraction of pixels to be clipped off top of range
   clip_bot  fraction of pixels to be clipped off bottom of range

 OUTPUT:     result=[range_bot,range_top], where range_bot and range_top
             are the numerical range of the color scale
             
 EXAMPLE:    compute colorscale range such that 99% of the pixels are
             within the range:
 
             range=cliprange(image,.005,.005) 

  author:  Paul Ricchiazzi                            sep93
           Institute for Computational Earth System Science
           University of California, Santa Barbara

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\cliprange.pro)


CLOSEDEV

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

 PURPOSE:
   This procedure close teh open graphic device

 CATEGORY:
   PLOT/MPLOT

 CALLING SEQUENCE:
   CLOSEDEV

 MODIFICATION HISTORY:
   Written by:    F. Holland, 19 Jun, 1997
   Modified:      T.B. 1997-Nov

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\closedev.pro)


CLOSE_DEVICE[1]

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

 PURPOSE:
        CLOSE_DEVICE closes the PostScript device and spawns
        a print job to the printer specified by the user or
        it can be used to close a graphics window.

 CATEGORY:
        Printing

 CALLING SEQUENCE:
        CLOSE_DEVICE [,OLD_DEVICE] [,keywords]

 INPUTS:
        OLD_DEVICE (str) -> Name of device that shall become the active
             plotting device. If omitted, "X", "WIN" or "MAC" will be
             set depending on !VERSION.OS_FAMILY. Hence, specification of
             OLD_DEVICE is only rarely needed.
             This parameter works together with the OLD_DEVICE parameter
             of OPEN_DEVICE which returns the device name before the
             postscript device (or a graphics device) is opened.
             The OLD_DEVICE parameter can be misused to set the output 
             device to anything! Therefore, it's probably safest to not 
             use it and stick with the operating system dependent default.

 KEYWORD PARAMETERS:
        LABEL -> a string that contains an annotation for a postscript
             plot (usually a user name and/or filename). The current 
             data and time will be appended if TIMESTAMP is set. 
             NOTE: TIMESTAMP will produce an annotation even if LABEL
             is not provided. The annotation is only added to postscript 
             plots and only if the ps file is actually open.

        /TIMESTAMP  -> add date and time to the LABEL on the plot.
             If no LABEL is provided, the username and filename (value 
             of FILENAME will be used or the filename of the current 
             postscript file will be added). The timestamp is only added 
             to postscript plots and only on the last page.

        PRINTER    (str) -> name of the printer queue to send output to.
             Default is 'none', i.e. the postscript file will only be 
             closed and can then be manually printed e.g. using the Unix 
             lpr command. Direct printing only works in Unix environments.

        WINDOW -> window number to be closed (or -1 if current)

        _EXTRA -> any additional keywords to CLOSE_DEVICE will be
             passed on to STRDATE which is used to format the date
             and time string. Possible values are: /SHORT, /SORTABLE,
             /GERMAN.

        LCOLOR -> the color value for the LABEL (default 1).

        LPOSITION -> the position of the LABEL in normalized coordinates
             (a two-element vector with default [0.98,0.007]).

        LSIZE -> the charcter size of the LABEL (default 0.7).

        LALIGN -> the alignment of the LABEL (default 1).

        FILENAME   (str) -> name of the PostScript file.
             This keyword is now obsolete since the name of the postscript 
             file is determined automatically. It is kept as a surrogate 
             for LABEL to ensure compatibility with older implementations. 

 OUTPUTS:
        If postscript device is active, a *.ps file will be closed and 
        optionally sent to the printer.

 SUBROUTINES:

 REQUIREMENTS:
        Needs STRDATE for the TIMESTAMP option.

 NOTES: 
        The WINDOW keyword is only evaluated if the current device supports 
        windows [!D.FLAGS AND 256) GT 0]. If you only want to close a 
        postscript file and don't fuss around with your screen windows
        then simply don't set this keyword.

        23 Aug 2000:
        I am about to change to Liam Gumley's method for opening
        postscript files. This routine is merely kept for compatibility!

 EXAMPLE:
        CLOSE_DEVICE
            closes a postscript file (if opened) and resets the current
            plotting device to 'X', 'WIN', or 'MAC' depending on the
            OS_FAMILY.

        CLOSE_DEVICE, PRINTER='hplj4', LABEL='mgs', /TIMESTAMP
            If current device name is PS then the postscript file will
            be closed, a user, date and time label will be added and 
            the file will be spooled to the  printer queue 'hplj4'. 
            NOTE: Printing of the file fails if you specified FILENAME as 
            a relative path in the OPEN_DEVICE command and you changed your 
            working directory while the device was opened.
  
        CLOSE_DEVICE, WIN=-1
            If current device name is PS then the postscript file will
            be closed. If the current device is a screen device (that 
            supports windows), then the active window will be deleted.
 
 MODIFICATION HISTORY:
        bmy, 18 Aug 1997: VERSION 1.00
        bmy, 19 Aug 1997: VERSION 1.01
        mgs, 20 Aug 1997: VERSION 1.02
        mgs, 08 Apr 1998: VERSION 2.00 
           - automatic filename detection
           - default device depending on OS_FAMILY
        mgs, 21 May 1998: 
           - added L.. keywords to control label and timestamp output
        mgs, 18 Nov 1998:
           - added output of username as default in timestamp

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\close_device.pro)


CLOSE_DEVICE[2]

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

 PURPOSE:
   This procedure close the open graphic device

 CATEGORY:
   PLOT/MPLOT

 CALLING SEQUENCE:
   CLOSE_DEVICE

 KEYWORD PARAMETERS:
   If the following graphical keywords are provided they are multiplied by
   the quoted factors if a non-screen device is closed.

         CHARSIZE = charsize (factor 1./1.72)
         SYMSIZE = symsize (factor 1./1.72)
         THICK = thick (factor 1./2.0)
         CHARTHICK = charthick (factor 1./2.0)
         XTHICK = xthick (factor 1./2.0)
         YTHICK = ythick (factor 1./2.0)

 MODIFICATION HISTORY:
   Written by:    F. Holland, 19 Jun, 1997
   Modified:      T.B. 1997-DEC-16
   15.02.2000:    charsize and symsize are divided by 1.72 (size_factor),
                       thick, charthick, xthick, and ythick are divided by 2.0 (thick_factor)

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\close_device.pro)


CLOUD_ART

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:  cloud_art

 PURPOSE:  draw an idealized cloud

 USEAGE:   cloud_art,pos,bumps=bumps

 INPUT:    
  pos      normal coordinates of cloud frame, [xll,yll,xur,yur]
           where ll=lower left corner and ur=upper right corner


 KEYWORD INPUT:
  bumps    number of bumps on upper side of cloud. (default=6)
  

 OUTPUT:

 DISCUSSION:

 LIMITATIONS:

 COMMON BLOCKS:

 SIDE EFFECTS:
  
 EXAMPLE:  

    w8x11
    cloud_art,[.1,.8,.9,.9],bumps=8

 AUTHOR:   Paul Ricchiazzi                        15 Mar 96
           Institute for Computational Earth System Science
           University of California, Santa Barbara
           paul@icess.ucsb.edu

 REVISIONS:

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\cloud_art.pro)


CLR_SCALE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CLR_SCALE
 PURPOSE:
       Clear image scaling values embedded by put_scale.
 CATEGORY:
 CALLING SEQUENCE:
       clr_scale, [img]
 INPUTS:
 KEYWORD PARAMETERS:
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
       Notes: Pixel value 90 is used to overwrite pixels 0 to 89
         if 1234567890 is found in the first 10 pixels.
 MODIFICATION HISTORY:
       R. Sterner, 1995 Feb 28

 Copyright (C) 1995, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\clr_scale.pro)


CLSTRSHD

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:           clstrshd

 USEAGE:            result=clstrshd(a, binsz)
                    result=clstrshd(a, binsz, /align, /compare)

 PURPOSE:           compute super pixel cluster shade statistical test
                    of a scene. the cluster shade is a test of skewness
                    in the greylevel histogram of each superpixel.

 INPUT:
         a          image array

         binsz      A scalar specifying the number of horizontal and 
                    vertical sub-pixels in one super pixel. 
                    BINSZ must be an odd integer.

         align      If set, output arrays are REBINed back up to the 
                    original size and output array cell centers are aligned
                    with input array cell centers.

         compare    if set, compare A and ABIN with the FLICK procedure

 OUTPUT:
                    cluster shade value at superpixel cell centers.

 AUTHOR:            Paul Ricchiazzi    oct92 
                    Earth Space Research Group, UCSB

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\clstrshd.pro)


CM2NORM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CM2NORM
 PURPOSE:
       Convert from cm to normalized coordinates.
 CATEGORY:
 CALLING SEQUENCE:
       cm2norm, xcm, ycm, xn, yn
 INPUTS:
       xcm, ycm = coordinates of a point in cm.   in
       poscm = plot page position in cm.          in
 KEYWORD PARAMETERS:
 OUTPUTS:
       xn, yn = same point in normalized system.  out
       or
       cm2norm, poscm, posn
         posn = page position in normalized system. out
           the page position arrays have the format: [x1,y1,x2,y2]
           where (x1,y1) = lower left corner,
           and (x2,y2) = upper right corner of plot area.
 COMMON BLOCKS:
 NOTES:
       Notes: Be sure plot device is set first.
         For postscript plots call psinit first.
 MODIFICATION HISTORY:
       R. Sterner 13 Nov, 1989

 Copyright (C) 1989, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\cm2norm.pro)


CMAPPLY

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

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

 PURPOSE:
   Applies a function to specified dimensions of an array

 MAJOR TOPICS:
   Arrays

 CALLING SEQUENCE:
   XX = CMAPPLY(OP, ARRAY, DIMS, [/DOUBLE], [TYPE=TYPE])

 DESCRIPTION:
   CMAPPLY will apply one of a few select functions to specified 
   dimensions of an array.  Unlike some IDL functions, you *do* have
   a choice of which dimensions that are to be "collapsed" by this
   function.  Iterative loops are avoided where possible, for 
   performance reasons.

   The possible functions are:             (and number of loop iterations:)
     +     - Performs a sum (as in TOTAL)       number of collapsed dimensions
     AND   - Finds LOGICAL "AND" (not bitwise)  same
     OR    - Finds LOGICAL "OR"  (not bitwise)  same
     *     - Performs a product                 LOG_2[no. of collapsed elts.]

     MIN   - Finds the minimum value            smaller of no. of collapsed
     MAX   - Finds the maximum value            or output elements

     USER  - Applies user-defined function      no. of output elements


   It is possible to perform user-defined operations arrays using
   CMAPPLY.  The OP parameter is set to 'USER:FUNCTNAME', where
   FUNCTNAME is the name of a user-defined function.  The user
   defined function should be defined such that it accepts a single
   parameter, a vector, and returns a single scalar value.  Here is a
   prototype for the function definition:

      FUNCTION FUNCTNAME, x, KEYWORD1=key1, ...
         scalar = ... function of x or keywords ...
         RETURN, scalar
      END

   The function may accept keywords.  Keyword values are passed in to
   CMAPPLY through the FUNCTARGS keywords parameter, and passed to
   the user function via the _EXTRA mechanism.  Thus, while the
   definition of the user function is highly constrained in the
   number of positional parameters, there is absolute freedom in
   passing keyword parameters.

   It's worth noting however, that the implementation of user-defined
   functions is not particularly optimized for speed.  Users are
   encouraged to implement their own array if the number of output
   elements is large.


 INPUTS:

   OP - The operation to perform, as a string.  May be upper or lower
        case.

        If a user-defined operation is to be passed, then OP is of
        the form, 'USER:FUNCTNAME', where FUNCTNAME is the name of
        the user-defined function.

   ARRAY - An array of values to be operated on.  Must not be of type
           STRING (7) or STRUCTURE (8).

 OPTIONAL INPUTS:

   DIMS - An array of dimensions that are to be "collapsed", where
          the the first dimension starts with 1 (ie, same convention
          as IDL function TOTAL).  Whereas TOTAL only allows one
          dimension to be added, you can specify multiple dimensions
          to CMAPPLY.  Order does not matter, since all operations
          are associative and transitive.  NOTE: the dimensions refer
          to the *input* array, not the output array.  IDL allows a 
          maximum of 8 dimensions.
          DEFAULT: 1 (ie, first dimension)

 KEYWORDS:

   DOUBLE - Set this if you wish the internal computations to be done
            in double precision if necessary.  If ARRAY is double 
            precision (real or complex) then DOUBLE=1 is implied.
            DEFAULT: not set

   TYPE - Set this to the IDL code of the desired output type (refer
          to documentation of SIZE()).  Internal results will be
          rounded to the nearest integer if the output type is an
          integer type.
          DEFAULT: same is input type

   FUNCTARGS - If OP is 'USER:...', then the contents of this keyword
               are passed to the user function using the _EXTRA
               mechanism.  This way you can pass additional data to
               your user-supplied function, via keywords, without
               using common blocks.
               DEFAULT: undefined (i.e., no keywords passed by _EXTRA)

 RETURN VALUE:

   An array of the required TYPE, whose elements are the result of
   the requested operation.  Depending on the operation and number of
   elements in the input array, the result may be vulnerable to
   overflow or underflow.

 EXAMPLES:
   Shows how CMAPPLY can be used to total the second dimension of the
   array called IN.  This is equivalent to OUT = TOTAL(IN, 2)

   IDL> IN  = INDGEN(5,5)
   IDL> OUT = CMAPPLY('+', IN, [2])
   IDL> HELP, OUT
   OUT             INT       = Array[5]

   Second example.  Input is assumed to be an 5x100 array of 1's and
   0's indicating the status of 5 detectors at 100 points in time.
   The desired output is an array of 100 values, indicating whether
   all 5 detectors are on (=1) at one time.  Use the logical AND
   operation.

   IDL> IN = detector_status             ; 5x100 array
   IDL> OUT = CMAPPLY('AND', IN, [1])    ; collapses 1st dimension
   IDL> HELP, OUT
   OUT             BYTE      = Array[100]

   (note that MIN could also have been used in this particular case,
   although there would have been more loop iterations).

   Third example.  Shows sum over first and third dimensions in an
   array with dimensions 4x4x4:

   IDL> IN = INDGEN(4,4,4)
   IDL> OUT = CMAPPLY('+', IN, [1,3])
   IDL> PRINT, OUT
        408     472     536     600

   Fourth example. A user-function (MEDIAN) is used:

   IDL> IN = RANDOMN(SEED,10,10,5)
   IDL> OUT = CMAPPLY('USER:MEDIAN', IN, 3)
   IDL> HELP, OUT
   OUT             FLOAT     = Array[10, 10]

   (OUT(i,j) is the median value of IN(i,j,*))

 MODIFICATION HISTORY:
   Mar 1998, Written, CM
   Changed usage message to not bomb, 24 Mar 2000, CM
   Signficant rewrite for *, MIN and MAX (inspired by Todd Clements
     ); FOR loop indices are now type
     LONG; copying terms are liberalized, CM, 22, Aug 2000
   More efficient MAX/MIN (inspired by Alex Schuster), CM, 25 Jan
     2002
   Make new MAX/MIN actually work with 3d arrays, CM, 08 Feb 2002
   Add user-defined functions, ON_ERROR, CM, 09 Feb 2002

  $Id: cmapply.pro,v 1.4 2002/02/09 16:32:23 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmapply.pro)


CMCONGRID

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

 PURPOSE:
       Shrink or expand the size of an array by an arbitrary amount.
       This IDL procedure simulates the action of the VAX/VMS
       CONGRID/CONGRIDI function.

	This function is similar to "REBIN" in that it can resize a
       one, two, or three dimensional array.   "REBIN", however,
       requires that the new array size must be an integer multiple
       of the original size.   CONGRID will resize an array to any
       arbitrary size (REBIN is somewhat faster, however).
       REBIN averages multiple points when shrinking an array,
       while CONGRID just resamples the array.

 CATEGORY:
       Array Manipulation.

 CALLING SEQUENCE:
	array = CONGRID(array, x, y, z)

 INPUTS:
       array:  A 1, 2, or 3 dimensional array to resize.
               Data Type : Any type except string or structure.

       x:      The new X dimension of the resized array.
               Data Type : Int or Long (greater than or equal to 2).

 OPTIONAL INPUTS:
       y:      The new Y dimension of the resized array.   If the original
               array has only 1 dimension then y is ignored.   If the
               original array has 2 or 3 dimensions then y MUST be present.

       z:      The new Z dimension of the resized array.   If the original
               array has only 1 or 2 dimensions then z is ignored.   If the
               original array has 3 dimensions then z MUST be present.

 KEYWORD PARAMETERS:
       INTERP: If set, causes linear interpolation to be used.
               Otherwise, the nearest-neighbor method is used.

	CUBIC:	If set, uses "Cubic convolution" interpolation.  A more
		accurate, but more time-consuming, form of interpolation.
		CUBIC has no effect when used with 3 dimensional arrays.

       MINUS_ONE:
               If set, will prevent CONGRID from extrapolating one row or
               column beyond the bounds of the input array.   For example,
               If the input array has the dimensions (i, j) and the
               output array has the dimensions (x, y), then by
               default the array is resampled by a factor of (i/x)
               in the X direction and (j/y) in the Y direction.
               If MINUS_ONE is present (AND IS NON-ZERO) then the array
               will be resampled by the factors (i-1)/(x-1) and
               (j-1)/(y-1).

       HALF_HALF:
               If set, will tell CONGRID to extrapolate a *half* row
               and column on either side, rather than the default of
               one full row/column at the ends of the array.  If you
               are interpolating images with few rows, then the
               output will be more consistent with this technique.
               This keyword is intended as a replacement for
               MINUS_ONE, and both keywords probably should not be
               used in the same call to CONGRID.

 OUTPUTS:
	The returned array has the same number of dimensions as the original
       array and is of the same data type.   The returned array will have
       the dimensions (x), (x, y), or (x, y, z) depending on how many
       dimensions the input array had.

 PROCEDURE:
       IF the input array has three dimensions, or if INTERP is set,
       then the IDL interpolate function is used to interpolate the
       data values.
       If the input array has two dimensions, and INTERP is NOT set,
       then the IDL POLY_2D function is used for nearest neighbor sampling.
       If the input array has one dimension, and INTERP is NOT set,
       then nearest neighbor sampling is used.

 EXAMPLE:
       ; vol is a 3-D array with the dimensions (80, 100, 57)
       ; Resize vol to be a (90, 90, 80) array
       vol = CONGRID(vol, 90, 90, 80)

 MODIFICATION HISTORY:
       DMS, Sept. 1988.
       DMS, Added the MINUS_ONE keyword, Sept. 1992.
 	Daniel Carr. Re-wrote to handle one and three dimensional arrays
                    using INTERPOLATE function.
 	DMS, RSI, Nov, 1993.  Added CUBIC keyword.
       Craig Markwardt, Dec, 1997.  Added halfhalf keyword to
                        more evenly distribute "dead" pixel row
       Use uniformly spaced grid points for half_half W. Landsman   Feb. 2000
              (and slightly modified by C. Markwardt 14 Feb 2000)

  $Id: cmcongrid.pro,v 1.2 2001/03/25 18:10:47 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmcongrid.pro)


CMDHISTORY[1]

[Previous Routine] [Next Routine] [List of Routines]
 This routine retrieves the recall buffer and
 reverses its order to make useful in a text
 widget, skipping empty lines.

 @Hidden

 @Returns
   This function returns the recall buffer in
   reverse order.

 @Author
   JLP - RSI Global Services

 @History
   March 31, 2005 - Initial version

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\CODEBANK\cmdhistory.pro)


CMDHISTORY[2]

[Previous Routine] [Next Routine] [List of Routines]
 This procedure updates the text widget with the
 command buffer values, positioning the scrolling
 text window so the most recent commands are visible.

 @Hidden

 @Param
   Text {in}{required}{type=long}
       Set this parameter to the ID of the text
       widget to be populated.
 @Param
   Commands {in}{required}{type=string vector}
       Set this parameter to the vector of strings
       to populate the text widget.

 @Author
   JLP - RSI Global Services

 @History
   March 31, 2005 - Initial version

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\CODEBANK\cmdhistory.pro)


CMDHISTORY[2]

[Previous Routine] [Next Routine] [List of Routines]
 This procedure manages events from the application.

 @Param
   Event {in}{required}{type=event structure}
       Set this parameter to the event structure generated
       by the GUI.

 @Hidden

 @Uses
   CmdHistory_Get_Commands

 @Author
   JLP - RSI Global Services

 @History
   March 31, 2005 - Initial version

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\CODEBANK\cmdhistory.pro)


CMDHISTORY[3]

[Previous Routine] [Next Routine] [List of Routines]
 This procedure continuously updates a text widget
 with the contents of the IDL command line recall
 buffer.  This allows the user to copy, edit and
 paste useful sequences of commands back to the
 command line, or to an IDL procedure source file.

 @Examples 
   IDL> CMDHISTORY 
@Uses CmdHistory_Event
CmdHistory_Get_Commands @Author JLP - RSI Global Services @History March 31, 2005 - Initial version @File_Comments This tool may be helpful to people who make extensive use of the IDL command line. It creates a continuously- updating editable text widget containing the command line history from which you can copy, edit and paste back to the IDL command line. It is built around the IDL 6.2 function RECALL_COMMANDS.
Learn more about the IDLdoc documentation style at http://www.rsinc.com/codebank/search.asp?FID=100

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\CODEBANK\cmdhistory.pro)


CMPLXGEN

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:      cmplxgen

 USEAGE:       result=cmplxgen(nx,ny[,/center])

 INPUT:
   nx,ny       dimensions of output
 
 KEYWORD INPUT:
   center      if set RESULT is shifted so that the (0,0) point
               is the central element of the complex array

 OUTPUT:     
               float(result)     = array of column indecies
               imaginary(result) = array of row indecies

 EXAMPLE:      r=cmplxgen(4,3)

                          0 1 2 3                      0 0 0 0
               float(r) = 0 1 2 3       imaginary(r) = 1 1 1 1
                          0 1 2 3                      2 2 2 2

 AUTHOR:       Paul Ricchiazzi              oct92
               Earth Space Research Group,  UCSB

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\cmplxgen.pro)


CMPRODUCT

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

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

 PURPOSE:
   CMPRODUCT() is the multiplicative equivalent of TOTAL().

 CALLING SEQUENCE:
   Result = CMPRODUCT(ARRAY)

 DESCRIPTION: 

   Calculates the product of all the elements of an array.  Vector
   multiplication in groups of powers of two make this operation
   faster than a simple FOR loop.  The number of actual
   multiplications is still N_ELEMENTS(ARRAY).  Double precision
   should be used for the highest accuracy when multiplying many
   numbers.

 INPUTS:

   ARRAY - Array of elements to multiply together.  For instance,
           ARRAY could contain the dimensions of another array--then
           CMPRODUCT(ARRAY) would be the total number of elements of
           that other array.

 RETURNS:
  The result of the function is the total product of all the elements
  of ARRAY.

 EXAMPLE:

 SEE ALSO:

   TOTAL, PRODUCT (from Astronomy User's Library)

 MODIFICATION HISTORY:
   Written, CM, 28 Mar 2000
     (based on outline of PRODUCT by William Thompson)

  $Id: cmproduct.pro,v 1.2 2001/03/25 18:10:42 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmproduct.pro)


CMPS_FORM

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

 PURPOSE:
   This function puts up a form the user can configure a PostScript
   device driver. The function result (if the user selects either the
   ACCEPT or CREATE FILE buttons) can be sent directly to the DEVICE
   procedure by means of its _Extra keyword.  User's predefined
   configurations may be retrieved from a common block.

 AUTHOR:
   *********** CM 01 Feb 2000 VERSION *************
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov
   $Id: cmps_form.pro,v 1.4 2001/12/11 20:20:37 craigm Exp $

   Based almost entirely on, but a totally revamped version of, CMPS_FORM by 
   FANNING SOFTWARE CONSULTING (David Fanning Ph.D.) http://www.dfanning.com

 MAJOR TOPICS:
   Device Drivers, Hardcopy Output, PostScript Output

 PROCEDURE:
   This is a pop-up form widget. It is a modal or blocking widget.
   Keywords appropriate for the PostScript DEVICE command are returned.

   Use your LEFT mouse button to move the "Plot Window" around the page.
   Use your RIGHT mouse button to draw your own "Plot Window" on the page.

 HELP:
   formInfo = CMPS_FORM(/Help)

 CALLING SEQUENCE:
    formInfo = CMPS_FORM(xoffset, yoffset, Cancel=cancelButton)

 OPTIONAL INPUTS:

    XOFFSET -- Optional xoffset of the top-level base of cmps_form. Default is
    to try to center the form on the display.

    YOFFSET -- Optional yoffset of the top-level base of cmps_form. Default is
    to try to center the form on the display.

 INPUT KEYWORD PARAMETERS:

    BITS_PER_PIXEL -- The initial configuration of the bits per pixel button.

    BLOCKING -- Set this keyword to make this a blocking widget under IDL 5.0.
    (All widget programs block under IDL 4.0.)

    COLOR -- The initial configuration of the color switch.

    DEFAULTS -- A stucture variable of the same type and structure as the
    RETURN VALUE of cmps_form. It will set initial conditions. This makes
    it possible to start cmps_form up again with the same values it had the
    last time it was called. For example:

       mysetup = cmps_form()
       newsetup = cmps_form(Defaults=mysetup)

    ENCAPSULATED -- The initial configuration of the encapsulated switch.

    FILENAME -- The initial filename to be used on the form.

    HELP -- Prints a helpful message in the output log.

    INCHES -- The initial configuration of the inches/cm switch.

    INITIALIZE -- If this keyword is set, the program immediately returns the
    "localdefaults" structure. This gives you the means to configue the
    PostScript device without interrupting the user.

    SELECT -- used only when INITIALIZE is set.  Set SELECT to a
              string which identifies the predefined configuration to
              be returned by cmps_form when INITIALIZE is set.  This is
              a convenient way to select a predefined config
              non-interactively.

    LANDSCAPE -- The initial configuration of the landscape/portrait switch.

    LOCALDEFAULTS -- A structure like the DEFAULTS structure. If specified,
    then it is added as a predefined configuration entry called "Local".
    See below for a further discussion of predefined configurations.

    PREDEFINED -- An alternate way to specify predefined
                  configurations.  Pass an array of structures to
                  populate the "predefined" dropbox in the
                  dialog. This array, if specified, overrides the the
                  common block technique.

    XOFFSET -- The initial XOffSet of the PostScript window.

    YOFFSET -- The initial YOffSet of the PostScript window.

    XSIZE -- The initial XSize of the PostScript window.

    YSIZE -- The initial YSize of the PostScript window.

    ASPECT -- The aspect ratio of the window (Y/X).  This keyword can
              substitute for one of XSIZE or YSIZE.
 
    PRESERVE_ASPECT -- Set this keyword if you want to hold the
                       aspect ratio constant.

    PAPERSIZE -- If set, allows user to specify the size of the paper
                 media to be printed on, as a scalar string.  NOTE:
                 this specification cannot be passed to DEVICE, but
                 can be selected for completeness's sake.  Default is
                 'Letter'.

    MARGINSIZE -- Size of the margins on all sides.  Default is 0.25 inches.
                  When MARGINSIZE is non-zero, a graphic cannot directly
                  abut the edge of the page.  This is normally a good thing,
                  since there is often a  non-printable region which borders
                  the page.

   DEFAULTPAPER -- Default paper size to use, when it is unspecified
                   in a predefined, "local", or "default"
                   configuration.  This value also overrides any
                   configuration from common blocks.  European users
                   will probably set this to 'A4'.

   PARENT -- if this widget is invoked by another widget program,
             then this keyword parameter must be set to the top level
             widget which is to serve as the group leader.  Failure
             to do so will result in unexpected behavior.  IDL 4
             programs do not need to pass this parameter.  Default:
             NONE.

 OUTPUT KEYWORD PARAMETERS

    CANCEL -- This is an OUTPUT keyword. It is used to check if the user
    selected the "Cancel" button on the form. Check this variable rather
    than the return value of the function, since the return value is designed
    to be sent directly to the DEVICE procedure. The varible is set to 1 if
    the user selected the "Cancel" button. Otherwise, it is set to 0.

    CREATE -- This output keyword can be used to determine if the user
    selected the 'Create File' button rather than the 'Accept' button.
    The value is 1 if selected, and 0 otherwise.

    PAPERSIZE -- If set to a named variable, any newly selected paper
    size is returned in that variable.

    XPAGESIZE -- Size of paper in "X" dimension, in units given by
                 the returned config structure.

    YPAGESIZE -- Size of paper in "Y" dimension, in units given by
                 the returned config structure.

    PAGEBOX -- specifies the page rectangle relative to the plot
               window, in normalized units.  A 4-vector of the form
               [XLL, YLL, XUR, YUR] is returned, giving the positions
               of the lower left (LL) and upper right (UR) corners of
               the page with respect to the plot window.  Thus, the
               following command:

                    PLOT, x, y, position=PAGEBOX

               will construct a graphic whose plot region exactly
               fills the page (with no margin around the edges).

               Naturally, the page is usually larger than the
               graphics window, so the normalized coordinates will
               usually fall outside the range [0,1].

               However, the bounding box constructed by the
               Postscript driver includes only the graphics window.
               Anything drawn outside of it may be clipped or
               discarded.

 RETURN VALUE:

     formInfo = { cmps_form_INFO, $
                  xsize:0.0, $        ; The x size of the plot
                  xoff:0.0, $         ; The x offset of the plot
                  ysize:0.0, $        ; The y size of the plot
                  yoff:0.0 $          ; The y offset of the plot
                  filename:'', $      ; The name of the output file
                  inches:0 $          ; Inches or centimeters?
                  color:0, $          ; Color on or off?
                  bits_per_pixel:0, $ ; How many bits per image pixel?
                  encapsulated:0,$    ; Encapsulated or regular PostScript?
                  isolatin1:0,$       ; Encoded with ISOLATIN1?
                  landscape:0 }       ; Landscape or portrait mode?

 USAGE:

  The calling procedure for this function in a widget program will
  look something like this:

     info.ps_config = cmps_form(/Initialize)

     formInfo = cmps_form(Cancel=canceled, Create=create, $
                          Defaults=info.ps_config)

     IF NOT canceled THEN BEGIN
        IF create THEN BEGIN
           thisDevice = !D.Name
           Set_Plot, "PS"
           Device, _Extra=formInfo

           Enter Your Graphics Commands Here!

           Device, /Close
           Set_Plot, thisDevice
           info.ps_config = formInfo
        ENDIF ELSE
           info.ps_config = formInfo
     ENDIF

 MAJOR FUNCTIONS and PROCEDURES:

   None. Designed to work originally in conjunction with XWindow, a
   resizable graphics window.  [ NOTE: this modified version of
   cmps_form, by Craig Markwardt, is incompatible with the original
   version of XWINDOW. ]

 MODIFICATION HISTORY:

   Based on cmps_form of : David Fanning, RSI, March 1995.
   Major rewrite by: Craig Markwardt, October 1997.
     - Drawing and updating of form and sample box are now modular
     - Option of storing more than one predefined postscript configuration
     - Selection of paper size by name
     - Access to predfined configurations through (optional) common
       block
   Several additions, CM, April 1998  VERSION CM2.0
     - better integration of paper sizes throughout program.
       Predefined configurations now also know about paper.
     - allow passing predefined configurations instead of using
       common block
     - addition of ISOLATIN selection, and streamlining of dialog
       appearance
   Fixed bug in INITIALIZE w.r.t. paper sizes, CM, Nov 1998
   Added SELECT keyword, CM, 09 Dec 1998
   Added Parent keyword to allow modal widgets in IDL 5, 19 Jan 1999
   Added "Choose" button for filename selection, 19 Sep 1999
   Added ability to program different button names, 19 Sep 1999
   Added ASPECT and PRESERVE_ASPECT, based on work by Aaron Barth, 18
     Oct 1999
   Removed NOCOMMON documentation and logic, 19 Oct 1999, CM
   Added aspect to cmps_form_numevents (per Aaron Barth), 18 Oct 1999
   Corrected small bug under Initialize keyword (inches), 18 Oct 1999
   Made call to *_pscoord more consistent, 18 Oct 1999
   Added XPAGESIZE, YPAGESIZE and PAGEBOX keywords, 19 Oct 1999
   Small cosmetic cleanup, CM, 01 Feb 2000
   Fix for IDL 5.5's handling of structures with arrays, CM, 11 Dec 2001

 COMMON BLOCKS:
 
   The user may store frequently used or helpful configurations in a 
   common block, and cmps_form() will attempt to access them.  This
   provides a way for the user to have persistent, named,
   configurations.

   NOTE: this format has changed since the last version.  You may
   have to quit your IDL session for the changes to take effect
   properly.  If you have place a predefined configuration in your
   startup file, you should review the new format.
   
     COMMON CMPS_FORM_CONFIGS, cmps_form_DEFAULT_PAPERSIZE, $
                               cmps_form_STDCONFIGS

        cmps_form_DEFAULT_PAPERSIZE - a string designating the default
                                    paper size, when none is given.
                                    The predefined configurations
                                    offerred by this program will
                                    respect the default value.  (See
                                    also the DEFAULTPAPER keyword.)

        cmps_form_STDCONFIGS - An array of cmps_form_CONFIG structures,
                             each containing information about one
                             predefined configuration, such as its
                             name and size of paper.  Each "config"
                             element is a cmps_form_INFO structure,
                             which contains the actual postscript
                             configuration.

   See the IDL source code cmps_form_LOAD_CONFIGS for an example of how
   to make a list of configurations.  One possibility would be to
   declare and populate the common block from within the user's
   start-up script, allowing the same configurations to appear in
   every session.

   cmps_form() takes its initial list of configurations from this
   common block if it exists.  A default list is provided ala the
   procedure cmps_form_LOAD_CONFIGS.  Any modifications that take place
   during the cmps_form() widget session are not transferred back to
   the common block upon return.  It might be useful to be able to do
   this, through some form of 'save' procedure.

   Also, if the PREDEFINED keyword is used, then the common block is
   not consulted.

  $Id: cmps_form.pro,v 1.4 2001/12/11 20:20:37 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmps_form.pro)


CMREPLICATE

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

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

 PURPOSE:
   Replicates an array or scalar into a larger array, as REPLICATE does.

 CALLING SEQUENCE:
   ARRAY = CMREPLICATE(VALUE, DIMS)

 DESCRIPTION: 

   The CMREPLICATE function constructs an array, which is filled with
   the specified VALUE template.  CMREPLICATE is very similar to the
   built-in IDL function REPLICATE.  However there are two
   differences:

      * the VALUE can be either scalar or an ARRAY.

      * the dimensions are specified as a single vector rather than
        individual function arguments.

   For example, if VALUE is a 2x2 array, and DIMS is [3,4], then the
   resulting array will be 2x2x3x4.

 INPUTS:

   VALUE - a scalar or array template of any type, to be replicated.
           NOTE: These two calls do not produce the same result:
                  ARRAY = CMREPLICATE( 1,  DIMS)
                  ARRAY = CMREPLICATE([1], DIMS)
           In the first case the output dimensions will be DIMS and
           in the second case the output dimensions will be 1xDIMS
           (except for structures).  That is, a vector of length 1 is
           considered to be different from a scalar.

   DIMS - Dimensions of output array (which are combined with the
          dimensions of the input VALUE template).  If DIMS is not
          specified then VALUE is returned unchanged.

 RETURNS:
   The resulting replicated array.  

 EXAMPLE:
   x = [0,1,2]
   help, cmreplicate(x, [2,2])
         INT       = Array[3, 2, 2]
   Explanation: The 3-vector x is replicated 2x2 times.

   x = 5L
   help, cmreplicate(x, [2,2])
         LONG      = Array[2, 2]
   Explanation: The scalar x is replicated 2x2 times.

 SEE ALSO:

   REPLICATE

 MODIFICATION HISTORY:
   Written, CM, 11 Feb 2000
   Fixed case when ARRAY is array of structs, CM, 23 Feb 2000 
   Apparently IDL 5.3 can't return from execute().  Fixed, CM, 24 Feb
     2000
   Corrected small typos in documentation, CM, 22 Jun 2000

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmreplicate.pro)


CMRESTORE

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

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

 PURPOSE:
   Restore variables from an IDL SAVE file.

 CALLING SEQUENCE: (various)
   CMRESTORE, filename                           (implicit)
   CMRESTORE, filename, var1, var2, ..., [, NAMES=names]
   CMRESTORE, filename, DATA=pointers, NAMES=names, PASS_METHOD='POINTER'
   CMRESTORE, filename, DATA=handles,  NAMES=names, PASS_METHOD='HANDLE'
   CMRESTORE, filename, DATA=structure,             PASS_METHOD='STRUCT'
   
 DESCRIPTION: 

   CMRESTORE is a replacement for the built-in IDL procedure RESTORE.
   It restores variables and data from an existing IDL SAVE file,
   written either by SAVE or CMSAVE.  The CMSV utility library must
   be installed in your IDL path to use CMSAVE and CMRESTORE.

   The primary advantage to CMRESTORE is the ability to selectively
   restore only certain variables from the input file (based on
   name).  CMRESTORE provides a number of ways to pass the data
   between routines, typically using a pointer or structure, which
   avoids the unsafe practice of restoring variables in the caller's
   namespace.  However, CMRESTORE can restore variables into the
   caller's namespace, but users should be aware that this capacity
   is somewhat limited in IDL versions 5.2 and below.


 ==================================================================
   Research Systems, Inc. has issued a separate license intended
   to resolve any potential conflict between this software and the
   IDL End User License Agreement. The text of that license
   can be found in the file LICENSE.RSI, included with this
   software library.
 ==================================================================

 COMPATIBILITY:

   -- File Format --

   CMRESTORE should be able to read files written by SAVE and CMSAVE
   from IDL version 4 to version 5.4.

   CMRESTORE cannot restore objects, pointers, compressed files, or
   data sets larger than 2 gigabytes.
   
   Data types available in newer versions of IDL, such as pointers
   and long integers, will not be readable in older versions of IDL
   which do not have those data types.

   -- Calling Interface --

   For the most part, all capabilities of CMRESTORE are available to
   the user.  However, it should be noted that passing variables by
   positional parameter is not available under IDL 4, unless NAMES is
   used to name the variables explicitly.  Also, under IDL versions
   5.2 and previous, it is not possible for CMRESTORE to restore
   variables into the caller's name space if they are not yet
   defined.

   This procedure is part of the CMSVLIB SAVE library for IDL by
   Craig Markwardt.  You must have the full CMSVLIB core package
   installed in order for this procedure to function properly.

 INPUTS:

   FILENAME - the name of the SAVE file.
              Default: none, this parameter must be specified.

   VAR{i} - The values to be restored.  By default the save name is
            taken from the named variables that are passed.  These
            default names can be overridden by using the NAMES
            keyword.

            If no variables are passed as positional parameters, they
            can still be saved using the DATA keyword.  By invoking
            CMRESTORE without positional parameters or DATA,
            CMRESTORE automatically will attempt to restore the
            variables to the calling routine's name space (the
            "implicit" technique).

               NOTE: in IDL 5.2 and below, user routines are not
               allowed to *CREATE* new variables in the caller's name
               space.  CMRESTORE may fail if the variable in
               undefined in the caller.  Therefore you must define it
               before calling CMRESTORE.  The safer practice is to
               use the VAR{i} positional parameters, or the DATA
               keyword.

 KEYWORDS:

   FILENAME - the name of the SAVE file.  The positional FILENAME
              parameter takes precedence over the keyword FILENAME
              parameter.

   PASS_METHOD - a scalar string, describing the method of passing
                 data between the caller and CMRESTORE.  The keyword
                 can take the value 'ARGUMENT', 'POINTER', 'HANDLE'
                 or 'STRUCT'.  A value of 'ARGUMENT' indicates that
                 data values will be passed by command line argument,
                 and is the default.  Other values are described
                 below.

   DATA - A list of data elements to be restored from the output
          file.  The data elements can be one of the following,
          depending on the value of PASS_METHOD.  The means of
          extracting the data, and the method of naming each
          variable, are also indicated.

            * PASS_METHOD='POINTER': An array of pointers to the variables
                    Data: pointed-to value     Name: from NAMES keyword
            * PASS_METHOD='HANDLE':  An array of handles to the variables
                    Data: pointed-to value     Name: from NAMES keyword
            * PASS_METHOD='STRUCT':  A structure containing data to be saved
                    Data: tag value            Name: tag name

          Data values are restored one by one, using the appropriate
          name.  Note that any variables passed as positional
          parameters will cause the DATA keyword to be ignored.

          CMRESTORE will allocate any pointer or handle resources.
          The calling routine is responsible for deallocating any
          pointer or handle resources.

   NAMES - a string array, giving the names for each variable.  

           If the data are passed by positional parameters, the names
           are assigned according to the position of the parameter in
           the procedure call.  

           If the data are passed by an array of pointers or handles,
           then the names are assigned according to the position of
           the data in the array.  In this case there is no other way
           to supply the variable name.  NAMES is required.

           If the data are passed in a structure, then the names are
           assigned according to the position of the data in the
           structure.  The values specified in the names keyword
           override the tag names.

   STATUS - upon return, an integer indicating the status of the
            operation.  A value of 1 indicates success, while 0
            indicates failure.  A failure condition does not
            necessarily indicate that an individual variable could
            not be restored; use the VARSTATUS keyword to detect such
            situations.

   VARSTATUS - upon return, an integer array indicating the status of
               the restore operation for each variable.  A value of 1
               at position i in the array indicates success for the
               ith variable, while a value of 0 indicates failure.

   ERRMSG - upon return, a string indicating the status of the
            operation.  The empty string indicates success, while a
            non-empty string indicates failure and describes the
            error condition.

   QUIET - if set, then the error message is returned to the calling
           routine.  By default an error condition causes execution
           to stop and the message to be printed on the console.

   VERBOSE - if set, then a short message is printed for each
             variable.

 EXAMPLE:

   CMSAVE, VAR1, VAR2, FILENAME='test.sav'
   CMSAVE, VAR1, VAR2, FILENAME='test.sav', NAMES=['A','B']

     Save the data in VAR1 and VAR2 to the file test.sav.  In the
     first case the saved variable names will be VAR1 and VAR2.  In
     the second case the saved variable names will be A and B.

   POINTERS = [ptr_new(VAR1), ptr_new(VAR2)]
   CMSAVE, DATA=POINTERS, NAMES=['A','B'], FILENAME='test.sav'

     Save the data in VAR1 and VAR2 to the file test.sav.  The saved
     variable names will be A and B.

   STRUCTURE = {A: VAR1, B: VAR2}
   CMSAVE, DATA=STRUCTURE, FILENAME='test.sav'

     Save the data in VAR1 and VAR2 to the file test.sav.  The saved
     variable names will be A and B.

 SEE ALSO:

   CMSAVE, SAVE, RESTORE

 MODIFICATION HISTORY:
   Written, 14 May 2000
   Documented, 22 Sep 2000
   Restore into caller's name space now permitted, 11 Jan 2001
   Documented "implicit" restore a little better, w/ errors, 01 Mar 2001
   Make version checks with correct precision, 19 Jul 2001, CM
   Restore with no args automatically does ALL, is this right?,
     CM, 20 Aug 2001
   Added notification about RSI License, 13 May 2002, CM

 $Id: cmrestore.pro,v 1.18 2002/05/13 06:41:10 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmrestore.pro)


CMSAVE

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

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

 PURPOSE:
   Save IDL variables to a file.  (IDL v5 and greater)

 CALLING SEQUENCE: (various)
   CMSAVE, var1, var2, ..., FILENAME=filename [, NAMES=names]
   CMSAVE, DATA=pointers, NAMES=names, FILENAME=filename
   CMSAVE, DATA=handles, NAMES=names,  FILENAME=filename
   CMSAVE, DATA=structure,             FILENAME=filename
   
 DESCRIPTION: 

   CMSAVE is a replacement for the built-in IDL procedure SAVE, with
   more flexibility and increased capabilities.

   CMSAVE produces output files that are compatible with the standard
   save format of IDL versions 4 and 5 (and perhaps greater).
   Variables may be restored by using either the built-in procedure
   RESTORE, or CMRESTORE.  The CMSV utility library must be installed
   in your IDL path to use CMSAVE and CMRESTORE.

   The primary advantages to CMSAVE are the ability to append
   additional variables to an existing SAVE file, and several
   flexible ways to pass the data and variable names to be saved.
   CMSAVE also attempts to run on all IDL versions.

   To append variables to an existing file, simply specify the APPEND
   keyword, and the filename of an existing writable SAVE file.
   Variables will be appended to the end of the file.  It is possible
   to append a variable with the same name as an existing variable in
   a file.  Both data values are stored in the file.  However the
   results upon restore are undefined.  There is also a limitation
   that only one series of heap values -- pointed-to data -- may be
   saved in a file.

   By the normal convention of the built-in SAVE command, both the
   data and variable names to be saved are passed as parameters on
   the command line.  Each parameter must be a named variable; both
   the name and value are saved.

   This convention may be used in invoking CMSAVE as well.  However,
   in addition to passing the data by positional parameter, the user
   can pass the data using the DATA keyword.  If the DATA keyword is
   used, then an array of pointers or handles may be passed, or a
   structure of values may be passed.  (see below)  If both are
   passed, then the positional parameters take precedence.

   It is also possible to explicitly rename the saved variables: the
   saved name does not need to be the name of the named variable.
   Use the NAMES keyword to override the default name.  By default
   the name is drawn from any named variables, or from the structure
   tag names if the DATA keyword is used with a structure.  The NAMES
   keyword takes precedence over these values.  NOTE: Values passed
   by pointer or handle are not named by default, and so will not be
   saved unless the NAMES keyword is used.

 ==================================================================
   Research Systems, Inc. has issued a separate license intended
   to resolve any potential conflict between this software and the
   IDL End User License Agreement. The text of that license
   can be found in the file LICENSE.RSI, included with this
   software library.
 ==================================================================

 COMPATIBILITY:

   -- File Format --
   Files written by CMSAVE should be readable with all known versions
   of IDL at the time of this writing (version 4 - version 5.4).  It
   is expected that this compatibility will persist.

   CMSAVE cannot write objects, compressed files, or data sets larger
   than 2 gigabytes.

   Data types available in newer versions of IDL, such as pointers
   and long integers, will not be readable in older versions of IDL
   which do not have those data types.

   -- Calling Interface --

   For the most part, all capabilities of CMSAVE are available to the
   user.  However, it should be noted that passing variables by
   positional parameter is not available under IDL 4, unless NAMES is
   used to name the variables explicitly.

   This procedure is part of the CMSVLIB SAVE library for IDL by
   Craig Markwardt.  You must have the full CMSVLIB core package
   installed in order for this procedure to function properly.

 INPUTS:

   VAR{i} - The variables to be saved.  By default the save name is
            taken from the named variables that are passed.  These
            default names can be overridden by using the NAMES
            keyword.

            Variables can also be specified by passing an array of
            handles or pointers in the DATA keyword.

            If no variables are passed as positional parameters or
            using DATA, then CMSAVE will assume that *all* variables
            at the caller's level should be saved (this is similar
            behavior to the built-in SAVE routine).  Note that system
            variables cannot be saved with CMSAVE.

 KEYWORDS:

   ALL - for compatibility with the built-in SAVE routine.  Ignored.
         Note that CMSAVE cannot save system variables.

   FILENAME - the name of the output file.
              Default: 'cmsave.sav'

   DATA - A list of data elements to be saved to the output file.
          The data elements can be one of the following.  The means
          of extracting the data, and the method of naming each
          variable, are also indicated.

            * An array of pointers to the variables
                    Data: pointed-to value     Name: from NAMES keyword
            * An array of handles to the variables
                    Data: pointed-to value     Name: from NAMES keyword
            * A 1-element structure containing data to be saved.
                    Data: tag value            Name: tag name

          Data values are saved one by one, using the appropriate
          name.  Note that any variables passed as positional
          parameters will cause the DATA keyword to be ignored.

          The calling routine is responsible for deallocating any
          pointer or handle resources.

   COMPATIBILITY - a string, which describes the format to be used in
          the output file.  Possible values are:

                  'IDL4' - format of IDL version 4;
                  'IDL5' - format of IDL versions 5.0-5.3;
                  'IDL6' - not supported yet, for versions 5.4-above;
                  'RIVAL1' - same as 'IDL5', plus a directory entry is
                            written to the file.
           Note that files written in IDL5 format may still be
           readable by IDL v.4.
           Default: 'IDL5'

   NAMES - a string array, giving the names for each variable.  

           If the data are passed by positional parameters, the names
           are assigned according to the position of the parameter in
           the procedure call.  This can be especially useful to
           rename local variables, and to give names to expressions.

           If the data are passed by an array of pointers or handles,
           then the names are assigned according to the position of
           the data in the array.  In this case there is no other way
           to supply the variable name.  NAMES is required.

           If the data are passed in a structure, then the names are
           assigned according to the position of the data in the
           structure.  The NAMES keyword values override the tag
           names.

   APPEND - if set, then the specified variables are appended to an
            existing file.  

            Repeated variables will not cause an error, however they
            may not be restored properly using the built-in RESTORE
            procedure.  It may also not be permitted to append
            variables that contain heap pointers, to a save file
            which already contains heap data.

   STATUS - upon return, an integer indicating the status of the
            operation.  A value of 1 indicates success, while 0
            indicates failure.  A failure condition does not
            necessarily indicate that an individual variable could
            not be written; use the VARSTATUS keyword to detect such
            situations.

   VARSTATUS - upon return, an integer array indicating the status of
               the save operation for each variable.  A value of 1 at
               position i in the array indicates success for the ith
               variable, while a value of 0 indicates failure.

   ERRMSG - upon return, a string indicating the status of the
            operation.  The empty string indicates success, while a
            non-empty string indicates failure and describes the
            error condition.

   QUIET - if set, then the error message is returned to the calling
           routine.  By default an error condition causes execution
           to stop and the message to be printed on the console.

   VERBOSE - if set, then a short message is printed for each
             variable.

   XDR - for compatibility with the built-in SAVE routine.  Ignored.

 EXAMPLE:

   CMSAVE, VAR1, VAR2, FILENAME='test.sav'
   CMSAVE, VAR1, VAR2, FILENAME='test.sav', NAMES=['A','B']

     Save the data in VAR1 and VAR2 to the file test.sav.  In the
     first case the saved variable names will be VAR1 and VAR2.  In
     the second case the saved variable names will be A and B.

   POINTERS = [ptr_new(VAR1), ptr_new(VAR2)]
   CMSAVE, DATA=POINTERS, NAMES=['A','B'], FILENAME='test.sav'

     Save the data in VAR1 and VAR2 to the file test.sav.  The saved
     variable names will be A and B.  Data are passed by pointer.

   STRUCTURE = {A: VAR1, B: VAR2}
   CMSAVE, DATA=STRUCTURE, FILENAME='test.sav'

     Save the data in VAR1 and VAR2 to the file test.sav.  The saved
     variable names will be A and B.  Data are passed by structure.

 SEE ALSO:

   CMRESTORE, SAVE, RESTORE, CMSVLIB

 MODIFICATION HISTORY:
   Written, 14 May 2000
   Documented, 22 Sep 2000
   Made "more" compatible with SAVE; additional documentation, 11 Jan
     2001, CM
   Make version checks with correct precision, 19 Jul 2001, CM
   Added notification about RSI License, 13 May 2002, CM

 $Id: cmsave.pro,v 1.14 2002/05/13 06:41:10 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsave.pro)


CMSAVEDIR

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

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

 PURPOSE:
   Display a directory of the variables in an IDL SAVE file.

 CALLING SEQUENCE:
   CMSAVEDIR, filename [, /VERBOSE, /QUIET, ... ]
   
 DESCRIPTION: 

   CMSAVEDIR will display a listing of the variables and other
   objects stored in an IDL SAVE file.

   For command-line users the primary function of CMSAVEDIR will be
   to find out what data is stored in a file and when it was saved.
   For that, they simply need to type: CMSAVEDIR, 'myfile.sav'

   CMSAVEDIR also offers a number of features for programmers.
   CMSAVEDIR essentially interrogates the save file and discovers the
   numbers, names and types of each of the variables stored in the
   file.  Programmers can use that information to decide whether or
   how to open a file using the other routines in the CMSVLIB.
   Various keyword parameters are used return this information, as
   documented below.

 ==================================================================
   Research Systems, Inc. has issued a separate license intended
   to resolve any potential conflict between this software and the
   IDL End User License Agreement. The text of that license
   can be found in the file LICENSE.RSI, included with this
   software library.
 ==================================================================

 COMPATIBILITY:

   -- File Format --

   CMSAVEDIR cannot examine compressed save files, or files larger
   than 2 gigabytes.

   This procedure is part of the CMSVLIB SAVE library for IDL by
   Craig Markwardt.  You must have the full CMSVLIB core package
   installed in order for this procedure to function properly.

 INPUTS:

   FILENAME - a scalar string, the name of the file to be examined.

 KEYWORDS:

   VERBOSE - if set, print more detailed information about the input file.

   QUIET - if set, then do not print any output.  Programmers can use
           this keyword to allow CMSAVEDIR to return information
           about the file silently.

   STATUS - upon output, 1 for success, otherwise to indicate
            failure.
   ERRMSG - upon output, if a failure occurs, a message describing
            the error condition.
  
   N_VARIABLES - upon output, the number of variables in the file.
   VAR_NAMES - upon output, contains a string array of the names of
               the variables stored in the file.
   TYPES - upon output, an 11xN_VARIABLES array containing the SIZE
           information of each variable in the file.

   N_PRO - upon output, the number of procedures stored in the file.
   PRO_NAMES - upon output, the names of the procedures stored in the
               file, as a string array.

   N_FUNCTION - upon output, the number of functions stored in the
                 file.
   FUNC_NAMES - upon output, the names of the functions stored in the
                file, as a string array.

   NAMED_STRUCTS - upon output, a string array listing any named
                   structures which appear in the SAVE file.
   NAMED_CLASSES - upon output, a string array listing any named
                   class structures which appear in the SAVE file.

   TIMESTAMP - upon output, contains the timestamp record information
               in a structure.  The fields of the structure are:
                    SAVE_DATE - string - date saved
                    SAVE_USER - string - user who saved file
                    SAVE_HOST - string - host name on which file
                                         saved

   VERSION - upon output, contains the version record information in
             a structure.  The fields of the structure are:
                    FORMAT_VERSION - integer - major format version
                    ARCH    - string - saving host's !VERSION.ARCH
                    OS      - string - saving host's !VERSION.OS
                    RELEASE - string - saving host's !VERSION.RELEASE

   FORCE - if set, will force CMSAVEDIR to open the file even if it
           detects a potential incompatibility.

 EXAMPLE:

   IDL> cmsavedir, 'int_str_intarr.sav'
   ** int_str_intarr.sav
   ** Sun Apr  9 20:28:25 2000 (craigm@beach.gsfc.nasa.gov)
   ** IDL v5.2 (linux)
     A               INT       =        0
     B               STRING    = 'hello'
     C               INT       = Array[3]
   ** 3 variable(s), 0 heap value(s) and 0 procedure(s) in 1376 bytes

 SEE ALSO:

   CMRESTORE, CMSAVE, SAVE, RESTORE, CMSVLIB

 MODIFICATION HISTORY:
   Documented, 12 Jan 2001, CM
   Added USAGE message, 09 Jun 2001, CM
   Fixed bug in printing common variables, 17 Mar 2002, CM
   Added notification about RSI License, 13 May 2002, CM
   

 $Id: cmsavedir.pro,v 1.16 2002/05/13 06:41:10 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsavedir.pro)


CMSET_OP

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

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

 PURPOSE:
   Performs an AND, OR, or XOR operation between two sets

 CALLING SEQUENCE:
   SET      = CMSET_OP(A, OP, B)

 DESCRIPTION: 

   SET_OP performs three common operations between two sets.  The
   three supported functions of OP are:

        OP          Meaning
      'AND' - to find the intersection of A and B;
      'OR'  - to find the union of A and B;
      'XOR' - to find the those elements who are members of A or B 
              but not both;

   Sets as defined here are one dimensional arrays composed of
   numeric or string types.  Comparisons of equality between elements
   are done using the IDL EQ operator.

   The complements of either set can be taken as well, by using the
   NOT1 and NOT2 keywords.  For example, it may be desireable to find
   the elements in A but not B, or B but not A (they are different!).
   The following IDL expressions achieve each of those effects:

      SET = CMSET_OP(A, 'AND', /NOT2, B)   ; A but not B
      SET = CMSET_OP(/NOT1, A, 'AND', B)   ; B but not A

   Note the distinction between NOT1 and NOT2.  NOT1 refers to the
   first set (A) and NOT2 refers to the second (B).  Their ordered
   placement in the calling sequence is entirely optional, but the
   above ordering makes the logical meaning explicit.

   NOT1 and NOT2 can only be set for the 'AND' operator, and never
   simultaneously.  This is because the results of an operation with
   'OR' or 'XOR' and any combination of NOTs -- or with 'AND' and
   both NOTs -- formally cannot produce a defined result.

   The implementation depends on the type of operands.  For integer
   types, a fast technique using HISTOGRAM is used.  However, this
   algorithm becomes inefficient when the dynamic range in the data
   is large.  For those cases, and for other data types, a technique
   based on SORT() is used.  Thus the compute time should scale
   roughly as (A+B)*ALOG(A+B) or better, rather than (A*B) for the
   brute force approach.  For large arrays this is a significant
   benefit.

 INPUTS:

   A, B - the two sets to be operated on.  A one dimensional array of
          either numeric or string type.  A and B must be of the same
          type.  Empty sets are permitted, and are either represented
          as an undefined variable, or by setting EMPTY1 or EMPTY2.

   OP - a string, the operation to be performed.  Must be one of
        'AND', 'OR' or 'XOR' (lower or mixed case is permitted).
        Other operations will cause an error message to be produced.

 KEYWORDS:

   NOT1, NOT2 - if set and OP is 'AND', then the complement of A (for
                NOT1) or B (for NOT2) will be used in the operation.
                NOT1 and NOT2 cannot be set simultaneously.

   EMPTY1, EMPTY2 - if set, then A (for EMPTY1) or B (for EMPTY2) are
                    assumed to be the empty set.  The actual values
                    passed as A or B are then ignored.

   INDEX - if set, then return a list of indices instead of the array
           values themselves.  The "slower" set operations are always
           performed in this case.

           The indices refer to the *combined* array [A,B].  To
           clarify, in the following call: I = CMSET_OP(..., /INDEX);
           returned values from 0 to NA-1 refer to A[I], and values
           from NA to NA+NB-1 refer to B[I-NA].

   COUNT - upon return, the number of elements in the result set.
           This is only important when the result set is the empty
           set, in which case COUNT is set to zero.

 RETURNS:

   The resulting set as a one-dimensional array.  The set may be
   represented by either an array of data values (default), or an
   array of indices (if INDEX is set).  Duplicate elements, if any,
   are removed, and element order may not be preserved.

   The empty set is represented as a return value of -1L, and COUNT
   is set to zero.  Note that the only way to recognize the empty set
   is to examine COUNT.

 SEE ALSO:

   SET_UTILS.PRO by RSI

 MODIFICATION HISTORY:
   Written, CM, 23 Feb 2000
   Added empty set capability, CM, 25 Feb 2000
   Documentation clarification, CM 02 Mar 2000
   Incompatible but more consistent reworking of EMPTY keywords, CM,
     04 Mar 2000
   Minor documentation clarifications, CM, 26 Mar 2000
   Corrected bug in empty_arg special case, CM 06 Apr 2000
   Add INDEX keyword, CM 31 Jul 2000
   Clarify INDEX keyword documentation, CM 06 Sep 2000
   Made INDEX keyword always force SLOW_SET_OP, CM 06 Sep 2000
   Added CMSET_OP_UNIQ, and ability to select FIRST_UNIQUE or
     LAST_UNIQUE values, CM, 18 Sep 2000
   Removed FIRST_UNIQUE and LAST_UNIQUE, and streamlined
     CMSET_OP_UNIQ until problems with SORT can be understood, CM, 20
     Sep 2000 (thanks to Ben Tupper)
   Still trying to get documentation of INDEX and NOT right, CM, 28
     Sep 2000 (no code changes)

  $Id: cmset_op.pro,v 1.2 2001/03/25 18:10:42 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmset_op.pro)


CMSVLIB

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

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

 PURPOSE:
   Initialize the CMSVLIB save library

 CALLING SEQUENCE:
   VALUE = CMSVLIB(/QUERY)
   
 DESCRIPTION: 

   This function initializes the CMSVLIB library to read, write and
   interrogate IDL save files.  Use the QUERY keyword to determine
   whether the full CMSVLIB library is present.

   The procedures in the library are:

    High-level
      CMSAVE - save variables to a save file
      CMRESTORE - restore variables from a save file
      CMSAVEDIR - list contents of a save file 
      CMSVLIB (function) - this file

    Mid-level  
      CMSV_OPEN - open a save file for reading or writing
      CMSVREAD - read non-pointer data from file
      CMSVWRITE - write non-pointer data to file

    Low-level
      CMSV_RREC - read record from save file
      CMSV_RVTYPE - read variable type information from file
      CMSV_RDATA - read variable data from file
      CMSV_WREC - write record to save file
      CMSV_WVTYPE - write variable type information to file
      CMSV_WDATA - write variable data to file

    Utility
      CMSV_RRAW (function) - read raw integer or string data from file
      CMSV_WRAW - write raw integer or string data to file
      CMSV_PTRSUM - create a heap data inventory
      CMSV_TEST - test the library
      TAGSIZE (function) - determine the types of all tags in a structure
      HELPFORM (function) - create HELP-like string describing a variable

   Users should consult 

   This procedure is part of the CMSVLIB SAVE library for IDL by
   Craig Markwardt.  You must have the full CMSVLIB core package
   installed in order for this procedure to function properly.  


 ==================================================================
   Research Systems, Inc. has issued a separate license intended
   to resolve any potential conflict between this software and the
   IDL End User License Agreement. The text of that license
   can be found in the file LICENSE.RSI, included with this
   software library.
 ==================================================================

 INPUTS:

   None

 KEYWORDS:

   QUERY - if set, determine whether the CMSVLIB library is
           installed.  Function returns 1 upon success, 0 upon
           failure.

 EXAMPLE:


 SEE ALSO:

   CMRESTORE, SAVE, RESTORE, CMSVLIB

 MODIFICATION HISTORY:
   Written, 2000
   Documented, 24 Jan 2001
   Added notification about RSI License, 13 May 2002, CM

 $Id: cmsvlib.pro,v 1.3 2002/05/13 06:41:10 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsvlib.pro)


CMSVREAD

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

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

 PURPOSE:
   Read a single variable from an open SAVE file

 CALLING SEQUENCE:

   CMSVREAD, UNIT, DATA [, NAME=NAME, /NO_DATA, VERSION=VERSION,
                           TIMESTAMP=TIMESTAMP ]
   
 DESCRIPTION: 

   CMSVREAD reads a single IDL variable from an open IDL SAVE file.
   The file should already have been opened as a normal file using
   OPENR.

   CMSVREAD is a simplified version of the CMSVLIB package, and as
   such is not capable of reading heap data (pointers) or object
   data.  Strings, structures, and all array types are supported.

   This procedure is part of the CMSVLIB SAVE library for IDL by
   Craig Markwardt.  You must have the full CMSVLIB core package
   installed in order for this procedure to function properly.

 ==================================================================
   Research Systems, Inc. has issued a separate license intended
   to resolve any potential conflict between this software and the
   IDL End User License Agreement. The text of that license
   can be found in the file LICENSE.RSI, included with this
   software library.
 ==================================================================

 INPUTS:

   UNIT - the open file unit.

   DATA - a named variable, into which the new data is to be read.

 KEYWORDS:

   NAME - upon output, the name of the saved variable is returned in
          this keyword.  If a failure or end of file condition
          occurs, name will be undefined upon return.

   STRUCTURE_NAME - if the data to be read is a structure, upon
                    output, this keyword will contain the name of the
                    structure.  A value of '' indicates an anonymous
                    structure.

   SIZE - upon output, the SIZE type of the data is returned in this
          keyword.

   NO_DATA - if set, no data is read from the file, only the variable
            name and type.

   TIMESTAMP - after the first call to CMSVREAD on a newly opened
               file, this keyword will contain the file timestamp
               structure.

   VERSION - after the first call to CMSVREAD on a newly opened file,
             this keyword will contain the file version information,
             if available.

   QUIET - if set, error messages are not printed.
           Default: an error causes errors to be printed with MESSAGE

   STATUS - upon return, this keyword will contain 1 for success and
            0 for failure.

   ERRMSG - upon return with a failure, this keyword will contain the
            error condition as a string.

 EXAMPLE:

   Read all variables from a file, and print help on them.

   openr, 50, 'test.sav'
   name = ''
   while n_elements(name) GT 0 do begin   ;; EOF signalled by NAME undefined
      cmsvread, 50, data, name=name
      help, name, data
   end
   close, 50

 SEE ALSO:

   CMSVWRITE, CMRESTORE, CMSAVE, RESTORE, CMSVLIB

 MODIFICATION HISTORY:
   Written and documented, 11 Jan 2001, CM
   Added notification about RSI License, 13 May 2002, CM

 $Id: cmsvread.pro,v 1.7 2002/05/13 06:41:10 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsvread.pro)


CMSVWRITE

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

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

 PURPOSE:
   Write a single variable to an open SAVE file

 CALLING SEQUENCE:

   CMSVWRITE, UNIT, DATA [ , NAME=NAME, COMPATIBILITY=COMPAT ]
   
 DESCRIPTION: 

   CMSVWRITE writes a single IDL variable to an open IDL SAVE file.
   The file should already have been opened for writing as a normal
   file using OPENW or OPENU.

   CMSVWRITE is a simplified version of the CMSVLIB package, and as
   such is not capable of writing heap data (pointers) or object
   data, or structures that contain them.  Strings, structures, and
   all array types are supported.

   This procedure is part of the CMSVLIB SAVE library for IDL by
   Craig Markwardt.  You must have the full CMSVLIB core package
   installed in order for this procedure to function properly.

 ==================================================================
   Research Systems, Inc. has issued a separate license intended
   to resolve any potential conflict between this software and the
   IDL End User License Agreement. The text of that license
   can be found in the file LICENSE.RSI, included with this
   software library.
 ==================================================================

 INPUTS:

   UNIT - the open file unit.

   DATA - the data to be written.

 KEYWORDS:

   NAME - the optional name of the variable to be written (must be a
          valid variable name).
          Default: CMSVWRITE automatically creates a valid name.
  
   COMPATIBILITY - a string, which describes the format to be used in
          the output file.  Possible values are:

                  'IDL4' - format of IDL version 4;
                  'IDL5' - format of IDL versions 5.0-5.3;
                  'IDL6' - not supported yet, for versions 5.4-above;
                  'RIVAL1' - same as 'IDL5'
           Note that files written in IDL5 format may still be
           readable by IDL v.4.
           Default: 'IDL5'

   NO_END - a save file must terminate with an "end" record.  By
            default, CMSVWRITE will append such a record after the
            variable is written, and then rewind the file pointer.
            The end record must be written after the last variable,
            but is optional otherwise.  Set this keyword to disable
            writing the end record (for performance reasons).

   QUIET - if set, error messages are not printed.
           Default: an error causes errors to be printed with MESSAGE

   STATUS - upon return, this keyword will contain 1 for success and
            0 for failure.

   ERRMSG - upon return with a failure, this keyword will contain the
            error condition as a string.

 EXAMPLE:

   Write variables A, B, C and D to a file.

   openw, 50, 'test.sav'       ;; Add /STREAM under VMS !
   cmsvwrite, 50, a, name='a'
   cmsvwrite, 50, b, name='b'
   cmsvwrite, 50, c, name='c'
   close, 50

 SEE ALSO:

   CMSVREAD, CMRESTORE, CMSAVE, SAVE, CMSVLIB

 MODIFICATION HISTORY:
   Written and documented, 11 Jan 2001, CM
   Make version checks with correct precision, 19 Jul 2001, CM
   Added notification about RSI License, 13 May 2002, CM

 $Id: cmsvwrite.pro,v 1.11 2002/05/13 06:41:10 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsvwrite.pro)


CMSV_OPEN

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

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

 PURPOSE:
   Open IDL SAVE file for reading or writing

 CALLING SEQUENCE:
   CMSV_OPEN, UNIT, FILENAME, OFFSET, $
          ACCESS=ACCESS, /FORCE, /GET_LUN, /REOPEN, $
          COMPATIBILITY=COMPATIBILITY, $
          STATUS=STATUS, ERRMSG=ERRMSG
   
 DESCRIPTION: 

   CMSV_OPEN opens an IDL SAVE-formatted file for reading or writing.
   The mode of operation is controlled by the ACCESS keyword, which
   may be either 'R' for reading, 'W' for writing, or 'RW' for
   read/write access.

   'R': In the case of reading, the specified file is opened with
   read-only access, and the first bytes are examined to verify that
   it is indeed a valid IDL SAVE file.  

   'W': In the case of writing, the specified file is opened with
   write access, and the initial file signature is written.  

   'RW': In the case of read-write access, the file must already
   exist as a valid SAVE file.  Users are advised that every time
   they switch between reading and writing operations, they must use
   POINT_LUN to flush the file buffers.

   The CMSVLIB routines do not support file sizes greater than 2 GB,
   nor SAVE files created with the COMPRESS option.

   Upon return, the file pointer is positioned at the start of the
   first valid SAVE record.  The file offset is returned in OFFSET.
   The user is responsible for reading or writing the remainder of
   the file with other library routines.

   The file unit is determined based on the following criteria.  This
   behavior is similar to the OPEN family of procedures, except for
   the REOPEN keyword.

     * If REOPEN is set then it is assumed that UNIT is an
       already-open file, and FILENAME is ignored.  

     * If GET_LUN is set then a file unit is allocated with GET_LUN,
       and upon success this unit is returned in UNIT.

     * Otherwise it is asssumed that UNIT is a valid but unopened
       file unit.  Upon successful return, UNIT is opened.

   This procedure is part of the CMSVLIB SAVE library for IDL by
   Craig Markwardt.  You must have the full CMSVLIB core package
   installed in order for this procedure to function properly.

 ==================================================================
   Research Systems, Inc. has issued a separate license intended
   to resolve any potential conflict between this software and the
   IDL End User License Agreement. The text of that license
   can be found in the file LICENSE.RSI, included with this
   software library.
 ==================================================================


 INPUTS:

   UNIT - a logical unit number (a scalar).  In the case of GET_LUN,
          a file unit will be allocated and returned in UNIT.  In the
          default case, or REOPEN, UNIT must be a valid file unit
          upon input.  For REOPEN the corresponding file must be
          seekable.

   FILENAME - a scalar string specifying the filename path (ignored
              for REOPEN).

   OFFSET - upon return, the file offset of the next available SAVE
            record.


 KEYWORDS:

   ACCESS - a scalar string, case insensitive:
               'R' - read-only access
               'W' - write access (new file)
               'RW' - read-write access (existing file)
            Default: 'R' - read-only

   GET_LUN - if set, the file unit is allocated using GET_LUN

   FORCE - if set, then the file is opened despite a detected file
           format inconsistency.

   REOPEN - if set, then an already-opened file is manipulated.  The
            valid file unit must be specified by UNIT, and FILENAME
            is ignored.

   COMPATIBILITY - a string, which describes the format to be used in
          the output file.  Possible values are:

                  'IDL4' - format of IDL version 4;
                  'IDL5' - format of IDL versions 5.0-5.3;
                  'IDL6' - not supported yet, for versions 5.4-above;
                  'RIVAL1' - same as 'IDL5', plus a directory entry is
                            written to the file.
           Note that files written in IDL5 format may still be
           readable by IDL v.4.
           Default: 'IDL5'


   STATUS - upon return, this keyword will contain 1 for success and
            0 for failure.

   ERRMSG - upon return with a failure, this keyword will contain the
            error condition as a string.

 EXAMPLE:


 SEE ALSO:

   CMRESTORE, SAVE, RESTORE, CMSVLIB

 MODIFICATION HISTORY:
   Written, 2000
   Documented, 24 Jan 2001
   Change BLOCK to STREAM to support VMS properly, 14 Feb 2001, CM
   Added notification about RSI License, 13 May 2002, CM

 $Id: cmsv_open.pro,v 1.12 2002/05/13 06:41:10 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsv_open.pro)


CMSV_PTRSUM

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

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

 PURPOSE:
   Construct an inventory of heap data accessible to a variable

 CALLING SEQUENCE:
   CMSV_PTRSUM, VAR, LIST
   
 DESCRIPTION: 

   This procedure constructs an inventory of heap data that is
   accessible to a single variable.  It searches all array elements,
   recursively through structure tags, and by dereferencing pointers.
   Users can use this procedure to determine all heap variables that
   need to be saved to disk.

   This procedure is part of the CMSVLIB SAVE library for IDL by
   Craig Markwardt. 

 ==================================================================
   Research Systems, Inc. has issued a separate license intended
   to resolve any potential conflict between this software and the
   IDL End User License Agreement. The text of that license
   can be found in the file LICENSE.RSI, included with this
   software library.
 ==================================================================

 INPUTS:

   VAR - the variable to be examined

   LIST - upon output, an array of pointers, each of which points to
          a heap variable accessible to VAR.  If there are no heap
          data pointed to by VAR, then LIST returns a NULL value.

 KEYWORDS:

   NULL - if set, return the null value in LIST instead of the
          pointer list.  VAR is ignored.

   HAS_OBJECTS - upon return, the value is 1 if VAR contains or
                 points to an object reference, and 0 if not.


 EXAMPLE:


 SEE ALSO:

   CMRESTORE, SAVE, RESTORE, CMSVLIB

 MODIFICATION HISTORY:
   Written, 2000
   Documented, 24 Jan 2001
   Make version checks with correct precision, 19 Jul 2001, CM
   Added notification about RSI License, 13 May 2002, CM

 $Id: cmsv_ptrsum.pro,v 1.7 2002/05/13 06:41:10 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsv_ptrsum.pro)


CMSV_RDATA

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

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

 PURPOSE:
   Read SAVE-formatted data variable record from input block or file unit

 CALLING SEQUENCE:
   CMSV_RDATA, BLOCK, POINTER, SIZE, DATA, UNIT=UNIT, $
          TEMPLATE=TEMPLATE, /TEMPORARY, PTR_INDEX=PTR_INDEX, $
          PTR_CALLBACK=PTR_CALLBACK, PTR_OFFSETS=PTR_OFFSETS, $
          OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
   
 DESCRIPTION: 

   CMSV_RDATA reads the data portion of an IDL SAVE variable record.
   An IDL variable is stored in two components: the type descriptor
   which describes the name, type, and dimensions of the variable;
   and the data record, which contains the raw data of the variable.
   This procedure reads the raw data and returns it to the user.  The
   initial type portion of the record must have already been read
   using the CMSV_RVTYPE procedure.

   CMSV_RDATA supports the following variable types:

     BYTE(1),INT(2),LONG(3) - integer types
     UINT(12),ULONG(13),LONG64(14),ULONG64(15) - integer types (IDL >5.2 only)
     FLOAT(4),DOUBLE(5),COMPLEX(6),DCOMPLEX(9) - float types
     STRING(7) - string type
     STRUCT(8) - structure type
     POINTER(10) - pointer type - SEE BELOW
     NOT SUPPORTED - OBJ(11) - object reference type - NOT SUPPORTED

   Arrays and structures containing any of the supported types are
   supported (including structures within structures).

   For scalars and arrays of numeric or string types, the caller must
   only supply the SIZE parameter, which specifies the type and
   dimensions of the variable to be read.  This information can be
   obtained from the CMSV_RVTYPE routine. The data is returned in the
   output parameter DATA.

   For structure data, in addition to specifying the SIZE array, the
   user must also supply a "template" describing the structure into
   which the data will be read.  This template is simply a "blank"
   form of the data structure, and is returned by CMSV_RVTYPE.

   Thus, a simple way to read structure, numeric or string data is
   the following code (with error checking removed)

     CMSV_RVTYPE, block, pointer, name, size, template=template, unit=unit
     CMSV_RDATA, block, pointer, size, data, template=template, unit=unit

   [ This code assumes the record header has been read with
   CMSV_RREC. ]

 ==================================================================
   Research Systems, Inc. has issued a separate license intended
   to resolve any potential conflict between this software and the
   IDL End User License Agreement. The text of that license
   can be found in the file LICENSE.RSI, included with this
   software library.
 ==================================================================

 POINTER DATA

   Pointer data stored in IDL SAVE files are particularly difficult
   to manage, because the actual heap variables are stored in
   separate records which *precede* the record of interest.  Thus, if
   your application requires the reading of pointer data, you must
   perform special processing in your own code in order to support
   it.  In essence, you must maintain an inventory of heap variables
   as they are encountered in the file.

   If these procedures are not followed then pointer data will not be
   read, and a LONG integer value appears in the pointers' places.
   Under IDL 4, pointer data can never be read.

   This is accomplished by placing some additional logic in your file
   processing loop.  There are four separate components to this: (1)
   loop initialization; (2) reading a HEAP_INDEX record; (3) parsing
   a HEAP_DATA record; and (4) passing extra arguments to CMSV_RDATA.
   The additional state information is maintained in two variables
   named PTR_INDEX, which keeps track of the heap variable numbers,
   and PTR_OFFSETS, which stores the file location of each variable.

   (1) Loop initialization: is quite simple, use the following code:
       ptr_index   = [0L]
       ptr_offsets = [0L]
       ptr_data    = [ptr_new()]

   (2) Reading HEAP_INDEX, which is an array of values indicating
       the heap variable numbers of each heap variables.  These
       values are stored in PTR_INDEX:

          CMSV_RHEAP, block, pointer, index, unit=unit
          ptr_index   = [ptr_index, index]
          ptr_offsets = [ptr_offsets, lonarr(n_elements(index))]
          ptr_data    = [ptr_data, ptrarr(n_elements(index))]

   (3) Parse the HEAP_DATA record.  Here were are interested in the
       heap variable number, and the file offset.
       
       opointer = pointer
       CMSV_RVTYPE, block, pointer, vindex, /heap, unit=unit
       
       vindex = floor(vindex(0))
       wh = where(ptr_index EQ vindex)
       ptr_offsets(wh(0)) = offset + opointer

       Keep in mind that the file offset is OFFSET+POINTER.

   (4) Pass extra parameters to CMSV_RDATA.  The user simply passes
       these extra variables to the CMSV_RDATA procedure, which
       automatically recognizes heap data and reads it from the
       appropriate location.

       CMSV_RVTYPE, block, pointer, name, size, unit=unit, template=tp
       CMSV_RDATA, block, pointer, size, data, template=tp, $
         unit=unit, ptr_offsets=ptr_offsets, $
         ptr_index=ptr_index, ptr_data=ptr_data

   If this technique is used properly, only those heap variables
   which are needed are read.  Thus, there are never any lost or
   dangling pointers.  Since each bit of heap data is stored in a
   variable returned to the user, it is not necessary to
   PTR_FREE(ptr_data); in fact, doing so would corrupt the input
   data.

 BLOCK, POINTER, OFFSET

   This procedure can read data from a byte array, a file unit, or
   both.  In fact, this procedure is designed to implement "lazy"
   reading from a file, which is to say, it normally reads from a
   byte array of data.  However, if the requested data goes beyond
   the end of the byte array, more data is read from the file on
   demand.  This way the user gets the benefit of fast memory access
   for small reads, but guaranteed file access for large reads.

   The terminology is as follows: BLOCK is a byte array which
   represents a portion of, or an entire, IDL SAVE file.  The block
   may be a cached portion of an on-disk file, or an entire in-memory
   SAVE file.  POINTER is the current file pointer within BLOCK
   (i.e., the next byte to be read is BLOCK[POINTER]).  Hence, a
   POINTER value of 0 refers to the start of the block.  OFFSET is
   the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
   OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
   The following diagram shows the meanings for BLOCK, POINTER and
   OFFSET schematically:


                 0 <-  OFFSET  -> |
   FILE          |----------------|------*--------|--------->

   BLOCK                          |------*--------|
                                  0      ^ POINTER
     

   This procedure is part of the CMSVLIB SAVE library for IDL by
   Craig Markwardt.  You must have the full CMSVLIB core package
   installed in order for this procedure to function properly.

 INPUTS:

   BLOCK - a byte array, a cache of the SAVE file.  Users will
           usually not access this array directly.  Users are advised
           to clear BLOCK after calling POINT_LUN.

   POINTER - a long integer, a pointer to the next byte to be read
             from BLOCK.  CMSVLIB routines will automatically
             advance the pointer.

   SIZE - an array of integers describing the type and dimensions of
          the variable to be read, in the format returned by the
          SIZE() routine.  This parameter is required.

   DATA - upon output, the data variable.  If any heap data is read,
          the user is ultimately responsible for freeing it.


 KEYWORDS:

   UNIT - a file unit.  If a library routine reads to the end of
          BLOCK, or if BLOCK is undefined, then this file UNIT will
          be accessed for more data.  If undefined, then BLOCK must
          contain the entire file in memory.

   TEMPLATE - for structure data (data type 8), a "blank" structure
              containing the fields and data values to be read in.
              This structure is returned by CMSV_RVTYPE.
              This keyword is mandatory for structure data.

   TEMPORARY - if set, BLOCK becomes undefined upon return.

   PTR_OFFSETS - array of file offsets, as described above.  Default:
                 pointer data is converted to an integer.

   PTR_INDEX - array of heap variable indices, as described above.
               Default:  pointer data is converted to an integer.

   PTR_DATA - array of pointers, as described above.  
               Default:  pointer data is converted to an integer.

   OFFSET - the file offset of byte zero of BLOCK.  Default: 0
            (OFFSET is used by this routine)

   STATUS - upon return, this keyword will contain 1 for success and
            0 for failure.

   ERRMSG - upon return with a failure, this keyword will contain the
            error condition as a string.

 EXAMPLE:


 SEE ALSO:

   CMRESTORE, SAVE, RESTORE, CMSVLIB

 MODIFICATION HISTORY:
   Written, 2000
   Documented, 24 Jan 2001
   Added UNDEFINED data type for IDL >5.3, CM, 21 Apr 2001
   Fixed bug for pointers within structures, CM, 21 Apr 2001
   Add support for IDL 4 byte-compiled strings, CM, 22 Apr 2001
   Make version checks with correct precision, 19 Jul 2001, CM
   Added notification about RSI License, 13 May 2002, CM

 $Id: cmsv_rdata.pro,v 1.10 2002/05/13 06:41:10 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsv_rdata.pro)


CMSV_RRAW

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

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

 PURPOSE:
   Read raw SAVE data from input block or file unit

 CALLING SEQUENCE:
   DATA = CMSV_RRAW( BLOCK, POINTER, NELT, UNIT=UNIT, $
                     STRING=STRING, LONG=LONG, BYTE=BYTE, TYPE=TYPE, $
                     OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG )
   
 DESCRIPTION: 

   This function reads raw integer or string data from an IDL SAVE
   file.  This is the lowest level reading function in the library,
   intended for developers who are investigating new and existing
   SAVE file formats.

   The primary use of this function will be to read raw integer and
   string data from the input.  By default, a single value is read as
   a scalar; however a vector of values can be read using the NELT
   parameter.  Special keywords are provided for the common data
   types STRING, LONG and BYTE.  Other integer types can be read
   using the TYPE keyword.  Users who want to read the data from an
   IDL variable should use CMSV_RDATA, which can handle
   multidimensional data, as well as floating point and structure
   data.

   A secondary use of this function is to buffer the data in BLOCK.
   This will ensure that BLOCK contains enough data to convert NELT
   integers without reading from disk.  CMSV_RRAW itself does not
   convert any values so the return value should be ignored.


 ==================================================================
   Research Systems, Inc. has issued a separate license intended
   to resolve any potential conflict between this software and the
   IDL End User License Agreement. The text of that license
   can be found in the file LICENSE.RSI, included with this
   software library.
 ==================================================================

 BLOCK, POINTER, OFFSET

   This procedure can read data from a byte array, a file unit, or
   both.  In fact, this procedure is designed to implement "lazy"
   reading from a file, which is to say, it normally reads from a
   byte array of data.  However, if the requested data goes beyond
   the end of the byte array, more data is read from the file on
   demand.  This way the user gets the benefit of fast memory access
   for small reads, but guaranteed file access for large reads.

   The terminology is as follows: BLOCK is a byte array which
   represents a portion of, or an entire, IDL SAVE file.  The block
   may be a cached portion of an on-disk file, or an entire in-memory
   SAVE file.  POINTER is the current file pointer within BLOCK
   (i.e., the next byte to be read is BLOCK[POINTER]).  Hence, a
   POINTER value of 0 refers to the start of the block.  OFFSET is
   the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
   OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
   The following diagram shows the meanings for BLOCK, POINTER and
   OFFSET schematically:


                 0 <-  OFFSET  -> |
   FILE          |----------------|------*--------|--------->

   BLOCK                          |------*--------|
                                  0      ^ POINTER
     

   This procedure is part of the CMSVLIB SAVE library for IDL by
   Craig Markwardt.  You must have the full CMSVLIB core package
   installed in order for this procedure to function properly.


 INPUTS:

   BLOCK - a byte array, a cache of the SAVE file.  Users will
           usually not access this array directly.  Users are advised
           to clear BLOCK after calling POINT_LUN.

   POINTER - a long integer, a pointer to the next byte to be read
             from BLOCK.  CMSVLIB routines will automatically
             advance the pointer.

   NELT - optional parameter specifying the number of values to read.
          If unspecified, then a scalar value is read and returned.
          If specified, then a vector of NELT values is read and
          returned.


 KEYWORDS:

   BUFFER - if set, CMSV_RRAW will ensure that BLOCK contains at
            least NELT values without converting them.  The return
            value should be ignored.  This keyword is ignored for
            strings.

   LONG - if set, the values are converted as LONG integers.

   BYTE - if set, the values are converted as BYTEs.

   STRING - if set, the values are converted as STRINGs.  Each string
            may be of variable length.

   TYPE - if none of the above keywords is set, then values of type
          TYPE are read.  TYPE should be a string, one of 'BYTE',
          'FIX', 'LONG', 'ULONG', 'LONG64', or 'ULONG64'.
          If no type is specified then BYTEs are read.

   UNIT - a file unit.  If a library routine reads to the end of
          BLOCK, or if BLOCK is undefined, then this file UNIT will
          be accessed for more data.  If undefined, then BLOCK must
          contain the entire file in memory.

   OFFSET - the file offset of byte zero of BLOCK.  Default: 0
            (OFFSET is used by this routine)

   STATUS - upon return, this keyword will contain 1 for success and
            0 for failure.

   ERRMSG - upon return with a failure, this keyword will contain the
            error condition as a string.

 EXAMPLE:


 SEE ALSO:

   CMRESTORE, SAVE, RESTORE, CMSVLIB

 MODIFICATION HISTORY:
   Written, 2000
   Documented, 24 Jan 2001
   Added notification about RSI License, 13 May 2002, CM

 $Id: cmsv_rraw.pro,v 1.6 2002/05/13 06:41:10 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsv_rraw.pro)


CMSV_RREC

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

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

 PURPOSE:
   Read SAVE-formatted record header from input block or file unit

 CALLING SEQUENCE:
   CMSV_RREC, BLOCK, POINTER, DATA, UNIT=UNIT, $
        BLOCK_TYPE=BLOCK_TYPE, BLOCK_NAME=BLOCK_NAME, NEXT_BLOCK=NEXT_BLOCK, $
        INITIALIZE=INITIALIZE, FULL=FULL, PROMOTE64=PROMOTE64, $
        OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
   
 DESCRIPTION: 

   This procedure reads the header of an IDL SAVE record.  The header
   consists of four bytes at the beginning of each record which
   indentifies the type and size of the record.  This procedure also
   additionally reads many full records as noted below.

   Users can determine the block type by examining the values
   returned in the BLOCK_TYPE and BLOCK_NAME keywords.  The following
   values are supported.  Some record types contain additional data.
   CMSV_RREC reads some of these record types automatically (those
   entries below marked with [this procedure]).  Other records do not
   contain any additional data at all (those entries marked with an
   [empty]), and thus require no further processing.

    BLOCK_TYPE      BLOCK_TYPE         READ RECORD DATA WITH...

       0         = 'START_MARKER'      [empty]
       1         = 'COMMON_BLOCK'      [this procedure]
       2         = 'VARIABLE'          CMSV_RVTYPE / CMSV_RDATA
       3         = 'SYSTEM_VARIABLE'   CMSV_RVTYPE / CMSV_RDATA
       6         = 'END_MARKER'        [empty]
       10        = 'TIMESTAMP'         [this procedure]
       12        = 'COMPILED'          no published procedure
       13        = 'IDENTIFICATION'    [this procedure]
       14        = 'VERSION'           [this procedure]
       15        = 'HEAP_INDEX'        [this procedure]
       16        = 'HEAP_DATA'         CMSV_RVTYPE
       17        = 'PROMOTE64'         [empty]

   For records that contain variable data, the external procedures
   CMSV_RVTYPE and CMSV_RDATA must be used, as noted above.
   Otherwise CMSV_RREC will read and convert the appropriate data
   automatically and return it in the DATA positional parameter.

   The offset of the next record is returned in the NEXT_BLOCK
   keyword.  For file input, the command, "POINT_LUN, UNIT,
   NEXT_BLOCK" will position the file pointer to the next block.

   Users should be aware that the SAVE files produced by IDL version
   5.4 appear to have a different header format.  The new header size
   is five bytes, and is incompatible with the older format.  In
   order to activate the longer header size, the PROMOTE64 keyword
   must be set.

   By default the entire record is not read from the file at once.
   Users that wish to operate on the entire record immediately should
   set the FULL keyword.

   After issuing a POINT_LUN the block cache in BLOCK must be reset
   using the /INITIALIZE keyword.

 ==================================================================
   Research Systems, Inc. has issued a separate license intended
   to resolve any potential conflict between this software and the
   IDL End User License Agreement. The text of that license
   can be found in the file LICENSE.RSI, included with this
   software library.
 ==================================================================

 SPECIFIC RECORD TYPES

   CMSV_RREC reads certain specific record types automatically and
   returns the data in the positional parameter data.  Users should
   pass a named variable in this parameter to retrieve the return
   value.

   When a record of type 'VERSION' (14) is encountered, it is read,
   and returned as a structure. The returned data are of the form:

         { FORMAT_VERSION: 0L, $   ; Format version number of file
           ARCH: '', $             ; !VERSION.ARCH of creating host
           OS: '', $               ; !VERSION.OS of creating host
           RELEASE: '' }           ; !VERSION.RELEASE of creating host

   When a record of type 'TIMESTAMP' (10) is encountered, it is read,
   and returned as a structure. The returned data are of the form:

          { SAVE_DATE: '', $  ; Date the save file was created
            SAVE_USER: '', $  ; User name who  created file
            SAVE_HOST: '' }   ; Host name that created file

   Save files created by IDL version 4 do not contain a timestamp
   record.

   When a record of type 'IDENTIFICATION' (13) is encountered, it is
   read, and returned as a structure.  The returned data are of the
   form:

          { AUTHOR: '', $  ; Author of SAVE file
            TITLE:  '', $  ; Title of SAVE file
            IDCODE: '' }   ; Identifying code for SAVE file

   It appears that this record is not used in IDL version 5 or later.

   When a record of type 'COMMON_BLOCK' (1) is encountered, it is
   read and returned.  A common block descriptor consists of an array
   of strings whose first element is the common block name, and whose
   remaining elements are the common block variable names.  No
   variable data are stored with the common block definition.

   When a record of type 'HEAP_INDEX' (15) is encountered, it is read
   and returned in DATA.  The heap index specifies a list of which
   heap variables are stored in the current save file.  These indices
   are simply numbers which identify each heap variable (i.e.,
   "" would have an index of 2).  Users should note that
   the heap index will not necessarily be sequentially increasing,
   and may have gaps.

   Users should consult CMSV_RDATA for instructions on how to read
   heap data.
   

 BLOCK, POINTER, OFFSET

   This procedure can read data from a byte array, a file unit, or
   both.  In fact, this procedure is designed to implement "lazy"
   reading from a file, which is to say, it normally reads from a
   byte array of data.  However, if the requested data goes beyond
   the end of the byte array, more data is read from the file on
   demand.  This way the user gets the benefit of fast memory access
   for small reads, but guaranteed file access for large reads.

   The terminology is as follows: BLOCK is a byte array which
   represents a portion of, or an entire, IDL SAVE file.  The block
   may be a cached portion of an on-disk file, or an entire in-memory
   SAVE file.  POINTER is the current file pointer within BLOCK
   (i.e., the next byte to be read is BLOCK[POINTER]).  Hence, a
   POINTER value of 0 refers to the start of the block.  OFFSET is
   the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
   OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
   The following diagram shows the meanings for BLOCK, POINTER and
   OFFSET schematically:


                 0 <-  OFFSET  -> |
   FILE          |----------------|------*--------|--------->

   BLOCK                          |------*--------|
                                  0      ^ POINTER
     

   This procedure is part of the CMSVLIB SAVE library for IDL by
   Craig Markwardt.  You must have the full CMSVLIB core package
   installed in order for this procedure to function properly.  


 INPUTS:

   BLOCK - a byte array, a cache of the SAVE file.  Users will
           usually not access this array directly.  Users are advised
           to clear BLOCK after calling POINT_LUN.

   POINTER - a long integer, a pointer to the next byte to be read
             from BLOCK.  CMSVLIB routines will automatically
             advance the pointer.


 KEYWORDS:

   UNIT - a file unit.  If a library routine reads to the end of
          BLOCK, or if BLOCK is undefined, then this file UNIT will
          be accessed for more data.  If undefined, then BLOCK must
          contain the entire file in memory.

   OFFSET - the file offset of byte zero of BLOCK.  Default: 0
            (OFFSET is used by this routine)

   BLOCK_TYPE - upon return, the numeric record type, as described
                above.

   BLOCK_NAME - upon return, a scalar string specifying the record
                type, as specified above.

   NEXT_BLOCK - upon return, file offset of the next record in the
                file.

   INITIALIZE - if set, then BLOCK and POINTER are initialized to a
                pristine state.  All data in these two variables is
                lost before reading the next record.

   FULL - if set, then the entire record will be read into BLOCK.

   STATUS - upon return, this keyword will contain 1 for success and
            0 for failure.

   ERRMSG - upon return with a failure, this keyword will contain the
            error condition as a string.

 EXAMPLE:


 SEE ALSO:

   CMRESTORE, SAVE, RESTORE, CMSVLIB

 MODIFICATION HISTORY:
   Written, 2000
   Documented, 24 Jan 2001
   Fix typo for RHEAP call, CM, 21 Apr 2001
   Added notification about RSI License, 13 May 2002, CM

 $Id: cmsv_rrec.pro,v 1.11 2002/05/13 06:41:10 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsv_rrec.pro)


CMSV_RVTYPE

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

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

 PURPOSE:
   Read variable type information from input block or file unit

 CALLING SEQUENCE:
   CMSV_RVTYPE, BLOCK, POINTER, NAME, SIZE, UNIT=UNIT, $
          TEMPLATE=TEMPLATE, SUFFIX=SUFFIX, $
          /NO_CREATE, /NO_TYPE, /HEAP, /SYSTEM, $
          STRUCTURE_NAME=STNAME, $
          NAMED_STRUCTS=STRUCTS, NAMED_CLASSES=CLASSES, $
          OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
   
 DESCRIPTION: 

   CMSV_RVTYPE reads the type portion of an IDL SAVE variable record.
   An IDL variable is stored in two components: the type descriptor
   which describes the name, type, and dimensions of the variable;
   and the data record, which contains the raw data of the variable.
   This procedure reads the type descriptor returns it to the user.
   This procedure can also determine the name of a variable; the heap
   index number of a heap variable; and other important information.
   Once the type of the data has been determined, the data portion
   can be read using the CMSV_RDATA procedure.

   CMSV_RVTYPE should recognize and correctly return type descriptor
   information about all known IDL data types, as of this writing.
   It should be noted that CMSV_RDATA will not necessarily be capable
   of reading all of these data types, but the description of the
   data should still be readable.  Users can then use this
   information to print a summary of the file contents for example.

   The type information are normally returned in the SIZE parameter,
   which gives the IDL variable type, and the dimensions of the
   variable just as the IDL built-in function SIZE() would do.
   However, in the case of structures, there is much more information
   to convey.  To assist the user a blank template structure is
   returned in the keyword parameter TEMPLATE, which they can then
   pass on to CMSV_RDATA.

   Users should be aware of structure and class name clashes.  The
   problem arises because CMSV_RVTYPE must actually instantiate any
   named structures or classes in the file.  If these named
   structures clash with the definitions of the structures on the
   user's local computer, then an error will result.  To prevent
   this, the user can use the SUFFIX keyword.  If the SUFFIX keyword
   contains a string, then this string is appended to any structure
   names discovered in the save file, before instantiation.  Thus, as
   long as the suffix is a unique string, there will be no clashes
   with local structure definitions.  Users are advised to pick a
   different suffix for *each* save file that they open.

   CMSV_RVTYPE also provides some diagnostic information about the
   variable.  Users can pass the NAMED_STRUCTS and NAMED_CLASSES
   keywords in order to discover what named structures, classes and
   superclasses are stored in the save file (this is especially
   useful with the NO_TYPE keyword).  Since the contents of
   NAMED_STRUCTS and NAMED_CLASSES are not destroyed, but appended to
   instead, users are advised to clear these variables when opening
   each new file.
   

 ==================================================================
   Research Systems, Inc. has issued a separate license intended
   to resolve any potential conflict between this software and the
   IDL End User License Agreement. The text of that license
   can be found in the file LICENSE.RSI, included with this
   software library.
 ==================================================================

 BLOCK, POINTER, OFFSET

   This procedure can read data from a byte array, a file unit, or
   both.  In fact, this procedure is designed to implement "lazy"
   reading from a file, which is to say, it normally reads from a
   byte array of data.  However, if the requested data goes beyond
   the end of the byte array, more data is read from the file on
   demand.  This way the user gets the benefit of fast memory access
   for small reads, but guaranteed file access for large reads.

   The terminology is as follows: BLOCK is a byte array which
   represents a portion of, or an entire, IDL SAVE file.  The block
   may be a cached portion of an on-disk file, or an entire in-memory
   SAVE file.  POINTER is the current file pointer within BLOCK
   (i.e., the next byte to be read is BLOCK[POINTER]).  Hence, a
   POINTER value of 0 refers to the start of the block.  OFFSET is
   the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
   OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
   The following diagram shows the meanings for BLOCK, POINTER and
   OFFSET schematically:


                 0 <-  OFFSET  -> |
   FILE          |----------------|------*--------|--------->

   BLOCK                          |------*--------|
                                  0      ^ POINTER
     

   This procedure is part of the CMSVLIB SAVE library for IDL by
   Craig Markwardt.  You must have the full CMSVLIB core package
   installed in order for this procedure to function properly.  


 INPUTS:

   BLOCK - a byte array, a cache of the SAVE file.  Users will
           usually not access this array directly.  Users are advised
           to clear BLOCK after calling POINT_LUN.

   POINTER - a long integer, a pointer to the next byte to be read
             from BLOCK.  CMSVLIB routines will automatically
             advance the pointer.

   NAME - upon return, the identifier of the variable.  For named
          variables, NAME is a string.  For heap variables, NAME is
          an integer heap index.

   SIZE - upon return, an integers array describing the variable type
          and size, in the same format as returned by the built-in
          function SIZE.

 KEYWORDS:

   TEMPLATE - upon return, if the variable is a structure, TEMPLATE
              will contain a single blank template structure, which
              can be used in calls to CMSV_RDATA.

   NO_CREATE - if set, then do not create any template structures
               (saves execution time and structure name clashes).

   NO_TYPE - if set, do not read type information.  CMSV_RVTYPE
             returns only the variable NAME or heap index.

   HEAP - if set, then read the variable type assuming it is a heap
          variable (a HEAP_DATA record).

   SYSTEM - if set, then read the variable type assuming it is a
            system variable (a SYSTEM_VARIABLE record).

   SUFFIX - a scalar string, the suffix to be appended to any
            structure names to force them to be unique.

   STRUCTURE_NAME - upon return, if the variable is a named
                    structure, STRUCTURE_NAME will contain the name
                    of the structure as a string.

   NAMED_CLASSES /
   NAMED_STRUCTS - upon input, this keyword should contain an
                   undefined or a string array value.

                   If the variable contains any named structure/class
                   definitions, CMSV_RVTYPE will append those names
                   upon return, including any enclosed structures or
                   superclasses.

   UNIT - a file unit.  If a library routine reads to the end of
          BLOCK, or if BLOCK is undefined, then this file UNIT will
          be accessed for more data.  If undefined, then BLOCK must
          contain the entire file in memory.

   OFFSET - the file offset of byte zero of BLOCK.  Default: 0
            (OFFSET is not used by this routine at this time)

   STATUS - upon return, this keyword will contain 1 for success and
            0 for failure.

   ERRMSG - upon return with a failure, this keyword will contain the
            error condition as a string.

 EXAMPLE:


 SEE ALSO:

   CMRESTORE, SAVE, RESTORE, CMSVLIB

 MODIFICATION HISTORY:
   Written, 2000
   Documented, 24 Jan 2001
   Added notification about RSI License, 13 May 2002, CM

 $Id: cmsv_rvtype.pro,v 1.11 2002/05/13 06:41:10 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsv_rvtype.pro)


CMSV_TEST

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

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

 PURPOSE:
   Test the CMSVLIB library

 CALLING SEQUENCE:
   CMSV_TEST, FILENAME, USER_VALUE=UVALUE
   
 DESCRIPTION: 

   CMSV_TEST performs a standard test of the CMSVLIB library.  It
   reads and writes a save file using several different methods in an
   attempt to test the different ways that the library can be used.
   The test procedure can be used to verify that the library is
   functioning properly.

   By default, this procedure provides standard values to be written,
   but the user can provide one of them with the USER_VALUE keyword.
   If the user's data contains pointers, they must expect tests
   listed under CMSVREAD and CMSVWRITE to fail.

   By default the file is written in the current directory, but this
   can be changed with the FILENAME parameter.

   This procedure is part of the CMSVLIB SAVE library for IDL by
   Craig Markwardt.  You must have the full CMSVLIB core package
   installed in order for this procedure to function properly.


 ==================================================================
   Research Systems, Inc. has issued a separate license intended
   to resolve any potential conflict between this software and the
   IDL End User License Agreement. The text of that license
   can be found in the file LICENSE.RSI, included with this
   software library.
 ==================================================================

 INPUTS:

   FILENAME - a scalar string, the output path.  
              Default: 'CMSVTEST.SAV' in current directory

 KEYWORDS:

   USER_VALUE - any IDL variable to be saved, in place of variable
                "C" in the test.

 EXAMPLE:


 SEE ALSO:

   CMRESTORE, SAVE, RESTORE, CMSVLIB

 MODIFICATION HISTORY:
   Written, 2000
   Documented, 24 Jan 2001
   Resolve all routines at start, and add VMS keyword, 14 Feb 2001, CM
   Make version checks with correct precision, 19 Jul 2001, CM
   Added notification about RSI License, 13 May 2002, CM

 $Id: cmsv_test.pro,v 1.8 2002/05/13 06:41:10 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsv_test.pro)


CMSV_WDATA

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

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

 PURPOSE:
   Write SAVE-formatted data variable record to output block or file

 CALLING SEQUENCE:
   CMSV_WDATA, BLOCK, POINTER, DATA, UNIT=UNIT, TEMPORARY=TEMPORARY, $
               PTR_INDEX=PTR_INDEX, PTR_DATA=PTR_DATA, $
               OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
   
 DESCRIPTION: 

   CMSV_WDATA writes the data portion of an IDL SAVE variable record.
   An IDL variable is stored in two components: the type descriptor
   which describes the name, type, and dimensions of the variable;
   and the data record, which contains the raw data of the variable.
   This procedure writes the raw data to the output.  The initial
   type descriptor portion of the record must have already been
   writtenusing the CMSV_WVTYPE procedure.

   Under normal circumstances a user will write variable or heap data
   using the CMSV_WREC procedure.

   CMSV_WDATA supports the following variable types:

     BYTE(1),INT(2),LONG(3) - integer types
     UINT(12),ULONG(13),LONG64(14),ULONG64(15) - integer types (IDL >5.2 only)
     FLOAT(4),DOUBLE(5),COMPLEX(6),DCOMPLEX(9) - float types
     STRING(7) - string type
     STRUCT(8) - structure type
     POINTER(10) - pointer type - SEE BELOW
     NOT SUPPORTED - OBJ(11) - object reference type - NOT SUPPORTED

   Arrays and structures containing any of the supported types are
   supported (including structures within structures).

   The caller must specify in the DATA parameter, the data to be
   written to output.  The variable passed as DATA must have the same
   type and dimensions as passed to CMSV_WVTYPE.

   Unlike most of the other output routines, this procedure is able
   to send its output to a file rather than to the BLOCK buffer.  If
   the UNIT keyword is specified then output is sent to that file
   UNIT, after any pending BLOCK data is first sent.  Users should
   note that after such operations, the BLOCK POINTER and OFFSET
   parameters may be modified (ie reset to new values).

   See CMSV_WREC for instructions on how to write heap data.

   [ This code assumes the record header and type descriptor have
   been written with CMSV_WREC and CMSV_WVTYPE. ]

 ==================================================================
   Research Systems, Inc. has issued a separate license intended
   to resolve any potential conflict between this software and the
   IDL End User License Agreement. The text of that license
   can be found in the file LICENSE.RSI, included with this
   software library.
 ==================================================================


 BLOCK, POINTER, OFFSET

   This procedure writes data to a byte array or a file.  If the UNIT
   keyword is specified then file is sent to the specified unit
   number rather than to the buffer BLOCK.  However, the intent is
   for users to accumulate a significant amount of data in a BLOCK
   and then write it out with a single call to WRITEU.  Users should
   be aware that the block can be larger than the buffered data, so
   they should use something like the following:

          WRITEU, UNIT, BLOCK(0:POINTER-1)

   When library routines do indeed write buffered BLOCK data to disk,
   they will appropriately reset the BLOCK and POINTER.  Namely,
   BLOCK will be reset to empty, and POINTER will be reset to zero.
   OFFSET will be advanced the according number of bytes.

   The terminology is as follows: BLOCK is a byte array which
   represents a portion of, or an entire, IDL SAVE file.  The block
   may be a cached portion of an on-disk file, or an entire in-memory
   SAVE file.  POINTER is the current file pointer within BLOCK
   (i.e., the next byte to be read is BLOCK[POINTER]).  Hence, a
   POINTER value of 0 refers to the start of the block.  OFFSET is
   the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
   OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
   The following diagram shows the meanings for BLOCK, POINTER and
   OFFSET schematically:


                 0 <-  OFFSET  -> |
   FILE          |----------------|------*--------|--------->

   BLOCK                          |------*--------|
                                  0      ^ POINTER
     

   This procedure is part of the CMSVLIB SAVE library for IDL by
   Craig Markwardt.  You must have the full CMSVLIB core package
   installed in order for this procedure to function properly.  


 INPUTS:

   BLOCK - a byte array, a cache of the SAVE file.  Users will
           usually not access this array directly.  Users are advised
           to clear BLOCK after calling POINT_LUN or writing the
           block to disk.

   POINTER - a long integer, a pointer to the next byte to be read
             from BLOCK.  CMSVLIB routines will automatically
             advance the pointer.

   DATA - the data to be written, of any save-able data type.

 KEYWORDS:

   TEMPORARY - if set, then the input DATA are discarded after being
               written, as a memory economy provision.

   PTR_INDEX - a heap index array for the data being written, if any
               heap data records have been written.
               Default: no pointers are written

   PTR_DATA - an array of pointers, pointing to the heap values being
              written.
              Default: no pointers are written

   UNIT - a file unit.  If specified then data are directed to the
          file unit rather than to the buffer BLOCK.

   OFFSET - the file offset of byte zero of BLOCK.  
            Upon output, if the file pointer is advanced, OFFSET will
            also be changed.
            (OFFSET is not currently used by this routine)
            Default: 0

   STATUS - upon return, this keyword will contain 1 for success and
            0 for failure.

   ERRMSG - upon return with a failure, this keyword will contain the
            error condition as a string.

 EXAMPLE:


 SEE ALSO:

   CMRESTORE, SAVE, RESTORE, CMSVLIB

 MODIFICATION HISTORY:
   Written, 2000
   Documented, 24 Jan 2001
   Added notification about RSI License, 13 May 2002, CM

 $Id: cmsv_wdata.pro,v 1.8 2002/05/13 06:41:10 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsv_wdata.pro)


CMSV_WRAW

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

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

 PURPOSE:
   Write raw SAVE data to output block

 CALLING SEQUENCE:
   CMSV_WRAW, BLOCK, POINTER, DATA, UNIT=UNIT, $
              STRING=STRING, LONG=LONG, BYTE=BYTE, TYPE=TYPE, $
              OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
   
 DESCRIPTION: 

   This procedure writes raw integer or string data to an IDL SAVE
   block in memory.  This is the lowest level writing function in the
   library, intended for developers who are investigating new and
   existing SAVE file formats.

   The data to be written is specified by the DATA parameter.  The
   data must be of type BYTE, LONG or STRING, and the type is
   determined automatically from the data itself.  [ The mnemonic
   STRING LONG and BYTE keywords are accepted for programming clarity
   but ignored. ]

   This procedure accepts but currently ignores the UNIT keyword.  It
   is the caller's responsibility to write the BLOCK data to disk
   when appropriate.

 ==================================================================
   Research Systems, Inc. has issued a separate license intended
   to resolve any potential conflict between this software and the
   IDL End User License Agreement. The text of that license
   can be found in the file LICENSE.RSI, included with this
   software library.
 ==================================================================


 BLOCK, POINTER, OFFSET

   This procedure writes data to a byte array only.  The intent is
   for users to accumulate a significant amount of data in a BLOCK
   and then write it out with a single call to WRITEU.  Users should
   be aware that the block can be larger than the buffered data, so
   they should use something like the following:

          WRITEU, UNIT, BLOCK(0:POINTER-1)

   When library routines do indeed write buffered BLOCK data to disk,
   they will appropriately reset the BLOCK and POINTER.  Namely,
   BLOCK will be reset to empty, and POINTER will be reset to zero.
   OFFSET will be advanced the according number of bytes.

   The terminology is as follows: BLOCK is a byte array which
   represents a portion of, or an entire, IDL SAVE file.  The block
   may be a cached portion of an on-disk file, or an entire in-memory
   SAVE file.  POINTER is the current file pointer within BLOCK
   (i.e., the next byte to be written is BLOCK[POINTER]).  Hence, a
   POINTER value of 0 refers to the start of the block.  OFFSET is
   the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
   OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
   The following diagram shows the meanings for BLOCK, POINTER and
   OFFSET schematically:


                 0 <-  OFFSET  -> |
   FILE          |----------------|------*--------|--------->

   BLOCK                          |------*--------|
                                  0      ^ POINTER
     

   This procedure is part of the CMSVLIB SAVE library for IDL by
   Craig Markwardt.  You must have the full CMSVLIB core package
   installed in order for this procedure to function properly.  


 INPUTS:

   BLOCK - a byte array, a cache of the SAVE file.  Users will
           usually not access this array directly.  Users are advised
           to clear BLOCK after calling POINT_LUN or writing the
           block to disk.

   POINTER - a long integer, a pointer to the next byte to be written
             from BLOCK.  CMSVLIB routines will automatically advance
             the pointer.

   DATA - the data to be written.  Must of type STRING, BYTE or LONG.


 KEYWORDS:

   LONG - ignored (to be used for clarity)
   BYTE - ignored (to be used for clarity)
   STRING - ignored (to be used for clarity)

   UNIT - a file unit.  Currently ignored.

   OFFSET - the file offset of byte zero of BLOCK.  
            Upon output, if the file pointer is advanced, OFFSET will
            also be changed.
            (OFFSET is not currently used by this routine)
            Default: 0

   STATUS - upon return, this keyword will contain 1 for success and
            0 for failure.

   ERRMSG - upon return with a failure, this keyword will contain the
            error condition as a string.

 EXAMPLE:


 SEE ALSO:

   CMRESTORE, SAVE, RESTORE, CMSVLIB

 MODIFICATION HISTORY:
   Written, 2000
   Documented, 24 Jan 2001
   Added notification about RSI License, 13 May 2002, CM

 $Id: cmsv_wraw.pro,v 1.6 2002/05/13 06:41:10 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsv_wraw.pro)


CMSV_WREC

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

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

 PURPOSE:
   Write SAVE-formatted record header to output block or file

 CALLING SEQUENCE:
   CMSV_WDATA, BLOCK, POINTER, DATA, IDENT, UNIT=UNIT, $
               INITIALIZE=INITIALIZE, NO_DATA=NO_DATA, $
               NO_TYPE=NO_TYPE, COMPATIBILITY=COMPAT, $
               BLOCK_TYPE=BLOCK_TYPE, BLOCK_NAME=BLOCK_NAME,
               NEXT_BLOCK=NEXT_BLOCK, $
               [ ... EXTRA KEYWORDS ... ]
               OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
   
 DESCRIPTION: 

   This procedure writes most types of IDL SAVE record, including the
   header and contents.  The header consists of four bytes at the
   beginning of each record which indentifies the type and size of
   the record.  This procedure also writes the contents of certain
   records, as noted below.

   Users can specify the block type by passing the BLOCK_TYPE or
   BLOCK_NAME keywords.  The values listed in the following table are
   supported.  CMSV_WREC writes the contents of essentially all
   record types as well.  Some records do not contain any contents at
   all (those entries marked with an [empty]) and thus require no
   further processing.

    BLOCK_TYPE      BLOCK_TYPE         WRITE RECORD CONTENTS WITH...

       0         = 'START_MARKER'      [empty]
       1         = 'COMMON_BLOCK'      [this procedure]
       2         = 'VARIABLE'          [this procedure]
       3         = 'SYSTEM_VARIABLE'   [this procedure]
       6         = 'END_MARKER'        [empty]
       10        = 'TIMESTAMP'         [this procedure]
       12        = 'COMPILED'          no published procedure
       13        = 'IDENTIFICATION'    [this procedure]
       14        = 'VERSION'           [this procedure]
       15        = 'HEAP_INDEX'        [this procedure]
       16        = 'HEAP_DATA'         [this procedure]
       17        = 'PROMOTE64'         [empty]

   For records that contain variable data, the external procedures
   CMSV_WVTYPE and/or CMSV_WDATA may be used, however it is not
   recommended, since the record header must finally be re-written by
   the user.  Users can write the entire record with this procedure.

   After issuing a POINT_LUN, or after writing the BLOCK to disk, the
   block cache in BLOCK must be reset using the /INITIALIZE keyword.

 ==================================================================
   Research Systems, Inc. has issued a separate license intended
   to resolve any potential conflict between this software and the
   IDL End User License Agreement. The text of that license
   can be found in the file LICENSE.RSI, included with this
   software library.
 ==================================================================

 SPECIFIC RECORD TYPES

   CMSV_WREC reads certain specific record types automatically based
   on data passed in the DATA parameter.  

   Records of type 'VARIABLE' (2), 'SYSTEM_VARIABLE' (3) and
   'HEAP_DATA' (16) require both the DATA and IDENT parameters.  For
   the first two record types, the IDENT parameter is the name of the
   variable, as a scalar string.  Variable names should be valid IDL
   variable names, uppercase, and have no embedded spaces.  For the
   'HEAP_DATA' record type, the IDENT parameter is the heap index
   value, as described below.  The DATA itself can be any supported
   IDL variable type (as described in CMSV_WVTYPE).

   For records that accept data in the form of a structure, as listed
   below, the listed structure tag entries are optional.  If the user
   does not provide a value, then a suitable default will be computed
   by this procedure (listed in parentheses).

   A record of type 'VERSION' (14) has the following structure:

         { FORMAT_VERSION: 0L, $   ; Format version number of file (5)
           ARCH: '', $             ; !VERSION.ARCH of creating host
           OS: '', $               ; !VERSION.OS of creating host
           RELEASE: '' }           ; !VERSION.RELEASE of creating host

   A record of type 'TIMESTAMP' (10) has the following structure:

          { SAVE_DATE: '', $  ; Date the save file was created (SYSTIME(0))
            SAVE_USER: '', $  ; User name who  created file ('UNKNOWN')
            SAVE_HOST: '' }   ; Host name that created file ('UNKNOWN')

   Save files created by IDL version 4 do not contain a timestamp
   record.  Under Unix this procedure will attempt to discover the
   user and host names automatically.

   A record of type 'IDENTIFICATION' (13) has the following
   structure:

          { AUTHOR: '', $  ; Author of SAVE file ('')
            TITLE:  '', $  ; Title of SAVE file  ('')
            IDCODE: '' }   ; Identifying code for SAVE file ('')

   It appears that this record is not used in IDL version 5 or later.

   A record of type 'COMMON_BLOCK' (1) defines a named common block
   and its variables.  A common block descriptor consists of an array
   of strings whose first element is the common block name, and whose
   remaining elements are the common block variable names.  Thus, a
   common block descriptor must have at least two elements.  No
   variable data are stored with the common block definition.

   A record of type 'HEAP_INDEX' (15) defines the heap index in a
   SAVE file.  The heap index specifies a list of which heap
   variables are stored in the current save file.  These indices are
   simply numbers which identify each heap variable (i.e.,
   "" would have an index of 2).  The heap index can use
   any numbers to identify the heap data; however it is required that
   all index entries have corresponding heap data values.

 WRITING HEAP DATA

   If your data contains heap data and/or pointers, then users must
   take special care in writing their data.  Writing heap data is
   actually more straightforward than reading it.  There are several
   steps involved which can be summarized as followed: (1) take
   inventory of HEAP data; (2) write HEAP_INDEX record; (3) write one
   HEAP_DATA record for each heap variable; and (4) write any other
   variables using the heap index.

   (1) Take inventory of heap data.  Before writing any data to the
       SAVE file, use the CMSV_PTRSUM procedure to discover all
       pointer variables in the data set, like so:

          cmsv_ptrsum, var, ptrlist

       PTRLIST contains an array of any heap variables pointed to by
       VAR (including structures or pointed-to variables).  If
       multiple variables are to be written, then the inventory must
       contain the union of all heap variables.

   (2) Write a HEAP_INDEX record.  The heap index is an array of long
       integers which identify the heap variables.  In principle it
       doesn't matter which integers are used, however there must be
       a one-to-one correspondence between the entries in the heap
       index and the heap identifiers used in the next step.  In this
       example a simple LINDGEN is used:

           index = lindgen(n_elements(ptrlist))
           cmsv_wrec, block, pointer, index, block_name='HEAP_INDEX', $
             offset=offset

   (3) Write one HEAP_DATA record for each heap variable.  Issue one
       CMSV_WREC call for each entry in PTRLIST, as follows for the
       ith heap variable:

           cmsv_wrec, block, pointer, ptrlist(i), block_name='HEAP_DATA', $
             ptr_index=index, ptr_data=ptrlist, offset=offset

       Note that the PTR_INDEX and PTR_DATA keywords are required
       because heap data may itself contain pointers.  The PTR_INDEX
       and PTR_DATA keywords enable the CMSV_WREC procedure to write
       appropriate descriptors when it encounters pointers.

   (4) Write remaining data.  For the ith variable, use:

          cmsv_wrec, block, pointer, var(i), name(i), block_name='VARIABLE',$
             ptr_index=index, ptr_data=ptrlist, offset=offset

       As above, using the PTR_INDEX and PTR_DATA keywords will allow
       the CMSV_WREC procedure to write the appropriate data.


 BLOCK, POINTER, OFFSET

   This procedure writes data to a byte array or a file.  If the UNIT
   keyword is specified then file is sent to the specified unit
   number rather than to the buffer BLOCK.  However, the intent is
   for users to accumulate a significant amount of data in a BLOCK
   and then write it out with a single call to WRITEU.  Users should
   be aware that the block can be larger than the buffered data, so
   they should use something like the following:

          WRITEU, UNIT, BLOCK(0:POINTER-1)

   When library routines do indeed write buffered BLOCK data to disk,
   they will appropriately reset the BLOCK and POINTER.  Namely,
   BLOCK will be reset to empty, and POINTER will be reset to zero.
   OFFSET will be advanced the according number of bytes.

   The terminology is as follows: BLOCK is a byte array which
   represents a portion of, or an entire, IDL SAVE file.  The block
   may be a cached portion of an on-disk file, or an entire in-memory
   SAVE file.  POINTER is the current file pointer within BLOCK
   (i.e., the next byte to be read is BLOCK[POINTER]).  Hence, a
   POINTER value of 0 refers to the start of the block.  OFFSET is
   the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
   OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
   The following diagram shows the meanings for BLOCK, POINTER and
   OFFSET schematically:


                 0 <-  OFFSET  -> |
   FILE          |----------------|------*--------|--------->

   BLOCK                          |------*--------|
                                  0      ^ POINTER
     

   This procedure is part of the CMSVLIB SAVE library for IDL by
   Craig Markwardt.  You must have the full CMSVLIB core package
   installed in order for this procedure to function properly.  


 INPUTS:

   BLOCK - a byte array, a cache of the SAVE file.  Users will
           usually not access this array directly.  Users are advised
           to clear BLOCK after calling POINT_LUN or writing the
           block to disk.

   POINTER - a long integer, a pointer to the next byte to be read
             from BLOCK.  CMSVLIB routines will automatically
             advance the pointer.

   DATA - the record contents to be written, as describe above.

   IDENT - for record types 'VARIABLE' (2) and 'SYSTEM_VARIABLE' (3),
           the name of the variable as a scalar string.  For record
           type 'HEAP_DATA' (16), the heap index identifier as a
           scalar long integer.

 KEYWORDS:

   BLOCK_NAME - a scalar string specifying the record type, as
                described above.  The BLOCK_TYPE keyword takes
                precedence over BLOCK_NAME.

   BLOCK_TYPE - a scalar integer specifying the record type, as
                described above.

   NEXT_BLOCK - if specified, the file offset of the next record
                location.
                Default: the offset will be computed automatically.

   INITIALIZE - if the keyword is set, then the BLOCK is emptied and
                the POINTER is reset before any new data is written.

   NO_TYPE - if set, no type descriptor or data are written for
             variable records.

   NO_DATA - if set, no data are written for variable records.


   TEMPORARY - if set, then the input DATA are discarded after being
               written, as a memory economy provision.

   PTR_INDEX - a heap index array for the data being written, if any
               heap data records have been written.
               Default: no pointers are written

   PTR_DATA - an array of pointers, pointing to the heap values being
              written.
              Default: no pointers are written

   UNIT - a file unit.  If specified then data are directed to the
          file unit rather than to the buffer BLOCK.

   OFFSET - the file offset of byte zero of BLOCK.  
            Upon output, if the file pointer is advanced, OFFSET will
            also be changed.
            (OFFSET is not currently used by this routine)
            Default: 0

   COMPATIBILITY - a string, which describes the format to be used in
          the output file.  Possible values are:

                  'IDL4' - format of IDL version 4;
                  'IDL5' - format of IDL versions 5.0-5.3;
                  'IDL6' - not supported yet, for versions 5.4-above;
                  'RIVAL1' - same as 'IDL5', plus a directory entry is
                            written to the file.
           Note that files written in IDL5 format may still be
           readable by IDL v.4.
           Default: 'IDL5'

   STATUS - upon return, this keyword will contain 1 for success and
            0 for failure.

   ERRMSG - upon return with a failure, this keyword will contain the
            error condition as a string.

 EXAMPLE:


 SEE ALSO:

   CMRESTORE, SAVE, RESTORE, CMSVLIB

 MODIFICATION HISTORY:
   Written, 2000
   Documented, 24 Jan 2001
   Added notification about RSI License, 13 May 2002, CM

 $Id: cmsv_wrec.pro,v 1.8 2002/05/13 06:41:10 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsv_wrec.pro)


CMSV_WVTYPE

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

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

 PURPOSE:
   Write variable type information to output block

 CALLING SEQUENCE:
   CMSV_WVTYPE, BLOCK, DATA, IDENT, $
                HEAP=HEAP, SYSTEM=SYSTEM, UNIT=UNIT, $
                OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
   
 DESCRIPTION: 

   CMSV_WVTYPE writes the type portion of an IDL SAVE variable
   record.  An IDL variable is stored in two components: the type
   descriptor which describes the name, type, and dimensions of the
   variable; and the data record, which contains the raw data of the
   variable.  This procedure writes the type descriptor based on a
   variable passed by the user.  Once the type descriptor has been
   written, the data portion can be written using the CMSV_WDATA
   procedure.

   CMSV_WVTYPE should recognize and correctly output type descriptors
   for all currently known IDL data types, except for object
   references.  Type information is inferred from the DATA parameter
   passed by the user.  

   Heap data is a special case, since the data itself are stored
   separately from the pointer in the SAVE file.  Three steps must be
   satisfied: a HEAP_INDEX record must be written; a valid HEAP_DATA
   record must be written containing a type descriptor (written with
   this procedure) and the heap data; and the named pointer itself
   must be written.


 ==================================================================
   Research Systems, Inc. has issued a separate license intended
   to resolve any potential conflict between this software and the
   IDL End User License Agreement. The text of that license
   can be found in the file LICENSE.RSI, included with this
   software library.
 ==================================================================

 BLOCK, POINTER, OFFSET

   This procedure writes data to a byte array only.  The intent is
   for users to accumulate a significant amount of data in a BLOCK
   and then write it out with a single call to WRITEU.  Users should
   be aware that the block can be larger than the buffered data, so
   they should use something like the following:

          WRITEU, UNIT, BLOCK(0:POINTER-1)

   When library routines do indeed write buffered BLOCK data to disk,
   they will appropriately reset the BLOCK and POINTER.  Namely,
   BLOCK will be reset to empty, and POINTER will be reset to zero.
   OFFSET will be advanced the according number of bytes.

   The terminology is as follows: BLOCK is a byte array which
   represents a portion of, or an entire, IDL SAVE file.  The block
   may be a cached portion of an on-disk file, or an entire in-memory
   SAVE file.  POINTER is the current file pointer within BLOCK
   (i.e., the next byte to be written is BLOCK[POINTER]).  Hence, a
   POINTER value of 0 refers to the start of the block.  OFFSET is
   the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
   OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
   The following diagram shows the meanings for BLOCK, POINTER and
   OFFSET schematically:


                 0 <-  OFFSET  -> |
   FILE          |----------------|------*--------|--------->

   BLOCK                          |------*--------|
                                  0      ^ POINTER
     

   This procedure is part of the CMSVLIB SAVE library for IDL by
   Craig Markwardt.  You must have the full CMSVLIB core package
   installed in order for this procedure to function properly.  


 INPUTS:

   BLOCK - a byte array, a cache of the SAVE file.  Users will
           usually not access this array directly.  Users are advised
           to clear BLOCK after calling POINT_LUN or writing the
           block to disk.

   POINTER - a long integer, a pointer to the next byte to be written
             from BLOCK.  CMSVLIB routines will automatically advance
             the pointer.

   DATA - the data to be written, of any save-able data type.

   IDENT - for variables, the name of the variable as a string; for
           heap data, the heap index as an integer.

 KEYWORDS:

   HEAP - if set, the data is treated as heap data, and IDENT must be
          an integer heap index.

   SYSTEM - if set, the data is assumed to be a system variable.

   UNIT - a file unit.  Currently ignored.

   OFFSET - the file offset of byte zero of BLOCK.  
            Upon output, if the file pointer is advanced, OFFSET will
            also be changed.
            (OFFSET is not currently used by this routine)
            Default: 0

   STATUS - upon return, this keyword will contain 1 for success and
            0 for failure.

   ERRMSG - upon return with a failure, this keyword will contain the
            error condition as a string.

 EXAMPLE:


 SEE ALSO:

   CMRESTORE, SAVE, RESTORE, CMSVLIB

 MODIFICATION HISTORY:
   Written, 2000
   Documented, 24 Jan 2001
   Added notification about RSI License, 13 May 2002, CM

 $Id: cmsv_wvtype.pro,v 1.13 2002/05/13 06:41:10 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsv_wvtype.pro)


CMSYSTIME

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

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

 PURPOSE:
   Compute seconds since Jan 1, 1970 and (Modified) Julian Days

 CALLING SEQUENCE:
   TIMEVAL1 = CMSYSTIME(TIMEVAL0, ...)

 DESCRIPTION: 

   CMSYSTIME serves two functions.  It computes the current time in a
   fashion similar to the built-in IDL system function SYSTIME().  It
   also can convert between various time representations and systems,
   including a textual format.

   The current time can be obtained by invoking CMSYSTIME with the
   /NOW keyword (which is entirely equivalent to SYSTIME(1)).

   The most substantial part of CMSYSTIME, which distinguishes it
   from SYSTIME, is its ability to convert between different time
   formats.  CMSYSTIME recognizes can recognize and convert between
   time in seconds (seconds since Jan 1, 1970 [ = SEC ]) and days
   (Julian days [ = JDAY ] or "Modified" Julian days [ = MJD = JDAY -
   2400000.5 ]).  It can also recognize and convert between local and
   GM time.  

   CMSYSTIME takes maximum care to preserve the full numerical
   precision of the time values.  It converts all values to double
   precision and may return days and seconds with fractional parts.

   CMSYSTIME can also represent any time textually, not just the
   current time.  The following textual formats are supported:
        DOW MMM DD hh:mm:ss YYYY              - (Default - same as SYSTIME)
        DOW MMM DD YYYY hh:mm:ss.uuuuuu TTTTT - (/EXTENDED)
   where DOW and MMM are the abbreviated day of week and month in
   English, DD is the day of the month, YYYY is the year, hh:mm:ss is
   the time in 24 hr military time, uuuuuu are additional
   microseconds, TTTTT is the timezone offset (in +hhmm
   representation).

   CMSYSTIME accepts one parameter, the input time to be converted.
   Unlike SYSTIME, the *function* of CMSYSTIME is governed by various
   keywords, as summarized in the following table:

   Converting from                       Converting to
   ---------------                       -------------
   JDAY - /FROM_JULIAN                   JDAY - /JULIAN
   MJD  - /FROM_MJD                      MJD  - /MJD
   SEC  - (Default)                      SEC  - /SECONDS
   Current time - /NOW                   TEXT - (Default or /EXTENDED)

   Local time - /FROM_LOCAL              Local time - /LOCAL
   GM time - (Default)                   GM time - (Default)
   
   If no argument is specified, the default is to report the current
   time textually in the GM time zone.  CMSYSTIME automatically
   determines the local time zone.

 INPUTS:

   TIMEVAL0 - input time, in seconds or days, as described above.
              This value is ignored if the NOW keyword is set.  Array
              values are allowed.

 KEYWORDS:

   NOW - If set, TIMEVAL0 is ignored and the current time is used as
         input.

   FROM_JULIAN - If set, TIMEVAL0 is in Julian days.
   FROM_MJD    - If set, TIMEVAL0 is in Modified Julian days (MJD).
   FROM_LOCAL  - If set, TIMEVAL0 is in the local time zone.
                 If no FROM_ keywords are set, the input is assumed
                 to be seconds from Jan 1, 1970.

   JULIAN  - If set, the input is converted to Julian days upon output.
   MJD     - If set, the input is converted to MJD upon output.
   SECONDS - If set, the input is converted to seconds from Jan
             1, 1970 upon output.
   LOCAL   - If set, the input is converted to the local time zone.
             If no "destination" keywords are set, the output is
             converted to textual representation.

   EXTENDED - Convert to a textual representation with additional
              information, as noted above.

   TIMEZONE - Upon output, the timezone offset is returned in this
              keyword.  The offset is time difference in seconds
              between GM time and the local time, such that LOCALTIME
              = GMTIME + TIMEZONE

 RETURNS:
   The resulting converted time(s), either as a double precision
   number or a string.

 EXAMPLE:
   
   The equivalent to SYSTIME(0)
     IDL> print, systime(0) & print, cmsystime(/now, /local)
     Wed Jul  5 12:10:46 2000
     Wed Jul  5 12:10:46 2000

   The equivalent to SYSTIME(1)
     IDL> print, systime(1) & print, cmsystime(/now,/seconds)
        9.6277750e+08
        9.6277750e+08

   Comparison between local and GM time zones (I live in the Eastern
    US, daylight savings)
     IDL> print, cmsystime(/now,/extended)
     Wed Jul  5 2000 16:13:15.659000 -0400
     IDL> print, cmsystime(/now,/local,/extended)
     Wed Jul  5 2000 12:13:15.664000 -0400
    
   What day of the week was it 200 days ago?  (Note, there are 86400
    seconds in one day)
     IDL> today = cmsystime(/now,/seconds)
     IDL> print, cmsystime(today-86400L*200, /local)
     Sat Dec 18 12:17:52 1999
    

 SEE ALSO:

   SYSTIME, JULDAY, CALDAT

 MODIFICATION HISTORY:
   Written, CM, 05 Jul 2000
   Printed time zone is zero when LOCAL=0, CM, 21 Aug 2000

  $Id: cmsystime.pro,v 1.2 2001/03/25 18:10:42 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsystime.pro)


CNES

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

 PURPOSE:
	This procedure is an example how to translate a cnes file

 CATEGORY:
   EXAMPLES

 CALLING SEQUENCE:
   cnes


 MODIFICATION HISTORY:
 	Written by:	R. Bauer , May, 4, 1997

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\examples\cnes.pro)


CNES2NCDF

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

 PURPOSE:
	This  procedure will translate a cnes Data File and translate it into
   a netCDF File.

 CATEGORY:
	DATAFILES/FILTER


 CALLING SEQUENCE:
	cnes2ncdf,file=file,inpath=inpath,outpath=outpath,[campaign=campaign],[/xp] ,[gps_aus=gps_aus]

 INPUTS:
   file:      the filename of the cnes file
   inpath:    the path where the cnesfile is
   outpath:   the path where the result should be stored

 OPTIONAL INPUTS:
   campaign:  the campaign name belonging to the cnes file

 KEYWORD PARAMETERS:
   xp:        will use pickfile for opening a cnes file

 OPTIONAL OUTPUTS:
   gps_aus:  the GPS data array from the cnesfile


 EXAMPLE:
   inpath = '/usr/local/icg/icg1/daten/experiments/adeos/cnes/asc/'
   outpath = '/usr/local/icg/icg1/daten/experiments/adeos/cnes/bin/'
   file = 'kir05110297.krn'
   campaign = 'ADEOS1997'
   cnes2ncdf,file=file,inpath=inpath,outpath=outpath,campaign=campaign

 MODIFICATION HISTORY:
 	Written by:	R.Bauer March, 3, 1997
   1999-Nov-06 help added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\cnes2ncdf.pro)


CNES_KIR2NCDF

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

 PURPOSE:
	This  procedure will translate a cnes KIR Data File and translate it into
   a netCDF File.

 CATEGORY:
	DATAFILES/FILTER


 CALLING SEQUENCE:
	cnes_kir2ncdf,file=file,inpath=inpath,outpath=outpath,[campaign=campaign],[/xp] ,[gps_aus=gps_aus]

 INPUTS:
   file:      the filename of the cnes file
   inpath:    the path where the cnesfile is
   outpath:   the path where the result should be stored

 OPTIONAL INPUTS:
   campaign:  the campaign name belonging to the cnes file

 KEYWORD PARAMETERS:
   xp:        will use pickfile for opening a cnes file

 OPTIONAL OUTPUTS:
   gps_aus:  the GPS data array from the cnesfile


 EXAMPLE:
   inpath = '/usr/local/icg/icg1/daten/experiments/adeos/cnes/asc/'
   outpath = '/usr/local/icg/icg1/daten/experiments/adeos/cnes/bin/'
   file = 'kir05110297.krn'
   campaign = 'ADEOS1997'
   cnes_kir2ncdf,file=file,inpath=inpath,outpath=outpath,campaign=campaign

 MODIFICATION HISTORY:
 	Written by:	R.Bauer March, 3, 1997
   1999-Nov-06 help added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\cnes_kir2ncdf.pro)


COLOR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       COLOR
 PURPOSE:
       Set a color in the color table by specifying color name.
 CATEGORY:
 CALLING SEQUENCE:
       color, name, [index, r, g, b]
 INPUTS:
       name = color name (like red, green, ...).           in
         Name may be modified by the words dark, pale,
         very dark, very pale.
         (Only one very is handled).  Default color=white.
       index = color table index for new color (def=last). in
       r, g, b = components of color table to modify.      in,out
         If r,g,b sent then table is not loaded.
 KEYWORD PARAMETERS:
       Keywords:
         FILE=f  color file to use instead of the default.
           Text file, each line has r g b color_name.
         /LEARN prompts for r,g,b values of an unknown color.
         /LIST lists all available colors.
         MAXNUMBER=mx  return number of colors known.
         NUMBER=n  Select color by color number (0 to MAXNUMBER-1).
           Index # 255 is set by default.  To set a different index
           a dummy color name must also be given.  It is ignored.
           Ex: color,'dum',50,number=7  sets index 50 to color 7.
           If no args are given default color and index used.
         NAME = nam  return name of selected color.
           Useful with NUMBER keyword.
         TEXT=txt  returns 0 or 255, whichever best with color.
         RED=r.  Return red value for specified color.
         GREEN=g.  Return green value for specified color.
         BLUE=b.  Return blue value for specified color.
         /EXIT exit without modifying screen color table.
 OUTPUTS:
 COMMON BLOCKS:
       color_com
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 26 Dec 1989
       R. Sterner, 7 Jun, 1990 --- polished for vms.
       R. Sterner, 4 Feb, 1991 ---- made system independent.
       R. Sterner, 1997 Dec 30 --- Converted colors file to text file
       and dropped need for Env. Var.
       R. Sterner, 1998 Jan 14 --- Switched to !d.table_size instead
       of !d.n_colors.

 Copyright (C) 1989, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\color.pro)


COLOR24

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

 PURPOSE:

       The purpose of this function is to convert a RGB color triple
       into the equivalent 24-bit long integer. The 24-bit integer
       can be decomposed into the appropriate color by interpreting
       the lowest 8 bits as red, the middle 8 bits as green, and the
       highest 8 bits as blue.

 AUTHOR:

       FANNING SOFTWARE CONSULTING
       David Fanning, Ph.D.
       1645 Sheely Drive
       Fort Collins, CO 80526 USA
       Phone: 970-221-0438
       E-mail: davidf@dfanning.com
       Coyote's Guide to IDL Programming: http://www.dfanning.com/

 CATEGORY:

       Graphics, Color Specification.

 CALLING SEQUENCE:

       color = COLOR24(rgb_triple)

 INPUTS:

       RGB_TRIPLE: A three-element column or row array representing
       a color triple. Or an N-by-three element array of color triples.
       The values of the elements must be between 0 and 255.

 KEYWORD PARAMETERS:
       None.

 COMMON BLOCKS:
       None.

 SIDE EFFECTS:
       None.

 RESTRICTIONS:
       None.

 EXAMPLE:

       To convert the color triple for the color YELLOW,
       (255, 255, 0), to the hexadecimal value '00FFFF'x
       or the decimal number 65535, type:

       color = COLOR24([255, 255, 0])

       This routine was written to be used with device-independent
       color programs like GETCOLOR.

 MODIFICATION HISTORY:

       Written by:  David Fanning, 3 February 96.
       Completely revised the algorithm to accept color arrays. 19 October 2000. DWF.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\color24.pro)


COLORBAR[1]

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

 PURPOSE:
       The purpose of this routine is to add a color bar to the current
       graphics window.

 AUTHOR:

   FANNING SOFTWARE CONSULTING
   David Fanning, Ph.D.
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: davidf@dfanning.com
   Coyote's Guide to IDL Programming: http://www.dfanning.com/

 CATEGORY:
       Graphics, Widgets.

 CALLING SEQUENCE:
       COLORBAR

 INPUTS:
       None.

 KEYWORD PARAMETERS:

       BOTTOM:   The lowest color index of the colors to be loaded in
                 the bar.

       CHARSIZE: The character size of the color bar annotations. Default is 1.0.

       COLOR:    The color index of the bar outline and characters. Default
                 is !P.Color..

       DIVISIONS: The number of divisions to divide the bar into. There will
                 be (divisions + 1) annotations. The default is 6.

       FONT:     Sets the font of the annotation. Hershey: -1, Hardware:0, True-Type: 1.

       FORMAT:   The format of the bar annotations. Default is '(I5)'.

       INVERTCOLORS: Setting this keyword inverts the colors in the color bar.

       MAXRANGE: The maximum data value for the bar annotation. Default is
                 NCOLORS.

       MINRANGE: The minimum data value for the bar annotation. Default is 0.

       MINOR:    The number of minor tick divisions. Default is 2.

       NCOLORS:  This is the number of colors in the color bar.

       POSITION: A four-element array of normalized coordinates in the same
                 form as the POSITION keyword on a plot. Default is
                 [0.88, 0.15, 0.95, 0.95] for a vertical bar and
                 [0.15, 0.88, 0.95, 0.95] for a horizontal bar.
;
       RANGE:    A two-element vector of the form [min, max]. Provides an
                 alternative way of setting the MINRANGE and MAXRANGE keywords.

       RIGHT:    This puts the labels on the right-hand side of a vertical
                 color bar. It applies only to vertical color bars.

       TITLE:    This is title for the color bar. The default is to have
                 no title.

       TOP:      This puts the labels on top of the bar rather than under it.
                 The keyword only applies if a horizontal color bar is rendered.

       VERTICAL: Setting this keyword give a vertical color bar. The default
                 is a horizontal color bar.

 COMMON BLOCKS:
       None.

 SIDE EFFECTS:
       Color bar is drawn in the current graphics window.

 RESTRICTIONS:
       The number of colors available on the display device (not the
       PostScript device) is used unless the NCOLORS keyword is used.

 EXAMPLE:
       To display a horizontal color bar above a contour plot, type:

       LOADCT, 5, NCOLORS=100
       CONTOUR, DIST(31,41), POSITION=[0.15, 0.15, 0.95, 0.75], $
          C_COLORS=INDGEN(25)*4, NLEVELS=25
       COLORBAR, NCOLORS=100, POSITION=[0.15, 0.85, 0.95, 0.90]

 MODIFICATION HISTORY:
       Written by: David Fanning, 10 JUNE 96.
       10/27/96: Added the ability to send output to PostScript. DWF
       11/4/96: Substantially rewritten to go to screen or PostScript
           file without having to know much about the PostScript device
           or even what the current graphics device is. DWF
       1/27/97: Added the RIGHT and TOP keywords. Also modified the
            way the TITLE keyword works. DWF
       7/15/97: Fixed a problem some machines have with plots that have
            no valid data range in them. DWF
       12/5/98: Fixed a problem in how the colorbar image is created that
            seemed to tickle a bug in some versions of IDL. DWF.
       1/12/99: Fixed a problem caused by RSI fixing a bug in IDL 5.2. Sigh... DWF.
       3/30/99: Modified a few of the defaults. DWF.
       3/30/99: Used NORMAL rather than DEVICE coords for positioning bar. DWF.
       3/30/99: Added the RANGE keyword. DWF.
       3/30/99: Added FONT keyword. DWF
       5/6/99: Many modifications to defaults. DWF.
       5/6/99: Removed PSCOLOR keyword. DWF.
       5/6/99: Improved error handling on position coordinates. DWF.
       5/6/99. Added MINOR keyword. DWF.
       5/6/99: Set Device, Decomposed=0 if necessary. DWF.
       2/9/99: Fixed a problem caused by setting BOTTOM keyword, but not NCOLORS. DWF.
       8/17/99. Fixed a problem with ambiguous MIN and MINOR keywords. DWF
       8/25/99. I think I *finally* got the BOTTOM/NCOLORS thing sorted out. :-( DWF.
       10/10/99. Modified the program so that current plot and map coordinates are
            saved and restored after the colorbar is drawn. DWF.
       3/18/00. Moved a block of code to prevent a problem with color decomposition. DWF.
       4/28/00. Made !P.Font default value for FONT keyword. DWF.
       9/26/00. Made the code more general for scalable pixel devices. DWF.
       1/16/01. Added INVERTCOLORS keyword. DWF.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\colorbar.pro)


COLORBAR[2]

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

 PURPOSE:
        Draw a colorbar (legend) with labels

 CATEGORY:
        Colors

 CALLING SEQUENCE:
        COLORBAR [,options]

 INPUTS:

 KEYWORD PARAMETERS:
        COLOR  -> the drawing color for boxes and labels 
             (default: !P.COLOR)
 
        BOTTOM -> first color index to use (default: 1)

        NCOLORS -> number of colors to use (default: 
             !D.N_Colors-bottom)

        MIN, MAX -> range of the data (default bottom and 
             bottom+ncolors-1

        LABEL -> array with label values (must be numeric).
             Normally, it is easier to generate labels with the 
             DIVISIONS options, but this allows tighter control 
             (e.g. 1,2,5,10,20 labels on logarithmic scales).
             Default (if no DIVISIONS are given): min and max

        DIVISIONS -> number of labels to put on the colorbar.
             Note that this keyword is overwritten by LABEL.
             The labels will be equally spaced and the /LOG option
             will be honored.

        FORMAT -> output format of the labels. Default is determined
             according to the range given in min and max. Label strings 
             will be trimmed, so you can safely specify f14.2 for example.

        SCIENTIFIC -> If set, will call STRSCI to put the colorbar
             labels in scientific notation format (e.g. in the form
             A x 10^B).  STRSCI will use the format string specified 
             in the FORMAT keyword.

        /LOG -> logarithmic spacing of labels (colors are *always* 
             linearily distributed)

        C_COLORS -> array of color indices for "discrete" color bars
             e.g. in filled contour plots. You must also use the 
             C_LEVELS keyword, otherwise there will most likely be
             a mismatch between your plot colors and your colorbar 
             colors. COLORBAR normally limits the number of labels
             it prints to 10. Use the SKIP keyword to force a different
             behaviour. If C_COLORS is not undefined it overrides the
             settings from NCOLORS, and BOTTOM.

        C_LEVELS -> array with label values for discrete colorbars.
             Use the LABEL keyword for continuous colors. C_LEVELS
             must have the same number of elements as C_COLORS and 
             assigns one label to each color change (LABEL distributes
             the labels evenly). Use the SKIP keyword to skip labels.
             As default, COLORBAR limits the number of labels printed 
             to 10. 
             NB: In order to be consistent with the behaviour of the 
             CONTOUR procedure, colorbar disregards the first entry of
             C_LEVELS.

        SKIP -> print only every nth discrete label. Default is computed
             so that COLORBAR will print no more than 10 labels.

        STARTLABEL -> for discrete colorbars: the first left box side to be
             labeled. Default is 1, i.e. between the first two boxes.

        /VERTICAL -> set this keyword to produce a vertical colorbar
             (default is horizontal). Note that out-of-range boxes are
             only implemented for horizontal color bars.

        POSITION -> a position value or 4-element vector. If POSITION
             contains only one element, it will be centered at the
             bottom or right side of the page and extend over 60% of
             the total plotting area.

        CHARSIZE -> character size (default !p.charsize)

        TITLE -> a title string (similar to XTITLE or YTITLE for PLOT)

        UNIT -> a unit string that will be added to the right (top) of
             the labels

        BotOutOfRange, TopOutOfRange -> a colorindex value for data
             that falls below or above the normal plot range. If given,
             an extra box will be drawn to the left or right of the color-
             bar, and the colorbar will shrink in size. A default label
             '<' ('>') will be placed below. Note that these options are
             only available for horizontal colorbars.

        BOR_Label, TOR_Label -> label values for BOTOutOfRange and 
             TopOutOfRange that replace the defaults.

 OUTPUTS:

 SUBROUTINES:

 REQUIREMENTS:
        The user should have some knowledge about colortables and the
        use of parts of a colortable.
        This program uses STRSCI for labels in scientific notation.

 NOTES:
        This routine was designed after David Fanning's colorbar
        routine and enhanced. Some of the postscript
        handling of DF was removed, positioning is a little easier but
        maybe a little less flexible; out-of-range boxes have been
        added.

 EXAMPLE:
        ; draw a colorbar with all available colors on top of index 20
        ; will be placed at the bottom of the page

        colorbar,bottom=20,min=min(data),max=max(data)

        ; draw another colorbar above the first one, use logarithmic scale

        colorbar,bottom=20,min=0.1,max=10.,labels=[0.1,0.5,1.,5.10.],/log, $
              position=0.3,unit='ppt'

        ; (simply add keyword /vertical and you'll get it flipped)

        ; colorbar with out-of-range information on right side only
        ; Here we used 20 colors for the plot, the 21st is for 
        ; out-of-range data

        colorbar,bottom=20,ncolors=20,min=0,max=100,divisions=5, $
              TopOutOfRange=40

 MODIFICATION HISTORY:
        mgs, 02 Jun 1998: VERSION 1.00
        mgs, 14 Nov 1998: - changed default format to f14.2 from f6.2
        mgs, 19 Nov 1998: - added cbdefaultformat function to better handle
                            default labeling format.
        mgs, 28 Nov 1998: - default labelling format now exponential for
                            values gt 1.e6
        mgs, 19 May 1999: - unit string placed a little further right
                            in horizontal colorbars.
        mgs, 27 May 1999: - added functionality for discrete colorbars
                            (C_COLORS, C_LEVELS, and SKIP keywords)
        bmy, 02 Jun 1999: - added /SCIENTIFIC keyword
                          - updated comments
        mgs, 14 Sep 1999: - charsize bug fix. Needed to check for 0.
        mgs, 23 Sep 1999: - now uses !P.COLOR as default color (as it was originally)
                          - BOTTOM default now 1 (because 0 is the standard beackground
                            value)
        mgs, 17 Dec 1999: - fixed zero division for SKIP=0
                          - added StartLabel keyword for discrete colorbars
        mgs, 20 Dec 1999: - disregard first entry of C_LEVELS

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\colorbar.pro)


COLORBAR__DEFINE

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

 PURPOSE:
       The purpose of this routine is to implement a COLORBAR object
       class. The ColorBar is rendered in the direct graphics system.

 AUTHOR:
       FANNING SOFTWARE CONSULTING
       David Fanning, Ph.D.
       1645 Sheely Drive
       Fort Collins, CO 80526 USA
       Phone: 970-221-0438
       E-mail: davidf@dfanning.com
       Coyote's Guide to IDL Programming: http://www.dfanning.com

 CATEGORY:
       Graphics.

 CALLING SEQUENCE:
       colorbar = Obj_New("COLORBAR")

 INPUTS:
       All inputs to the program are via keyword parameters.

 KEYWORD PARAMETERS:

   Background: Background color. This is the color with which the colorbar is
               erased. The default color is !P.Background.
   Bottom: Bottom color index of colors allocated to colorbar.
   Charsize: Character size of annotation. Default is 1.0.
   Color: Color of annotation and outline. Default is !P.Color.
   Font: Font to use for annotation. Default is -1, Hershey fonts.
   Format: Format of annotation. Default is "(F8.2)".
   Major: The number of major tick intervals. Default is 5.
   Minor: The number of minor tick intervals. Default is 2.
   MinusOne: Set this keyword to choose MinusOne keyword on the Congrid command
               that resizes the colorbar into the window.
   NColors: The number of colors allocated to colorbar. Default is (256 <
            !D.N_Colors).
   Neighbor: Set to indicate Nearest Neighbor sampling for Congrid. Default is
             0 (Bilinear).
   Position: The position of colorbar in normalized coordinates. Default for a
             horizontal colorbar is [0.15, 0.88, 0.85, 0.95]. Default for a
             vertical colorbar is [0.88, 0.15, 0.95, 0.85]. These defaults are
             designed for a 400 by 400 window.
   Range: The data range on colorbar. Default is [0, 255].
   TickLen: The length of tick marks. Default is -0.1
   TickV:   Locations for the tick marks in data units. This is the same as
            the [XY]TickV keyword. Default is to do what IDL would do
            normally.
   Vertical: Set this keyword if you want a vertical colorbar. Default is
             horizontal.
   XEraseBox: A five-element vector of X points (normalized) for erasing the
              colorbar plot. Normally this keyword will not have to be used.
              The program uses the plot REGION for erasing. But larger
              character sizes can result in annotation going outside the
              region enclosed by the plot. If that is the case, then use this
              keyword along with YEraseBox to specify a larger-than-normal
              erasure area. The points are sent to the POLYFILL command for
              erasing.

                 POLYFILL, xEraseBox, yEraseBox, /Normal, Color=background

   YEraseBox: A five-element vector of Y points (normalized) for erasing the
              colorbar plot.

 OBJECT METHODS:

   Clamp: This procedure method allows the color bar range to be "clamped"
          to a particular data range.

   Draw: This procedure method draws the colorbar in the display window. The
         ERASE keyword to this method will erase the current colorbar (by
         calling the ERASE method) before drawing the colorbar in the display
         window.

               colorbar->Draw

   Erase: This procedure method erases the colorbar object in the window. It
          accomplishes this by performing a POLYFILL in the background color.
          This method is primarily useful for interactive graphics display
          devices.
               colorbar->Erase

   GetProperty: This procedure method allows one to obtain the current state
                of the object via the keyword parameters listed above.

               colorbar->GetProperty, Range=currentRange, Title=currentTitle
               Print, currentRange, currentTitle

   SetProperty: This procedure method allows one to set the properties of the
                colorbar object via the keywords described above. In addition,
                a DRAW and ERASE keyword are provided so that the colorbar can
                be immediately drawn when the new property is set.

               colorbar->SetProperty, Range=[500, 15000], /Erase, /Draw

 COMMON BLOCKS:
       None.

 SIDE EFFECTS:
       The display window is not erased first.

 RESTRICTIONS:
       None.

 EXAMPLE:
       To create a colorbar, use it, then destroy it, type:

       colorbar = Obj_New("COLORBAR", Title='Colorbar Values', Range=[0,1000],$
                  Format='(I4)')
       Window
       LoadCT, 5
       colorbar->Draw
       colorbar->SetProperty, Range=[0,500], /Erase, /Draw
       Obj_Destroy, colorbar

 MODIFICATION HISTORY:
       Written by: David Fanning, Fanning Software Consulting,
                   26 November 1998.
       Added Horizontal keyword to SetProperty method and fixed problem in
       going from Vertical to Horizontal color bars. 29 Nov 1998. DWF.
       Added LoadCT method and current color table index to object.
             6 December 1998.
       Fixed a bug dealing with nearest neighbor resampling. 30 Mar 1999. DWF.
       Fixed a bug with how NCOLORS and BOTTOM keywords interacted.
             29 Aug 1999. DWF.
       10 Oct 99. Modified the program so that current plot and map coordinates
                are saved and restored after the colorbar is drawn. DWF.
       26 May 2000 Added {XY}TICKV capability to the draw method. This
                required adding TickV to the object data structure, and to the
                INIT, GetProperty and SetProperty methods.
                Changed default tick length to -0.1. DWF (and Jack Saba)
       18 Nov 2001. Added Clamp method. DWF.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\colorbar__define.pro)


COLORCHART

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

 PURPOSE:
    produce a chart with many colors to test printers and find colors
    suitable for plotting.
    EXPERIMENTAL STATUS - NOT PERFECT

 CATEGORY:
    Colors

 MODIFICATION HISTORY:
    mgs, some time in 1999.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\colorchart.pro)


COLORIZE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       COLORIZE
 PURPOSE:
       Colorize an image.
 CATEGORY:
 CALLING SEQUENCE:
       colorize
 INPUTS:
 KEYWORD PARAMETERS:
       Keywords:
         IMAGE=img  Name of GIF image to colorize.
         COLORS=clr Name of GIF image with color areas to overlay.
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
       Notes: Result is displayed on screen.
 MODIFICATION HISTORY:
       R. Sterner, 1999 Aug 17

 Copyright (C) 1999, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\colorize.pro)


COLORS8BIT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       COLORS8BIT
 PURPOSE:
       Show array of 256 colors in a window.
 CATEGORY:
 CALLING SEQUENCE:
       colors8bit
 INPUTS:
 KEYWORD PARAMETERS:
       Keywords:
         BLACK=blk  Specify black or dark color (def=0).
         WHITE=wht  Specify white or bright color (def=1).
           These are used for the index numbers.
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
       Notes: useful to pick colors from the window systems
       colors in case IDL cannot control the colors.  For
       example, when using 256 colors on a workstation and
       a widget, the IDL colors will not show up while using
       the widget.  This may make it impossible to use the
       widget.  One work around is to use good window colors
       for the IDL graphics.  For example, window color 23
       may be white and 32 blue.  If XOR mode graphics is used
       then XOR 55 with 23 to get 32 (32 = 23 xor 55).  If the
       background color is bck and you want plot color clr then
       just plot (bck XOR clr), where the plot crosses the
       background it will be that color.
 MODIFICATION HISTORY:
       R. Sterner, 1998 May 12

 Copyright (C) 1998, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\colors8bit.pro)


COLORWARN

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       COLORWARN
 PURPOSE:
       Warn if available IDL colors too few.
 CATEGORY:
 CALLING SEQUENCE:
       colorwarn
 INPUTS:
 KEYWORD PARAMETERS:
       Keywords:
         MINIMUM=n  Alert if below this value.
         /QUIET     Suppress information message.
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 1996 Feb 23

 Copyright (C) 1996, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\colorwarn.pro)


COLOR_BAR

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:  color_bar

 PURPOSE:  draw a horizontal color bar

 USEAGE:   color_bar

 INPUT:    
   levels  
     a vector of physical values (required)

   colors  
     a vector of color values. If colors is not specified a
     continuous spectrum of colors between colors values 1 and
     !d.n_colors-2 are used.


 KEYWORD INPUT:
   pos
     position of color bar in normal or subnormal coordinates
     [xmin,ymin,xmax,ymax], if pos is not specified, CURBOX is
     called to set the color bar position interactively.

   digits
     number of significant digits used in number scale label
     digits=0 causes an integer format to be used. any positive value
     causes a floating point format.

   stride
     if set, label only those intervals which have n mod stride eq 0,
     where n is the number of intervals counting left to right.
   
   subnorm
     use subnormal coordinates to specify pos. subnormal coordinates
     vary from 0 to 1 across the range of the last plotting window.
     If not set, normalized coordinates are used.
 
   labels  a string array of labels for color values. 

           if nlabels eq nlevels   ==> center labels under tick marks
           if nlabels eq nlevels-1 ==> center labels between tick marks
           otherwise               ==> execution stops, error message issued

           where nlabels=n_elements(labels) and nlevels=n_elements(levels)

   title   overall title for color bar, appears below labels


 OUTPUT:
  none

 DISCUSSION:

 LIMITATIONS:

 COMMON BLOCKS:

 SIDE EFFECTS:
  
 EXAMPLE:  

    loadct,5
    !y.omargin=[10,0]
    !p.multi=[0,2,2]
    r=randata(50,50,s=4) & r=(r-3)
    levels=-9+indgen(10)
    colors=findrng(20,!d.n_colors,9)
    confill,r,/noscale,levels=levels,colors=colors
    confill,rotate(r,1),/noscale,levels=levels,colors=colors
    confill,rotate(r,2),/noscale,levels=levels,colors=colors
    confill,rotate(r,3),/noscale,levels=levels,colors=colors
    !y.omargin=0

    labels='10!a-'+strcompress(string(8-indgen(9)),/rem)
    title='ozone mass density (ug/m3)'
    color_bar,levels,colors,labels=labels,title=title

; use a continuous spectrum of colors

    !y.omargin=[10,0]
    !p.multi=[0,2,2]
    r=randata(50,50,s=4) & r=(r-3)
    levels=-9+indgen(10)
    colors=findrng(20,!d.n_colors,9)
    tvim,r & tvim,rotate(r,1) & tvim,rotate(r,2) & tvim,rotate(r,3)
    !y.omargin=0

    color_bar,indgen(10),labels=labels,title=title

 AUTHOR:   Paul Ricchiazzi                        09 Feb 96
           Institute for Computational Earth System Science
           University of California, Santa Barbara
           paul@icess.ucsb.edu

 REVISIONS:

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\color_bar.pro)


COLOR_FRAME

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:  color_frame

 PURPOSE:  draw a color background on which to overlay plots

 USEAGE:   result=color_frame(color,pos=pos,xmargin=xmargin,ymargin=ymargin)

 INPUT:  
   color  
     the background color of the plot frame  
   

 KEYWORD INPUT:
   pos
     4 element vector specifying the lower left and upper right
     normalized coordinates of the plot frame [xll,yll,xur,yur]

   xmargin
     2 element vector specifying the left and right margins in character
     width units

   ymargin
     2 element vector specifying the lower and upper margins in character
     height units

   bg_color
     back ground color used outside of plot frame
;
 OUTPUT:
   result
     4 element vector specifying the lower left and upper right
     normalized coordinates of the plot frame [xll,yll,xur,yur]

 DISCUSSION: 
     COLOR_FRAME can be used to produce color backgrounds within plot
     frames.  Since COLOR_FRAME itself calls PLOT to obtain the
     default frame position, it is necessary to include the NOERASE
     keyword in the PLOT call that actually draws the plot. See examples.

 LIMITATIONS:

 COMMON BLOCKS:

 SIDE EFFECTS:
  
 EXAMPLE:  

  !p.multi=[0,1,2]
  loadct,5
  xx=findrng(-2.5,2.5,200)
  yy=exp(-xx^2)
  yc=cos(xx*10)
  plot,xx,yy,pos=color_frame(50),/noerase
  plot,xx,yc*yy,pos=color_frame(70),/noerase

  plot,xx,yc^2*yy,pos=color_frame(90),/noerase
  plot,xx,yc^3*yy,pos=color_frame(110),/noerase
   
;; multi-frame plot

  loadct,5
  !p.multi=[0,1,2]
  plot,xx,yy,pos=color_frame(100,ymargin=ymulti(p,np=2)),/noerase
  plot,xx,yc*yy,pos=color_frame(60,ymargin=ymulti(p)),/noerase
   
;; plot within a plot

  loadct,5
  !p.multi=0
  plot,xx,yy*yc,pos=color_frame(50,bg=10),/noerase
  plot,xx,yy,pos=color_frame(100,pos=boxpos(/cur)),/noerase

;; color in frame over a different background color

  loadct,5
  plot,xx,yy,pos=color_frame(100,bg=50),/noerase,color=255
  
 AUTHOR:   Paul Ricchiazzi                        23 Feb 96
           Institute for Computational Earth System Science
           University of California, Santa Barbara
           paul@icess.ucsb.edu

 REVISIONS:

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\color_frame.pro)


COLOR_KEY

[Previous Routine] [Next Routine] [List of Routines]
ROUTINE:     COLOR_KEY

PURPOSE:     draws a numbered color scale.  
             NOTE: COLOR_KEY is intended to replace PUT_COLOR_SCALE

USEAGE:     
            COLOR_KEY,pos=pos,ysize=ysize,range=range,inc=inc,$
                    charsize=charsize,barwidth=barwidth,step=step,$
                    labels=labels,title=title,colors=colors,nbotclr=nbotclr

PURPOSE:    Draws a numbered color scale

INPUT:      no required input

OPTIONAL KEYWORD INPUT:

  pos          2 element vector, x and y device coordinates of lower 
               left hand corner of color bar.  If POS is not set the
               color bar will be placed one character width to the 
               right of the lower right corner of the last defined 
               data window

  xoff         x offset of color bar from right edge of plot frame in
               units of default character with.  (default=1) xoff is
               disabled when pos is set.

  range        array which contains full range of physical values,
               The number scale limits are computed fron min(range) and
               max(range).  (default=0-255)

  inc          increment step of the number scale in physical units
               If INC is not set the number scale increment is set 
               automatically

  step         if set to one, the color table is modified with STEP_CT.
               The color scale is stepped at the number scale intervals. 

  colors       a vector of discreet colors selected from the original
               color table.  In this case the original color table is
               not modified and the number of elements of COLORS
               is used to find the number scale increments. This
               option should be used with devices that do not accept
               user specified color tables (such as the Apple Laser
               Writers).  BEWARE: when the COLORS option is used with
               TVIM's SCALE option care must be taken to ensure that
               COLOR_KEY's number scale matches the quantity values.
               Unlike the STEP option, this is not automatic (see
               example below)

  nbotclr      number of reserved colors at the bottom of the color
               table.  these colors will not appear in the color key.

  charsize     character size on number scale

  ysize        vertical size of color bar in device units. 
               if ysize is negative, the abs of ysize is interpreted
               as the normalized z coordinate of the top of the bar.

  barwidth     width of color bar (default=1)

  labels       a vector of strings used to label the color key levels
               if not set the default color key number labels are
               used.  If the number of elements in LABELS is the same
               as the number of elements in COLORS then the labels
               will appear in the middle of a given color band
               instead of at the boundary between colors.

  title        color scale title drawn to the right of the color key

  slevels      selected levels at which to mark vertical scale. If LABELS
               is also set, the number of elements in LABELS should be
               equal to either nsl, or nsl-1 where nsl is the number of
               elements in SLEVELS.  The SLEVELS input does not work when
               COLORS is also specified.

  rct          if set, reverse direction of grey scale increase.  This
               keyword can be used on black & white printers to allow
               large field values to be represented by dark colors.
               
               

KEYWORD OUTPUT

  clevels      physical values at the color key tic marks

  SIDE EFFECTS:
               if STEP is set COLOR_KEY calls STEP_CT to discreetize
               the color scale.  To return to original color table
               enter STEP_CT,/OFF

EXAMPLE:

; on devices which allow user defined color tables:

      loadct,0
      TVIM,dist(200),/scale
      COLOR_KEY,range=dist(200),inc=20,/step ; change the color scale
      COLOR_KEY,range=dist(200),inc=40,/step ; change it again

; on devices with a single hard-wired color table:

      d=dist(200)+20.
      inc=step_size(d)            ; finds good step size
      dmin=fix(min(d)/inc)*inc
      dmax=fix(max(d)/inc)*inc
      nclrs=(dmax-dmin)/inc
      colors=!p.color*indgen(nclrs)/(nclrs-1)
      TVIM,colors((d-dmin)/inc),/scale,/c_map
      color_key,range=[dmin,dmax],colors=colors


; draw one big color key which applies to all tvim images on frame
 
      !p.multi=[0,2,2]
      loadct,5
      im1=randata(128,128,s=3)
      im2=rotate(im1,5)
      im3=rotate(im1,7)
      im4=rotate(im1,2)
      range=[min(im1,max=mx),mx]
      !x.omargin=[0,20]
      tvim,im1,range=range
      tvim,im2,range=range
      tvim,im3,range=range
      tvim,im4,range=range
      color_key,range=range,xoff=10,ysize=-.97

; logarithmic scales  

      im=randata(128,128)
      im=abs(im) & im=3*(im/max(im) > .001)
      tvim,im,/rmarg ; here we assume im is the log10 of some plot quantity.

      ndec=3       ; number of decades

      slevels=[1.] ; starting value
      for i=0,ndec-1 do slevels=[slevels,(findgen(9)+2)*10.^i]
      slevels=alog10(slevels)
      labels=strarr(n_elements(slevels))
      labels(indgen(ndec+1)*9)=string(f='("10!a",i1,"!b")',indgen(ndec+1))
      color_key,range=im,slevels=slevels,labels=labels


 AUTHOR:       Paul Ricchiazzi    jan93 
               Earth Space Research Group, UCSB

 REVISIONS:
 20sep93: put in LABELS option
 21sep93: use pure white blankout color for postscript
 22sep93: put in COLORS option
 09sep96: put in SLEVELS option
 

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\color_key.pro)


COLOR_PAL

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:                 color_pal

 AUTHOR:                 Terry Figel, ESRG, UCSB 10-21-92

 CALLING SEQUENCE:        color_pal

 PURPOSE:                 Displays Color palette in a seperate window

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\color_pal.pro)


COLOR_QUANJ

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       COLOR_QUANJ
 PURPOSE:
       Combines Red, Green, Blue components into a color image.
 CATEGORY:
 CALLING SEQUENCE:
       c = color_quanj(red, grn, blu, r, g, b)
 INPUTS:
       red, grn, blu = Red, green, and blue images.   in
 KEYWORD PARAMETERS:
       Keywords:
         COLORS=n  Number of colors to have in final image
           (def=number of available colors).
         /DITHER   Combined using dithering.
         /DISPLAY  Display resulting image.
         /ORDER    Display image with first line at top.
 OUTPUTS:
       r,g,b = Color table for combined color image.  out
       c = Resulting color image.                     out
 COMMON BLOCKS:
 NOTES:
       Notes: This routine uses another color combining method
         then color_quan, it writes the image to a JPEG file and
         then reads it back.  This gives better results than
         color_quan in some cases.
 MODIFICATION HISTORY:
       R. Sterner, 1995 Nov 24

 Copyright (C) 1995, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\color_quanj.pro)


COLOR_SCHEME

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

 PURPOSE:
   This procedure is used to load one or more predefined dynamical color scheme (ct_*.pro')

 CATEGORY:
   PLOT/PLOT2D

 CALLING SEQUENCE:
   color_scheme,plot,[scheme_code=scheme_code]

 INPUTS:
   plot: This is the defined plot scructure look at pl_init
         If it is not given defaults will be loaded from pl_init

 KEYWORD PARAMETERS:
   scheme_code: the integer code or "character string" of the color scheme
               1:  a dyamical color code from yellow - red - blue - green - black that's the default
               2:  a dyamical color code from blue - red - yellow
               3:  a dyamical color code from blue - green - yellow - red
               12: a dyamical color code from yellow - red - blue
               20: a dynamical gray scaled color code
               'ct_yellow_red_blue'

  EXAMPLE:
   color_scheme,plot,scheme_code=1
   or for setting up of two colorsystems:
   color_scheme,plot,scheme_code=[20,2]
   or
   color_scheme,plot,scheme_code=['ct_yellow_red_blue_green_black','ct_yellow_red_blue']



 MODIFICATION HISTORY:
 	Written by:	R.Bauer (ICG-1), 1997-Oct-5
                       R.Bauer 1997-Nov-12 additional colortable
                       1998-Jul-8 multiple color tables added
               1999-Feb-05 because of idl5.2 interpretation of !d.n_colors this constant is replaced by def_n_colors()
               1999-Feb-28 color names changed
               1999-Dec-08 some more colortables added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\color_scheme.pro)


COLOR_WHEEL

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       COLOR_WHEEL
 PURPOSE:
       Pick a color using a color wheel.
 CATEGORY:
 CALLING SEQUENCE:
       color_wheel, clr
 INPUTS:
 KEYWORD PARAMETERS:
       Keywords:
         /VARYWHEEL means vary wheel brightness using bar.
         XPOS=xpos, YPOS=ypos Window position.
         SIZE=sz  Size of color wheel (def=200).
 OUTPUTS:
       clr = Returned color.   out
         -1 means ignore new color.
 COMMON BLOCKS:
 NOTES:
       Notes: color is selected by clicking on a color
         wheel and brightness bar.
 MODIFICATION HISTORY:
       R. Sterner, 2000 Aug 22
       R. Sterner, 2001 Feb 15 --- Added HSV and RGB listing.

 Copyright (C) 2000, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\color_wheel.pro)


COMBINE_PATH_FILE

[Previous Routine] [Next Routine] [List of Routines]
 USERLEVEL:
   TOPLEVEL

 NAME:
   combine_path_file

 PURPOSE:
   This function will combine path and file, change '\' to '/' and add '/' to the path if necessaray

 CATEGORY:
   PROG_TOOLS/STRINGS

 CALLING SEQUENCE:
   result=combine_path_file(path,file)

 INPUTS:
   path,file : scalar strings

 OUTPUTS:
    result: correct combination of path and file

 SIDE EFFECTS
   will resolve multiple // into /

 EXAMPLE:
   result=combine_path_file('d:\/temp','test.xxx')
   will return result:'d:/temp/test.xxx'

   result=combine_path_file('d:\/temp','')
   will return result:'d:/temp/'

 MODIFICATION HISTORY:
   Written by Franz Rohrer Aug 1998
   Modified

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\combine_path_file.pro)


COMMALIST

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       COMMALIST
 PURPOSE:
       Return a given array as a comma delimited text list.
 CATEGORY:
 CALLING SEQUENCE:
       list = commalist(array, [form])
 INPUTS:
       array = Input array of numbers.          in
       form = Optional format (like I3).        in
 KEYWORD PARAMETERS:
       Keywords:
         /NOCOMMAS  do not add commas to returned list.
         DELIMITER=del Delimiter instead of comma.
 OUTPUTS:
       list = Returned text string with list.   out
 COMMON BLOCKS:
 NOTES:
       Note: see wordarray as a near inverse.
 MODIFICATION HISTORY:
       R. Sterner, 1995 Nov 28
       R. Sterner, 1998 Jul 31 --- Added DELIMITER=d, also fixed for alpha.

 Copyright (C) 1995, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\commalist.pro)


COMPASS

[Previous Routine] [Next Routine] [List of Routines]
ROUTINE:     compass

USEAGE       compass, lat0,lon0,alat,alon,rng,az
             compass, lat0,lon0,rng,az,alat,alon,/to_latlon

PURPOSE:     Given the geographical coordinates of an array of points
             on the on the earth's surface, compute the great-circle 
             distance and compass heading from the central point.
             Distances and azimuth angles about the central point are 
             provided in KM and Degrees.  

             If TO_LATLON is set, convert the specified range and
             azimuth values to lat, lon coordinates

INPUT:
  lat0       geographic latitude (degrees) of central point
  lon0       geographic longitude (degrees) of central point
 
INPUT/OUTPUT
  alat       geographic latitudes

  alon       geographic longitudes

  rng        great circle distances (km) from (lat0,lon0) to (alat,alon)

  az         azimuth angles (degrees), azimuth is measured clockwise
             from due north (compass heading)

KEYWORD INPUT:
 to_latlon   if set, rng, az input converted to lat, lon


EXAMPLE:

;; plot family of great circles passing though lat,lon=(0,0)

  rng=findrng(0,2*!pi*6371.2,400)
  map_set,/cyl,/cont,/grid
  for az=0,90,15 do begin &$
   compass,0,0,rng,az,alat,alon,/to_latlon & oplot,alon,alat & endfor
  

;; find the range and az of Janus Island from Palmer Station

  lat0=-64.767 & lon0=-64.067 & alat=-64.78 & alon=-64.11
  compass,lat0,lon0,alat,alon,rng,az
  compass,lat0,lon0,rng,az,nlat,nlon,/to_latlon 
  print,f='(6a13)','alat','alon','rng','az','nlat','nlon' &$
  print,alat,alon,rng,az,nlat,nlon


  author:  Paul Ricchiazzi                            jan93
           Institute for Computational Earth System Science
           University of California, Santa Barbara

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\compass.pro)


COMPILE_PLOT

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

 PURPOSE:
	This routine writes a precompiled idl sav file


 CATEGORY:
   PRECOMPILE

 CALLING SEQUENCE:
   compile_plot


 MODIFICATION HISTORY:
 	Written by:	R.Bauer (ICG-1), 1998-Jul-05
   1999-02-28 independent_path removed

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\compile_plot.pro)


COMPOSE_STRUCTURE

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

 PURPOSE:
	This is the reverse function to decompose_structure.
	For details see that procedure.

 CATEGORY:
	PROG_TOOLS

 CALLING SEQUENCE:
	result = compose_structure(pstruc [, index])

 INPUTS:
	pstruc: Array of structures as it is obtained from the procedure
		decompose_structure

 KEYWORD PARAMETERS:
	/NO_FREE: If set no PTR_FREE command will be issued to destroys the heap variables.

 OPTIONAL INPUTS:
	index: Index vector to subscribe single elements of pstruc

 OUTPUTS:
	This function returns a 'normal' structure.

 EXAMPLE:
	see decompose_structure

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 09.12.1999
	04.01.2000:	Added PTR_FREE command
	05.01.2000:	Got rid of LINK tag
	12.01.2000:	Added keyword parameter /NO_FREE

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\compose_structure.pro)


COMPOUND

[Previous Routine] [Next Routine] [List of Routines]
 pro compound,compound_string,density,z_array

	Type in a chemical formula and the density.  The routine
	then figures out the atomic weight in g/mole of "molecules"
	and how many of what Z atoms you have.	The
	density isn't really needed here; it's just that if
	what you type is defined in
		(your directory) compound.dat
               (a system directory; see below) compound.dat
	then you can type
		compound,'protein',density,atwt,z_array
	and get both the density and z_array set for you.

	Note that you can do "zshow,z_array" to check out the
	composition.

 CJJ Feb 93

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\HENKE\compound.pro)


COMP_BITS

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

 PURPOSE:
	This function performs a bitwise AND operation on two operands.

 CATEGORY:
	MATH

 CALLING SEQUENCE:
	result = comp_bits(var, value)

 INPUTS:
	var, value: the two operands

 KEYWORD PARAMETERS:
	/BIT - operand  is treated as bit number.
		the following AND operation is performed: var AND 2^value

 OUTPUTS:
	This function either returns 0 if the bitwise AND operation returns 0 or
	1 in any other case.

 EXAMPLE:
	print, comp_bits(9, 1) --> 1
	print, comp_bits(9, 3, /BIT) --> 1

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 08. Jun 98.
	30.04.1999:	Removed debug statement

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\comp_bits.pro)


COMP_K_OH_NO2

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

 PURPOSE:
   This procedure compares different literature values for the reaction constant OH+NO2

 CATEGORY:
   PHYSCHEM

 CALLING SEQUENCE:
   comp_k_oh_no2

 INPUTS:

 OUTPUTS:

 EXAMPLE:
   comp_k_oh_no2

   MODIFICATION HISTORY:
   Written by: Franz Rohrer March 1999

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\comp_k_oh_no2.pro)


CONCATENATE_NCDF_INHALT

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

 PURPOSE:
   This function will concatenate two structures read from a ncdf-file into one.

 CATEGORY:
   PROG_TOOLS/STRUCTURES

 CALLING SEQUENCE:
   result=concatenate_ncdf_inhalt(master,client)

 INPUTS:
   master: master structure
   client:

 OUTPUTS:
   result: concatenated structure
   Tags 'time', 'param' and the tags flagged in 'flags' are concatenated from master and client.
   All other tags will be taken from master only.
   Tag 'valid' will be updated correctly.

 EXAMPLE:


 MODIFICATION HISTORY:
   Written by Franz Rohrer Jan 1999

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\concatenate_ncdf_inhalt.pro)


CONCATINATE_TWO_STRUCTURE_TAGS

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

 PURPOSE:
   The result of this function is an structure where the elements of two structure tags are concatinated

 CATEGORY:
   PROG_TOOLS/STRUCTURES

 CALLING SEQUENCE:
   Result=concatinate_two_structure_tags(master,client)

 INPUTS:
  master: The master structure
  client: the client structure
  both structure have to have the same tag names defined

 OUTPUTS:
   This function returns a structure

 EXAMPLE:

 MODIFICATION HISTORY:
   Written by:	R.Bauer (ICG-1),  1998-Sep-29
   1999-Nov-06 help added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\concatinate_two_structure_tags.pro)


CONCAT_STR

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

	PURPOSE:
		This function concatenates two structures

	CATEGORY:
		PROG_TOOLS/STRUCTURES

	CALLING SEQUENCE:
		result = concat_str(master, client [,/OVERWRITE] [,/PARSE] [,ERR = err])

	INPUTS:
		master, client: Two structures

	KEYWORD PARAMETERS:
		/OVERWRITE: If set, a tag of client will overwrite a tag with the same name in master.
			The default is that all tags from master are part of the returned stucture.
		ERR: If set to a named variable the error status of the routine will be returned:
			0: no error, 1: error ocurred (see log window)
		/PARSE: If set, a tag in client will be removed if its name starts with the same
			string as the name of a master tag (e.g. master = {tag: 4}, client = {tag_name: 9.2})
			If not set (default), a tag in client will only be removed if a tag with exactly
			the same name appears in master.

	OUTPUTS:
		This function returns the structure which results from the concatenation of the two
		structures master and client

	EXAMPLE:
		master = {a: 1, b: 'ASD'}
		client = {b: 7L, c: 6.78}
		HELP, concat_str(master, client), /STR
			** Structure <1362ec4>, 3 tags, length=16, refs=1:
		   	A               INT              1
			   B               STRING    'ASD'
			   C               FLOAT           6.78000

		master={col: 3, thick: 2, ycharsize: 2}
		client={color: 5, thick: 1, charsize: 3}
		HELP, concat_str(master, client, /PARSE), /STR
			** Structure <1353bf8>, 4 tags, length=8, refs=1:
			   COL             INT              3
			   THICK           INT              2
			   YCHARSIZE       INT              2
			   CHARSIZE        INT              3

	MODIFICATION HISTORY:
		Written by:	Frank Holland, 02. May 1998.
		15.11.1998:	Header added
		17.11.1998:	Implemented new procedure to build concatenated structure
		17.02.1999:	Changed entry under PURPOSE
		28.04.1999:	Added KEYWORD parameter PARSE

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\concat_str.pro)


CONCOORD

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CONCOORD
 PURPOSE:
       Convert between two linear coordinate systems.
 CATEGORY:
 CALLING SEQUENCE:
       concoord, x1, y1, x2, y2
 INPUTS:
       x1,y1 = input coordinates.          in
 KEYWORD PARAMETERS:
       Keywords:
         /ROUND means round output to nearest integers.
           Intended for pixel coordinates.
         /TO_1  the input point(s), x1,y1, are in system 2 and are
           to be converted to system 1.  /TO_1 is the default.
         /TO_2  the input point(s), x1,y1, are in system 1 and are
           to be converted to system 2.
         /INIT  means initialize coordinate transformations.
           In this case x1,y1 are the known reference point
           coordinates in system 1, and x2,y2 are the known
           reference point coordinates in system 2.
           At least 3 non-colinear reference points are needed
           to define the coordinate transformations, more are
           ok.  So for /INIT all 4 parameters are inputs and
           arrays of at least 3 elements.
         NAME1=nm1, NAME2=nm2  Optional coordinate system names,
           def=system 1 and system 2.  Only on /INIT.
           Use /SYSTEMS to display system names at a later time.
           Very useful to make the correct calls clear.
 OUTPUTS:
       x2,y2 = output coordinates.         out
 COMMON BLOCKS:
       concoord_com
 NOTES:
       Notes: Example for pixel coordinates and lat/long:
         concoord,ix,iy,lng,lat,/init,name1='Pixels',name2='Long/lat'
           ix,iy are arrays of ref pt pixel coord, lng,lat are
           arrays of ref pt long, lat.
         concoord,lng,lat,ix,iy,/to_1,/round
           From long,lat find pixel coordinates.
 MODIFICATION HISTORY:
       R. Sterner, 1996 Oct 2

 Copyright (C) 1996, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\concoord.pro)


CONFILL

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:  confill

 PURPOSE:  display a contour plot with filled contours 

 USEAGE:   confill,z,x,y,xrange=xrange,yrange=yrange,charsize=charsize,$
                   title=title,stitle=stitle,xtitle=xtitle,ytitle=ytitle,$
                   aspect=aspect,colors=colors,range=range,nlevels=nlevels,$
                   rmarg=rmarg,pcharsize=pcharsize,lcharsize=lcharsize,$
                   c_thick=c_thick,c_label=c_label,c_charsize=c_charsize,$
                   c_orientation=c_orientation,c_spacing=c_spacing,$
                   downhill=downhill,xtype=xtype,ytype=ytype,$
                   c_color=c_color,labels=labels,position=position,$
                   levels=levels,rgb_data=rgb_data,noscale=noscale

 INPUT:    
  z
    array of field values

  x
    one or two dimensional array of x axis points

  y
    one or two dimensional array of y axis points

    IF z,x, and y are all one dimensional vectors and all the same
    size, it is assumed that irregularly grided data is being
    supplied.  In this case the routine TRIANGULATE is called to get
    the Delaunay triangulation of the data.  The triangulation info
    is then passed on to CONTOUR


 KEYWORD INPUT:

  title
    plot title

  xtitle
    x axis title
 
  ytitle
    y axis title

  stitle
    color key title (drawn to the right of color scale)

  noscale 
    if set, no color key will be drawn

  rmarg 
    right margin expansion factor to provide more room for extra wide
    color scale annotation (default=1)

  xrange
    x axis range. (default = [0,x_dimension-1])

  yrange
    y axis range. (default = [0,y_dimension-1])

  range
    two element vector indicating physical range over which
    to distribute contour levels. 

  nlevels
    maximum number of contour levels.  If LEVELS is not set the
    actual number of contour levels is determined automatically by
    AUTORANGE.  NLEVELS sets the maximum allowed number of levels,
    the actual number of levels may be less.

  levels
    contour level values (vector).  The default contour levels are
    set by AUTORANGE. The automatically selected levels chosen by
    AUTORANGE can be retrieved by setting LEVELS to a named variable
    which is initially undefined or set to zero.

  labels
     a vector of strings used to label the color key levels.  If not
     set the default color key number labels are used.  If the number
     of elements in LABELS is the same as the number of elements in
     COLORS then the labels will appear in the middle of a given
     color band instead of at the boundary between colors.  If COLORS
     is not set, the number of elements in LABELS should be at least
     as large as the number of color key segments plus one.  

  colors
     an array of color indicies used to fill contours.  The number of
     color values should be one less than the number of levels. The
     default colors are chosen to be uniformally distributed over the
     full color table.  The automatically selected colors chosen by
     CONFILL are:  colors=fix((!d.n_colors-2)*(1+findgen(nclr))/nclr),
     where nclr=n_elements(levels)-1.  If COLORS is set to a negative
     number these automatically chosen colors are reversed so that dark 
     colors are used to represent high intensity areas.

     NOTE: The default color indicies generated by CONFILL never
     include color index 0 or !d.n_colors-1.  These indicies are
     reserved for the overall plot background and foreground colors.
     For best results, color index 0 and !d.n_colors-1 should
     correspond to pure black and white respectively, which is
     usually the case in the predefined color tables supplied by RSI.
     A predefined color table that doesn't follow this rule can be
     redefined using TVLCT to put black and white in these slots,
     without affecting any of the filled contours used in the CONFILL
     plot:   tvlct,0,0,0,0 & tvlct,255,255,255,!d.n_colors-1
     
  c_label 
     integer array indicating which contour lines to label.  For
     example, c_label=[0,0,0,1,0,1] indicates that the contour lines
     which correspond to levels(3) and levels(5) are to be labeled.
     The number of C_LABELs should be the same as the number of
     LEVELS. By default no contour lines are labeled.

  c_thick
     thickness of contour lines (may be a vector of values),
     Default is 1.

  c_color
     color of contour lines (may be a scalor or vector of values).
     If c_color is negative then the color of contour lines is chosen
     to maximize contrast with adjacent fill colors. The default is
     not to drawn contour lines.  This keyword must be set to get 
     contour lines.

     NOTE: The number of contour levels is determined automatically
     if LEVELS is not set.  Hence, it may not be possible to guess
     how many values of LABELS, COLORS, C_LABEL, C_THICK or C_COLOR
     should be specified. It is probably safer not to include these
     parameters unless LEVELS is also specified.
        
  c_orientation
    If the FILL keyword is set, this keyword can be set to the angle,
    in degrees counterclockwise from the horizontal, of the lines
    used to fill contours.  If neither C_ORIENTATION or C_SPACING are
    specified, the contours are solid filled.
        
  c_spacing
    If the FILL keyword is set, this keyword can be used to control
    the distance, in centimeters, between the lines used to fill the
    contours.

  xtype
    Set this keyword to specify a logarithmic X axis.
        
  ytype
    Set this keyword to specify a logarithmic Y axis.
        
  downhill
    Set this keyword to label each contour with short, perpendicular
    tick marks that point in the "downhill" direction, making the
    direction of the grade readily apparent. If this keyword is set,
    the contour following method is used in drawing the contours.

    NOTE: Due to a bug in IDL_3.6,  the concurrent use of C_LABEL and
          DOWNHILL causes an IDL session crash.  For this reason the
          DOWNHILL option is disabled on IDL_3.6.
        
  aspect
    the x over y aspect ratio of the output image. If not set, the 
    aspect ratio is adjusted to fill the available plotting area.

  position
    specifies the lower left and upper right CONFILL frame position in
    normal coordinates.  When set POSITION overides the setting of
    ASPECT.

  pcharsize
    character size of numbers along x and y axis and the title
    (default is !p.charsize if non-zero, 1 otherwise)
 
    NOTE: The character size of the x and y-axis number scale
    annotation may be independently controlled by the !x.charsize or
    !y.charsize system variables.  For example, the x and y axis
    number scale characters may be made invisible by setting these
    variables to a very small non-zero number before calling CONFILL.
    Remember to restore normal character sizes by setting !x.charsize
    and !y.charsize to 1 or zero after the call to CONFILL.

  lcharsize
    character size of color key number or labels (default is
    pcharsize if set, otherwise !p.charsize if non-zero, 1 otherwise)

  barwidth
     width of color key which appears to right of contour plot (default=1).

  rgb_nodata
    if set, regions with field values less then the minimum of LEVELS
    or RANGE will be colored with the RGB values specified in
    RGB_NODATA (a scalor or three element vector).  Color index 1 is
    used for the nodata color.  When RGB_NODATA is set don't use
    color index 1 in the COLORS input vector.  

    NOTE: RGB_NODATA has no effect unless either RANGE or LEVELS is
    set.  This is because the default contour levels are set so that
    the minimum level is less than the minimum field value.

  overplot if set, current field is super imposed over a previous
    confill plot this option only works when z,x, and y are all one
    dimensional vectors and all the same size, in which case it is
    assumed that irregularly grided data is being supplied.  In this
    case the routine TRIANGULATE is called to get the Delaunay
    triangulation of the data.  The triangulation info is then passed
    on to CONTOUR.

 DEPENDENCIES: COLOR_KEY, AUTORANGE

 SIDE EFFECTS: if RGB_NODATA is set the rgb value of color index 1
               is modified

 EXAMPLES:

 loadct,5
 n=128
 zz=randata(n,n,s=4)
 xx=findrng([-120,-100],n)
 yy=findrng([20,50],n)
 confill,zz,xx,yy,title='Plot title',xtitle='x-axis',ytitle='y-axis',$
         stitle='contour levels',c_color=-1

 confill,zz,xx,yy,title='Plot title',xtitle='x-axis',ytitle='y-axis',$
         stitle='contour levels',c_color=-1,rgb_nodata=!p.color/2

; labeled regions

 levels=-3+findgen(6)*2
 labels=[' ocean','  rain!c forrest',' sand',$
         ' old!c snow',' real!c new!c snow']
 confill,zz,xx,yy,title='Plot title',xtitle='x-axis',ytitle='y-axis',$
         stitle='surface types',labels=labels,levels=levels,barwidth=.5

; contour irregularly grided data

 loadct,5
 w8x11
 n=128
 z=randata(n,n,s=4)
 x=findgen(n)
 y=findgen(n)
 !p.multi=[0,1,2]
 confill,z,x,y,title='Regularly Grided',c_color=-1

 ii=randomu(iseed,200)*(n*n-1)         ; random sample points
 zz=z(ii)                              ; random samples
 xx=ii mod n                           ;   (zz,xx,yy are vectors)
 yy=ii / n
 confill,zz,xx,yy,title='Randomly Sampled',c_color=-1

 oplot,xx,yy,psym=4,color=1,symsize=.4 ; show locations of sample points

; overlay three irregular regions in one confill plot

 loadct,5
 w8x11
 n=128
 z=randata(n,n,s=4)
 ii=randomu(iseed,200)*(n*n-1)         ; random sample points
 zz=z(ii)                              ; random samples
 xx=ii mod n                           ;   (zz,xx,yy are vectors)
 yy=ii / n
 confill,zz,xx,yy,xrange=[0,300]
 confill,zz^2,xx+150,yy/2,/overplot
 confill,sqrt(zz>0),xx+150,70+yy/2,/over


 AUTHOR:   Paul Ricchiazzi                        24 May 95
           Institute for Computational Earth System Science
           University of California, Santa Barbara

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\confill.pro)


CONFRAC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		CONFRAC
 VERSION:
		4.0
 PURPOSE:
		Performs continued fraction evaluation.
 CATEGORY:
		Mathematical function (general).
 CALLING SEQUENCE:
		Result = CONFRAC( A, B [,X [, keywords]])
 INPUTS:
	A
		A numeric scalar, vector or a 2-D array.  A(i,*) contains the i-th
		A coefficient(s) of the continued fraction.
	B
		Same as A for the B coefficient(s).  A and B must agree in their first
		dimension, i.e. if A is an (N,M) array (including the possibility of
		M = 1) then B must be an (N,M') array, with an arbitrary M'.
 OPTIONAL INPUT PARAMETERS:
	X
		Numeric, otherwise arbitrary.  When provided, X is used together with
		A and B to determine the continued fraction coefficients.
 KEYWORD PARAMETERS:
	AFUNCTION
		Name of a function to be used (with the CALL_FUNCTION routine) to
		determine the A coefficients.  Optional.
	BFUNCTION
		Same as AFUNCTION for the B coefficients.  Optional.
	EPSILON
		Smallness parameter, determining the allowed evaluation error.
		Optional.  Default values are machine dependent, established through
		TOLER which calls MACHAR().
	/RELATIVE
		Switch.  If set, EPS represent the allowed relative evaluation error.
	ERROR
		Optional output, see below.
	STATUS
		Optional output, see below.
 OUTPUTS:
		Returns the value(s) of the continued fraction.  The result is of the
		same format as X (a scalar if X is not given).  The type of the result
		is the highest of the types of A, B, and X, but no lower than 4 (float).
 OPTIONAL OUTPUT PARAMETERS:
	ERROR
		The name of the variable to receive the estimated evaluation error.
		Given in the same format as X (scalar if X isn't provided).  If
		RELATIVE is set the error returned is relative.
	STATUS
		The name of the variable to receive evaluation status information.
		Same format as ERROR.  Possible values are:
			0 - evaluation didn't converge.
			1 - OK.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		None other then the restrictions on A, B, as mentioned above.
 PROCEDURE:
		CONFRAC evaluates continued fractions of the form

			res = a(0)/(b(0) + a(1)/(b(1) + a(2)/(b(2) + ......

		Using the recurrence relation from Numerical Recipies, Sec 5.2.  The
		designation of the coefficients a(i), b(i) depends on the data
		provided, as follows:

		1)  If X isn't provided then a(i) = A(i) (or A(i,0) if A is a 2-dim
			array) and same is true for b(i) (using B)
		2)  If X is provided then a(i) = Sum_j(A(i,j)*X^j) and the same for b(i)
			using B.  In other words the fraction coefficients are polynomials
			in X, using columns of A, B, as polynomial coefficients.  Note that
			if A and/or B are one dimensional arrays then only X^0 is used i.e.
			we are back to case 1.
		3)  If AFUN and/or BFUN are provided then a(i) = afun(x,A(i,*),i) and
			same for b(i) with BFUN and B.  The functions can be arbitrary but
			they must accept at least three parameters.

		CONFRAC uses CALCTYPE, CAST, DEFAULT, FPU_FIX, POLEVAL, TOLER and TYPE
		from MIDL.
 MODIFICATION HISTORY:
		Created 20-DEC-1994 by Mati Meron.
		Modified 10-SEP-1998 by Mati Meron.  Underflow filtering added.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\confrac.pro)


CONGRID2

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CONGRID2
 PURPOSE:
       Alternate (and limited) congrid using interpolate.
 CATEGORY:
 CALLING SEQUENCE:
       z2 = congrid2(z,mx,my)
 INPUTS:
       z = input 2-d array.                   in
       mx, my = requested output array size.  in
 KEYWORD PARAMETERS:
       Keywords:
         /INTERPOLATE means do bilinear interpolation.
           Default is nearest neighbor.
         /CENTERED means assume pixels centered.  This means
           the pixel at (0,0) is clipped to 1/4 size.
           Default is that pixel start (not center) is at index.
 OUTPUTS:
       z2 = resulting array.                  out
 COMMON BLOCKS:
 NOTES:
       Notes: tries to correct problems in congrid.  Result may
         look odd due to extrapolation.  For example, using
         /CENT and /INTERP gives results with magnified pixels
         not all the same size.
 MODIFICATION HISTORY:
       R. Sterner, 1996 Dec 2

 Copyright (C) 1996, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\congrid2.pro)


CONGRID8C

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CONGRID8C
 PURPOSE:
       Do 24 bit congrid interpolation on 8 bit color image.
 CATEGORY:
 CALLING SEQUENCE:
       out = congrid8c(in, nx, ny)
 INPUTS:
       in = input 8 bit color image.                in
       nx,ny = New output image dimensions.         in
 KEYWORD PARAMETERS:
       Keywords:
         INRED=r1   Input image red color table.
         INGREEN=g1 Input image green color table.
         INBLUE=b1  Input image blue color table.
           If these are not given the current color table is used.
         RED=r1   Output image red color table.
         GREEN=g1 Output image green color table.
         BLUE=b1  Output image blue color table.
         /INTERP, /CUBIC, and /MINUS_ONE work as for congrid.
 OUTPUTS:
       out = interpolated output image.             out
 COMMON BLOCKS:
 NOTES:
       Notes: Intended for 8 bit color images such as GIF or TIFF.
 MODIFICATION HISTORY:
       R. Sterner, 1994 May 4

 Copyright (C) 1994, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\congrid8c.pro)


CONJ_MM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		CONJ_MM
 VERSION:
		4.0
 PURPOSE:
		Returns complex conjugate values.
 CATEGORY:
		Mathematical, general.
 CALLING SEQUENCE:
		Result = CONJ_MM (X)
 INPUTS:
	X
		Numerical, otherwise arbitrary.
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
		None.
 OUTPUTS:
		Returns the complex conjugate of the input, if the input is complex,
		else returns the input.  The only difference from the RSI function CONJ
		is that the output of CONJ_MM is always of the same numerical type as
		the input.
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		None.
 PROCEDURE:
		Straightforward.  Calling CAST and ISNUM from MIDL.
 MODIFICATION HISTORY:
		Created 15-JUL-2000 by Mati Meron.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\conj_mm.pro)


CONNECTED

[Previous Routine] [Next Routine] [List of Routines]
 routine:      connected

 useage:       connected,image,nstring,view=view

 purpose:      The bi-level image is searched for all pixels which are
               are part a continous set of adjacent pixels. Those pixel
               groupings which contain fewer than NSTRING "on" pixels are
               set to zero.
 input:

   image       a bi-level image array (2d)

   nstring     the number of "on" pixels required for a given cluster of
               adjacent pixels to survive.

 output:
   image       a bi-level image with islands composed of fewer than nstring
               pixels removed.

 EXAMPLE:

   r=randata(128,128,s=2) gt 7
   connected,r,3,/view

 WARNING:      this procedure can take a lot of time for large images.
               for images larger than 64 x 64 computation times goes
               something like 
                               time=c * (NX x NY)^2

               for a DecStation 5000/240, c=7.4e-8, and 
               a 256x256 image takes about 5 minutes.

  author:  Paul Ricchiazzi                            Nov93
           Institute for Computational Earth System Science
           University of California, Santa Barbara

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\connected.pro)


CONSTANTS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		CONSTANTS
 VERSION:
		4.0
 PURPOSE:
		Creates or updates a system variable named !PCON.  !PCON is a structure
		the fields of which contain values of physical constants as follows:
		!PCON
			USYS  - Unit System.  Either 'MKS' or CGS'.
			C     -	Speed of light.
			E     -	Electron charge.
			H     -	Planck constant.
			ME    -	Electron mass.
			K     -	Boltzman constant.
			NA    -	Avogadro constant.

			ECONV -	Used internally for unit conversion.

			HBAR  -	Planck constant divided by 2*pi.
			ALPHA -	Fine structure constant.
			AMU   -	Atomic mass unit.
			SIGMA -	Stefan-Boltzman radiation constant.

		All the values are given in a double precision format.  Of course, the
		actual accuracy depends on how precisely they can be measured.
 CATEGORY:
		Utility.
 CALLING SEQUENCE:
		CONSTANTS [,/MKS or /CGS]
 INPUTS:
		None.
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
	/MKS
		Switch.  Sets the units system to MKS.  This is also the default.
	/CGS
		Switch.  Sets the units system to CGS.  Default is MKS.
 OUTPUTS:
		None.
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		M_CONS.  Contains a single parameter, EXISTS.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		Can't use both MKS and CGS at the same time.
 PROCEDURE:
		Either creates or, if EXISTS is defined, updates the system variable
		!PCONS.  Uses ONE_OF from MIDL.
 MODIFICATION HISTORY:
		Created 30-MAR-1994 by Mati Meron.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\constants.pro)


CONTLEV

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:    contlev

 PURPOSE:    find a good set of contour levels 

 USEAGE:     result=contlev(a)

 INPUT:      
   a         an array

 KEYWORD INPUT:
   maxlev    maximum number of levels on the plot.  Setting this keyword to,
             say, 5 does not mean you will get 5 levels.  It just means no
             more than 5 levels will be generated.

 OUTPUT:
   result    a vector of contour levels

 EXAMPLE:    contour,dist(20),levels=contlev(dist(20),maxlev=8)

  author:  Paul Ricchiazzi                            feb94
           Institute for Computational Earth System Science
           University of California, Santa Barbara

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\contlev.pro)


CONTRASTZOOM

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

 PURPOSE:

       The purpose of this program is to demonstrate how to
       zoom an image "in place" and how to window and level
       (set "contrast and brightness") an image using object
       graphics functionality. The exercise involves using
       multiple views in an object graphics scene, and being
       able to interact with different views in different ways.

 AUTHOR:

       FANNING SOFTWARE CONSULTING
       David Fanning, Ph.D.
       1645 Sheely Drive
       Fort Collins, CO 80526 USA
       Phone: 970-221-0438
       E-mail: davidf@dfanning.com
       Coyote's Guide to IDL Programming: http://www.dfanning.com

 CATEGORY:

       Widgets, Object Graphics.

 CALLING SEQUENCE:

       ContrastZoom, image

 REQUIRED INPUTS:

       None. The image "mr_knee.dcm" from the examples/data directory
       is used if no data is supplied in call.

 OPTIONAL INPUTS

       image: A 2D image array of any data type.

 OPTIONAL KEYWORD PARAMETERS:

       COLORTABLE: The number of a color table to use as the image palette.
       Color table 0 (grayscale) is used as a default.

       GROUP_LEADER: The group leader for this program. When the group leader
       is destroyed, this program will be destroyed.

 COMMON BLOCKS:

       None.

 SIDE EFFECTS:

       None.

 RESTRICTIONS:

       None. The Coyote Library program VCOLORBAR is included.

 EXAMPLE:

       To use this program with your 8-bit image data and a red-temperature
       color scale, type:

          IDL> ContrastZoom, image, Colortable=3

 NOTES:

       The left image is used to "zoom" into a portion of the image.
       The aspect ratio of the sub-image is always preserved. To see
       the entire image, click and release the mouse button in this
       window.

       The center image is used to adjust the contrast and brightness
       (sometimes called the "window" and "level" of the image. Click and
       drag the mouse vertically to set contrast. Click and drag the mouse
       horizontally to set brightness. To return to original values (25%
       contrast and 75% brightness), click and release in the center image.

       The color bars shows the image values of the image.

 MODIFICATION HISTORY:

       Written by David Fanning, 18 November 2001.
       Added second colorbar to show the relationship of the clamped
          colors to the overall image values. 19 November 2001. DWF.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\contrastzoom.pro)


CONT_ERROR_19990804

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

 PURPOSE:
   This example shows the error by contour and triangulation

 CATEGORY:
   EXAMPLES/PLOT/PLOT2D

 CALLING SEQUENCE:
   cont_error_19990804

 EXAMPLE:
 cont_error_19990804


 MODIFICATION HISTORY:
       Written by:     R.Bauer (ICG-1), 1999-Aug-04

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\examples\plot\plot2d\cont_error_19990804.pro)


CONV13B_10B

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

 PURPOSE:
   this procedure will remove all ^M in unix from pc created idlscripts

 CATEGORY:
   PROG_TOOLS

 CALLING SEQUENCE:
   conv13b_10b,file_name

 INPUTS:
   file_name: the name of the file

 RESTRICTIONS:
 will only work on unix

 EXAMPLE:
   conv13b_10b

 MODIFICATION HISTORY:
 	Written by:	R.Bauer (ICG-1),August 1997
   1999-Nov-06 help added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\conv13b_10b.pro)


CONVERT_ICGS_NAME

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

 PURPOSE:
	If an ICG structure and a short name (tag name) is provided this function returns
	one of the following: [short name, tag name, long name, unit].

 CATEGORY:
	ICG_STRUCT/PROG_TOOLS

 CALLING SEQUENCE:
	result = convert_icgs_name(icgs, name)

 INPUTS:
	icgs: ICG structure
	name: short name of parameter in ICG structure (scalar or array).

 KEYWORD PARAMETERS:
	/TAG_NAME: If set name is interpreted as tag name.
	/TO_SHORT_NAME: If set conversion is to short name.
	/TO_TAG_NAME: If set conversion is to tag name.
	/TO_LONG_NAME: If set conversion is to long name ('NONE' if not defined).
	/TO_UNITS: If set conversion is to unit ('NONE' if not defined).

 OUTPUTS:
	This function returns the [short name, tag name, long name, unit] for
	parameters in an ICG structure which are characterized by their short
	or tag name.

 EXAMPLE:
	hox_data = read_ncdf('hox.nc')
	PRINT, convert_icgs_name(hox_data, 'OH', /TO_LONG_NAME)   ---> 'OH radical concentration'

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 18.02.2000

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\convert_icgs_name.pro)


CONVERT_IND

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CONVERT_IND
 PURPOSE:
       Convert a text description of runs of indices to numbers.
 CATEGORY:
 CALLING SEQUENCE:
       ind = convert_ind(txt)
 INPUTS:
       txt = text string or array.     in
 KEYWORD PARAMETERS:
 OUTPUTS:
       ind = long array of indices.    out
 COMMON BLOCKS:
 NOTES:
       Notes: txt contains a list of integers.  A range may
         be indicated by the syntax b:e where b = beginning,
         and e = end of the range.  A step, s, may also be
         given: b:e:s.  An example list might be:
         txt=['2,3,4,10:20:2,25:30','34,35,38:40','50:100:10,111']
         print,convert_ind(txt) gives:
         2   3   4  10  12  14  16  18  20  25  26  27  28  29  30
         34  35  38  39  40  50  60  70  80  90 100 111
	  Inverse of LISTRUNS.PRO.
 MODIFICATION HISTORY:
       R. Sterner, 24 Jul, 1991

 Copyright (C) 1991, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\convert_ind.pro)


CONVERT_INDEX

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

 PURPOSE:
        Converts a 1-D array index (such as is returned from 
        WHERE, UNIQ, etc) to the appropriate 1-D, 2-D, or 3-D
        array indices

 CATEGORY:
        Array Tools

 CALLING SEQUENCE:
        Result = CONVERT_INDEX( Index, Dim )

 INPUTS:
        INDEX  -> The 1-D array index to be converted to  
                  multi-dimensional indices.  INDEX is returned
                  to the calling program unchanged.
 
        DIM    -> A vector containing the dimensions of the array
                  for which multi-dimensional indices are required.

 KEYWORD PARAMETERS:
        FORTRAN -> Interpret array indices as FORTRAN indices, i.e.
                  starting from 1 instead of 0. This applies to INPUT 
                  and OUTPUT indices!

 OUTPUTS:
        Returns either a vector index or a vector of multi-dimensional 
        array indices as the value of the function. If INDEX is a 
        1-dimensional parameter, the result will have n_elements(dim)
        dimensions, if Index is a multidimensional parameter, the result
        will be a scalar.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        Right now only works for 3-D arrays and smaller.  Will
        eventually do the general case...

 EXAMPLE:

 IDL> print,convert_index([1,1],[2,2])
           3
 IDL> print,convert_index([2,2],[2,2])
 % CONVERT_INDEX: Index[0] greater than Dim[0]
 % CONVERT_INDEX: Index[1] greater than Dim[1]
            6
 IDL> print,convert_index([2,2],[2,2],/FORTRAN)
            4       ; <<<-- shifted by 1 !

 IDL> print,convert_index(72,[72,46,20])
            0           1           0
 IDL> print,convert_index(72,[72,46,20],/FORTRAN)
           72           1           1
 
 MODIFICATION HISTORY:
        bmy, 07 Oct 1998: VERSION 1.00
        mgs, 07 Oct 1998: VERSION 1.20
               - made result etc LONG arrays
               - allow sany dimensions now
               - added reverse operation if index is multidimensional
               - added FORTRAN keyword 
        mgs, 23 Aug 2000: - changed copyright to open source

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\convert_index.pro)


CONVERT_LON

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

 PURPOSE:
        Convert longitudes from -180..180 to 0..360 or vice 
        versa.

 CATEGORY:
        Geography

 CALLING SEQUENCE:
        CONVERT_LON,data,names,Pacific=Pacific,Atlantic=Atlantic, $
                 minval=minval

 INPUTS:
        DATA -> A data array (lines,vars) or vector containing 
            longitude data. If DATA is a 2D array, the NAMES
            parameter must be given to identify the LONgitude variable.

        NAMES -> A string list of variable names. The longitude data
            must be labeled 'LON', unless specified with the LONNAME
            keyword. The NAMES parameter is not needed, if a data
            vector is passed.

 KEYWORD PARAMETERS:
        PACIFIC -> Convert longitudes from -180..180 to 0..360

        ATLANTIC -> Convert from 0..360 to -180..180

        LONNAME -> Name of the longitude variable if a name other
            than 'LON' is used.

 OUTPUTS:
        The longitude column in the data array will be changed.

 SUBROUTINES:

 REQUIREMENTS:

 NOTES:

 EXAMPLE:
        londat = [ -180.,-179.,-0.1,0.1,179.,180.,270.,359.]
        CONVERT_LON,londat,/Pacific
        print,londat

        CONVERT_LON,londat,/Atlantic
        print,londat

 MODIFICATION HISTORY:
        mgs, 25 Aug 1998: VERSION 1.00
        mgs, 19 May 1999: - now makes sure that longitude range does
                            not exceed -180..180 or 0..360
        mgs, 24 Jun 1999: - bug fix: choked at missing values 
        mgs, 23 Aug 2000: - changed copyright to open source

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\convert_lon.pro)


CONVERT_UNIT

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

 PURPOSE:
        Convert data to a different unit. You can either 
        replace a unit by the corresponding standard SI unit or 
        replace a specific unit with another one.

 CATEGORY:
        General Science

 CALLING SEQUENCE:
        CONVERT_UNIT,DATA,UNIT,TOPARAM [,keywords]

 INPUTS:
        DATA -> A data vector, array, or a single value that shall
            be converted to a new unit. 

        UNIT -> A string variable containing the (current) unit of 
            DATA. This will be replaced by the new unit afterwards.
            If omitted, you must give the FROM_UNIT keyword to indicate
            the current unit of DATA.

        TOPARAM -> The unit to convert DATA to. This is equivalent to 
            the keyword TO_UNIT and overwrites it.

 KEYWORD PARAMETERS:
        FROM_UNIT -> An individual unit to search and replace. If not
            given, any unit will be converted to TO_UNIT, as long as
            the current unit belongs to the same physicalcategory. 

        TO_UNIT -> An individual unit to convert to. If not given, all
            unit that are converted (see FROM_UNIT) will be replaced
            by the standard SI unit of their physicalcategory.

        For the individual unit and categories see FIND_UNIT 

        RESULT -> returns 1 if conversion was successful, 0 otherwise
            This keyword is mostly for consistency witholder routines.
            It is more convenient to test !ERROR_STATE.CODE for being
            0.

        MINVAL -> minimum valid data value. Only data above this 
            value will be converted (default: -1.E30)

        QUIET -> In case of an error, an error message is displayed,
            and the !ERROR_STATUS system variable is set to reflect the
            error condition (program execution continues). Set the
            QUIET keyword to suppress the error message.

 OUTPUTS:
        DATA will be converted and unit will contain new names.

 SUBROUTINES:

 REQUIREMENTS:
        Uses FIND_UNIT

 NOTES:
        CONVERT_UNIT wil return the value and unit unchanged if
        the unit was not found in the standard list (see FIND_UNIT)
        or the physicalcategory of the target unit does not match the
        physicalcategory of the source unit. In these cases, 
        !ERROR_STATE.CODE will be set to signal an error condition.

        Should try the udunits implementation by ?????

 EXAMPLE:
        ; create some data
        data = findgen(100)
        unit = 'cm'

        ; convert all data to SI unit of same category (m)
        convert_unit,data,unit

        ; test success
        if (!ERROR_STATE.CODE ne 0) then stop

        ; convert temperature in Fahrenheit to 'deg C'
        ; (multiple calls to capture all different spellings)
        ; Data will only be changed if unit is indeed Fahrenheit
        convert_unit,data,unit,from='F',to='deg C'
        convert_unit,data,unit,from='degF',to='deg C'
        convert_unit,data,unit,from='deg F',to='deg C'

        ; (easier way) convert any temperature to 'C'
        ; This will also convert 'K' !
        ; Don't display error message
        convert_unit,data,unit,to='C',/QUIET

        ; convert 'mph' data to SI ('m/s')
        convert_unit,data,unit,from='mph'

        ; explicitely convert 'cm' to 'm'
        convert_unit,data,'cm','m'
        ; equivalent to
        convert_unit,data,from='cm',to='m'

 MODIFICATION HISTORY:
        mgs, 26 Aug 1998: VERSION 1.00
        mgs, 27 Aug 1998: 
            - added RESULT and QUIET keywords
            - improved error handling
        mgs, 23 Aug 2000: 
            - changed copyright to open source

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\convert_unit.pro)


CONVOL_MM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		CONVOL_MM
 VERSION:
		4.0
 PURPOSE:
		Calculates the convolution of two functions represented by arrays.
 CATEGORY:
		Mathematical, array function.
 CALLING SEQUENCE:
		Result = CONVOL_MM (FAR, GAR [, keywords])
 INPUTS:
	FAR
		Array, numeric, otherwise arbitrary.
	GAR
		Ditto.
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
	/NOCENTER
		Switch.  Prevents centering one array over the other (corresponds to
		the CENTER = 0 setting in IDL CONVOL.  The default is CENTERED.
	/REVERSE
		Switch.  Reverses the direction, i.e instead of f(x-x')g(x') the
		integrand becomes f(x+x')g(x').
	/CLIP
		Switch.  If set, the edges of the result (which cannot be fully
		convolved) are set to zero, same as the default behavior of IDL CONVOL.
		The default behaviour of CONVOL_MM corresponds to the IDL CONVOL
		EDGE_WRAP SETTING.
	EDGE_VAL
		Accepts a value to be used for all the "beyond the edge " elements.
		if EDGE_VAL is provided, /CLIP is ignored.  EDGE_VAL and EDGE_TRUNCATE
		are mutually exclusive.
	/EDGE_TRUNCATE
		Switch.  If set, the "beyond the edge" elements are obtained by a
		propagation of the edge elements of FAR.  EDGE_TRUNCATE and EDGE_VAL
		are mutually exclusive.
	/NOROUND
		Switch.  Normally, if both input arrays are of one of the integer
		types, the result is rounded before type casting to the output type.
		Setting NOROUND prevents the rounding.
 OUTPUTS:
		Returns the result of the convolution with dimensions corresponding to
		the bigger of the two arrays.
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		None.
 PROCEDURE:
		Uses FFT.  Faster then the IDL CONVOL, and differs from it in few
		significant aspects, as follows:

		1) The two arrays are treated symmetrically, i.e. the result stays the
		same if they are exchanged (with the exception that when /REVERSE is
		set, it is always the second array that's reversed.
		2) The problem with IDL CONVOL, where the centered convolution is
		calculated in a reversed direction (versus standard mathematical
		practice) has been corrected.
		3) The arrays don't have to be of the same dimensionality.  If they're
		not they are imbedded in an array big enough to contained both and
		padded with zeroes (default), a constant value (if EDGE_VAL is used)
		or the edge elements of FAR (if EDGE_TRUNCATE is used).

		Calls CALCTYPE, CAST, EXTEND_ARRAY, FPU_FIX and TYPE from MIDL.
 MODIFICATION HISTORY:
		Created 15-NOV-1996 by Mati Meron as M_CONVOL.
		Modified 20-JAN-1997 by Mati Meron.  Streamlined (through the use of
		EXTEND_ARRAY and added keyword EDGE_TRUNCATE.
		Modified 15-SEP-1998 by Mati Meron.  Underflow filtering added.
		Renamed 25-SEP-1999 by Mati Meron, to CONVOL_MM.
		Modified 25-DEC-2000 by Mati Meron.  Added rounding for integer types
		and the keyword NOROUND.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\convol_mm.pro)


CONV_UNIX_VAX

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
      CONV_UNIX_VAX
 PURPOSE:
      To convert Unix IDL data types to Vax IDL data types. 
 EXPLANATION:
      CONV_UNIX_VAX assumes the Unix IDL data type is IEEE standard in either
      big-endian or little-endian format.

 CALLING SEQUENCE:
      CONV_UNIX_VAX, variable, [ SOURCE_ARCH = ]

 PARAMETERS:
      variable - The data variable to be converted.  This may be a scalar
            or an array.  Valid datatypes are integer, longword,
            floating point, and double precision. The result of the 
            conversion is passed back in the original variable.
 OPTIONAL INPUT KEYWORD:  
      SOURCE_ARCH = name (string) of source architecture
            if using this function on a VAX, otherwise
            !VERSION.ARCH is used to determine the conversion.
            **If run on a VAX, the default is to assume the source to be
            a little-endian machine with IEEE floating point
            (e.g. MIPSEL or Alpha***).
 RESTRICTIONS:
      Requires that data be from IEEE standard Unix machines
      (e.g. SUN, MIPSEL, or Alpha).
 EXAMPLE:
      Read a 100 by 100 matrix of floating point numbers from a data
      file created on a Sun.  Then convert the matrix values into
      VAX format.

      IDL> openr,1,'vax_float.dat
      IDL> data = fltarr(100,100)
      IDL> forrd,1,data
      IDL> CONV_UNIX_VAX,data,SOURCE_ARCH='sparc'

 MODIFICATION HISTORY:
      Version 1      By John Hoegy            13-Jun-88
      04-May-90 - WTT:  Created CONV_UNIX_VAX from VAX2SUN,
                         reversing floating point procedure.
       Modified  P. Keegstra             September 1994
           Implemented MIPSEL and ALPHA architecture,
           distinguishing VMS and OSF
       Modified  P. Keegstra             February 1995
           Added 386 PC based architectures
       If since V5.1 then VMS is always little endian    June 1998
       Convert to IDL V5.0   W. Landsman                 June 1998

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\conv_unix_vax.pro)


COO_CONV

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		COO_CONV
 VERSION:
		4.0
 PURPOSE:
		Transforms values between the coordinate systems supported by IDL.
		Allowed coord systems are DATA, DEVICE (only for X, Y axes) and NORMAL.
		Functionally similar to the IDL function CONVERT_COORD, COO_CONV is
		maintained for historical reasons.
 CATEGORY:
		Plotting /General Graphics.
 CALLING SEQUENCE:
		Result = COO_CONV( R, AXIS = AX [, keywords])
 INPUTS:
	R
		numeric, otherwise arbitrary, assumed to be a coordinate(s) in the
		direction specified by AXIS.
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
	AXIS
		Sets the transformation axis.  Accepts either a numeric value, one of
		(0, 1, 2) or a character value (only first character matters), one of
		('X', 'Y', 'Z').  Mandatory.
	FROM
		Character value (only first 3 characters matter), specifies input
		coord. system.  One of ('DATA','DEVICE','NORMAL').  Defaults to 'DATA'.
	TO
		Same as FROM.  Specifies output coord. system.
 OUTPUTS:
		'' (0 length string) in case of failure (bad keyword value), otherwise
		returns the transformed value as floating (or double if the input is
		of type double).
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		None.
 PROCEDURE:
		Uses calls to CAST, DEFAULT, FPU_FIX, ISNUM, STREQ, STRMATCH_MM and
		TYPE from MIDL.  Converts coordinates using values provided by relevant
		system variables.
 MODIFICATION HISTORY:
		Created 15-JUL-1991 by Mati Meron.
		Modified 10-SEP-1998 by Mati Meron.  Underflow filtering added.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\coo_conv.pro)


CORRELATE_ALL_COLUMNS

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

 PURPOSE:
   This function calculates the correlation coefficients (Pearson, Spearman, or Kendall)
   for a 2 dim data matrix

 CATEGORY:
   MATH

 CALLING SEQUENCE:
   Result = CORRELATE_ALL_COLUMNS(Value, [Text], [/SPEARMAN], [/KENDALL])

 INPUTS:
   Value:  2d data array

 OPTIONAL INPUTS:
   Text:   column header(title) for input array

 KEYWORD PARAMETERS:
   SPEARMAN:       if set Spearman rank correlation will be used (default: Pearson)
   KENDAL:         if set Kendal tau rank correlation will be used (default: Pearson)
   MISSING_VALUE:  if set to a single number these values will be excluded from calculation
   SIGNIFICANCE:   upper limit for significance to be plotted (def 1.0), see R_CORRELATE
   R_MINIMUM:      lower limit for correlation coeff. to be plotted (def 0.0)
   PLOT_ROWS, PLOT_COLS    number of rows and columns in plot
   N_MINIMUM:      minimum of data points to be considered for correaltion and plot
   SORT_BY_R       if set output array will be sorted after correlation coeff.
   SORT_BY_SIGNIF  if set output array will be sorted after significance
   REVERSE_ORDER   if set reverse order sorting, highest correlation first
   FIXED_COLUMN    if set to column number or an array of column numbers this column/these columns
                       will be correlated against all other columns
   EXCLUDE_COLUMNS if set to a cloumns number these columns will be excluded
   NO_PLOT:        suppress plotting
   PSFILE:         postscript filename for plotting (def: idl.ps)
   MESSAGE:        if set messages will be printed
   ERR:            if set to a named variable an error is indicated (OK:0, error:1)
   _EXTRA:         additional keywords can be provided for plot, init_dev, init_mplot

 OUTPUTS:
   This function returns a structure r containing the indeces to the columns r.i and r.j
   and the respective correlation coefficient r.r and a significance level r.s

 EXAMPLE:
   nr=100 & nc=3
   v = FINDGEN(nr,nc)+nr*RANDOMU(s,nr,nc)
   PRINT, correlate_all_columns(v, /MESSAGE)
       % CORRELATE_ALL_COLUMNS: no column headers given
       % CORRELATE_ALL_COLUMNS: Pearson's linear correlation
       % CORRELATE_ALL_COLUMNS: plotting COLUMN1 vs. COLUMN0 (0,1)
       % CORRELATE_ALL_COLUMNS: plotting COLUMN2 vs. COLUMN0 (0,2)
       % CORRELATE_ALL_COLUMNS: plotting COLUMN2 vs. COLUMN1 (1,2)
           {           1           0      0.59619999      0.00000000}
           {           2           0      0.57707387      0.00000000}
           {           2           1      0.48136258      0.00000000}

 MODIFICATION HISTORY:
   Written by: Theo Brauers, 1998-DEC-1

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\correlate_all_columns.pro)


COSANGLE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		COSANGLE
 VERSION:
		4.0
 PURPOSE:
		Finds the Cosine of the angle between two vectors.
 CATEGORY:
		Geometry, General.
 CALLING SEQUENCE:
		Result = COSANGLE ( U, V)
 INPUTS:
	U, V
		Vectors, numeric, same length, otherwise arbitrary.
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
		None.
 OUTPUTS:
		Returns the Cosine of the angle between the two vectors.
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		Vectors must be non-zero.
 PROCEDURE:
		Uses the functions FPU_FIX, VINP and VNORM from MIDL.
 MODIFICATION HISTORY:
		Created 30-JUNE-1992 by Mati Meron.
		Added to MIDL 10-NOV-1997 by Mati Meron.
		Modified 10-SEP-1998 by Mati Meron.  Underflow filtering added.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\cosangle.pro)


COSD

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

 PURPOSE:
       Return the cosine of an angle specified in degrees rather than radians.

 CALLING SEQUENCE:
       x = cosd(deg)

 INPUTS:
       angle   angle in degrees

 OPTIONAL INPUTS:

 OUTPUTS:
       Cosine of angle returned.

 PROCEDURE

 COMMON BLOCKS:
       None.

 NOTES

 REFERENCES
 
 AUTHOR and DATE:
     Jeff Hicke     Earth Space Research Group, UCSB  12/07/93

 MODIFICATION HISTORY:

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\cosd.pro_)


COSFILT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       COSFILT
 PURPOSE:
       Cosine tapered weighting array to use for FFT filtering.
 CATEGORY:
 CALLING SEQUENCE:
       W = COSFILT(DATA, F1, F2, [F3, F4])
 INPUTS:
       DATA = 1-d data array (only used to find array size).   in
       F1 = filter start of rolloff (fraction of sample freq). in
       F2 = end of rolloff (fraction of sample freq).          in
          or
       F1 = filter start of rollup (fraction of sample freq).  in
       F2 = end of rollup (fraction of sample freq).           in
       F3 = filter start of rolloff (fraction of sample freq). in
       F4 = end of rolloff (fraction of sample freq).          in
         F1 < F2 < F3 < F4 <= .5
 KEYWORD PARAMETERS:
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner., B. Gotwols  7 Apr, 1987.
       Johns Hopkins University Applied Physics Laboratory.

 Copyright (C) 1987, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\cosfilt.pro)


COSSCATANG

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

 PURPOSE:
       Return the scattering angle of the incident and emerging rays.
       NOTE:  the scattering angle is defined as 180 degrees when
       sza = vza = 0 and phi = 180.

 CALLING SEQUENCE:
       cos_omega = cosscatang(cossza, cosvza, phi)

 INPUTS:
       cossza    cosine of solar (or incident) zenith angle 
       cosvza    cosine of viewing (or emergin or satellite) zenith angle 
       phi       relative azimuth angle; this is defined as the difference
                 between the solar azimuth angle and the viewing azimuth
                 angle; when sat, sun are in the same position in
                 the sky, phi = 0

 OPTIONAL INPUTS:

 OUTPUTS:
       The scattering angle is returned.

 EXAMPLE:
 IDL> print,acosd(cosscatang(cosd(60),cosd(60),0))
       0.00000
 IDL> print,acosd(cosscatang(cosd(60),cosd(60),180))
       120.000

 PROCEDURE

 COMMON BLOCKS:
       None.

 NOTES

 REFERENCES
 
 AUTHOR and DATE:
     Jeff Hicke     Earth Space Research Group, UCSB  1/04/94

 MODIFICATION HISTORY:

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\cosscatang.pro)


COSTAP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       COSTAP
 PURPOSE:
       Cosine taper weighting from 1 at center to 0 at ends.
 CATEGORY:
 CALLING SEQUENCE:
       w = costap(n,[f])
 INPUTS:
       n = # of pts in weighting array.               in
       f = fraction of pts in flat region (def=0).    in
 KEYWORD PARAMETERS:
 OUTPUTS:
       w = weight with values from 0 to 1.            out
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       Written by R. Sterner, 6 Dec, 1984.
       Johns Hopkins University Applied Physics Laboratory.

 Copyright (C) 1984, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\costap.pro)


COUNT_NAME

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

 PURPOSE:
   This function increments a given name with a number. The old number is stored in an heap variable named: 'count_name_'+name

 CATEGORY:
   PROG_TOOLS

 CALLING SEQUENCE:
   Result=count_name(name,[/reset])

 INPUTS:
   name: the name which should be used as base for the counting

 KEYWORD_PARAMETERS:
  reset: if set counter is set zero

 EXAMPLE:
 PRINT,count_name('test')
 test_1

 MODIFICATION HISTORY:
       Written by:     R.Bauer (ICG-1), 1999-Mar-20

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\count_name.pro)


COYOTE_FIELD

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

 PURPOSE:

   The purpose of this compound widget is to provide an alternative
   to the CW_FIELD widget offered in the IDL distribution. What has
   always annoyed me about CW_FIELD is that the text widgets do not
   look editable to the users on Windows platforms. This program
   corrects that deficiency and adds some features that I think
   would be helpful. For example, you can now assign an event handler
   to the compound widget.

 AUTHOR:
   FANNING SOFTWARE CONSULTING
   David Fanning, Ph.D.
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: davidf@dfanning.com
   Coyote's Guide to IDL Programming: http://www.dfanning.com/

 CATEGORY:

   General programming.

 CALLING SEQUENCE:

   fieldID = COYOTE_Field(parent, Title='X Size: ", Value=256, /IntegerValue)

 INPUT PARAMETERS:

   parent -- The parent widget ID of the compound widget. Required.

 INPUT KEYWORDS:

   Column -- Set this keyword to have the Label Widget above the Text Widget.
   CR_Only -- Set this keyword if you only want Carriage Return events. If
              this keyword is not set, all events are returned. No events
              are returned unless the EVENT_PRO or EVENT_FUNC keywords are used.
   DoubleValue -- Set this keyword if you want DOUBLE values returned.
   Decimal -- Set this keyword to the number of digits to the right of the decimal
              point in FLOATVALUE and DOUBLEVALUE numbers.
   Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
   Event_Func -- Set this keyword to the name of an Event Function. If this
                 keyword is undefined and the Event_Pro keyword is undefined,
                 all compound widget events are handled internally and not
                 passed on to the parent widget.
   Event_Pro -- Set this keyword to the name of an Event Procedure. If this
                keyword is undefined and the Event_Func keyword is undefined,
                all compound widget events are handled internally and not
                passed on to the parent widget.
   FieldFont -- The font name for the text in the Text Widget.
   FloatValue -- Set this keyword for FLOAT values.
   Frame -- Set this keyword to put a frame around the compound widget.
   IntegerValue -- Set this keyword for INTEGER values.
   LabelFont -- The font name for the text in the Label Widget.
   LabelSize -- The X screen size of the Label Widget.
   LongValue -- Set this keyword for LONG values.
   Row=row -- Set this keyword to have the Label beside the Text Widget. (The default.)
   Scr_XSize -- The X screen size of the compound widget.
   Scr_YSize -- The Y screen size of the compound widget.
   StringValue -- Set this keyword for STRING values. (The default.)
   Title -- The text to go on the Label Widget.
   UValue -- A user value for any purpose.
   Value -- The "value" of the compound widget.
   XSize -- The X size of the Text Widget.

 COMMON BLOCKS:

   None.

 RESTRICTIONS:

   None.

 EVENT STRUCTURE:

   All events are handled internally unless either the Event_Pro or Event_Func
   keywords are used to assign an event handler to the compound widget. By
   default all events generated by the text widget are passed to the assigned
   event handler. If you wish to receive only Carriage Return events, set the
   CR_Only keyword.

   event = { COYOTE_FIELD, $      ; The name of the event structure.
             ID: 0L, $            ; The ID of the compound widget's top-level base.
             TOP: 0L, $           ; The widget ID of the top-level base of the hierarchy.
             HANDLER: 0L, $       ; The event handler ID. Filled out by IDL.
             Value: Ptr_New(), $  ; A pointer to the widget value.
             Type:""              ; A string indicating the type of data in the VALUE field.
           }                      ; Values are "INT", "LONG", "FLOAT", "DOUBLE", or "STRING".

 EXAMPLE:

   An example program is provided at the end of the COYOTE_FIELD code. To run it,
   type these commands:

      IDL> .Compile COYOTE_Field
      IDL> Example

 MODIFICATION HISTORY:

   Written by: David Fanning, 17 NOV 1999.
   Added check to make float and double values finite. 18 NOV 1999. DWF.
   Fixed a bug when selecting and deleting all numerical text. 19 NOV 1999. DWF.
   Added DECIMAL and DIGITS keywords. 2 Jan 2000. DWF.
   Added the POSITIVE keyword. 12 Jan 2000. DWF.
   Fixed a few minor bugs with delete and digits. 12 Jan 2000. DWF.
   Made GET_VALUE function return pointer to data, instead of data. 12 Jan 2000. DWF.
   Fixed a small typo: "aveDecimal" to "haveDecimal". 10 March 2000. DWF.
   Fixed a small problem with the Example program. 7 Oct 2000. DWF.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\coyote_field.pro)


CPLOT_ALL_COLUMNS

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

 PURPOSE:
   This function plots all columns of a matrix versus 1 vector

 CATEGORY:
   MATH

 CALLING SEQUENCE:
   CPLOT_ALL_COLUMNS, X, Value, Text

 INPUTS:
   Xvalue:     vector of N elements
   Yvalue:     array of [N, M] elements

 OPTIONAL INPUTS:
   Text:   column header(title) for input array

 KEYWORD PARAMETERS:
   MISSING_VALUE:  if set to a single number these values will be excluded from calculation
   PLOT_ROWS, PLOT_COLS    number of rows and columns in plot
   PSFILE:         postscript filename for plotting (def: idl.ps)
   MESSAGE:        if set messages will beprinted
   ERR:            if set to a named variable an error is indicated (OK:0, error:1)
   _EXTRA:         additional keywords can be provided for plot, init_dev, init_mplot

 EXAMPLE:
   nr=100 & nc=3
   v = FINDGEN(nr,nc)+nr*RANDOMU(s,nr,nc)
   plot_all_columns(v[*,0], v, /MESSAGE)

 MODIFICATION HISTORY:
   Written by: Theo Brauers, 1998-DEC-1

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\cplot_all_columns.pro)


CPOSPRINT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CPOSPRINT
 PURPOSE:
       Print a string showing character positions.
 CATEGORY:
 CALLING SEQUENCE:
       cposprint, s
 INPUTS:
       s = input string to print.  in
 KEYWORD PARAMETERS:
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
       Note: prints character positions above string.
 MODIFICATION HISTORY:
       R. Sterner, 2000 May 31

 Copyright (C) 2000, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\cposprint.pro)


CREATED

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CREATED
 PURPOSE:
       Return file creation host, user, and time stamp or tag.
 CATEGORY:
 CALLING SEQUENCE:
       txt = created()
 INPUTS:
 KEYWORD PARAMETERS:
       Keywords:
         VERB=verb First word to use (def=Created).
 OUTPUTS:
       txt = returned text.        out
       Ex: Created on tesla by Sterner on Tue Jul  1 14:22:15 1997
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 1997 Jul 1

 Copyright (C) 1997, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\created.pro)


CREATE_GRIDFILE

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

 PURPOSE:
    This procedure generates a netcdf file with grid information for
    regular grids or gaussian grids corresponding to a spectral
    truncation of T21, T30, T42, T63, T85, T106, T126, T170, T213, or
    TL319. The netcdf file contains the three variable lon, lat, and
    lat_weight. Lat_weight is the area weighting factor for latitudes
    (integral = 1).

 CATEGORY:
    Geography

 AUTHOR:
    Martin Schultz
    Max-Planck-Institute for Meteorology
    Bundesstr. 55, 20146 Hamburg, Germany
    martin.schultz@dkrz.de

 MODIFICATION HISTORY:
    mgs, 24 Aug 2000: VERSION 1.00

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\create_gridfile.pro)


CREATE_HISTORY

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

 PURPOSE:
	This function returns the following - history - string:
	' [  at  ]'

 CATEGORY:
	PROG_TOOLS/STRUCTURES

 CALLING SEQUENCE:
	Result = create_history([text])

 OPTIONAL INPUTS:
	text: A text string (scalar) which will appear in the history string.

 OUTPUTS:
	This function returns the following - history - string:
	' [  at  ]'

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 24.09.1999
	18.11.1999:	Added optional input parameter: text
	19.11.1999:	Minor change on default setting for text.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\create_history.pro)


CREATE_HREF

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

 PURPOSE:
   This function creates an HTML href from a file name

 CATEGORY:
   PROG_TOOLS/HTML

 CALLING SEQUENCE:
   Result=CREATE_HREF(Location, Name)

 INPUTS:
   Location:   filename with path
               example: 'a.txt', 'http://ich313.ich.kfa-juelich.de/test.html'

 OPTIONAL INPUTS:
   Name:       Name to appear in the browser, if not given location will be
               taken instead

 KEYWORD PARAMETERS:
   FULLNAME:   if this keyword is set the name wil not be stripped for
               directory etc.

 OUTPUTS:
   This function returns the hrefs for the input files

 EXAMPLE:
   a=['a.txt', 'b.txt']
   print, transpose(create_href(a))
       a.txt
       b.txt

 MODIFICATION HISTORY:
   Written by: Theo Brauers 1998 July 26

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\create_href.pro)


CREATE_INFO_STRUCT

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

 PURPOSE:
   This function defines a structure for informations about files (ENZ,ZUS,NC )
   and for informations to write a html-file

 CATEGORY:
   DATAFILES/ZCHN

 CALLING SEQUENCE:
       s= CREATE_INFO_STRUCT(n_sets,n_header, n_flags  $
         ,FILE_NAME=FILE_NAME,FILETYPE=FILETYPE, FILEDATE=FILEDATE, EXPERIMENT=experiment )

 INPUTS:
   n_sets  : number of rows of structure s.data (tags: text,nvalid,mean,median,stdev,minimum,maximum)
             output of zus_fb_info or nc_info or enz_info
   n_header: number of rows of header

 KEYWORD PARAMETERS:
   FILENAME, FILETYPE, FILEDATE, EXPERIMENT

 OUTPUTS:
   a structure for example s
       .file_infoname         : name of file
       .file_info.filetype    : 'zus' or 'enz' or 'nc'
       .file_info.filedate    : date of file
       .record_info.jstime : DBLARR(2) start-time and end-time in julian seconds
       .record_info.ntime  : STRARR(2) start-time and end-time in normal date and time
       .record_info.n_records: number of rows of time- and parameter vectors
       .record_info.n_sets : number of columns
       .pi.pi_name:
       .pi.email  :
       .pi.phone_number  :
       .pi.organisation  :
       .hsrefs.ps   :'ps'   (reference to ps-file:filename+.ps)
       .hsrefs.data :'data' (reference to
       .hsrefs.html :'html' (reference to html-file: filename+.savinfo.html)
       .data.text   :description of a data column (string-array )
       .data.nvalid :array containing the number of valid values of a column
       .data.mean   :array containing the avarage values of a data column
       .data.median :array containing the median values of a data column
       .data.stdev  :array containing the standard deviation of a column
       .data.minimum:array containing the lowest values of a data column
       .data.maximum:array containing the greatest values of a data column
       .experiment.text: containing the experiment text of the file if it exists
       .header.text :string array containing the header of the file

 EXAMPLE:
     s= CREATE_INFO_STRUCT(n_sets,n_header , FILENAME=FILENAME)

 REVISION HISTORY:
       Written         Theo Brauers, Marsy Lisken,  July 1998
       Corrected
       Revised

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\create_info_struct.pro)


CREATE_WIDGET_BUTTON_SYMBOL

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

 PURPOSE:
 This function translates a given symbol to it's bitmap buttom equivalent

 CATEGORY:
   PROG_TOOLS/WIDGETS

 CALLING SEQUENCE:
   create_widget_button_symbol,symbol

 INPUTS:
   symbol: The by icgsym_n defined icg symbolnumber

 OPTIONAL INPUTS:
   buttom_size=buttom_size: the size of the buttom (multiples from 8)
                            see restrictions

 OUTPUTS:
	This function returns an array as input for widget_buttom

 RESTRICTIONS:
  At the moment while an error on the aix occurs this routine is not in a state to use
  really  the buttom_size key

 EXAMPLE:
   result=create_widget_button_symbol(208)
   print,result
   0   0   0   0
   0   0   0   0
   0   0   0   0
   0   0   0   0
   0   0   0   0
   0   0   0   0
   0   0   0   0
   0   0   0   0
   0   0   0   0
   0 240   7   0
   0 248  15   0
   0 252  31   0
   0 254  63   0
   0 254  63   0
   0 254  63   0
   0 254 127   0
   0 254  63   0
   0 254  63   0
   0 254  63   0
   0 254  63   0
   0 248  15   0
   0 248  15   0
   0   0   0   0
   0   0   0   0
   0   0   0   0
   0   0   0   0
   0   0   0   0
   0   0   0   0
   0   0   0   0
   0   0   0   0
   0   0   0   0
   0   0   0   0

 MODIFICATION HISTORY:
 	Written by:	R.Bauer (ICG-1), 1998-Apr-04
   2000-Feb-18 help changed to call_help

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\create_widget_button_symbol.pro)


CROSSI

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CROSSI
 PURPOSE:
       Interactive cross-hair cursor on screen or plot.
 CATEGORY:
 CALLING SEQUENCE:
       crossi, [x, y, z]
 INPUTS:
 KEYWORD PARAMETERS:
       Keywords:
         /DATA   Causes data coordinates to be used (default).
         /DEVICE Causes window device coordinates to be used.
         /NORMAL Causes normalized coordinates to be used.
         /ORDER  Reverse device y coordinate (0 at window top).
         /PIXEL  Show pixel value.
         COLOR=c Set color of line (ignored for /XOR).
           Use -2 for dotted line.
         LINESTYLE=s Line style.
         MAG=m   Magnification for an optional magnified window.
           Setting MAG turns window on. /MAG gives magnification 10.
         SIZE=sz Mag window approx. size in pixels (def=200).
         XFORMAT=xfn  These keywords are given names of functions
         YFORMAT=yfn  that accept the numeric value of x or y
           and return a corresponding string which is displayed
           in place of the actual value.  For example, Julian
           days could be displayed as a date with jd2date.
         XSIZE=xs, YSIZE=ys  Coordinate display widths.
         /JS  Means X axis is time in Julian seconds. Example:
           x=maken(-2e8,-1.9e8,200) & y=maken(20,30,200)
           z=bytscl(makez(200,200))
           izoom,x,y,z,/js
           crossi,/js
         /NOSTATUS   Inhibits status display widget.
         SETSTAT=st  May use the same status display widget on
           each call to crossi (stays in same position).
           On first call: the status widget structure is returned.
           Following calls: send st.  Must use with /KEEP.
           To delete status display widget after last box1 call:
             widget_control,st.top,/dest (or drop /KEEP)
         /KEEP   Do not delete status widget or mag window on exit.
         /XMODE  Means use XOR plot mode instead of tvrd mode.
         INSTRUCTIONS=t  String array with exit instructions.
           Default: Press any button to exit.
         /DIALOG Means give an exit dialog box.
         MENU=m  A string array with exit dialog box options.
           An option labeled Continue is always added. Def=Continue.
         DEFAULT=def  Set exit menu default.
         EXITCODE=x Returns exit code.  Always 0 unless a dialog
           box is requested, then is selected exit option number.
         BUTTON=b   Returned button code: 1=left, 2=middle, 4=right.
 OUTPUTS:
       x = X coordinate of line.             in, out
       y = Y coordinate of line.             in, out
       z = optionally returned pixel value.  out
         Only if /PIXEL is specified.
 COMMON BLOCKS:
       js_com
 NOTES:
       Note: data coordinates are default.
         X and Y may be set to starting position in entry.
 MODIFICATION HISTORY:
       R. Sterner, 1994 May 16
       R. Sterner, 1994 May 19 --- Added mag window.
       R. Sterner, 1995 May 12 --- Added exit menu default.
       R. Sterner, 1995 Jun 30 --- Added /ORDER.
       R. Sterner, 1995 Oct 17 --- Added /PIXEL and RGB display.
       R. Sterner, 1995 Nov 30 --- Added color=-2 option.
       R. Sterner, 1998 Jan 15 --- Dropped the use of !d.n_colors.
       R. Sterner, 1999 Oct 05 --- Upgraded for true color.
       R. Sterner, 1999 Dec 07 --- Fixed /PIXEL for 24-bit color & mag bug.
       R. Sterner, 2001 Jan 12 --- Fixed for maps.

 Copyright (C) 1994, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\crossi.pro)


CROSSI2

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CROSSI2
 PURPOSE:
       Interactive cross-hair cursor on screen or plot.
 CATEGORY:
 CALLING SEQUENCE:
       crossi, [x, y]
 INPUTS:
 KEYWORD PARAMETERS:
       Keywords:
         /DATA   Causes data coordinates to be used (default).
         /DEVICE Causes window device coordinates to be used.
         /NORMAL Causes normalized coordinates to be used.
         /ORDER  Reverse device y coordinate (0 at window top).
         STATUS_PRO=pro  Name of optional status update procedure.
         /DETAILS for more info on using STATUS_PRO.
         COLOR=c Set color of line (ignored for /XOR).
           Use -2 for dotted line.
         LINESTYLE=s Line style.
         MAG=m   Magnification for an optional magnified window.
           Setting MAG turns window on. /MAG gives magnification 10.
         SIZE=sz Mag window approx. size in pixels (def=200).
         /XMODE  Means use XOR plot mode instead of tvrd mode.
         /DIALOG Means give an exit dialog box.
         MENU=m  A string array with exit dialog box options.
           An option labeled Continue is always added. Def=Continue.
         DEFAULT=def  Set exit menu default.
         EXITCODE=x Returns exit code.  Always 0 unless a dialog
           box is requested, then is selected exit option number.
         BUTTON=b   Returned button code: 1=left, 2=middle, 4=right.
 OUTPUTS:
       x = X coordinate of line.             in, out
       y = Y coordinate of line.             in, out
 COMMON BLOCKS:
 NOTES:
       Note: data coordinates are default.
         X and Y may be set to starting position in entry.
 MODIFICATION HISTORY:
       R. Sterner, 1996 Oct 6.
	R. Sterner, 1998 Jan 15 --- Dropped the use of !d.n_colors.

 Copyright (C) 1996, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\crossi2.pro)


CROSSI_FR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CROSSI_FR
 PURPOSE:
       Interactive cross-hair cursor on screen or plot.
 CATEGORY:
 CALLING SEQUENCE:
       crossi_fr, [x, y, z]
 INPUTS:
 KEYWORD PARAMETERS:
       Keywords:
         /DATA   Causes data coordinates to be used (default).
         /DEVICE Causes window device coordinates to be used.
         /NORMAL Causes normalized coordinates to be used.
         /ORDER  Reverse device y coordinate (0 at window top).
         /PIXEL  Show pixel value.
         COLOR=c Set color of line (ignored for /XOR).
           Use -2 for dotted line.
         LINESTYLE=s Line style.
         MAG=m   Magnification for an optional magnified window.
           Setting MAG turns window on. /MAG gives magnification 10.
         SIZE=sz Mag window approx. size in pixels (def=200).
         XFORMAT=xfn  These keywords are given names of functions
         YFORMAT=yfn  that accept the numeric value of x or y
           and return a corresponding string which is displayed
           in place of the actual value.  For example, Julian
           days could be displayed as a date with jd2date.
         XSIZE=xs, YSIZE=ys  Coordinate display widths.
         /JS  Means X axis is time in Julian seconds. Example:
           x=maken(-2e8,-1.9e8,200) & y=maken(20,30,200)
           z=bytscl(makez(200,200))
           izoom,x,y,z,/js
           crossi,/js
         /NOSTATUS   Inhibits status display widget.
         SETSTAT=st  May use the same status display widget on
           each call to crossi (stays in same position).
           On first call: the status widget structure is returned.
           Following calls: send st.  Must use with /KEEP.
           To delete status display widget after last box1 call:
             widget_control,st.top,/dest (or drop /KEEP)
         /KEEP   Do not delete status widget or mag window on exit.
         /XMODE  Means use XOR plot mode instead of tvrd mode.
         INSTRUCTIONS=t  String array with exit instructions.
           Default: Press any button to exit.
         /DIALOG Means give an exit dialog box.
         MENU=m  A string array with exit dialog box options.
           An option labeled Continue is always added. Def=Continue.
         DEFAULT=def  Set exit menu default.
         EXITCODE=x Returns exit code.  Always 0 unless a dialog
           box is requested, then is selected exit option number.
         BUTTON=b   Returned button code: 1=left, 2=middle, 4=right.
 OUTPUTS:
       x = X coordinate of line.             in, out
       y = Y coordinate of line.             in, out
       z = optionally returned pixel value.  out
         Only if /PIXEL is specified.
 COMMON BLOCKS:
       js_com
 NOTES:
       Note: data coordinates are default.
         X and Y may be set to starting position in entry.
 MODIFICATION HISTORY:
       R. Sterner, 1994 May 16
       R. Sterner, 1994 May 19 --- Added mag window.
       R. Sterner, 1995 May 12 --- Added exit menu default.
       R. Sterner, 1995 Jun 30 --- Added /ORDER.
       R. Sterner, 1995 Oct 17 --- Added /PIXEL and RGB display.
       R. Sterner, 1995 Nov 30 --- Added color=-2 option.

 Copyright (C) 1994, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\crossi_fr.pro)


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: crosspn.pro,v 1.2 2002/03/22 22:02:02 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\crosspn.pro)


CRS_EDIT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CRS_EDIT
 PURPOSE:
       Edit a bitmap to use for a cursor image.
 CATEGORY:
 CALLING SEQUENCE:
       crs_edit, img, msk
 INPUTS:
 KEYWORD PARAMETERS:
       Keywords:
         HOT=[ix,iy] x and y offsets to cursor hot spot (def=[8,8]).
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
       Notes: Displays current array values as a large version
         of the cursor.  Click on pixels to change state among
         black, white, and gray.  Transparent part of cursor is
         gray.  Left and middle mouse buttons change state,
         right button exits.
 MODIFICATION HISTORY:
       R. Sterner, 1999 Nov 24

 Copyright (C) 1999, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\crs_edit.pro)


CRYSTAL

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:  crystal

 PURPOSE:  compute the radius of an mie-sphere with scattering
           properties equivalent to a irregular crystal shape. 

 USEAGE:   crystal,type,rsph,nsph,area,volume, $
             d=d,t=t,bb=bb,bt=bt,l1=l1,l2=l2,l3=l3,a1=a1,a2=a2,a3=a3

 INPUT:    
   type    crystal type      description            Geom input parameters
           ------------      -----------            ---------------------
               1             hollow column          L1,a1,d
               2             bullet rosette         L1,a1,t
               3             dendrite on plate      L1,a1,bb,bt
               4             capped column          L1,L2,L3,a1,a2,a3


 KEYWORD INPUT:
;

      type 1:     hollow column

   L1          column length (um)
   a1          hexagonal face width (um)
   d           cavity depth at each end of column (um)

      type 2:     bullet rosette

   L1          column length (um)
   a1          hexagonal face width (um)
   t           conical pyramid height on bullet rosettes (um)

      type 3:     dendrite on plate

   L1          disk thickness (um)
   a1          hexagonal face width (um)
   bb          base width of dendrite (um)
   bt          length of dendrite (um)

      type 4:     capped column

   L1          cap thickness (um)
   L2          column length (um)
   L3          other cap thickness (um)
   a1          cap hexagonal face width (um)
   a2          hexagonal face width of column (um)
   a3          other cap hexagonal face width (um)

   These geometric parameters are difined in Takano and Liou, 1995:
     "Radiative Transfer in Cirrus Clouds. Part III: Light
      Scattering by Irregular Ice Crystals" JAS 152, No 7, April 1995

 OUTPUT:
   rsph        radius of equivalent Mie spheres (um)

   nsph        number of equivalent Mie spheres 
               (factors into particle distribution function in mie
               calculation if a distribution of crystal sizes are
               computed, see example)

   area        area in um^2

   volume      volume in um^3


 DISCUSSION:
               According to Warren and Grenfeld, the scattering
               parameters of an irregular crystal can be approximated
               by those of the set of equivalent Mie spheres, such
               that the both the area and volume of the set of
               spheres match those of the original crystal.

               Say the density of a given crystal type is N per unit volume
               the extinction coefficient, kappa, (per unit distance) is 
               given by,  

                     kappa = N * Q * A / 4 

               where Q is the unknown extinction efficiency and the factor
               of 4 is to turn area into average cross-sectional area.
               According to W&G, kappa is approximately given by,

                     kappa = N * Q_mie(rsph) * (nsph * pi rsph^2)

                           = N * Q_mie(rsph) * A/4

               The single scattering albedo and asymmetry factor are given by,

                     omega = omega_mie(rsph)

                     g = g_mie(rsph)


 EXAMPLE:  

; Plot equivalent mie radius versus crystal length

        l1=findrng(50,200,100)
        crystal,1,rsph,nsph,l1=l1,a1=50,d=10
        plot,l1,rsph

; Determine PDF of equivalent radius mie spheres given distribution
; of crystal shapes.  Suppose dendrite width is fixed and the number
; of particles of a given length is given by a lognormal pdf with
; cutoffs at 10 and 500um:
; 
        l1=findrng(10,500,100) & sig=.3
        w=exp(-alog10(l1/50.)^2/(2.*sig^2))

        crystal,1,rsph,nsph,l1=l1,a1=10.,d=0
        wmie=w*nsph                          ; pdf of equivalent mie sphere
                                             ; radius distribution

        !p.multi=[0,1,2]
        plot,l1,w,title='dendrite length pdf',xtitle='length'
        plot,rsph,wmie,title='equivalent mie radius pdf',xtitle='radius'


 REVISIONS:

 AUTHOR:   Paul Ricchiazzi                        27 Jul 95
           Institute for Computational Earth System Science
           University of California, Santa Barbara

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\crystal.pro)


CR_STRUCT_NAME

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

 PURPOSE:
	This function returns a unique structure name based on current
	date and time information and an additional random number.

 CATEGORY:
	PROG_TOOLS/STRUCTURES

 CALLING SEQUENCE:
	structure_name = cr_struct_name()

 COMMON BLOCKS:
	STORE_SEED: A Long Array[36] which stores the state of the random number generator

 EXAMPLE:
	PRINT, cr_struct_name()
		'Mon Mar 16 20:55:13 1998      425995'

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 17. Mar. 98.
	16.03.1999	Removed debug statement, Header edited

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\cr_struct_name.pro)


CSPEC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CSPEC
 PURPOSE:
       Compute ensemble averaged frequency spectrum of complex data.
 CATEGORY:
 CALLING SEQUENCE:
       s = cspec(z,n,sr,[freq])
 INPUTS:
       z = input signal: Z = X + iY.                   in
         If z has too few points, -1 is returned.
       n = number of points to use in each transform   in
         May be arbitrary.
       sr = sample rate in Hz                          in
         Needed to get actual units
 KEYWORD PARAMETERS:
       Keywords:
         OVERLAP=novr  number of points to overlap spectra (Def=0).
         ZEROPAD=zlen  length to zero pad out to (def=no 0 pad).
         N_ENSEMBLE=n  returned # spectra ensemble averaged.
         /NOTES lists some additional comments.
 OUTPUTS:
       freq = optionally output frequency array.       out
         If freq is requested then s is shifted for plots.
       s = spectral density in units of z**2/Hz.       out
         First value is DC, unless freq is requested.
 COMMON BLOCKS:
       cspec_com
 NOTES:
       Notes: For example, if Z=I+iQ, and I and Q are in volts,
         s will be volts**2/Hz
         Restrictions: one dimensional data only.
 MODIFICATION HISTORY:
       B. L. Gotwols Oct. 13, 1990.
       R. E. Sterner Sep. 13, 1991 --- added freq and cleaned up.
       R. E. Sterner Mar.  1, 1993 --- Tested for ntimes eq 0 sooner.
       R. Sterner, 1994 Oct 31 --- added overlap
       R. Sterner, 1994 Nov, 10 --- Added ZEROPAD keyword.

 Copyright (C) 1990, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\cspec.pro)


CTINT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CTINT
 PURPOSE:
       Interpolate between two color table entries.
 CATEGORY:
 CALLING SEQUENCE:
       ctint, r, g, b, i1, i2, [mode]
 INPUTS:
       i1, i2 = start and end index for interpolation.  in
       mode = interpolation mode (def=1).               in
         Color interpolation mode
       0 = Copy.  Copy color i1 to i1:i2 range.
       1 = R,G,B.  Interp each color independently.
       2 = H,S,V straight.  Through less sat. hues (grays).
       3 = H,S,V curved. Through sat. in-between hues.
       4 = Reverse.  Reverse colors in i1:i2 range.
       5 = Ramp value from i1 down to 0 at i2.
 KEYWORD PARAMETERS:
 OUTPUTS:
       r,g,b = color table, red, green, blue.           in out
 COMMON BLOCKS:
 NOTES:
       Note: Modifies the color table.
 MODIFICATION HISTORY:
       R. Sterner, 6 Sep, 1990
       R. Sterner, 18 Oct, 1993 --- Added Copy and Reverse.
       R. Sterner, 21 Oct, 1993 --- Added Ramp mode.

 Copyright (C) 1990, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\ctint.pro)


CTOOL

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CTOOL
 PURPOSE:
       Modify a color table using widgets.
 CATEGORY:
 CALLING SEQUENCE:
       ctool
 INPUTS:
 KEYWORD PARAMETERS:
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 13 Oct, 1993
       R. Sterner, 1998 Jan 15 --- Dropped the use of !d.n_colors.

 Copyright (C) 1993, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\ctool.pro)


CTRIM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CTRIM
 PURPOSE:
       Do a circular trim on an array.
 CATEGORY:
 CALLING SEQUENCE:
       b = ctrim(a)
 INPUTS:
       a = input array.           in
 KEYWORD PARAMETERS:
 OUTPUTS:
       b = output trimmed array.  out
 COMMON BLOCKS:
 NOTES:
       Note: if input array is not square then
         trimmed array is elliptical.
 MODIFICATION HISTORY:
       R. Sterner.  24 May, 1987.
       Johns Hopkins University Applied Physics Laboratory.
       R. Sterner, 25 Jan 1990 --- converted to SUN.

 Copyright (C) 1987, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\ctrim.pro)


CT_BLUE

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

 PURPOSE:
 
This procedure defines a linear interpolated color table
added to the previously defined first 20 colors
CATEGORY: PLOT/PLOT2D CALLING SEQUENCE: ct_blue OPTIONAL INPUTS: start_color: the start index between 0 and 255 where the colorsystem should loaded max_colors: the number of colors for the new color scheme OPTIONAL OUTPUTS: colors: the defined color system (as input for x_def_colortable) PROCEDURE: This routine will be used by color_scheme. Using color_scheme it is possible to load more colortables at once. If you like to have an integer code do a request by R.Bauer@fz_juelich.de EXAMPLE: @init color_scheme,plot,scheme_code='ct_blue' to load only one color table: ct_blue MODIFICATION HISTORY: Written by: x_def_colortable 1999-1-08

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\ct_blue.pro)


CT_BLUE_GREEN

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

 PURPOSE:
 
This procedure defines a linear interpolated color table
added to the previously defined first 20 colors
CATEGORY: PLOT/PLOT2D CALLING SEQUENCE: ct_blue_green OPTIONAL INPUTS: start_color: the start index between 0 and 255 where the colorsystem should loaded max_colors: the number of colors for the new color scheme OPTIONAL OUTPUTS: colors: the defined color system (as input for x_def_colortable) PROCEDURE: This routine will be used by color_scheme. Using color_scheme it is possible to load more colortables at once. If you like to have an integer code do a request by R.Bauer@fz_juelich.de EXAMPLE: @init color_scheme,plot,scheme_code='ct_blue_green' to load only one color table: ct_blue_green MODIFICATION HISTORY: Written by: x_def_colortable 1999-1-08

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\ct_blue_green.pro)


CT_BLUE_GREEN_YELLOW_RED

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

 PURPOSE:
 
This procedure defines a linear interpolated color table
added to the previously defined first 20 colors
CATEGORY: PLOT/PLOT2D CALLING SEQUENCE: ct_blue_green_yellow_red OPTIONAL INPUTS: start_color: the start index between 0 and 255 where the colorsystem should loaded max_colors: the number of colors for the new color scheme OPTIONAL OUTPUTS: colors: the defined color system (as input for x_def_colortable) PROCEDURE: This routine will be used by color_scheme. Using color_scheme it is possible to load more colortables at once. If you like to have an integer code do a request by R.Bauer@fz_juelich.de EXAMPLE: @init color_scheme,plot,scheme_code='ct_blue_green_yellow_red' to load only one color table: ct_blue_green_yellow_red MODIFICATION HISTORY: Written by: x_def_colortable 1999-2-28

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\ct_blue_green_yellow_red.pro)


CT_BLUE_RED

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

 PURPOSE:
 
This procedure defines a linear interpolated color table
added to the previously defined first 20 colors
CATEGORY: PLOT/PLOT2D CALLING SEQUENCE: ct_blue_red OPTIONAL INPUTS: start_color: the start index between 0 and 255 where the colorsystem should loaded max_colors: the number of colors for the new color scheme OPTIONAL OUTPUTS: colors: the defined color system (as input for x_def_colortable) PROCEDURE: This routine will be used by color_scheme. Using color_scheme it is possible to load more colortables at once. If you like to have an integer code do a request by R.Bauer@fz_juelich.de EXAMPLE: @init color_scheme,plot,scheme_code='ct_blue_red' to load only one color table: ct_blue_red MODIFICATION HISTORY: Written by: x_def_colortable 1999-1-08

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\ct_blue_red.pro)


CT_BLUE_RED_YELLOW

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

 PURPOSE:
 
This procedure defines a linear interpolated color table
added to the previously defined first 20 colors
CATEGORY: PLOT/PLOT2D CALLING SEQUENCE: ct_blue_red_yellow OPTIONAL INPUTS: start_color: the start index between 0 and 255 where the colorsystem should loaded max_colors: the number of colors for the new color scheme OPTIONAL OUTPUTS: colors: the defined color system (as input for x_def_colortable) PROCEDURE: This routine will be used by color_scheme. Using color_scheme it is possible to load more colortables at once. If you like to have an integer code do a request by R.Bauer@fz_juelich.de EXAMPLE: @init color_scheme,plot,scheme_code='ct_blue_red_yellow' to load only one color table: ct_blue_red_yellow MODIFICATION HISTORY: Written by: x_def_colortable 1999-2-28

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\ct_blue_red_yellow.pro)


CT_CYAN_GREEN_YELLOW_RED

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

 PURPOSE:
 
This procedure defines a linear interpolated color table
added to the previously defined first 20 colors
CATEGORY: PLOT/PLOT2D CALLING SEQUENCE: ct_cyan_green_yellow_red OPTIONAL INPUTS: start_color: the start index between 0 and 255 where the colorsystem should loaded max_colors: the number of colors for the new color scheme OPTIONAL OUTPUTS: colors: the defined color system (as input for x_def_colortable) PROCEDURE: This routine will be used by color_scheme. Using color_scheme it is possible to load more colortables at once. If you like to have an integer code do a request by R.Bauer@fz_juelich.de EXAMPLE: @init color_scheme,plot,scheme_code='ct_cyan_green_yellow_red' to load only one color table: ct_cyan_green_yellow_red MODIFICATION HISTORY: Written by: x_def_colortable 1999-2-28

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\ct_cyan_green_yellow_red.pro)


CT_GREY_191_32

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

 PURPOSE:
 
This procedure defines a linear interpolated color table
added to the previously defined first 20 colors
CATEGORY: PLOT/PLOT2D CALLING SEQUENCE: ct_grey_191_32 OPTIONAL INPUTS: start_color: the start index between 0 and 255 where the colorsystem should loaded max_colors: the number of colors for the new color scheme OPTIONAL OUTPUTS: colors: the defined color system (as input for x_def_colortable) PROCEDURE: This routine will be used by color_scheme. Using color_scheme it is possible to load more colortables at once. If you like to have an integer code do a request by R.Bauer@fz_juelich.de EXAMPLE: @init color_scheme,plot,scheme_code='ct_grey_191_32' to load only one color table: ct_grey_191_32 MODIFICATION HISTORY: Written by: x_def_colortable 1999-2-28

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\ct_grey_191_32.pro)


CT_GREY_220_70

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

 PURPOSE:
 
This procedure defines a linear interpolated color table
added to the previously defined first 20 colors
CATEGORY: PLOT/PLOT2D CALLING SEQUENCE: ct_grey_220_70 OPTIONAL INPUTS: start_color: the start index between 0 and 255 where the colorsystem should loaded max_colors: the number of colors for the new color scheme OPTIONAL OUTPUTS: colors: the defined color system (as input for x_def_colortable) PROCEDURE: This routine will be used by color_scheme. Using color_scheme it is possible to load more colortables at once. If you like to have an integer code do a request by R.Bauer@fz_juelich.de EXAMPLE: @init color_scheme,plot,scheme_code='ct_grey_220_70' to load only one color table: ct_grey_220_70 MODIFICATION HISTORY: Written by: x_def_colortable 1999-1-08

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\ct_grey_220_70.pro)


CT_NCDF

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

 PURPOSE:
 
This procedure defines a colorindices of 20 possible colors for plotxy
CATEGORY: PLOT/PLOTXY CALLING SEQUENCE: ct_ncdf,colors_ncdf OUTPUTS: colors_ncdf. : is a structure defining color names .black :0 .red :1 .blue :2 .green :3 .pink :4 .violett :5 .orange :6 .dark_red :7 .cyan :8 .yellow :9 .blue_green :10 .white :11 .light_grey :12 .medium_grey:13 gold :14 aquamarine :15 orchid :16 beige :17 EXAMPLE: ct_ncdf,colors_ncdf help,colors_ncdf,/str ** Structure <30027fbc>, 12 tags, length=24, refs=1: BLACK INT 0 RED INT 1 BLUE INT 2 GREEN INT 3 PINK INT 4 VIOLETT INT 5 ORANGE INT 6 DARK_RED INT 7 CYAN INT 8 YELLOW INT 9 BLUE_GREEN INT 10 WHITE INT 11 LIGHT_GREY INT 12 MEDIUM_GREY INT 13 MODIFICATION HISTORY: Written by Franz Rohrer Mai 1997 Modified 22. 5.97 : new colors violett and orange defined by R. Bauer 20. 8.97 : new_colors dark_red, cyan, yellow and blue_green defined by O. Bujok 10. 9.97 : new_color white defined by F. Rohrer 7. 4.98 : /silent introduced in loadct, F. Rohrer 22.03.99 : 4 new colors added, F. Rohrer 20.10.99 : function get_color_struct() added 'LOADCT,0,/silent' kommentiert

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\ct_ncdf.pro)


CT_PASTEL

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

 PURPOSE:
 
This procedure defines a linear interpolated color table
added to the previously defined first 20 colors
CATEGORY: PLOT/PLOT2D CALLING SEQUENCE: ct_pastel OPTIONAL INPUTS: start_color: the start index between 0 and 255 where the colorsystem should loaded max_colors: the number of colors for the new color scheme OPTIONAL OUTPUTS: colors: the defined color system (as input for x_def_colortable) PROCEDURE: This routine will be used by color_scheme. Using color_scheme it is possible to load more colortables at once. If you like to have an integer code do a request by R.Bauer@fz_juelich.de EXAMPLE: @init color_scheme,plot,scheme_code='ct_pastel' to load only one color table: ct_pastel MODIFICATION HISTORY: Written by: x_def_colortable 1999-2-28

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\ct_pastel.pro)


CT_YELLOW_RED_BLUE

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

 PURPOSE:
 
This procedure defines a linear interpolated color table
added to the previously defined first 20 colors
CATEGORY: PLOT/PLOT2D CALLING SEQUENCE: ct_yellow_red_blue OPTIONAL INPUTS: start_color: the start index between 0 and 255 where the colorsystem should loaded max_colors: the number of colors for the new color scheme OPTIONAL OUTPUTS: colors: the defined color system (as input for x_def_colortable) PROCEDURE: This routine will be used by color_scheme. Using color_scheme it is possible to load more colortables at once. If you like to have an integer code do a request by R.Bauer@fz_juelich.de EXAMPLE: @init color_scheme,plot,scheme_code='ct_yellow_red_blue' to load only one color table: ct_yellow_red_blue MODIFICATION HISTORY: Written by: x_def_colortable 1999-2-28

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\ct_yellow_red_blue.pro)


CT_YELLOW_RED_BLUE_GREEN_BLACK

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

 PURPOSE:
 
This procedure defines a linear interpolated color table
added to the previously defined first 20 colors
CATEGORY: PLOT/PLOT2D CALLING SEQUENCE: ct_yellow_red_blue_green_black OPTIONAL INPUTS: start_color: the start index between 0 and 255 where the colorsystem should loaded max_colors: the number of colors for the new color scheme OPTIONAL OUTPUTS: colors: the defined color system (as input for x_def_colortable) PROCEDURE: This routine will be used by color_scheme. Using color_scheme it is possible to load more colortables at once. If you like to have an integer code do a request by R.Bauer@fz_juelich.de EXAMPLE: @init color_scheme,plot,scheme_code='ct_yellow_red_blue_green_black' to load only one color table: ct_yellow_red_blue_green_black MODIFICATION HISTORY: Written by: x_def_colortable 1999-2-28

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\ct_yellow_red_blue_green_black.pro)


CUMULATE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CUMULATE
 PURPOSE:
       Array with the cumulative sum of an array.  Integrate.
 CATEGORY:
 CALLING SEQUENCE:
       out = cumulate(in)
 INPUTS:
       in = input array.             in
 KEYWORD PARAMETERS:
 OUTPUTS:
       out = cumulative sum of in.   out
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       Ray Sterner,  20 June, 1985.
	R. Sterner, 26 June, 1991 --- fixed long overflow bug.
       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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\cumulate.pro)


CURBOX

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

 PURPOSE:
        Emulate the operation of a variable-sized box cursor (also known as
        a "marquee" selector).  CURBOX can be used to select a sub-region
        from a TVIM image (see example).   

 CATEGORY:
        Interactive graphics.

 CALLING SEQUENCE:
        CURBOX, x1,x2,y1,y2

        curbox,x1,x2,y1,y2,xwin,ywin,xrng,yrng,init=init,$
                message=message,inc=inc, index=index,label=label, $
                color=color,charsize=charsize
+

 INPUTS:
   x1,x2,y1,y2
     coordinates of box edges. If XWIN,YWIN,XRNG,YRNG are set, then
     input is in data coordinates, otherwise in normalized coordinates.

 KEYWORD PARAMETERS:

   init
     If this keyword is set, the initial position of the cursor
     is given by X1,X2,Y1,Y2

   message
     If this keyword is set, print a short message describing
     operation of the cursor.

   xwin,ywin
     two element vectors giving normalized x and y coordinates of window
     subregion, for example that given by !x.window or !y.window
   
   xrng,yrng
     two elements vectors giving data range of window subregion, for 
     example, as given by !x.crange or !y.crange.  When CURBOX is used
     with TVIM (and XRANGE and YRANGE are not used with TVIM), XRNG
     and YRNG represent the total index range of the displayed
     image. X1,X2,Y1,Y2 will then be the array subrange of the
     selected region.

   index
     if set, the XRNG,YRNG,XWIN,YWIN parameters are set to the values of
     the last data window, i.e., !x.crange,!y.crange, !x.window, and
     !y.window respectively.  Setting INDEX causes X1,X2,Y1,Y2 to be
     interpreted as index range coordinates.
     
   inc
     increment by which to change cursor box size when right or left
     mouse button is pressed.  Specified in data index coordinates (i.e.,
     array index coordinate) when XWIN,YWIN,XRNG,YRNG are set, otherwise
     in normalized coordinates.  The x and y increments may be specified
     separately by providing INC as a two element array.

   label
     a string which is used to label the selected region.  The string is
     centered within the region and is sized to ensure that it fits within
     the box.  If LABEL is set the box is not erased after CURBOX returns
     
   color
     color used to label regions

   charsize
     character size used for region labels

   fill
     color used to fill box region, only effective when LABEL is set

 OUTPUTS:
   x1,x2,y1,y2
     normalized coordinates coordinates of box edges.  Howvever, if
     xwin, ywin, xrng, and yrng are set, output is in data index
     coordinates, i.e., x1,x2,y1,y2 provide the index range of the
     boxed region of the image.

     If xwin,ywin,xrng,yrng are set, the output range is clipped to be
     within the limits of xrng and yrng.  

 COMMON BLOCKS:
        None.

 SIDE EFFECTS:
        A box is drawn in the currently active window.  It is erased
        on exit.

 RESTRICTIONS:
        Works only with window system drivers.

 PROCEDURE:
        The graphics function is set to 6 for eXclusive OR.  This
        allows the box to be drawn and erased without disturbing the
        contents of the window.

        Operation is as follows:
   
        Left mouse button:   reduce box size
        Middle mouse button: increase box size
        Right mouse button:  Exit this procedure, returning the 
                             current box parameters.

        NOTE: CURBOX is designed for applications in which the aspect
              ratio of the cursor box is fixed. However, if the
              aspect ratio must be adjusted do the following: jam the
              box against one of the window borders.  If you force
              the box against the left or right borders (while
              keeping the cursor pointer within the window) box size
              is constrained to change only in the height. Similarly
              the box can be made fatter or thiner by pushing the box
              against the top or bottom. As usual the LMB decreases
              size and the MMB increases size.



; EXAMPLE
;
;    use curbox to interactively select subregions from a TVIM image

       w8x11
       !p.multi=[0,1,2]
       f=randata(128,128,s=3)
       tvim,f,/interp
       xw=!x.window & xr=!x.crange
       yw=!y.window & yr=!y.crange
        
       x1=60 & x2=80 & y1=60 & y2=80
       !p.charsize=2
       !p.multi=[4,2,4]
       curbox,x1,x2,y1,y2,xw,yw,xr,yr,/init,inc=4,/mess,label='region 1'
       confill,f(x1:x2,y1:y2),title='region 1'
       curbox,x1,x2,y1,y2,xw,yw,xr,yr,/init,inc=4,/mess,label='region 2'
       confill,f(x1:x2,y1:y2),title='region 2'
       curbox,x1,x2,y1,y2,xw,yw,xr,yr,/init,inc=4,/mess,label='region 3'
       confill,f(x1:x2,y1:y2),title='region 3'
       curbox,x1,x2,y1,y2,xw,yw,xr,yr,/init,inc=4,/mess,label='region 4'
       confill,f(x1:x2,y1:y2),title='region 4'

;    use CURBOX to find the normalized coordinates of a window region
;    of given aspect ratio

        x1=.4 & x2=x1+.3 & y1=.4 & y2=y1+.1
        curbox,x1,x2,y1,y2,/init,/mess
        print,x1,x2,y1,y2

 author   Paul Ricchiazzi      April, 1993

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\curbox.pro)


CURSIM

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:        cursim

 USEAGE:         cursim,a,yy,xx,range=range

 PURPOSE:        Use the graphics cursor to interrogate a TVIM image for
                 pixel values and positions. 

 INPUT:    

    a            image array, same size as used in TVIM image

    yy, xx       2-D arrays of "vertical" and "horizontal" position
                 in the geographical case these would be lat and lon arrays
                 If these arrays are not supplied the x and y data
                 coordinates are used instead.

 OPTIONAL INPUT:
    point        if set, CURSIM will print the range and azimuth 
                 of the cursor from this point. (Palmer = [-64.767,-64.067] )

                 When this option is used the lat,lon coordinates must
                 be available either in the data coordinates of the plot
                 (i.e., as specified by the XRANGE and YRANGE parameter 
                 in the TVIM call) or explicitly as the YY and XX parameters
                 in CURSIM

 EXAMPLE: 
                 tvim,hanning(200,200),xrange=[-180,180],yrange=[-90,90] 
                 map_set,0,0,/cont,/grid,pos=boxpos(/get),/noerase
                 cursim,hanning(200,200),point=[35,-120]

  author:  Paul Ricchiazzi                            sep92
           Institute for Computational Earth System Science
           University of California, Santa Barbara

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\cursim.pro)


CURSX

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:        cursx

 USEAGE:         cursx,xx,yy,verbose=verbose

 PROCEDURE:      Use the graphics cursor to find xy point on plot.
                 xy point is written to pop-up widget. 

                 If a single argument is supplied (XX) it is interpreted
                 as an image or z value which will be evaluated when
                 the LMB is pressed. This option works with TVIM images
                 or plots drawn with CONTOUR.

                 if two arguments are supplied (XX and YY) they are
                 interpreted as the x and y values of a curve in the xy
                 plane.  The y value of the function is evaluated when
                 the LMB is pressed. This option works with plots drawn
                 with PLOT

                 Hit and drag LMB to retrieve coordinates and values
                 Hit MMB to quit and retain pop-up display
                 Hit RMB to quit and destroy pop-up

 INPUT:          
   xx            x coordinate or image array

   yy            if present this parameter indicates CURSX should be run
                 in curve follow mode (CFM). In this mode the y value at a
                 x coordiate point is indicated with a drawn symbol. The
                 symbol position follows the shape of the drawn curve as
                 the cursor is dragged across the plot.
 
 Keyword input

   psym          symbol used to mark xy point in plot follow mode.
   symsize       symbol size
   color         color of symbol
   silent        if set, pop up window will not contain operating instructions
   interpolate   if set and non-zero, interpolate between defined x and y
                 points in plot follow mode
                 

 EXAMPLE: 
  plot,dist(20)
  cursx

; display value at a point

  f=randata(100,100,s=3)
  tvim,f,xra=[100,120],yra=[30,50],xtitle='longitude',ytitle='latitude',/scale
  cursx,f

; pick values off a plot using curve follow mode

  x=findgen(200)
  y=randf(200,1.5)
  plot,x,y
  loadct,5
  thick,2
  cursx,x,y,psym=1,symsize=2,color=100
  thick,1

  author:  Paul Ricchiazzi                            sep92
           Institute for Computational Earth System Science
           University of California, Santa Barbara

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\cursx.pro)


CURVE_LABEL

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

 PURPOSE:

       Draw labels close to one or more (up to 30) curves that have
       been previously plotted.

 CALLING SEQUENCE:

       CURVE_LABEL,X,Y1,[Y2,Y3,Y4,Y5],LABELS=LABELS, $
                  [COLOR=COLOR,XPOSITION=XPOSITION,YOFFSET=YOFFSET]
 
 INPUTS:
       X - xaxis vector (1D array)
       Y1 - 1st y axis vector to be labelled.

 OPTIONAL INPUTS:
       Y2 - 2nd y axis vector to be labelled.
       Y3 - 3rd y axis vector to be labelled.
       ....etc....
	
 KEYWORD PARAMETERS:

       LABELS - String array of labels.  The size of the LABELS array
                must match the number of y variables passed.  This
                keyword is required.

       XPOSITION - A scalar variable specifying where along the x
                   axis the labels are to be drawn, in normal
                   coordinates.  Default = 0.25.  Unless the
                   NO_REPOSITION keyword is set, this might get
                   changed if the procedure determines that the
                   labels are too close together when drawing
                   multiple labels.

       YOFFSET - A scalar specifying the distance in Y between the
                 labels and the curves, in normal
                 coordinates. Default = 0.01

       NO_REPOSITION - Set this to inhibit moving the label positions
                       if the labels are too close together when
                       drawing multiple labels.

       COLOR - Integer array of color indices for the labels.

       _EXTRA - The idl _EXTRA keyword, for additional graphics
                keywords to the XYOUTS procedure.
       

 PROCEDURE:

       All labels are lined up at one point along the xaxis.  The
       procedure will try to find a position along the xaxis for
       which the labels are not too close to each other.  If it fails
       at this, it will just stick the labels at x=0.25 (normal).

 EXAMPLE:

       To label a plot containing three curves, try something like
       this:

       plot,x,y1,/nodata
       oplot,x,y1,color=2
       oplot,x,y2,color=3
       oplot,x,y3,color=4
       curve_label,x,y1,y2,y3,labels=['Y1','Y2','Y3'],color=[2,3,4]

 MODIFICATION HISTORY:

       David L. Windt, Bell Labs, March, 1997.
       windt@bell-labs.com

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\windt\curve_label.pro)


CUTOFF_FIRST_CHARS

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

 PURPOSE:
	This function cuts off the first n characters from a string

 CATEGORY:
	PROG_TOOLS/STRINGS

 CALLING SEQUENCE:
	fc = CutOff_first_chars(charstr [,n] [,CUTOFF = co])

 INPUTS:
	charstr:	string of which the first n characters should be cut off.
	n: number of characters to cut off (default: 1).

 KEYWORD PARAMETERS:
	CUTOFF = co:	Named variable which will contain the truncated characters of charstr.
						This variable has to be initialised as a string before calling the routine.

 OUTPUTS:
	fc:	truncated string.

 EXAMPLE:
	a = 'Hello'
	fc = CutOff_First_Chars(a, 3, CUTOFF = co)
	PRINT, fc + '+' + co
		-> lo+Hel

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 04. Sep. 1998

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\cutoff_first_chars.pro)


CUTOFF_LAST_CHARS

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

 PURPOSE:
	This function cuts off the last n characters from a string

 CATEGORY:
	PROG_TOOLS/STRINGS

 CALLING SEQUENCE:
	fc = CutOff_last_chars(charstr [,n] [,CUTOFF = co])

 INPUTS:
	charstr:	string of which the last n characters should be cut off.
	n: number of characters to cut off (default: 1).

 KEYWORD PARAMETERS:
	CUTOFF = co:	Named variable which will contain the cut-off characters of charstr.
						This variable has to be initialised as a string before calling the routine.

 OUTPUTS:
	fc:	truncated string.

 EXAMPLE:
	a = 'Hello'
	fc = CutOff_last_chars(a, 3, CUTOFF = co)
	PRINT, fc + '+' + co
		-> He+llo

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 04. Sep. 1998

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\cutoff_last_chars.pro)


CW_BTGROUP

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

 PURPOSE:
	CW_BTGROUP is a compound widget that simplifies creating
	a base of buttons. It handles the details of creating the
	proper base (standard, exclusive, or non-exclusive) and filling
	in the desired buttons. Events for the individual buttons are
	handled transparently, and a CW_BTGROUP event returned. This
	event can return any one of the following:
		- The Index of the button within the base.
		- The widget ID of the button.
		- The name of the button.
		- An arbitrary value taken from an array of User values.

 CATEGORY:
	PROG_TOOLS/WIDGETS

 CALLING SEQUENCE:
		Widget = CW_BTGROUP(Parent, Names)

 PROCEDURE:
	To get or set the value of a CW_BTGROUP, use the GET_VALUE and
	SET_VALUE keywords to WIDGET_CONTROL. The value of a CW_BTGROUP
	is:

		-----------------------------------------------
		Type		Value
		-----------------------------------------------
		normal		None
		exclusive   	Index of currently set button
		non-exclusive	Vector indicating the position
				of each button (1-set, 0-unset)
		-----------------------------------------------


 INPUTS:
       Parent:		The ID of the parent widget.
	Names:		A string array, containing one string per button,
			giving the name of each button.

 KEYWORD PARAMETERS:

	BUTTON_UVALUE:	An array of user values to be associated with
			each button and returned in the event structure.
	COLUMN:		Buttons will be arranged in the number of columns
			specified by this keyword.
	EVENT_FUNCT:	The name of an optional user-supplied event function
			for buttons. This function is called with the return
			value structure whenever a button is pressed, and
			follows the conventions for user-written event
			functions.
	EXCLUSIVE:	Buttons will be placed in an exclusive base, with
			only one button allowed to be selected at a time.
	FONT:		The name of the font to be used for the button
			titles. If this keyword is not specified, the default
			font is used.
	FRAME:		Specifies the width of the frame to be drawn around
			the base.
	IDS:		A named variable into which the button IDs will be
			stored, as a longword vector.
	LABEL_LEFT:	Creates a text label to the left of the buttons.
	LABEL_TOP:	Creates a text label above the buttons.
	MAP:		If set, the base will be mapped when the widget
			is realized (the default).
	NONEXCLUSIVE:	Buttons will be placed in an non-exclusive base.
			The buttons will be independent.
	NO_RELEASE:	If set, button release events will not be returned.
	RETURN_ID:	If set, the VALUE field of returned events will be
			the widget ID of the button.
	RETURN_INDEX:	If set, the VALUE field of returned events will be
			the zero-based index of the button within the base.
			THIS IS THE DEFAULT.
	RETURN_NAME:	If set, the VALUE field of returned events will be
			the name of the button within the base.
	ROW:		Buttons will be arranged in the number of rows
			specified by this keyword.
	SCROLL:		If set, the base will include scroll bars to allow
			viewing a large base through a smaller viewport.
	SET_VALUE:	The initial value of the buttons. This is equivalent
			to the later statement:

			WIDGET_CONTROL, widget, set_value=value

	SPACE:		The space, in pixels, to be left around the edges
			of a row or column major base. This keyword is
			ignored if EXCLUSIVE or NONEXCLUSIVE are specified.
	UVALUE:		The user value to be associated with the widget.
	XOFFSET:	The X offset of the widget relative to its parent.
	XPAD:		The horizontal space, in pixels, between children
			of a row or column major base. Ignored if EXCLUSIVE
			or NONEXCLUSIVE are specified.
	XSIZE:		The width of the base.
	X_SCROLL_SIZE:	The width of the viewport if SCROLL is specified.
	YOFFSET:	The Y offset of the widget relative to its parent.
	YPAD:		The vertical space, in pixels, between children of
			a row or column major base. Ignored if EXCLUSIVE
			or NONEXCLUSIVE are specified.
	YSIZE:		The height of the base.
	Y_SCROLL_SIZE:	The height of the viewport if SCROLL is specified.
	TRACKING_EVENTS:Return tracking events.

 OUTPUTS:
       The ID of the created widget is returned.

 SIDE EFFECTS:
	This widget generates event structures with the following definition:

		event = { ID:0L, TOP:0L, HANDLER:0L, SELECT:0, VALUE:0 }

	The SELECT field is passed through from the button event. VALUE is
	either the INDEX, ID, NAME, or BUTTON_UVALUE of the button,
	depending on how the widget was created.

 RESTRICTIONS:
	Only buttons with textual names are handled by this widget.
	Bitmaps are not understood.

 MODIFICATION HISTORY:
	15 June 1992, AB
	7 April 1993, AB, Removed state caching.
	6 Oct. 1994, KDB, Font keyword is not applied to the label.
       10 FEB 1995, DJC  fixed bad bug in event procedure, getting
                         id of stash widget.
	11 April 1995, AB Removed Motif special cases.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\cw_btgroup.pro)


CW_BUTTONS

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

 PURPOSE:
  This compound widget function is used to set a group of buttons

 CATEGORY:
   PROG_TOOLS/WIDGETS

 CALLING SEQUENCE:
   result=cw_buttons(base,value,uvalue=uvalue,_extra=extra)

 INPUTS:
   base: the base where the widget should be placed in
   value: a structure of value and set
         .value: a vector of the text labels of the buttons
         .set        : a vector of 0 or 1 to set the buttons on


 KEYWORD PARAMETERS:
      uvalue: the users uvalue of the widget
      _extra: all keywords for widget_base
              and all keywords for buttons as buttons_ e.g. buttons_xsize

 OUTPUTS:
       This function returns widget id


 EXAMPLE:

PRO test_event,ev

   WIDGET_CONTROL,ev.id,get_uval=cmd
   WIDGET_CONTROL,ev.top,get_uvalue=b
   CASE cmd OF
      'done':WIDGET_CONTROL,ev.top,/dest
      'FF': BEGIN
         WIDGET_CONTROL,ev.id,get_value=v
         print,v.set
         idx=(WHERE(v.set EQ 1,count))[0]
         IF count GT 0 THEN BEGIN
            value={value:[strtrim(SINDGEN(idx+1),2)],set:MAKE_ARRAY(idx+1,/LONG,value=1)}
            WIDGET_CONTROL,b,set_value=value
         ENDIF
      END

      ELSE:
   ENDCASE
END
PRO test

   a=WIDGET_BASE(row=2)
   value={value:['MIN','SPEC','DEFAULT','MAX'],set:[1,0,0,0]}
   b=cw_buttons(a,value=value,uvalue='FF',row=1,button_xsize=60,frame=2,xoffset=0,yoffset=0,button_frame=1)
   value={value:['0'],set:[1]}
   b=cw_buttons(a,value=value,uvalue='EF',col=2,/nonexclusive,frame=2,xoffset=20,yoffset=0,button_frame=1)

   d=WIDGET_BUTTON(a,val='done',uval='done')
   WIDGET_CONTROL,/realize,a,set_uvalue=b
   XMANAGER,'test',a
END



 MODIFICATION HISTORY:
    Written by:     R.Bauer (ICG-1), 1999-Oct-11

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\cw_buttons.pro)


CW_CURVE_LABEL

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

 PURPOSE:

       A compound widget used to select the position for a curve
       label; this widget is intended to be used in conjunction with
       the CURVE_LABEL procedure in this directory, in that this
       widget lets the user select a value from a slider from 0 to
       one, corresponding to the XPOSITION keyword in CURVE_LABEL.
      
 CATEGORY:
 
	Compound widgets.

 CALLING SEQUENCE:
 
	Result = CW_CURVE_LABEL(PARENT)

 INPUTS:
 
       PARENT - The ID of the parent widget.  

 KEYWORD PARAMETERS:
 
	UVALUE - Supplies the user value for the widget.

       VALUE - Initial value for the widget: a floating point between
               0 and 1, corresponding to the XPOSITION keyword in
               CURVE_LABEL.
 
       TITLE - A title for the widget. 

       FRAME - Set to draw a frame around the widget; ignored if
               PARENT is present.

       FORMAT - Format string for CW_FSLIDER (default is F5.3)

       FONT - Fonts to use for labels and buttons.

       DONE - Set this to add a Done button, in addition to the
              standard Apply button.
 
 OUTPUTS:
 
       The ID of the created widget is returned.

 PROCEDURE/EXAMPLE:

         A slider widget is created in which the user can select a
         position value.  By pressing the "Apply" button, an event is
         returned, allowing the calling procedure to redraw the
         curve label if desired.

         This widget generates an event when the user presses the
         Apply button or the Done button, if present. The EVENT.TAG
         keyword will return either "APPLY" or "DONE" accordingly.

 MODIFICATION HISTORY:
 
       David L. Windt, Bell Labs, April 1997
       windt@bell-labs.com

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\windt\cw_curve_label.pro)


CW_DRAWCOLOR

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

 PURPOSE:

       This compound widget is used to place a label or color name next
       to a color patch. Clicking on the color patch allows the user
       to select another color

 AUTHOR:

       FANNING SOFTWARE CONSULTING
       David Fanning, Ph.D.
       1645 Sheely Drive
       Fort Collins, CO 80526 USA
       Phone: 970-221-0438
       E-mail: davidf@dfanning.com
       Coyote's Guide to IDL Programming: http://www.dfanning.com

 CATEGORY:

       Graphics

 CALLING SEQUENCE:

       colorpatchID = CW_DrawColor(parent)

 REQUIRED INPUTS:

       parent - The identifier of a parent base widget.

 OUTPUTS:

       colorpatchID - The widget identifier of the top-level base of this compound widget

 INPUT KEYWORDS:

   COLOR - The name of the color to be displayed. Color names come from PickColorName.
   COLUMN - Set this keyword to stack widgets in a column. Default is in a row.
   EVENT_FUNC - The name of an event handler function for this compound widget.
   EVENT_PRO -The name of an event handler procedure for this compound widget.
   INDEX - An index number where the color should be loaded. !D.Table_Size-2, by default.
   LABEL_LEFT - Set this keyword to have the label text aligned on the left of the label. Default is to center.
   LABEL_RIGHT - Set this keyword to have the label text aligned on the right of the label. Default is to center.
   LABELSIZE - This is the X size of the label widget (containing the label) in device coordinates. Default is natural size.
   LABELTEXT - This is the text on the label. Example, "Background Color", etc.
   TITLE - This is the title on the PickColorName program that allows the user to select another color.
   UVALUE - A user value for the widget.
   XSIZE - The xsize (in pixel units) of the color patch. By default, 20.
   YSIZE - The xsize (in pixel units) of the color patch. By default, 20.

 OUTPUT KEYWORDS:

   OBJECT - The object reference. Use this to call methods, etc.

 DEPENDENCIES:

       Reqires FSC_COLOR and PICKCOLORNAME from the Coyote Library:

                     http://www.dfanning.com/programs/fsc_color.pro
                     http://www.dfanning.com/programs/pickcolorname.pro

 MODIFICATION HISTORY:

       Written by David Fanning, March 2001.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\cw_drawcolor.pro)


CW_DRAWSIZE

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

 PURPOSE:
 
       A compound widget used to change the size of an existing
       draw widget.  The widget contains fields for the X and Y
       draw size (in pixels), an Apply button, and optionally a
       Done button.
      
 CATEGORY:
 
	Compound widgets.

 CALLING SEQUENCE:
 
	Result = CW_DRAWSIZE(PARENT,DRAW_WIDGET)

 INPUTS:
 
       PARENT - The ID of the parent widget.  

       DRAW_WIDGET - The id of the draw widget being resized.
 
 KEYWORD PARAMETERS:
 
	UVALUE - Supplies the user value for the widget.
 
       FRAME - set to draw a frame around the widget; ignored if
               PARENT is present.

       ROW - set to place the two window size fields (x,y) in a row.
 
       COLUMN - set to place the two window size fields (x,y) in a column.

       FONT - fonts to use for labels and buttons.

       DONE - set this to add a Done button, in addition to the standard
              Apply button.

       NO_RETURN - The default behavior is that the user must press
                    after entering new values.  Set this
                   keyword so that an event is returned even if the
                   user just changes a value and then moves the
                   cursor outside of the text entry area.

 OUTPUTS:
 
       The ID of the created widget is returned.

 PROCEDURE/EXAMPLE:

         A widget is created in which the user can specify the X and Y
         draw widget size in pixels.   By pressing the "Apply" button,
         the draw widget is resized, and an event is returned, allowing
         the calling procedure to repaint the window if desired.

         This widget generates an event when the user presses the
         Apply button or the Done button, if present. The EVENT.TAG
         keyword will return either "APPLY" or "DONE" accordingly.

 MODIFICATION HISTORY:
 
       David L. Windt, Bell Labs, March 1997
       windt@bell-labs.com

       DLW, June 1997, Added NO_RETURN keyword.

       DLW, Sep 1997, Fixed bug that caused initial values of X and Y
       pixel sizes to be displayed as floating point values rather
       than integers.
       

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\windt\cw_drawsize.pro)


CW_FIELD

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

 PURPOSE:
	This widget cluster function manages a data entry field widget.
	The field consists of a label and a text widget.  CW_FIELD's can
	be string fields, integer fields or floating-point fields.  The
	default is an editable string field.

 CATEGORY:
	Widget Clusters.

 CALLING SEQUENCE:
	Result = CW_FIELD(Parent)

 INPUTS:
	Parent:	The widget ID of the widget to be the field's parent.

 KEYWORD PARAMETERS:
	TITLE:	A string containing the text to be used as the label for the
		field.  The default is "Input Field:".

	VALUE:	The initial value in the text widget.  This value is
		automatically converted to the type set by the STRING,
		INTEGER, and FLOATING keywords described below.

	UVALUE:	A user value to assign to the field cluster.  This value
		can be of any type.

	FRAME:	The width, in pixels, of a frame to be drawn around the
		entire field cluster.  The default is no frame.

RETURN_EVENTS:	Set this keyword to make cluster return an event when a
		 is pressed in a text field.  The default is
		not to return events.  Note that the value of the text field
		is always returned when the WIDGET_CONTROL, field, GET_VALUE=X
		command is used.

   ALL_EVENTS: Like RETURN_EVENTS but return an event whenever the
		contents of a text field have changed.

	COLUMN:	Set this keyword to center the label above the text field.
		The default is to position the label to the left of the text
		field.

	ROW:	Set this keyword to position the label to the left of the text
		field.  This is the default.

	XSIZE:	An explicit horizontal size (in characters) for the text input
		area.  The default is to let the window manager size the
		widget.  Using the XSIZE keyword is not recommended.

	YSIZE:	An explicit vertical size (in lines) for the text input
		area.  The default is 1.

	STRING:	Set this keyword to have the field accept only string values.
		Numbers entered in the field are converted to their string
		equivalents.  This is the default.

     FLOATING:	Set this keyword to have the field accept only floating-point
		values.  Any number or string entered is converted to its
		floating-point equivalent.

      INTEGER:	Set this keyword to have the field accept only integer values.
		Any number or string entered is converted to its integer
		equivalent (using FIX).  For example, if 12.5 is entered in
		this type of field, it is converted to 12.

	LONG:	Set this keyword to have the field accept only long integer
		values.  Any number or string entered is converted to its
		long integer equivalent (using LONG).

	FONT:	A string containing the name of the X Windows font to use
		for the TITLE of the field.

    FIELDFONT:	A string containing the name of the X Windows font to use
		for the TEXT part of the field.

	NOEDIT:	Normally, the value in the text field can be edited.  Set this
		keyword to make the field non-editable.
		
   NO_RETURN:  The default behavior is that the user must press
                after entering new values.  Set this
               keyword so that an event is returned even if the
               user just changes a value and then moves the
               cursor outside of the text entry area.

     TEXT_ID:  The widget id of the text widget.

 OUTPUTS:
	This function returns the widget ID of the newly-created cluster.

 COMMON BLOCKS:
	None.

 PROCEDURE:
	Create the widgets, set up the appropriate event handlers, and return
	the widget ID of the newly-created cluster.

 EXAMPLE:
	The code below creates a main base with a field cluster attached
	to it.  The cluster accepts string input, has the title "Name:", and
	has a frame around it:

		base = WIDGET_BASE()
		field = CW_FIELD(base, TITLE="Name:", /FRAME)
		WIDGET_CONTROL, base, /REALIZE

 MODIFICATION HISTORY:
 	Written by:	Keith R. Crosley   June 1992
			KRC, January 1993 -- Added support for LONG
					     integers.
		        AB, 7 April 1993, Removed state caching.
			JWG, August 1993, Completely rewritten to make
				use of improved TEXT widget functionality
			ACY, 25 March, 1994, fix usage of FRAME keyword
                       KDB, May 1994, Initial value =0 would result
                                      in a null text field. Fixed
                                      keyword check.
                       David L. Windt, Bell Labs, June 1997,
                       Added NO_RETURN keyword.
                       David L. Windt, Bell Labs, March 1998,
                       Added TEXT_ID keyword.
                       windt@bell-labs.com

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\windt\cw_field.pro)


CW_FIELDS

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

 NAME:
   cw_fields

 PURPOSE:
  This compound widget function is used to set a group of lables and input data fields

 CATEGORY:
   PROG_TOOLS/WIDGETS

 CALLING SEQUENCE:
   result=cw_fields(base,value=value,uvalue=uvalue,_extra=extra)

 INPUTS:
   base: the base where the widget should be placed in


 KEYWORD PARAMETERS:

   value: a structure of description and values
         .label            : a vector of the text labels of the values
         .value            : a vector of the values, type of value musn't be string
         .description      : the label of the whole frame (if it's not defined no label is printed)


      uvalue: the users uvalue of the widget
      _extra: all keywords for widget_base
              and all keywords for widget_text or widget_label as text_ or label_ e.g. text_xsize or label_xsize

 OUTPUTS:
       This function returns widget id


 EXAMPLE:

PRO test2_event,ev

   WIDGET_CONTROL,ev.id,get_uval=cmd
   WIDGET_CONTROL,ev.top,get_uvalue=b
   CASE cmd OF
      'done':WIDGET_CONTROL,ev.top,/dest
      'FF': BEGIN
         WIDGET_CONTROL,ev.id,get_value=v
         print,v.value
         idx=(WHERE(v.value EQ 1,count))[0]
         IF count GT 0 THEN BEGIN
            value={label:['AHA','ABA'],value:[10.1,10.3]}
            WIDGET_CONTROL,b,set_value=value
         ENDIF
      END

      ELSE:
   ENDCASE
END
PRO test2

   a=WIDGET_BASE(row=2)
   value={label:['MIN','SPEC','DEFAULT','MAX'],value:[1,0,0,0]}
   b=cw_fields(a,value=value,uvalue='FF',row=1,text_xsize=10,text_editable=1,frame=2,xoffset=0,yoffset=0,button_frame=1)

   d=WIDGET_BUTTON(a,val='done',uval='done')
   WIDGET_CONTROL,/realize,a,set_uvalue=b
   XMANAGER,'test2',a
END


 MODIFICATION HISTORY:
    Written by:     R.Bauer (ICG-1), 1999-Oct-24
    2000-Feb-07 possible variable size of text fields added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\cw_fields.pro)


CW_LIST

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

 NAME:
   cw_list

 PURPOSE:
  This compound widget function is used to set up a input list

 CATEGORY:
   PROG_TOOLS/WIDGETS

 CALLING SEQUENCE:
   result=cw_list(base,value=value,uvalue=uvalue,_extra=extra)

 INPUTS:
   base: the base where the widget should be placed in


 KEYWORD PARAMETERS:
 value={label:fn.name+fn.ext,list:list,text:'',button:'FILE',list_selected:-1,button_pressed:0}

   value: a structure of description and values
         .label            : a label right to the button
         .list             : a vector of strings to set as value to the list
         .list_selected    : a vector of indices to set which list values are selected

 The following tags are optional:

         .button           : a string to set as value to the button
         .button_pressed   : 1 if button is pressed 0 if not
         .description      : the label of the whole frame (if it's not defined no description is printed)


      uvalue: the users uvalue of the widget
      _extra: all keywords for widget_base
              and all keywords for widget_text or widget_label or widget_button or widget_list as text_ or label_ e.g. text_xsize or label_xsize

 OUTPUTS:
       This function returns widget id

 EXAMPLE:
  PRO test_event,ev

     WIDGET_CONTROL,ev.id,get_uval=cmd
     WIDGET_CONTROL,ev.top,get_uvalue=b
     CASE cmd OF
        'done':BEGIN
           WIDGET_CONTROL,b,get_value=v
           IF v.list_selected[0] NE -1 THEN PRINT,v.list[v.list_selected]
            WIDGET_CONTROL,ev.top,/dest
        END
       'FF':BEGIN
          WIDGET_CONTROL,ev.id,get_value=v

          IF v.button_pressed EQ 1 THEN BEGIN
             file_name=DIALOG_PICKFILE(filter='*.nc')
             fn=file_path_name_ext(file_name)
             list=f_names(file_name,/time)
             value={label:fn.name+fn.ext,list:list,text:'',button:'FILE',list_selected:-1,button_pressed:0}
             WIDGET_CONTROL,ev.id,set_value=value
          ENDIF

        END
        ELSE:
     ENDCASE
  END
  PRO test

     a=WIDGET_BASE(row=2,/frame)
     value={label:'testdatei',list:STRTRIM(SINDGEN(40),2),text:'',button:'FILE',$
            list_selected:-1,button_pressed:0,description:'TEST'}
     b=cw_list(a,value=value,uvalue='FF',frame=2, XOFFSET=9,$
               YOFFSET=15 ,SCR_XSIZE=140 ,SCR_YSIZE=200,$
               /text_all_events, text_xsize=19,/text_editable,  $
               /list_multiple,list_ysize=10,list_xsize=20,$
               label_xsize=100,$
               button_ysize=20 )
     d=WIDGET_BUTTON(a,val='done',uval='done')
     WIDGET_CONTROL,/realize,a,set_uvalue=b
     XMANAGER,'test',a
  END

 

2nd example
PRO test2_event,ev WIDGET_CONTROL,ev.id,get_uval=cmd WIDGET_CONTROL,ev.top,get_uvalue=b CASE cmd OF 'done':BEGIN WIDGET_CONTROL,b,get_value=v IF v.list_selected[0] NE -1 THEN PRINT,v.list[v.list_selected] WIDGET_CONTROL,ev.top,/dest END 'FF':BEGIN WIDGET_CONTROL,ev.id,get_value=v IF v.button_pressed EQ 1 THEN BEGIN replace_tag,v,'list_selected','list_selected',INDGEN(2) WIDGET_CONTROL,ev.id,set_value=v ENDIF END ELSE: ENDCASE END PRO test2 a=WIDGET_BASE(row=2,/frame) value={label:'[0,1]',list:STRTRIM(SINDGEN(40),2),text:'',button:'PRESELECTION',$ list_selected:-1,button_pressed:0,description:'TEST'} b=cw_list(a,value=value,uvalue='FF',frame=2, XOFFSET=9,$ YOFFSET=15 ,SCR_XSIZE=140 ,SCR_YSIZE=200,$ /text_all_events, text_xsize=19,/text_editable, $ /list_multiple,list_ysize=10,list_xsize=20,$ label_xsize=100,$ button_ysize=20 ) d=WIDGET_BUTTON(a,val='done',uval='done') WIDGET_CONTROL,/realize,a,set_uvalue=b XMANAGER,'test2',a END MODIFICATION HISTORY: Written by: R.Bauer (ICG-1), 1999-Nov-07 2000-Jan-07 : button definition changed 2000-Jan-11 : pointer removed

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\cw_list.pro)


CW_PDRB

[Previous Routine] [Next Routine] [List of Routines]
 NAME: 
	cw_pdrb 
 
 PURPOSE: 
	cw_pdrb is a compound widget that simplifies creating 
	pulldown menus. It has a simpler interface than the XPDMENU 
	procedure, which it is intended to replace. Events for the 
	individual buttons are handled transparently, and a cw_pdrb 
	event returned. This event can return any one of the following: 
                The Index of the button within the base. 
                The widget ID of the button. 
                The name of the button. 
		 The fully qualified name of the button. This allows 
		  different sub-menus to contain buttons with the same 
		  name in an unambiguous way. 
 
 
 CATEGORY: 
	PROG_TOOLS/WIDGETS 
 
 CALLING SEQUENCE: 
	widget = cw_pdrb(Parent, Desc) 
 
 INPUTS: 
       Parent:	The ID of the parent widget. 
	Desc:	An array of strings or structures.  Each element contains 
		a menu description with two fields, a flag field, and 
		the name of the item.  If a structure, each element 
		is defined as follows: 
			{ cw_pdrb_S, flags:0, name:'' } 
 
		The name tag gives the name of button. The flags 
		field is a two-bit bitmask that controls how the button is 
		interpreted: 
 
		    Value	   Meaning 
		    ------------------------------------------- 
		     0     This button is neither the beginning 
			   nor the end of a pulldown level. 
		     1     This button is the root of a 
                          sub-pulldown menu. The sub-buttons 
			   start with the next button. 
		     2     This button is the last button at the 
			   current pulldown level. The next button 
			   belongs to the same level as the current 
			   parent button. 
		     3     This button is the root of a sub-pulldown 
			   menu, but it is also the last entry of 
			   the current level. 
 
	If Desc is a string, each element contains the flag field 
	followed by a backslash character, followed by the menu item's 
	contents.  See the example below. 
 
	event procedures:  An event procedure may be specified for an 
                                                element and all its children, by including a third field 
	in Desc, if Desc is a string array.  Events for buttons without 
	an event procedure, are dispatched normally. 
	See the example below. 
 
 KEYWORD PARAMETERS: 
	delimeter:        The character used to separate the parts of a 
			  fully qualified name in returned events. The 
			  default is to use the '.' character. 
	font:		  The name of the font to be used for the button 
			  titles. If this keyword is not specified, the 
			  default font is used. 
	help:		  If MBAR is specified and one of the buttons on the 
			  menubar has the label "help" (case insensitive) then 
			  that button is created with the /HELP keyword to 
			  give it any special appearance it is supposed to 
			  have on a menubar. For example, Motif expects 
			  help buttons to be on the right. 
	ids:		  A named variable into which the button IDs will 
			  be stored as a longword vector. 
	mbar:		  if constructing a menu-bar pulldown, set this 
			  keyword.  In this case, the parent must be the 
			  widget id of the menu bar of a top-level base, 
			  returned by WIDGET_BASE(..., MBAR=mbar). 
	return_id:	  If present and non-zero, the VALUE field of returned 
			  events will be the widget ID of the button. 
	return_index:	  If present and non-zero, the VALUE field of returned 
			  events will be the zero-based index of the button 
			  within the base. THIS IS THE DEFAULT. 
	return_name:	  If present and non-zero, the VALUE field of returned 
			  events will be the name of the selected button. 
	return_full_name: If present and non-zero, the VALUE field of returned 
               	  	events will be the fully qualified name of the 
			  selected button. This means that the names of all 
			  the buttons from the topmost button of the pulldown 
			  menu to the selected one are concatenated with the 
			  delimiter specified by the DELIMITER keyword. For 
			  example, if the top button was named COLORS, the 
			  second level button was named BLUE, and the selected 
			  button was named LIGHT, the returned value would be 
 
			  COLORS.BLUE.LIGHT 
 
			  This allows different submenus to have buttons with 
			  the same name (e.g. COLORS.RED.LIGHT). 
	uvalue:		  The user value to be associated with the widget. 
	xoffset:	  The X offset of the widget relative to its parent. 
	yoffset:	  The Y offset of the widget relative to its parent. 
 
 OUTPUTS: 
       The ID of the top level button is returned. 
 
 SIDE EFFECTS: 
	This widget generates event structures with the following definition: 
 
		event = { ID:0L, TOP:0L, HANDLER:0L, VALUE:0 } 
 
	VALUE is either the INDEX, ID, NAME, or FULL_NAME of the button, 
	depending on how the widget was created. 
 
 RESTRICTIONS: 
	Only buttons with textual names are handled by this widget. 
	Bitmaps are not understood. 
 
 EXAMPLE: 
	The following is the description of a menu bar with two buttons, 
	"Colors" and "Quit". Colors is a pulldown containing the colors 
	"Red", "Green", Blue", "Cyan", and "Magenta". Blue is a sub-pulldown 
	containing "Light", "Medium", "Dark", "Navy", and "Royal": 
 
		; Make sure cw_pdrb_S is defined 
		junk = { cw_pdrb_S, flags:0, name:'' } 
 
		; The description 
		desc = [ { cw_pdrb_S, 1, 'Colors' }, $ 
			     { cw_pdrb_S, 0, 'Red' }, $ 
			     { cw_pdrb_S, 0, 'Green' }, $ 
			     { cw_pdrb_S, 1, 'Blue' }, $ 
			         { cw_pdrb_S, 0, 'Light' }, $ 
			         { cw_pdrb_S, 0, 'Medium' }, $ 
			         { cw_pdrb_S, 0, 'Dark' }, $ 
			         { cw_pdrb_S, 0, 'Navy' }, $ 
			         { cw_pdrb_S, 2, 'Royal' }, $ 
			       { cw_pdrb_S, 0, 'Cyan' }, $ 
			       { cw_pdrb_S, 2, 'Magenta' }, $ 
			 { cw_pdrb_S, 2, 'Quit' } ] 
 
	The same menu may be defined as a string by equating the Desc parameter 
	to the following string array: 
 
	desc =[ '1\Colors' , $ 
		'0\Red' , $ 
		'0\Green' , $ 
		'1\Blue\BLUE_EVENT_PROC' , $ 
		'0\Light' , $ 
		'0\Medium' , $ 
		'0\Dark' , $ 
		'0\Navy' , $ 
		'2\Royal' , $ 
		'0\Cyan' , $ 
		'2\Magenta\MAGENTA_EVENT_PROC' , $ 
		'2\Quit'  ] 
 
 
	The following small program can be used with the above description 
	to create the specified menu: 
 
 
		base = widget_base() 
		menu = cw_pdrb(base, desc, /RETURN_FULL_NAME) 
		WIDGET_CONTROL, /REALIZE, base 
		repeat begin 
		  ev = WIDGET_EVENT(base) 
		  print, ev.value 
		end until ev.value eq 'Quit' 
		WIDGET_CONTROL, /DESTROY, base 
		end 
 
	Note that independent event procedures were specified for 
	the multiple Blue buttons (blue_event_proc), and the Magenta button 
	(magenta_event_proc). 
 
 MODIFICATION HISTORY: 
	18 June 1992, AB 
	16 Jan 1995, DMS, Added MBAR keyword, event procedures, 
			and menu descriptor strings. 
	2 July 1995, AB, Added HELP keyword. 
   21 Mar 1998, learned now that's an opposite problem will occur 
                if variables named same as functions 
                in the past functions would not be found if they have same names as variables 
                now variables won't be found if they have same names as functions whithout using [] 
 

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\cw_pdrb.pro)


CW_PDTMENU

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

 PURPOSE:
	CW_PDTMENU is a compound widget that simplifies creating
	pulldown menus. It has a simpler interface than the XPDTMENU
	procedure, which it is intended to replace. Events for the
	individual buttons are handled transparently, and a CW_PDTMENU
	event returned. This event can return any one of the following:
               - The Index of the button within the base.
               - The widget ID of the button.
               - The name of the button.
		- The fully qualified name of the button. This allows
		  different sub-menus to contain buttons with the same
		  name in an unambiguous way.


 CATEGORY:
	PROG_TOOLS/WIDGETS

 CALLING SEQUENCE:
	widget = CW_PDTMENU(Parent, Desc)

 INPUTS:
       Parent:	The ID of the parent widget.
	Desc:	An array of strings or structures.  Each element contains
		a menu description with two fields, a flag field, and
		the name of the item.  If a structure, each element
		is defined as follows:
			{ CW_PDTMENU_S, flags:0, name:'' }

		The name tag gives the name of button. The flags
		field is a two-bit bitmask that controls how the button is
		interpreted:

		    Value	   Meaning
		    -------------------------------------------
		     0     This button is neither the beginning
			   nor the end of a pulldown level.
		     1     This button is the root of a
                          sub-pulldown menu. The sub-buttons
			   start with the next button.
		     2     This button is the last button at the
			   current pulldown level. The next button
			   belongs to the same level as the current
			   parent button.
		     3     This button is the root of a sub-pulldown
			   menu, but it is also the last entry of
			   the current level.

	If Desc is a string, each element contains the flag field
	followed by a backslash character, followed by the menu item's
	contents.  See the example below.

	EVENT PROCEDURES:  An event procedure may be specified for an
	element and all its children, by including a third field
	in Desc, if Desc is a string array.  Events for buttons without
	an event procedure, are dispatched normally.
	See the example below.

 KEYWORD PARAMETERS:
	DELIMITER:        The character used to separate the parts of a
			  fully qualified name in returned events. The
			  default is to use the '.' character.
	FONT:		  The name of the font to be used for the button
			  titles. If this keyword is not specified, the
			  default font is used.
	HELP:		  If MBAR is specified and one of the buttons on the
			  menubar has the label "help" (case insensitive) then
			  that button is created with the /HELP keyword to
			  give it any special appearance it is supposed to
			  have on a menubar. For example, Motif expects
			  help buttons to be on the right.
	IDS:		  A named variable into which the button IDs will
			  be stored as a longword vector.
	MBAR:		  if constructing a menu-bar pulldown, set this
			  keyword.  In this case, the parent must be the 
			  widget id of the menu bar of a top-level base,
			  returned by WIDGET_BASE(..., MBAR=mbar).
	RETURN_ID:	  If present and non-zero, the VALUE field of returned
			  events will be the widget ID of the button.
	RETURN_INDEX:	  If present and non-zero, the VALUE field of returned
			  events will be the zero-based index of the button
			  within the base. THIS IS THE DEFAULT.
	RETURN_NAME:	  If present and non-zero, the VALUE field of returned
			  events will be the name of the selected button.
	RETURN_FULL_NAME: If present and non-zero, the VALUE field of returned
               	  events will be the fully qualified name of the
			  selected button. This means that the names of all
			  the buttons from the topmost button of the pulldown
			  menu to the selected one are concatenated with the
			  delimiter specified by the DELIMITER keyword. For
			  example, if the top button was named COLORS, the
			  second level button was named BLUE, and the selected
			  button was named LIGHT, the returned value would be

			  COLORS.BLUE.LIGHT

			  This allows different submenus to have buttons with
			  the same name (e.g. COLORS.RED.LIGHT).
	UVALUE:		  The user value to be associated with the widget.
	XOFFSET:	  The X offset of the widget relative to its parent.
	YOFFSET:	  The Y offset of the widget relative to its parent.
	TRACKING_EVENTS:  Enable widget tracking events.

 OUTPUTS:
       The ID of the top level button is returned.

 SIDE EFFECTS:
	This widget generates event structures with the following definition:

		event = { ID:0L, TOP:0L, HANDLER:0L, VALUE:0 }

	VALUE is either the INDEX, ID, NAME, or FULL_NAME of the button,
	depending on how the widget was created.

 RESTRICTIONS:
	Only buttons with textual names are handled by this widget.
	Bitmaps are not understood.

 EXAMPLE:
	The following is the description of a menu bar with two buttons,
	"Colors" and "Quit". Colors is a pulldown containing the colors
	"Red", "Green", Blue", "Cyan", and "Magenta". Blue is a sub-pulldown
	containing "Light", "Medium", "Dark", "Navy", and "Royal":

		; Make sure CW_PDTMENU_S is defined
		junk = { CW_PDTMENU_S, flags:0, name:'' }

		; The description
		desc = [ { CW_PDTMENU_S, 1, 'Colors' }, $
			     { CW_PDTMENU_S, 0, 'Red' }, $
			     { CW_PDTMENU_S, 0, 'Green' }, $
			     { CW_PDTMENU_S, 1, 'Blue' }, $
			         { CW_PDTMENU_S, 0, 'Light' }, $
			         { CW_PDTMENU_S, 0, 'Medium' }, $
			         { CW_PDTMENU_S, 0, 'Dark' }, $
			         { CW_PDTMENU_S, 0, 'Navy' }, $
			         { CW_PDTMENU_S, 2, 'Royal' }, $
			       { CW_PDTMENU_S, 0, 'Cyan' }, $
			       { CW_PDTMENU_S, 2, 'Magenta' }, $
			 { CW_PDTMENU_S, 2, 'Quit' } ]

	The same menu may be defined as a string by equating the Desc parameter
	to the following string array:
	
	desc =[ '1\Colors' , $
		'0\Red' , $
		'0\Green' , $
		'1\Blue\BLUE_EVENT_PROC' , $
		'0\Light' , $
		'0\Medium' , $
		'0\Dark' , $
		'0\Navy' , $
		'2\Royal' , $
		'0\Cyan' , $
		'2\Magenta\MAGENTA_EVENT_PROC' , $
		'2\Quit'  ]


	The following small program can be used with the above description
	to create the specified menu:


		base = widget_base()
		menu = cw_pdtmenu(base, desc, /RETURN_FULL_NAME)
		WIDGET_CONTROL, /REALIZE, base
		repeat begin
		  ev = WIDGET_EVENT(base)
		  print, ev.value
		end until ev.value eq 'Quit'
		WIDGET_CONTROL, /DESTROY, base
		end

	Note that independent event procedures were specified for
	the multiple Blue buttons (blue_event_proc), and the Magenta button 
	(magenta_event_proc).

 MODIFICATION HISTORY:
	18 June 1992, AB
	16 Jan 1995, DMS, Added MBAR keyword, event procedures,
			and menu descriptor strings.
	2 July 1995, AB, Added HELP keyword.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\cw_pdtmenu.pro)


CW_PLOTAXES

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

 PURPOSE:
 
       A compound widget used to change the type, range and style
       (bit 0) values of one or more plot axis structure variable.  A
       CW_PLOTAXIS (single axis) widget is created for each element
       of the LABELS input parameter. The widget also includes an
       Apply button, and (optionally) a Done button.
      
 CATEGORY:
 
	Compound widgets.

 CALLING SEQUENCE:
 
	Result = CW_PLOTAXES(PARENT,LABELS)

 INPUTS:
 
       PARENT - The ID of the parent widget.  

       LABELS - A string array of labels to be drawn to the left (or
                top) of each of the CW_PLOTAXIS widgets.

 OPTIONAL KEYWORD PARAMETERS:
 
	UVALUE - Supplies the user value for the widget.
 
       FRAME - Set to draw a frame around the widget.

       VALUE - An (n,4) array of initial values, where
               n = n_elements(LABELS), and each row has
               the form VALUE(i,*)=[type,min,max,style]

       FONT - Font keyword for labels etc.

       ROW - Set to create a row of column-oriented CW_PLOTAXIS widgets.

       COLUMN - Set to create a column of row-oriented CW_PLOTAXIS
                widgets. (default)
 
       DONE - Set this to add a Done button, in addition to the standard
              Apply button.

       AXIS_IDS - An array of widget id's for the individual
                  CW_PLOTAXIS widgets.

       X_SCROLL_SIZE, Y_SCROLL_SIZE - if these values are non-zero,
                                      then the base widget which
                                      holds the CW_PLOTAXIS widgets
                                      will include scroll bars.

       NO_RETURN - The default behavior is that the user must press
                    after entering new values.  Set this
                   keyword so that new values are accepted even if
                   the user just changes a value and then moves the
                   cursor outside of the text entry area.

 OUTPUTS:
 
       The ID of the created widget is returned.

 PROCEDURE/EXAMPLE:

         The idea is that this cw would be used in a widget intended
         to allow the user to interactively adjust the settings for a
         plot.  For instance, you might have a menu item such as Plot
         Options->Scaling, which would create a popup widget
         containing a CW_PLOTAXES subwidget for the X and Y plot
         variables.  When the user makes changes to the Type, Range,
         and Style values, and then presses the Apply button, the
         popup widget event handler would re-draw the plot
         accordingly.

         This widget generates an event when the user presses the
         Apply button or the Done button, if present. The EVENT.TAG
         keyword will return either "APPLY" or "DONE" accordingly.

         Example:
 
         axes=CW_PLOTAXES(BASE,['X','Y'],/DONE, $
                      VALUE=TRANSPOSE([[FLTARR(4)],[FLTARR(4)]]))

 MODIFICATION HISTORY:
 
       David L. Windt, Bell Labs, March 1997
       windt@bell-labs.com

       DLW, June 1997, Added NO_RETURN keyword.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\windt\cw_plotaxes.pro)


CW_RBFSLIDER

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

 PURPOSE:
	The standard slider provided by the WIDGET_SLIDER() function is
	integer only. This compound widget provides a floating point
	slider.

 CATEGORY:
	PROG_TOOLS/WIDGETS

 CALLING SEQUENCE:
	widget = CW_RBFSLIDER(Parent)

 INPUTS:
       Parent:		The ID of the parent widget.

 KEYWORD PARAMETERS:
	DRAG:		Set this keyword to zero if events should only
			be generated when the mouse is released. If it is
			non-zero, events will be generated continuously
			when the slider is adjusted. Note: On slow systems,
			/DRAG performance can be inadequate. The default
			is DRAG=0.
       EDIT:		Set this keyword to make the slider label be
			editable. The default is EDIT=0.
	FORMAT:		Provides the format in which the slider value is
			displayed. This should be a format as accepted by
			the STRING procedure. The default is FORMAT='(G13.6)'
	FRAME:		Set this keyword to have a frame drawn around the
			widget. The default is FRAME=0.
	MAXIMUM:	The maximum value of the slider. The default is
			MAXIMUM=100.
	MINIMUM:	The minimum value of the slider. The default is
			MINIMUM=0.
	SCROLL		Sets the SCROLL keyword to the WIDGET_SLIDER underlying
			this compound widget. Unlike WIDGET_SLIDER, the
			value given to SCROLL is taken in the floating units
			established by MAXIMUM and MINIMUM, and not in pixels.
	SUPPRESS_VALUE:	If true, the current slider value is not displayed.
			The default is SUPPRESS_VALUE=0.
	TITLE:		The title of slider. (The default is no title.)
	UVALUE:		The user value for the widget.
	VALUE:		The initial value of the slider
	VERTICAL:	If set, the slider will be oriented vertically.
			The default is horizontal.
	XSIZE:		For horizontal sliders, sets the length.
	YSIZE:		For vertical sliders, sets the height.
   XOFFSET:    The offset in x direction, if it's used then xsize=xsize-yoffset ;new March 98
   YOFFSET:    The offset in y direction, if it's used then ysize=ysize-yoffset ;new March 98

 OUTPUTS:
       The ID of the created widget is returned.

 SIDE EFFECTS:
	This widget generates event structures containing a field
	named value when its selection thumb is moved. This is a
	floating point value.

 PROCEDURE:
	WIDGET_CONTROL, id, SET_VALUE=value can be used to change the
		current value displayed by the widget.

	WIDGET_CONTROL, id, GET_VALUE=var can be used to obtain the current
		value displayed by the widget.

 MODIFICATION HISTORY:
	April 2, 1992, SMR and AB
		Based on the RGB code from XPALETTE.PRO, but extended to
		support color systems other than RGB.
	5 January 1993, Mark Rivers, Brookhaven National Labs
		Added EDIT keyword.
       7 April 1993, AB, Removed state caching.
	28 July 1993, ACY, set_value: check labelid before setting text.
	3 October 1995, AB, Added SCROLL keyword.
   30 March 1998 RB added xoffset and yoffset

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\cw_rbfslider.pro)


CYPH

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CYPH
 PURPOSE:
       Construct a cycle/phase array from time series data.
 CATEGORY:
 CALLING SEQUENCE:
       cyph, data, time
 INPUTS:
       data = time series data.             in
       time = time tag of each data point.  in
 KEYWORD PARAMETERS:
       Keywords:
         CPOUT=z  Returned reformatted data image.
         TOUT=t   Returned time for bottom line image.
         OFFSET=frac  Given starting offset into data as fraction
           of time slice size (def=0).
         SLICE=dx  Given slice size in samples (may be fractional).
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
       Notes: See also xcyph, a widget based interactive version.
 MODIFICATION HISTORY:
       R. Sterner, 1994 Mar 2.

 Copyright (C) 1994, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\cyph.pro)


D2DMS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       D2DMS
 PURPOSE:
       Function to convert from degrees to deg, min, sec.
 CATEGORY:
 CALLING SEQUENCE:
       s = d2dms( deg)
 INPUTS:
       deg = input in degrees.             in
 KEYWORD PARAMETERS:
       Keywords:
         DIGITS=n  Force degrees to have n digits.
 OUTPUTS:
       s = output string.                  out
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 1997 Jan 17

 Copyright (C) 1997, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\d2dms.pro)


DATATYPE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DATATYPE
 PURPOSE:
       Datatype of variable as a string (3 char or spelled out).
 CATEGORY:
 CALLING SEQUENCE:
       typ = datatype(var, [flag])
 INPUTS:
       var = variable to examine.         in
       flag = output format flag (def=0). in
 KEYWORD PARAMETERS:
       Keywords:
         NUMERIC=num returns a code indicating numeric type:
           0=non-numeric, 1=integer, 2=float, 3=complex.
         INTEGER_BITS=bits returns number of bits if integer:
           0=Not Integer, 8=Byte, 16=Int, 32=Long, 64=Long 64.
         /DESCRIPTOR returns a descriptor for the given variable.
           If the variable is a scalar the value is returned as
           a string.  If it is an array a description is return
           just like the HELP command gives.  Ex:
           datatype(fltarr(2,3,5),/desc) gives
             FLTARR(2,3,5)  (flag always defaults to 3 for /DESC).
 OUTPUTS:
       typ = datatype string or number.   out
          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         PTR
          OBJ       Object     11         OBJ
          UIN       U_Integer  12         UINT
          ULO       U_Long     13         ULON
          LLO       Long_64    14         LON64
          ULL       U_Long_64  15         ULON64
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       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.
       R. Sterner, 18 Mar, 1993 --- Added /DESCRIPTOR.
       R. Sterner, 1995 Jul 24 --- Added DCOMPLEX for data type 9.
       R. Sterner, 1999 Jun  4 --- Added types 10 on, also numeric and bits.
       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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\datatype.pro)


DATA_BLOCK

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DATA_BLOCK
 PURPOSE:
       Read the block of data following data_block call.
 CATEGORY:
 CALLING SEQUENCE:
       data_block, out
 INPUTS:
 KEYWORD PARAMETERS:
       Keywords:
         /CHECK  means just list data block lines without
           interpreting them.
         ERROR=err  Error flag: 0=ok, 1=error.
 OUTPUTS:
       out = returned array of data.   out
 COMMON BLOCKS:
 NOTES:
       Notes: Block of data must directly follow call to data_block.
       Examples:
         data_block, x
         ; 11,23,26.5, 34.7 42 EOD
       
              data_block, t
       ;        1, 2, 3      ; Line 1.
       ;       11,22,33      ; Line 2.
       ;       eod
        
        <> Values may be separated by commas, spaces, and/or tabs.
        <> The string EOD indicates the End Of Data and may be at
             the end of a line or on a separate line (but only once).
        <> Multiple data lines are allowed.
        <> Data always comes back as a floating 1-d array.
        <> Data lines must be commented out so IDL will ignore them.
        <> Anything following a second comment char is ignored.
       
 MODIFICATION HISTORY:
       R. Sterner, 1995 May 23
       R. Sterner, 2000 Aug 01 --- Fixed chnage in returned calling line #.

 Copyright (C) 1995, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\data_block.pro)


DATA_SEPARATOR

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

 PURPOSE:
   This function searches possible separators between data entries
   in a string.

 CATEGORY:
   PROG_TOOLS/STRINGS

 CALLING SEQUENCE:
   Result=DATA_SEPARATOR(string)

 INPUTS:
   string:  a string containing data seperated by
   ';' ',' tab or space

 OUTPUTS:
   This function returns the separator. If different separators or no
   separator is present, the string '0' is returned

 EXAMPLE:
   string = '12345, 234, 123'
   r=data_separator(string)
   print, r
   the output should be: ,

 MODIFICATION HISTORY:
   Written by: Theo Brauers, 1997-Sep-19

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\data_separator.pro)


DATA_SUBSET

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

 PURPOSE:
   This function makes a subset of data from the structure INHALT
   depending on a time range

 CATEGORY:
   PROG_TOOLS/STRUCTURES

 CALLING SEQUENCE:
   Result=data_subset(structure,time_range)

 INPUTS:
   structure:      The structure INHALT
   time_range:  An Array of start and end time

 OUTPUTS:
   The Result is a new Structure type INHALT whith the subset of called
   time_range

 EXAMPLE:
   Result=data_subset(INHALT,time_range)
   result=data_subset(inhalt,[dtime2js('1997-03-01 00:00:00 000'),$"
                              dtime2js('1997-03-05 00:00:00 000')])"


 MODIFICATION HISTORY:
 	Written by:	R.Bauer (ICG-1), Date. August 14 1997
   1999-Nov-06 help added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\data_subset.pro)


DATE2DN

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DATE2DN
 PURPOSE:
       Find day of year number from date.
 CATEGORY:
 CALLING SEQUENCE:
       dn = date2dn(date)
 INPUTS:
       date = date string (like 6 Jul, 1995).    in
 KEYWORD PARAMETERS:
 OUTPUTS:
       dn = day number in year (like 187).        out
 COMMON BLOCKS:
 NOTES:
       Notes: The format of the date is flexible except that the
         month must be month name.
         Dashes, commas, periods, or slashes are allowed.
         Some examples: 23 sep, 1985     sep 23 1985   1985 Sep 23
         23/SEP/85   23-SEP-1985   85-SEP-23   23 September, 1985.
         Doesn't check if month day is valid. Doesn't
         change year number (like 86 does not change to 1986).
         Dates may have only 2 numeric values, year and day. If
         both year & day values are < 31 then day is assumed first.
         systime() can be handled: dn=date2dn(systime()).
         Day number is returned as a string.
         For invalid dates dn is set to a null string.
         Times are allowed.
 MODIFICATION HISTORY:
       R. Sterner, 1995 Jul 6

 Copyright (C) 1995, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\date2dn.pro)


DATE2DOY

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DATE2DOY
 PURPOSE:
       Date to Day of Year conversion.
 CATEGORY:
 CALLING SEQUENCE:
       date2doy
 INPUTS:
 KEYWORD PARAMETERS:
       Keywords:
         FIRST=date1  Starting date for list of dates.
         LAST=date2   Ending date for list of dates.
           Date must be entered using month name, 3 letters
           or more.  Year, month, and day may be any order
           but must be separated by spaces, commas, tabs,slashes,
           or dashes (like 1998-Nov-25, NOT 1998nov25).
         FILE=file  Optional output file (else screen).
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 1998 Nov 25

 Copyright (C) 1998, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\date2doy.pro)


DATE2JD

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DATE2JD
 PURPOSE:
       Convert a date string to Julian Day number.
 CATEGORY:
 CALLING SEQUENCE:
       jd = date2jd(date)
 INPUTS:
       date = date string.                in
 KEYWORD PARAMETERS:
 OUTPUTS:
       jd = Returned Julian Day number.   out
 COMMON BLOCKS:
 NOTES:
       Note: date must contain month as a name of 3 or more leeters.
 MODIFICATION HISTORY:
       R. Sterner, 1996 Sep 15
       R. Sterner, 1999 Aug 4 --- Improved 2 digit year case.

 Copyright (C) 1996, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\date2jd.pro)


DATE2YMD

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DATE2YMD
 PURPOSE:
       Date text string to the numbers year, month, day.
 CATEGORY:
 CALLING SEQUENCE:
       date2ymd,date,y,m,d
 INPUTS:
       date = date string.		in
 KEYWORD PARAMETERS:
 OUTPUTS:
       y = year number.		out
       m = month number.		out
       d = day number.		out
 COMMON BLOCKS:
 NOTES:
       Notes: The format of the date is flexible except that the
         month must be month name.
         Dashes, commas, periods, or slashes are allowed.
         Some examples: 23 sep, 1985     sep 23 1985   1985 Sep 23
         23/SEP/85   23-SEP-1985   85-SEP-23   23 September, 1985.
         Doesn't check if month day is valid. Doesn't
         change year number (like 86 does not change to 1986).
         Dates may have only 2 numeric values, year and day. If
         both year & day values are < 31 then day is assumed first.
         systime() can be handled: date2ymd,systime(),y,m,d
         For invalid dates y, m and d are all set to -1.
 MODIFICATION HISTORY:
       Written by R. Sterner, 29 Oct, 1985.
       Johns Hopkins University Applied Physics Laboratory.
       25-Nov-1986 --- changed to REPCHR.
       RES 18 Sep, 1989 --- converted to SUN.
       R. Sterner, 1994 Mar 29 --- Modified to handle arrays.

 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\date2ymd.pro)


DATE_STRING

[Previous Routine] [Next Routine] [List of Routines]
 purpose:  return date string given year and day of year
 useage:   result=date_string(year,day)

 EXAMPLE:  print,date_string(1991,283)
             October 10, 1991

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\date_string.pro)


DAVERAGE

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:    daverage

 USEAGE:     daverage,lat,sza,yy

 PURPOSE:
             finds the daylight hour average of yy at each latitude
             point.  Average values are for spring or fall equinox

 INPUT:
   lat       array of latitude points
   sza       solar zenith angle array
   yy        function of solar zenith angle

 OUTPUT:
   result    average of yy over 12 hours (daylight)
 
 EXAMPLE:

   lat=indgen(10)*10
   sza=acos((indgen(11))*.1)/!dtor
   yy=90-sza
   !p.multi=[0,1,2]
   plot,sza,yy
   plot,lat,daverage(lat,sza,yy)



 procedure:  At the spring or fall equinox the solar zenith angle at
             a given latitude is given by,

               cos(sza)=cos(lat)*cos(phi) 

             where phi is the phase angle of the earth's rotation
             [= 2 pi*(time-12)/24)]

             thus for each value of lat we have

                     yave=integral(phi,yv)/!pi
             where,
                     yv=interpol(yy,mu,cos(lat*!dtor)*cos(phi*!dtor))
                     mu=cos(sza*!dtor)


 AUTHOR:   Paul Ricchiazzi                        24 Aug 95
           Institute for Computational Earth System Science
           University of California, Santa Barbara
           paul@icess.ucsb.edu

 REVISIONS:

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\daverage.pro)


DAYAVE

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:    dayave

 PURPOSE:    convert quantities which depend on sza to daily averages for 
             given values of day_of_year and latitude

 USEAGE:     result=dayave(doy,lat,sza,xx)

 INPUT:      
   doy       the day of year (vector)

   lat       latitude (vector)

   sza       a vector of solar zenith angles (degrees) monitonic increasing

   xx        a vector of a quantity which varies with SZA. If
             max(sza) lt 90 then it is assumed that xx=0 when
             (cos(sza) le 0).  If this is not the case, then data
             values for the full SZA angle range [-90,90] must be
             supplied.
             

 KEYWORD INPUT
   dt        averaging interval in hours (default=0.25 hours)

   zenith    zenith angles at each time, doy and lat (24/dt,nday,nlat)
             (returned by first call of DAYAVE, see below)
             if zero or absent, DAYAVE recomputes the zenith angle at 
             each point in the (DOY # LAT) input grid.  This can be
             fairly time consuming when there are lots of grid points.
             By supplying a zero filled named variable to DAYAVE you
             can retrieve the ZENITH grid for the next call to DAYAVE.

   night     if set, the interpolated value of xx is not set to zero 
             when sza is greater than 90.  This should be used for 
             physical quantities which maintain non-zero values even
             after sunset


 OUTPUT:
   result   the integral of xx(t) dt for the given days and latitudes


 EXAMPLE:
      !p.multi=[0,1,2]
      doy=findgen(365/30+1)*30
      lat=findgen(90/10+1)*10
      sza=findgen(90/10)*10
      xx=cos(sza*!dtor)
      zenith=0.                         ; zero filled named variable to 
                                        ; retrieve zenith angle grid 
      
      yy=dayave(doy,lat,sza,xx,zenith=zenith)
      tvim,yy,xrange=doy,yrange=lat,xtitle='day of year',ytitle='latitude',$
           title='daily integral of sup(cos(sza),0)',/scale,/interp

      xx2=xx^2
      yy2=dayave(doy,lat,sza,xx2,zenith=zenith)
      tvim,yy2,xrange=doy,yrange=lat,xtitle='day of year',ytitle='latitude',$
           title='daily average of sup(cos(sza)!a2!n,0)',/scale,/interp
  
  author:  Paul Ricchiazzi                            aug94
           Institute for Computational Earth System Science
           University of California, Santa Barbara

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\dayave.pro)


DAYGLOBE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DAYGLOBE
 PURPOSE:
       Show the area of daylight/night on a globe.
 CATEGORY:
 CALLING SEQUENCE:
       dayglobe, lat0, lng0, ang0
 INPUTS:
       lat0 = Latitude at center of globe.        in
       lng0 = Longitude at center of globe.       in
       ang0 = Rotation angle of image (deg CCW).  in
 KEYWORD PARAMETERS:
       Keywords:
         TIME=time  Time string (def=current).
         ZONE=hrs  Hours ahead of GMT (def=0).  Ex: zone=-4 for EDT.
         /DEEPER  means use deeper colors.
         /QUANTIZED  means 10 degree banded day colors.
         /BLACK   means use black background (else white).
         /COUNTRIES means plot countries.
         POINT='lng lat'  Point to mark.
         COLOR=clr Color of point as R G B like '0 255 0').
         /GRID  display a grid.
         CGRID=gclr  Color for Grid as R G B like '0 255 0').
         CHARSIZE=csz  Relative character size (def=1).
         /STEREO  means use Stereographic projection instead of
            Orthographic.
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 1999 Oct 14
       R. Sterner, 2000 Sep 19 --- Added quantized day colors.

 Copyright (C) 1999, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dayglobe.pro)


DAY_AVERAGE

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

 PURPOSE:
   This function calculates a small statistical survey for each day of a given data set of a given array

 CATEGORY:
   MATH

 CALLING SEQUENCE:
   Result = DAY_AVERAGE(time, array)

 INPUTS:
   time:  julian seconds
   array: data field

 OPTIONAL INPUTS:

 Keyword PARAMETERS:
   MISSING:    missing value to be ignored
   FORMAT:     format for numbers

 OUTPUTS:
   String array containing the statistics

 EXAMPLE:
   printtab, day_average(DINDGEN(144)*3600., DINDGEN(144))

 REVISION HISTORY:
       Written         Theo Brauers, Apr 1999

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\day_average.pro)


DBD_DIRTREE

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

 PURPOSE:
  this procedure write a html directory structure and creates the depending dir2html.html files.

 CATEGORY:
   DATAFILES/DBD

 CALLING SEQUENCE:
   dbd_dirtree,path,_extra=e

 INPUTS:
  path: the path to make the html tree

 KEYWORD PARAMETERS:
  _extra: to submit keywords to get_dir_tree or/and dir2htmlfile

 PROCEDURE:
  The tree html information file is stored one path segment before the submitted path.
  At the moment it is not possible to create a tree of the root path.

 EXAMPLE:
   dbd_dirtree,'C:\temp',level=5

 MODIFICATION HISTORY:
       Written by:     R.Bauer (ICG-1),  2000-May-25

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\dbd_dirtree.pro)


DCOLORS

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

 USEAGE          dcolors
                 dcolors,r=r,g=g,b=b,pickc=pickc,squeeze=squeeze,view=view

 INPUT:          none

 Keyword input:  

   pickc         if set, call pickc to adjust discreet colors

   squeeze       if set,  original color table is resampled to fit
                 in remaining color table index space.

   view          if set, draw palette of discreet colors to separate window

   r,g,b         red, green and blue values of discreet color table.
                 default colors:

                  r =  [0, 255,   0, 150, 255, 194, 125,   0, 255,  19,   0]
                  g =  [0,   0, 255, 150, 248, 196, 255, 175,  10, 215,   0]
                  b =  [0,   0,   0, 255,   6, 196, 185,   0, 246, 224, 255]

 OUTPUT:         none
 
 PURPOSE:        loads custom colors in lower part of current color
                 scale.  If SQUEEZE is set pre-existing color scale 
                 is squeezed to fit between color index n_elements(r)
                 and !d.n_colors.
 
  author:  Paul Ricchiazzi                            jan93
           Institute for Computational Earth System Science
           University of California, Santa Barbara

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\dcolors.pro)


DDEABM

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

 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:
   Integrate Ordinary Differential Equation with Adams-Bashford-Moulton

 MAJOR TOPICS:
   Numerical Analysis.

 CALLING SEQUENCE:
   DDEABM, FUNCT, T0, F0, TOUT, [ PRIVATE, FUNCTARGS=, STATE= , ]
     [ /INIT, /INTERMEDIATE, TSTOP=, EPSREL=, EPSABS=, ]
     [ TGRID=, YGRID=, YPGRID=, NGRID=, NFEV=, ]
     [ STATUS=, ERRMSG= ]

 DESCRIPTION:

  DDEABM performs integration of a system of one or more ordinary
  differential equations using a Predictor-Corrector technique.  An
  adaptive Adams-Bashford-Moulton method of variable order between
  one and twelve, adaptive stepsize, and error control, is used to
  integrate equations of the form:

     DF_DT = FUNCT(T, F)

  T is the independent variable, F is the (possibly vector) function
  value at T, and DF_DT is the derivative of F with respect to T,
  evaluated at T.  FUNCT is a user function which returns the
  derivative of one or more equations.  

  DDEABM is based on the public domain procedure DDEABM.F written by
  L. F. Shampine and M. K. Gordon, and available in the DEPAC package
  of solvers within SLATEC library.

  DDEABM is used primarily to solve non-stiff and mildly stiff
  ordinary differential equations, where evaluation of the user
  function is expensive, or high precision is demanded (close to the
  machine precision).  A Runge-Kutta technique may be more
  appropriate if lower precision is acceptable.  For stiff problems
  neither Adams-Bashford-Moulton nor Runge-Kutta techniques are
  appropriate.  DDEABM has code which detects the stiffness of the
  problem and reports it.

  The user can operate DDEABM in three different modes:

    * the user requests one output at a time (the default), and
      maintains the integrator state using the STATE keyword;

    * the user requests a grid of times (by passing an array to
      TOUT), and optionally maintains the integrator state for
      subsequent integrations using the STATE keyword;

    * the user requests output at the natural adaptive stepsizes
      using the /INTERMEDIATE keyword.

  When the user requests explicit output points using TOUT, it is
  likely that the output will be interpolated between two natural
  stepsize points.

  If the user requests a grid of outputs, and the integration fails
  before reaching the requested endpoint, then control returns
  immediately to the user with the appropriate STATUS code.

  The initial conditions are given by F0, when T = T0.  The number of
  equations is determined by the number of elements in F0.
  Integration stops when the independent variable T reaches the final
  value of TOUT.  If the user wants to continue the integration, it
  can be restarted with a new call to DDEABM, and a new value of
  TOUT.

 USER FUNCTION

  The user function FUNCT must be of the following form:

  FUNCTION FUNCT, T, F, PRIVATE, ...
     ; ... compute derivatives ...
     RETURN, DF_DT
  END

  The function must accept at least two, but optionally three,
  parameters.  The first, 'T', is the scalar independent variable
  where the derivatives are to be evaluated.  The second, 'F', is the
  vector of function values.  The function must return an array of
  same size as 'F'.  The third positional parameter, 'PRIVATE', is a
  purely optional PRIVATE parameter.  FUNCT may accept more
  positional parameters, but DDEABM will not use them.  Any number of
  keyword parameters can be passed using the FUNCTARGS keyword.

  The user function FUNCT must not modify either the independent
  variable 'T' or the function values 'F'.

 RESTARTING THE INTEGRATOR

  When restarting the integrator, the STATE keyword can be used to
  save some computation time.  Upon return from DDEABM the STATE
  keyword will contain a structure which describes the state of the
  integrator at the output point.  The user need merely pass this
  variable back into the next call to continue integration.  The
  value of T, and the function value F, must not be adjusted between
  calls to DDEABM.

  If T or F0 are to be adjusted, then the integrator must be
  restarted afresh *without* the previous state.  This can be
  achieved either by reseting STATE to undefined, or by setting the
  /INIT keyword to DDEABM.

 ERROR CONTROL

  Local error control is governed by two keywords, EPSABS and EPSREL.
  The former governs the absolute error, while the latter governs the
  relative or fractional error.  The error test at each iteration is:

     ABS(ERROR)   LE   EPSREL*ABS(F) + EPSABS
  
  A scalar value indicates the same constraint should be applied to
  every equation; a vector array indicates constraints should be
  applied individually to each component.

  Setting EPSABS=0.D0 results in a pure relative error test on that
  component. Setting EPSREL=0. results in a pure absolute error test
  on that component.  A mixed test with non-zero EPSREL and EPSABS
  corresponds roughly to a relative error test when the solution
  component is much bigger than EPSABS and to an absolute error test
  when the solution component is smaller than the threshold EPSABS.
  
  Proper selection of the absolute error control parameters EPSABS
  requires you to have some idea of the scale of the solution
  components.  To acquire this information may mean that you will
  have to solve the problem more than once. In the absence of scale
  information, you should ask for some relative accuracy in all the
  components (by setting EPSREL values non-zero) and perhaps impose
  extremely small absolute error tolerances to protect against the
  danger of a solution component becoming zero.
  
  The code will not attempt to compute a solution at an accuracy
  unreasonable for the machine being used.  It will advise you if you
  ask for too much accuracy and inform you as to the maximum accuracy
  it believes possible.

 HARD LIMIT ON T

  If for some reason there is a hard limit on the independent
  variable T, then the user should specify TSTOP.  For efficiency
  DDEABM may try to integrate *beyond* the requested point of
  termination, TOUT, and then interpolate backwards to obtain the
  function value at the requested point.  If this is not possible
  because the function because the equation changes, or if there is a
  discontinuity, then users should specify a value for TSTOP; the
  integrator will not go past this point.


 INPUTS:

  FUNCT - by default, a scalar string containing the name of an IDL
          function to be integrated.  See above for the formal
          definition of FUNCT.  (No default).

  T0 - scalar number, upon input the starting value of the
       independent variable T.  Upon output, the final value of T.

  Y - vector.  Upon input the starting values of the function for T =
      T0.  Upon output, the final (vector) value of the function.

  TOUT - must be at least a scalar, but optionally a vector,
         specifies the desired points of output.

         If TOUT is a scalar and INTERMEDIATE is not set, then DDEABM
         integrates up to TOUT.  A scalar value of the function at
         TOUT is returned in F.

         If TOUT is a scalar and /INTERMEDIATE is set, then DDEABM
         computes a grid of function values at the optimal step
         points of the solution.  The grid of values is returned in
         TGRID, YGRID, and YPGRID.  The final function value,
         evaluated at the last point in TOUT, is returned in F.

         If TOUT is a vector, then DDEABM computes a grid of function
         values at the requested points.  The grid of values is
         returned in TGRID, YGRID and YPGRID.  The final function
         value, evaluated at the last point in TOUT, is returned in
         F.

         It is possible for TOUT to be less than T0, i.e., to
         integrate backwards.

  PRIVATE - any optional variable to be passed on to the function to
            be integrated.  For functions, PRIVATE is passed as the
            second positional parameter.  DDEABM does not examine or
            alter PRIVATE.

 KEYWORD PARAMETERS:

   EPSABS - a scalar number, the absolute error tolerance requested
            in the integral computation.  If less than or equal to
            zero, then the value is ignored.
            Default: 0

   EPSREL - a scalar number, the relative (i.e., fractional) error
            tolerance in the integral computation.  If less than or
            equal to zero, then the value is ignored.
            Default: 1e-4 for float, 1d-6 for double

   ERRMSG - upon return, a descriptive error message.

   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.

   INIT - if set, indicates that the integrator is to be restarted
          afresh.

   INTERMEDIATE - if set, indicates that the integrator is to compute
                  at the natural step points.

   NFEV - upon output, the scalar number of function evaluations.

   NGRID - if /INTERMEDIATE is set, the number of points to compute
           before returning.
           Default: 1

   STATE - upon input and return, the integrator state.  Users should
           not modify this structure.  If the integrator is to be
           restarted afresh, then the /INIT keyword should be set, in
           order to clear out the old state information.

   STATUS - upon output, the integer status of the integration.

           1 - A step was successfully taken in the
               intermediate-output mode.  The code has not yet
               reached TOUT.
 
           2 - The integration to TOUT was successfully completed
               (T=TOUT) by stepping exactly to TOUT.
 
           3 - The integration to TOUT was successfully completed
               (T=TOUT) by stepping past TOUT.  Y(*) is obtained by
               interpolation.
 
                       *** Task Interrupted ***
                 Reported by negative values of STATUS
 
           -1 - A large amount of work has been expended.  (500 steps
                attempted)
 
           -2 - The error tolerances are too stringent.
 
           -3 - The local error test cannot be satisfied because you
                specified a zero component in EPSABS and the
                corresponding computed solution component is zero.
                Thus, a pure relative error test is impossible for
                this component.
 
           -4 - The problem appears to be stiff.
 
                       *** Task Terminated ***
                 Reported by the value of STATUS=-33
 
           -33 - The code has encountered trouble from which it
                 cannot recover.  A error message is printed
                 explaining the trouble and control is returned to
                 the calling program. For example, this occurs when
                 invalid input is detected.

   TGRID - upon output, the grid of values of T for which the
           integration is provided.

   TSTOP - a scalar, specifies a hard limit for T, beyond which the
           integration must not proceed.
           Default:  none, i.e., integration is allowed to
                    "overshoot"

   YGRID - upon output, the grid of function values for which the
           integration is provided.

   YPGRID - upon ouptut, the grid of function derivative values at
            the points where the integration is provided.

 EXAMPLES:


 REFERENCES:

   SAND79-2374 , DEPAC - Design of a User Oriented Package of ODE
                         Solvers.

   "Solving Ordinary Differential Equations with ODE, STEP, and INTRP",
       by L. F. Shampine and M. K. Gordon, SLA-73-1060.

    SLATEC Common Mathematical Library, Version 4.1, July 1993
    a comprehensive software library containing over
    1400 general purpose mathematical and statistical routines
    written in Fortran 77.  (http://www.netlib.org/slatec/)


 MODIFICATION HISTORY:
    Fix bug in TSTOP keyword, 09 May 2002, CM


  $Id: ddeabm.pro,v 1.13 2002/05/09 23:04:47 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\ddeabm.pro)


DEBUG

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

 PURPOSE:
       debugging of IDL routines

 CATEGORY:
       PROG_TOOLS

 CALLING SEQUENCE:
       DEBUG, version_string, file=filename

 INPUTS:
       version_string:   string containing info
       about the version an author of a routine

 OPTIONAL INPUTS:
       filename: output file for debug info
       (only on the first call of debug during an IDL session)

 OUTPUTS:

 SIDE EFFECTS:
       if called first time it creates the sysvar !debug with 2 tags:
       !debug.flag and !debug.file
       on next calls it controlls the output of the version
       string to screen and/or file:
       !debug.flag = 00000(0x00) : no output
                   = 00001(0x01) : screen
                   = 00010(0x02) : + systime
                   = 00100(0x04) : + calling routine
                   = 01000(0x08) : + file
       any combination possible

 EXAMPLE:
       debug, file='test.txt'
       !debug.flag=4
       ........
       debug, '1.11 T.B. 1997-JAN-1'

 REVISION HISTORY:
       Written         Franz Rohrer, June 1997
       Corrected
       Revised         Theo Brauers, Sep 1997
                       Theo Brauers, Oct 1997
                       !debug is struct

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\debug.pro)


DECOMPOSE_STRUCTURE

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

 PURPOSE:
	This function decomposes a structure into its single elements.

 CATEGORY:
	PROG_TOOLS

 CALLING SEQUENCE:
	result = decompose_structure(struc)

 INPUTS:
	struc: Any structure

 OPTIONAL INPUTS:
	pointer: This argument is for internal use only.

 OUTPUTS:
	This function returns a decomposed structure with the following tags:
		   NUM             LONG      --> running number
		   TN              STRING    --> tag name
		   VAL             POINTER   --> pointer to tag value
		   ROOT            STRING    --> root of tag

 EXAMPLE:
	s = {a: 0, b: {b1: FINDGEN(10), b2: 'LOP'}}
	p = decompose_structure(s)
	HELP, p
		P               STRUCT    = ->  Array[4]

	HELP, p, /STR
		** Structure <1350828>, 6 tags, length=32, refs=1:
		   LEV             LONG                 0					--> level of tag
		   TN              STRING    'A'								--> tag name
		   VAL             POINTER   				--> pointer to tag value
		   ROOT            STRING    ''								--> root of tag

	PRINT, p.lev   -->   0 0 1 1
	PRINT, p.tn    -->   A B B1 B2
	HELP, *p[0].val   -->     INT       =        0
	HELP, *p[1].val   -->     STRUCT    = ->  Array[1]
	HELP, *p[2].val   -->     FLOAT     = Array[10]
	HELP, *p[3].val   -->     STRING    = 'LOP'

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 09.12.1999
	04.01.2000:	Header was edited
	05.01.2000:	Removed tags NUM and LINK
	12.01.2000:	A named structure is returned

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\decompose_structure.pro)


DEFAULT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		DEFAULT
 VERSION:
		4.0
 PURPOSE:
		Provides an automatic default value for nondefined parameters.
 CATEGORY:
		Programming.
 CALLING SEQUENCE:
		Result = DEFAULT( X, Y [, keywords])
 INPUTS:
	X, Y
		Arbitrary, at least one needs to be defined.
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
	/STRICT
		Switch.  If set, X is considered defined only if it is of the same type
		as Y.
	/DTYPE
		Switch.  If set, the result will be typecast into the type of Y.
		Explicit settings for LOW and/or HIGH (see below) override DTYPE.
	LOW
		Numeric value representing a valid numeric type. If given, the result
		is of type >= LOW.
	HIGH
		Numeric value representing a valid numeric type. If given, the result
		is of type <= HIGH.
 OUTPUTS:
		X if it is defined, otherwise Y.
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		All type casting is bypassed if the result is not of numeric type.
 PROCEDURE:
		Uses the functions CAST, ISNUM and TYPE from MIDL.
 MODIFICATION HISTORY:
		Created 15-JUL-1991 by Mati Meron.
		Modified 15-NOV-1993 by Mati Meron.  The keyword TYPE has been replaced
		by STRICT.  Added keywords DTYPE, LOW and HIGH.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\default.pro)


DEFAULT_CACHE_PATH

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

 PURPOSE:
   The result of this function is the platform independent path for the cache files

 CATEGORY:
   PROG_TOOLS

 CALLING SEQUENCE:
  result=default_cache_path([/alternative_path])

 KEYWORD PARAMETERS:
   alternative_path: to use the alternative cache path. It is defined as if is_write_access to /private/tmp or $HOME for WS or TEMP for PC

 OUTPUTS
   result: a string with the pathname

 MODIFICATION HISTORY:
       R. Bauer, 1998-Jun-09
       1998-Jul-02 /scratch/cache now idl_source/idl_cache
   2000-Apr-06 environment variables are handled as strupcase and strlowcase


(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\default_cache_path.pro)


DEFAULT_RANGE (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        DEFAULT_RANGE  (function)

 PURPOSE:
        Make sure a RANGE argument or keyword is a valid 
        vector with at least two elements. Can also be used
        to limit RANGE to two elements. The argument may be a string
        containing one or more numeric values delimited by almost
        any character combination (including '..' and '-'). A '-'
        will be treated as seperator if it is preceeded by a  
        digit or not followed by a digit.
        The resulting range will be sorted and spans the minimum and
        maximum of the "data" given in the argument.

 CATEGORY:
        General programming

 CALLING SEQUENCE:
        range = DEFAULT_RANGE( ARG, DEFAULT [,/LIMIT2] )

 INPUTS:
        ARG     -> The range argument or keyword as passed into 
                   a procedure or function. This can be an undefined
                   variable or a variable with 1 or more elements.
                   If ARG contains 1 element, it will be repeated 
                   to range from and to the same number.

        DEFAULT -> A 2-element vector containing the default range 
                   if ARG is undefined. This argument is mandatory
                   although it is not used if ARG contains at least 
                   1 element.

 KEYWORD PARAMETERS:
        /LIMIT2 -> Limit the resulting RANGE vector to 2 elements.
                   Default is to return *at least* 2 elements.

        RANGE   -> Limit the RANGE vector to minimum and maximum value
                   given by this keyword.

        /NOSORT -> Do not sort the output. This can be useful for
                   longitude vectors spanning the Pacific ;-)

 OUTPUTS:
        A two (or more) element vector that can be used in statements
        like WHERE(x ge RANGE[0] AND x lt RANGE[1]).

 SUBROUTINES:
        none.

 REQUIREMENTS:
        none.

 NOTES:
        This function is meant for argument checking in procedures
        or functions, hence it will generally not be called from the
        command line.

 EXAMPLE:
        ; Suppose a procedure has a keyword parameter named LATRANGE.
        ; Before we use LATRANGE in any form, we should test it:
        LATRANGE = DEFAULT_RANGE(LATRANGE,[-90.,90.])
        ; This ensures that we have at least 2 elements in LATRANGE
        ; and it defaults LATRANGE to the whole globe if nothing was 
        ; passed in the LATRANGE keyword.

 MODIFICATION HISTORY:
        mgs, 29 Sep 1998: VERSION 1.00
        mgs, 17 Nov 1998: - added string handling
                          - added RANGE and NOSORT keywords
        mgs, 23 Aug 2000: - changed copyright to open source

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\default_range.pro)


DEFP2D

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

 PURPOSE:
   This procedure is used to replace tag arrays in the defined plot structure

 CATEGORY:
   PLOT/PLOT2D

 CALLING SEQUENCE:
   defp2d,struct,name,attvalue

 INPUTS:
	struct:   The structure which should be modified
	name:     The tagname which should be replaced
   attvalue: The new values which should be added to the structure

 OUTPUTS:
   struct: The modified structure

 EXAMPLE:
   defp2d,plot,'levels',indgen(10)

 MODIFICATION HISTORY:
 	Written by:	R.Bauer (ICG-1), 5. Oct 1997

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\defp2d.pro)


DEFSUBCELL

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

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

 PURPOSE:
   Returns a default subcell suitable for plotting in.

 CALLING SEQUENCE:
   sub = defsubcell( [default] )

 DESCRIPTION: 

   DEFSUBCELL returns a "nice" subcell, useful for plotting in.  It
   gives 8% margins on the left and bottom, and 5% margins on the
   right and top.

   A set of user-defined default values can be passed in.  Any that
   are negative are replaced by this function's.

 INPUTS:

   DEFAULT - a "default" subcell.  Any elements that are negative are
             replaced by DEFSUBCELL's notion of the proper margins.
             This feature is used, for example, by SUBCELLARRAY to
             make subcells that have special margins on certain sides
             and default ones on other sides.

 OPTIONAL INPUTS:
   NONE

 INPUT KEYWORD PARAMETERS:

   NONE

 RETURNS:
   The new subcell.

 PROCEDURE:

 EXAMPLE:

 SEE ALSO:

   DEFSUBCELL, SUBCELLARRAY

 EXTERNAL SUBROUTINES:

 MODIFICATION HISTORY:
   Written, CM, 1997

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\defsubcell.pro)


DEFTYPE

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

 PURPOSE:
   This function is able to translate a variable to the same type of another variable

 CATEGORY:
   MATH

 CALLING SEQUENCE:
   Result=deftype(data_with_type,value_without_type,[/value],[/type],[/char])

 INPUTS:
   data_with_type: A variable e.g. 10.5
   value_without_type: A variable e.g. 4

 KEYWORD PARAMETERS:
   value:  if the key value is used the result is
           value_without_type with the same type as data_with_type
   type:   if the key type is used result is the integer code of type of data_with_type
   char:   same as type diffeternt is thats the result is the name of the type

 OUTPUTS:
  see KEYWORD PARAMETERS:


 EXAMPLE:
   Result=deftype(10.5,4)
   Result is 4.00000

 MODIFICATION HISTORY:
   Written by:	R.Bauer (ICG-1), Jan. 2 1997
   1997-Nov-01 nicer programcode
   1998-Mar-04 limittest for integer included
   1998-Mar-04 default is now new_value
   1999-Nov-06 help added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\deftype.pro)


DEF_COLORSYSTEM

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

 PURPOSE:
  This procedure defines the colors for the colorsystem

 CATEGORY:
   PLOT/PLOT2D

 CALLING SEQUENCE:
   def_colorsystem,[colors=colors],[start_color=start_color],[max_colors=max_colors]

 KEYWORD PARAMETERS:
   colors=colors:           the RGB color code which describe the colors
                            default comes from ct_fr2
   start_color=start_color: the beginning index of the colorsystem
                            default is 20
   max_colors=max_colors:   the number of indices belonging to the colorsystem
                            default is def_n_colors()-1

 EXAMPLE:
   def_colorsystem,start=100,max_colors=50
   erase
   cbar

 MODIFICATION HISTORY:
 	Written by:	R.Bauer (ICG-1), 1998-Jul-09
               1999-Feb-05 because of idl5.2 interpretation of !d.n_colors this constant is replaced by def_n_colors()

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\def_colorsystem.pro)


DEF_COLOR_SYSV

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

 PURPOSE:
       This procedure defines the new system variable with color indices

 CATEGORY:
       PLOT

 CALLING SEQUENCE:
       def_color_sysv

 KEYWORD PARAMETERS:
       NAME: Name of new system variable (STRING) - default: !F

 OUTPUTS:
       the new system variable which is of type structure with the tags
         .black      :0
         .red        :1
         .blue       :2
         .geen       :3
         .pink       :4
         .violett    :5
         .orange     :6
         .dark_red   :7
         .cyan       :8
         .yellow     :9
         .blue_green :10
         .white      :11

 EXAMPLE:
       def_color_sysv
       HELP, !F, /STR
       ** Structure <88963dcc>, 12 tags, length=24, refs=2:
          BLACK           INT              0
          RED             INT              1
          BLUE            INT              2
          GREEN           INT              3
          PINK            INT              4
          VIOLETT         INT              5
          ORANGE          INT              6
          DARK_RED        INT              7
          CYAN            INT              8
          YELLOW          INT              9
          BLUE_GREEN      INT             10
          WHITE           INT             11

 SIDE EFFECTS:
       A new system variable is defined

 REVISION HISTORY:
     Definition of colors written by Franz Rohrer
     Wrapper written by Frank Holland, 28. Jan. 1998
       History:
           04.11.98:   Changed color structure from anonymous into a named structure

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\def_color_sysv.pro)


DEF_INHALT_DEF

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

 PURPOSE:
  This procedure write the definition procedure inhalt_def.pro for the structure inhalt

 CATEGORY:
   DATAFILES/NETCDF

 CALLING SEQUENCE:
   def_inhalt_def

 OUTPUTS:
   This procedure write the idl Source inhalt_def.pro

 OPTIONAL OUTPUTS:
    inhalt_def: could used for debugging

 MODIFICATION HISTORY:
 	Written by:	R.Bauer (ICG-1), 1997

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\def_inhalt_def.pro)


DEF_MPLOTSTR

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

 PURPOSE:
       This function defines a structure with default settings for plot keywords

 CATEGORY:
		PLOT/MPLOT

 CALLING SEQUENCE:
		mplot_str = def_mplotstr()

 OUTPUTS:
     This function returns a structure with the tags
         .screen
         .ps
         .printer
		each of which is a structure with tags which define values for different plot keywords

 EXAMPLE:
     ms = def_mplotstr()
		HELP, ms, /STR
		** Structure <13554f8>, 3 tags, length=84, refs=1:
		   SCREEN          STRUCT    -> SCREEN Array[1]
		   PS              STRUCT    -> PS Array[1]
		   PRINTER         STRUCT    -> PRINTER Array[1]

 REVISION HISTORY:
		Written by Frank Holland, 05.11.1999

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\def_mplotstr.pro)


DEF_NCDF_DIMENSIONS_FOR_PARAMETERS

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

 PURPOSE:
   write_ncdf
   This procedure sets the diension ids for the parameters and the flags

 CATEGORY:
   DATAFILES/NETCDF

 CALLING SEQUENCE:
   def_ncdf_dimensions_for_parameters,dimensions

 INPUTS:
   file_id:      the id of the netcdf File
   dimensions:   A Structure holding parameter and flag informations
   n_parameters: n_elements of parameter tags

   e.g.:
   DIMENSIONS    STRUCT
                 TIME:       STRUCT
                             NAME            STRING    ['time']
                             SIZE            LONG      [100]
                             P_ID            LONG                -1
                             D_IDS           LONG      [-1]
                             TYPE            LONG                 5

                  N2O:       STRUCT
                             NAME            STRING    ['time']
                             SIZE            LONG      [100]
                             P_ID            LONG                -1
                             D_IDS           LONG      [-1]
                             TYPE            LONG                 4
                             FLAG            STRUCT
                                             STDEV           STRUCT
                                                             NAME            STRING    ['time']
                                                             SIZE            LONG      [100]
                                                             P_ID            LONG                -1
                                                             D_IDS           LONG      [-1]
                                                             TYPE            LONG                 5

                  TAG_NAME:   STRING    ['TIME', 'N2O']
                  SHORT_NAME: STRING    ['time', 'N2O']
                  FLAG:       STRUCT
                              N2O             STRUCT
                                              SHORT_NAME      STRING    'N2O@STDEV'
                                              TAG_NAME        STRING    'STDEV'

 OUTPUTS:
   input structure is output structure
   dimensions for flags: dimensions.(i).flag.(ii).d_ids is altered to dimensions.(i).d_ids
   DIMENSIONS    STRUCT
                 TIME:       STRUCT
                             NAME            STRING    ['time']
                             SIZE            LONG      [100]
                             P_ID            LONG                -1
                             D_IDS           LONG      [-1]
                             TYPE            LONG                 5

                  N2O:       STRUCT
                             NAME            STRING    ['time']
                             SIZE            LONG      [100]
                             P_ID            LONG                -1
                             D_IDS           LONG      [-1]
                             TYPE            LONG                 4
                             FLAG            STRUCT
                                             STDEV           STRUCT
                                                             NAME            STRING    ['time']
                                                             SIZE            LONG      [100]
                                                             P_ID            LONG                -1
                                                             D_IDS           LONG      [-1]
                                                             TYPE            LONG                 5

                  TAG_NAME:   STRING    ['TIME', 'N2O']
                  SHORT_NAME: STRING    ['time', 'N2O']
                  FLAG:       STRUCT
                              N2O             STRUCT
                                              SHORT_NAME      STRING    'N2O@STDEV'
                                              TAG_NAME        STRING    'STDEV'



 EXAMPLE:
   def_ncdf_dimensions_for_parameters,dimensions

 MODIFICATION HISTORY:
       Written by:     R.Bauer (ICG-1), 1999-Mar-02
 name wird spaeter geändert
  2000-Feb-09  added MESSAGE,'Problem with dimensions of parameter: '+dimensions.short_name[i],/info

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\def_ncdf_dimensions_for_parameters.pro)


DEF_NCDF_VARIABLE

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

 PURPOSE:
   This routine defines all netCDF parameters and flags described in the dimensions structure.

 CATEGORY:
   DATAFILES/NETCDF

 CALLING SEQUENCE:
   def_ncdf_variable,file_id,dimensions

 INPUTS:
   file_id: the ncdf_open file_id of a netCDF File
   dimensions: a structure holding informations about type size and name of a parameter
   e.g.:
   DIMENSIONS    STRUCT
                 TIME:       STRUCT
                             NAME            STRING    ['time']
                             SIZE            LONG      [100]
                             P_ID            LONG                -1
                             D_IDS           LONG      [0]
                             TYPE            LONG                 5

                  N2O:       STRUCT
                             NAME            STRING    ['time']
                             SIZE            LONG      [100]
                             P_ID            LONG                -1
                             D_IDS           LONG      [0]
                             TYPE            LONG                 4
                             FLAG            STRUCT
                                             STDEV           STRUCT
                                                             NAME            STRING    ['time']
                                                             SIZE            LONG      [100]
                                                             P_ID            LONG                -1
                                                             D_IDS           LONG      [0]
                                                             TYPE            LONG                 5

                  TAG_NAME:   STRING    ['TIME', 'N2O']
                  SHORT_NAME: STRING    ['time', 'N2O']
                  FLAG:       STRUCT
                              N2O             STRUCT
                                              SHORT_NAME      STRING    'N2O@STDEV'
                                              TAG_NAME        STRING    'STDEV'



 OUTPUTS:
   dimensions: a structure holding informations about type size and name of a parameter
      the tag P_id is altered by the real parameter ID of the netCDF File

   e.g.
   DIMENSIONS    STRUCT
                 TIME:       STRUCT
                             NAME            STRING    ['time']
                             SIZE            LONG      [100]
                             P_ID            LONG                0
                             D_IDS           LONG      [0]
                             TYPE            LONG                 5

                  N2O:       STRUCT
                             NAME            STRING    ['time']
                             SIZE            LONG      [100]
                             P_ID            LONG                1
                             D_IDS           LONG      [0]
                             TYPE            LONG                 4
                             FLAG            STRUCT
                                             STDEV           STRUCT
                                                             NAME            STRING    ['time']
                                                             SIZE            LONG      [100]
                                                             P_ID            LONG               2
                                                             D_IDS           LONG      [0]
                                                             TYPE            LONG                 5

                  TAG_NAME:   STRING    ['TIME', 'N2O']
                  SHORT_NAME: STRING    ['time', 'N2O']
                  FLAG:       STRUCT
                              N2O             STRUCT
                                              SHORT_NAME      STRING    'N2O@STDEV'
                                              TAG_NAME        STRING    'STDEV'


 EXAMPLE:
 
TIME N2O TAG_NAME SHORT_NAME
str[1]str[1]TIMEtime
N2ON2O


TIME
NAME SIZE P_ID D_IDS TYPE
time100-105


N2O
NAME SIZE P_ID D_IDS TYPE
time100-104

def_ncdf_variable,file_id,dimensions
TIME N2O TAG_NAME SHORT_NAME
str[1]str[1]TIMEtime
N2ON2O


TIME
NAME SIZE P_ID D_IDS TYPE
time100005


N2O
NAME SIZE P_ID D_IDS TYPE
time100104

MODIFICATION HISTORY: Written by: R.Bauer (ICG-1), 1999-Mar-02

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\def_ncdf_variable.pro)


DEF_N_COLORS

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

 PURPOSE:
  This function returns 256 if !d.n_colors is gt 256 else !d.n_colors

 CATEGORY:
   PLOT

 CALLING SEQUENCE:
   Result=def_n_colors()

 EXAMPLE:
   print,def_n_colors()
   256

 MODIFICATION HISTORY:
   Written by:	R.Bauer (ICG-1), 1999, Feb. 05

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\def_n_colors.pro)


DEF_PLOTSTR_SYSV

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

 PURPOSE:
       This procedure defines the new system variable with default settings for plot keywords

 CATEGORY:
		PLOT/MPLOT

 CALLING SEQUENCE:
       def_plotstr_sysv

 KEYWORD PARAMETERS:
		NAME: Name of new system variable (STRING) - default: !FH_PLOTSTR

 OUTPUTS:
       a new system variable which is of type structure with the tags
         .screen
         .printer
		each of which has subtags which define values for different plot keywords

 EXAMPLE:
       def_plotstr_sysv
		HELP, !FH_PLOTSTR, /STR
		** Structure <88963dcc>, 12 tags, length=24, refs=2:
 SIDE EFFECTS:
		A new system variable is defined

 REVISION HISTORY:
		Written by Frank Holland, 12.06.98
		History:
			04.11.98:	Changed plot structure from anonymous into a named structure

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\def_plotstr_sysv.pro)


DEF_PLXY

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

 PURPOSE:
       This procedure defines the internal communication structure for plotxy-like procedures

 CATEGORY:
	PLOT/PLOTXY

 CALLING SEQUENCE:
       def_plxy,pl_xy

 OUTPUTS:
    pl_xy.                       : The predefined structure whith the following tags:
         .i_xn:        0
         .i_yn:        0
         .n_xn:        1
         .n_yn:        1
         .charsize:    0.
         .title_charsize :0.
         .c_charsize:  0.
         .framethick:  0.
         .thick:       0.
         .factor:      0.
         .xticklen:    0.
         .yticklen:    0.
         .zticklen:    0.

 EXAMPLE:
       def_plxy, pl_xy

 MODIFICATION HISTORY:
 	Written by:	Franz Rohrer September 1997

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\def_plxy.pro)


DEF_SIZES

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

 PURPOSE:
      definition of charsize and thick for plotxy-type procedures

 CATEGORY:
       PLOT/PLOTXY

 CALLING SEQUENCE:
       def_sizes,plot,pl_xy

 INPUTS:
       plot  : structure with plot-options (see pl_init.pro for details)

 OUTPUTS:
       pl_xy : structure with parameters for plotxy as defined by def_plxy

 EXAMPLE:
   def_sizes,plot,pl_xy

 MODIFICATION HISTORY:
       Written         Franz Rohrer, September 1997
       Corrected
         9.10.1997 added that ticklength would not be reduced if it's set to make gridlines
        29.10.1997 "IF strupcase(!version.os) EQ 'AIX' THEN corr = 0.75"
        11.01.1998 plot.charsize_norm_factor zur Normierung der Textbreite eingeführt, wird in plotinit berechnet
        03.06.00 : plot.spalten+plot.zeilen nach plot.columns+plot.rows umbenannt

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\def_sizes.pro)


DEF_VALID_FOR_PARAM

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

 PURPOSE:
   This function returns the valid information arrays for the ICG data_structure

 CATEGORY:
   DATAFILES

 CALLING SEQUENCE:
   Result=def_valid_for_param(param,quality, [valid_min=valid_min], [valid_max=valid_max], [fill_value=fill_value_intern], [missing_value=missing_value_intern], [struct_name=struct_name])

 INPUTS:
  param:   the data of a parameter
  quality: the quality flag vector describing quality of param

 KEYWORD PARAMETERS:
   valid_min:     if also valid_max is set the valid data range is from valid_min to valid_max
   valid_max:     if also valid_min is set the valid data range is from valid_min to valid_max
                  if no data fits in this range a message is given and valid from 0:*
   fill_value:    if set indicator value for setting fill valuess
   missing_value: if set indicator value for setting missing values
   struct_name:  name of the resulting structure by count_name(struct_name)

 PROCEDURE:
  if valid eq -1 then plot_min and plot_max = !values.f_nan

 EXAMPLE:
  fill_value=-999.9
  missing_value=-999.8
  param=findgen(10)
  param[1:2]=fill_value
  param[6:9]=missing_value
  result=def_valid_for_param(param,fill_value=fill_value, missing_value=missing_value)
  help,result,/str
  ** Structure <1357cf8>, 5 tags, length=48, refs=1:
      PLOT_MIN        FLOAT          0.000000
      PLOT_MAX        FLOAT           5.00000
      VALID           LONG      Array[4]
      FILLED          LONG      Array[2]
      MISSED          LONG      Array[4]

 
PLOT_MIN PLOT_MAX VALID FILLED MISSED
0.0000005.00000016
327
48
59

with QUALITY: fill_value=-999.9 missing_value=-999.8 param=findgen(10) quality=lonarr(10) quality[3:4]=32 param[1:2]=fill_value param[6:9]=missing_value result=def_valid_for_param(param,quality, fill_value=fill_value, missing_value=missing_value) help,result,/str ** Structure <136cc18>, 5 tags, length=40, refs=1: PLOT_MIN FLOAT 0.000000 PLOT_MAX FLOAT 5.00000 VALID LONG Array[2] FILLED LONG Array[2] MISSED LONG Array[4]
PLOT_MIN PLOT_MAX VALID FILLED MISSED
0.0000005.00000016
527
8
9

MODIFICATION HISTORY: Written by: R.Bauer (ICG-1), 1999-Mar-02 1999-05-11 all where function by double 1999-06-15 if all data are missing values now valid is -1 1999-06-24 because of an unknow WS aix idl error line 196 is changed now first valid is created in the structure and afterwards other variables the error happens in the routine where def_valid_for_param was called from the syntax was: INVALID DESCRIPTOR 1999-09-28 bug removed if nothing is valid then valid is now -1 2000-01-12 bug removed for a = {q: {param: 2., quality: 0, fill_value: -12345.}}. Element [0] is valid 2000-04-11 bug removed if fill_value or missing_value and param is of type string

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\def_valid_for_param.pro)


DEF_VALID_TAGNAME

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

 PURPOSE:
   This function translates short_names to tag_names

 CATEGORY:
   DATAFILES

 CALLING SEQUENCE:
   Result=def_valid_tagname(short_name,[consideration=consideration])

 INPUTS:
   short_name: the short name of a parameter

 KEYWORD PARAMETERS::
   consideration: beware of duplicate definitions

 EXAMPLE:
  print,def_valid_tag_name('test 1')
  TEST_1
  print,def_valid_tagname('test 1',consideration='test_1')
  TEST_1A

 MODIFICATION HISTORY:
       Written by:     R.Bauer (ICG-1), 1999-Mar-02

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\def_valid_tagname.pro)


DEGLITCH

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		DEGLITCH
 VERSION:
		4.0
 PURPOSE:
		Replaces exceptional array elements by the average of their neighbors.
 CATEGORY:
		Array Function.
 CALLING SEQUENCE:
		Result = DEGLITCH( ARR, THRESH [, keywords])
 INPUTS:
	ARR
		Array, numeric, otherwise arbitrary.
	THRESH
		Threshold value for element replacement.  Must be > 1.
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
	/DOWN
		Switch.  If set the correction is downward, i.e. elements which are too
		big (in absolute value) are replaced.  This is the default.
	/UP
		Switch.  If set the correction is upward, i.e. elements which are too
		small (in absolute value) are replaced.
	COUNT
		Optional output, see below.
 OUTPUTS:
		Returns the corrected array, i.e. an array of the same format as ARR,
		in which all the exceptional element have been replaced by the average
		of their neighbors.
 OPTIONAL OUTPUT PARAMETERS:
	COUNT
		The name of the variable to receive the number of exceptional elements.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		None.
 PROCEDURE:
		Compares the absolute values of the original array and the one obtained
		by neighborhood averaging.  Locates exceptions and replaces them by
		neighborhood average.  Uses FPU_FIX, NEIGHBORS and ONE_OF from MIDL.
 MODIFICATION HISTORY:
		Created 30-MARCH-1994 by Mati Meron.
		Modified 10-SEP-1998 by Mati Meron.  Underflow filtering added.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\deglitch.pro)


DEGRADE

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

 PURPOSE:      degrade image resolution by a factor of two

 USEAGE:       result=degrade(array)
 
 INPUT:   
   array       an image array of dimension NX x NY, where both nx
               ny are divisible by 2. If nx or ny are not divisible by
               2 a subimage is extracted that leaves off the last row 
               or column and is divisible by 2 in both directions.

 KEYWORD INPUT:

   min         if set the returned value for each superpixel is the min
               of each of the four subpixels

   max         if set the returned value for each superpixel is the max
               of each of the four subpixels

 output:
   result      image array of dimension NX/2 x NY/2 composed of 2 x 2 
               superpixel averages of u (except if MIN or MAX keyword is
               set, see above)

 AUTHOR:       Paul Ricchiazzi                        26 May 95
               Institute for Computational Earth System Science
               University of California, Santa Barbara 

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\degrade.pro)


DELCHR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DELCHR
 PURPOSE:
       Delete all occurrences of a character from a text string.
 CATEGORY:
 CALLING SEQUENCE:
       new = delchr(old, char)
 INPUTS:
       old = original text string.     in
       char = character to delete.     in
 KEYWORD PARAMETERS:
 OUTPUTS:
       new = resulting string.         out
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner.  5 Jul, 1988.
       Johns Hopkins Applied Physics Lab.
       RES 11 Sep, 1989 --- converted to SUN.
       R. Sterner, 27 Jan, 1993 --- dropped reference to array.

 Copyright (C) 1988, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\delchr.pro)


DELETE_FROM_PATH

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

 PURPOSE:
   This function deletes entries from the !path setting of IDL

 CATEGORY:
   PROG_TOOLS

 CALLING SEQUENCE:
   DELETE_FROM_PATH, str

 INPUTS:
   Str:  Input string, name of path entry to be deleted

 EXAMPLE:
   PRINT, !path
   DELETE_FORM_PATH, 'examples'
   PRINT, !path

 MODIFICATION HISTORY:
   Written by: Theo Brauers, 1999-JAN

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\delete_from_path.pro)


DELETE_TAG

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

 USERLEVEL:
   TOPLEVEL

 NAME:
    delete_tag

 PURPOSE:
   This functions deletes a tag in a structure, even within substructures.

 CATEGORY:
   PROG_TOOLS/STRUCTURES

 CALLING SEQUENCE:
   result = delete_tag(struct, tagname, [sub_structure = sub_structure])

 INPUTS:
   struct: the structure in which to delete the tag
   tagname: the name of the tag to be deleted (scalar or array),
            wildcards '*' are possible (see examples).

 KEYWORD PARAMETERS:
   sub_structure: to define a sub structure within struct where to delete the tag
   /ALL: If set all tags which agree to tagname will be deleted starting from the
         main level or the level 'sub_structure' downwards.

 OUTPUTS:
   This function returns a structure with some tags deleted.

 EXAMPLE:
   d = {A: 1, B: {B1: 0, B2: 1}, C: {B1: 0, B2: 1}}

   result = delete_tag(d, 'B')
   help, result, /str
   ** Structure <1342678>, 2 tags, length=8, refs=1:
   A               INT              1
   C               STRUCT    ->  Array[1]

   result = delete_tag(d, ['B*'], SUB = 'C')
   help, result, /str
   ** Structure <13694a8>, 2 tags, length=6, refs=1:
   A               INT              1
   B               STRUCT    ->  Array[1]

   result = delete_tag(d, '*B1', SUB = ['B', 'C'])
   help, result.b, /str
   ** Structure <1331be8>, 1 tags, length=2, refs=1:
   B2              INT              1

   result = delete_tag(d, ['B1', 'B2'], /ALL)
   help, result, /str
   ** Structure <170fac8>, 1 tags, length=2, refs=1:
   A               INT              1

   help,(delete_tag(d,'b1',sub_structure='B')).b,/str
   B2              INT              1

   help,(delete_tag(d,'b1',sub_structure='B')).c,/str
   ** Structure <1333618>, 2 tags, length=4, refs=1:
   B1              INT              0
   B2              INT              1

   help,(delete_tag(d,'*',sub_structure='B')),/str
   ** Structure <133b2d8>, 2 tags, length=6, refs=1:
   A               INT              1
   C               STRUCT    ->  Array[1]

   help,(delete_tag(d,'*',sub_structure='B',/sort)),/str
   ** Structure , 2 tags, length=6, refs=1:
   A               INT              1
   C               STRUCT    ->  Array[1]

   help,(delete_tag(d,sub_structure=['B','A'])),/str
   ** Structure <132fe78>, 2 tags, length=6, refs=1:
   A               INT              1
   C               STRUCT    ->  Array[1]

   help,(delete_tag(d,sub_structure=['B','C'])),/str
   ** Structure <1333288>, 1 tags, length=2, refs=1:
   A               INT              1

   help,(delete_tag(d,['B1','B2'],sub_structure=['B','C'])),/str
   ** Structure <46a9498>, 1 tags, length=2, refs=1:
   A               INT              1

   d = {ABRA: {B1: 0, B2: 1}, ABRA2B: {B1: 0, B2: 1}, ABRA3B: {B1: 0, B2: 1}}

   result=delete_tag(d,'abra')
   help,result,/str
   ** Structure <1365a48>, 2 tags, length=8, refs=1:
   ABRA2B          STRUCT    ->  Array[1]
   ABRA3B          STRUCT    ->  Array[1]

   result=delete_tag(d,'abra*')
   help,result,/str
   RESULT          INT       =       -1

   result=delete_tag(d,'abra?B')
   help,result,/str

   ** Structure <1364358>, 1 tags, length=4, refs=1:
   ABRA            STRUCT    ->  Array[1]

   d = {ABRA: {B1: 0, B2: {A:1}}, ABRA2B: {B1: 0, B2: {A:1}}, ABRA3B: {B1: 0, B2: {A:1}}}
   result=delete_tag(d,'A',sub_structure='abra.b2')
   help,result.abra,/str
   ** Structure <1365c68>, 1 tags, length=2, refs=2:
   B1              INT              0



 MODIFICATION HISTORY:
       Written by:     R.Bauer (ICG-1), 2000-Jan-05
       14.03.2000: Header edited

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\delete_tag.pro)


DELETE_TAG_FH

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

 PURPOSE:
	This function can be used to delete tags within a substructure of a given structure

 CATEGORY:
	PROG_TOOLS/STRUCTURES

 CALLING SEQUENCE:
	result = delete_tag(struct, tag_name)

 INPUTS:
	struct: Input structure.
	tag_name: Name of tag or array of tag names to be deleted from struct (STRING).

 KEYWORD PARAMETERS:
	SUB_STR = sub_str: Name of the substructure under which the tags are deletetd.

 OUTPUTS:
	This function returns a structure were the tags 'tag_name' have been removed.

 EXAMPLE:
	s0 = {H2O: {param: 4, units: 'mbar'}, O3: {param: 17, units: 'ppb'}}

	s1 = delete_tag(s0, 'H2O')
	HELP, s1, /STR
		** Structure , 1 tags, length=12, refs=1:
   		O3              STRUCT    ->  Array[1]
	HELP, s1.o3, /STR
		** Structure , 2 tags, length=12, refs=2:
		   PARAM           INT             17
		   UNITS           STRING    'ppb'

	s1 = delete_tag(s0, 'units')
	HELP, s1, /STR
		** Structure , 2 tags, length=4, refs=1:
		   H2O             STRUCT    ->  Array[1]
		   O3              STRUCT    ->  Array[1]
	HELP, s1.o3, /STR
		** Structure , 1 tags, length=2, refs=2:
		   PARAM           INT             17

	s1 = delete_tag(s0, 'units', SUB_STR = 'O3')
	HELP, s1.o3, /STR
		** Structure , 1 tags, length=2, refs=2:
		   PARAM           INT             17
	HELP, s1.h2o, /STR
		** Structure , 2 tags, length=12, refs=2:
		   PARAM           INT              4
		   UNITS           STRING    'mbar'

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 05.01.2000
	13.03.2000:	Header edited

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\delete_tag_fh.pro)


DELLOG

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

 PURPOSE:
  dummy procedure for the one defined by VMS idl

 CATEGORY:
   CASE_TOOLS

 CALLING SEQUENCE:
   dellog,a

 MODIFICATION HISTORY:
 R.Bauer 1998-Jul-24

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\dellog.pro)


DEL_FILE

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

 PURPOSE:
   This procedure deletes a file or files

 CATEGORY:
   PROG_TOOLS

 CALLING SEQUENCE:
   del_file,file

 INPUTS:
   file: the file(s) which should be deleted

 EXAMPLE:
   del_file,'test.dat'

 MODIFICATION HISTORY:
   Written by: R.Bauer (ICG-1), 1998-Jun-07
   1998-12-16 message added if file does not exist
   1999-09-13 get_ownership added
   2000-2-17 keyword verbose added T.B.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\del_file.pro)


DEL_TAG

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

 PURPOSE:
	This function deletes a tag from a given structure.
	It also handels an array of tags.

 CATEGORY:
	PROG_TOOLS/STRUCTURES

 CALLING SEQUENCE:
	x = del_tag(str, tag)

 INPUTS:
	str: variable name of structure
	tag: name of tag or array of tag names to be deleted (STRING)

 KEYWORD PARAMETERS:
	RETURN_ON_LAST_TAG_DELETED: Defines a variable which will be returned if the only tag
								in str is deleted.
	NAME: New name for a named structure (must not exist already)

 EXAMPLE:
	as = {Bsp1, a:0, b:'asd'}
	bs = del_tag(as, 'b', NAME = 'Bsp3')
	HELP, bs, /STR :
		** Structure BSP3, 1 tags, length=2:
		   A               INT              0

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 28. Jan. 98.
	29.09.98:	Debug statement deleted.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\del_tag.pro)


DEL_TAG2

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

 PURPOSE:
	This function deletes a tag from a given structure.
	It also handels an array of tags and/or 1-dim array of structures.

 CATEGORY:
	PROG_TOOLS/STRUCTURES

 CALLING SEQUENCE:
	x = del_tag2(str, tag)

 INPUTS:
	str: variable name of structure
	tag: name of tag or array of tag names to be deleted (STRING)

 KEYWORD PARAMETERS:
	RETURN_ON_LAST_TAG_DELETED: Defines a variable which will be returned if the only tag
								in str is deleted.
	NAME: New name for a named structure (must not exist already)

 OPTIONAL OUTPUTS:
	status: Status information 	=0: every thing worked fine;
								=1: something went wrong (see messages on screen)

 EXAMPLE:
	as = {Bsp1, a:0, b:'asd'}
	bs = del_tag2(as, 'b', NAME = 'Bsp3')
	HELP, bs, /STR :
		** Structure BSP3, 1 tags, length=2:
		   A               INT              0

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 11. Apr. 98.
	This program is based on the procedure del_tag.pro but provides additional features
	15.11.98:	call to debug deleted

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\del_tag2.pro)


DEMO_XYOUTS_AUTO

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

 PURPOSE:
   This routine shows the capabilities of xyouts_auto

 CATEGORY:
   EXAMPLES

 CALLING SEQUENCE:
   demo_xyouts_auto

 MODIFICATION HISTORY:
	Written by: Frank Holland, 29.10.1999

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\examples\demo_xyouts_auto.pro)


DENS2D

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE     dens2d,x,y,g,nbins=nbins,xrange=xrange,yrange=yrange,$
               title=title,xtitle=xtitle,ytitle=ytitle,psym=psym,$
               grid=grid,tvim=tvim,scale=scale,contur=contur


 PURPOSE     Compute and/or display the density function of a 2-d scatter
             of points with coordinate x and y

 INPUTS:
     x       array of values
     y       array of values (same size as x)

 OUTPUTS:    
  g          2-d histogram array of size nbins(0) x nbins(1)

 OPTIONAL INPUTS (keyword parameters):
  nbins      1 or 2 element vector, number of bins in x and y direction
             default is (20,20)
  xrange     2 element vector, binning range in x direction
  yrange     2 element vector, binning range in y direction
  charsize   character size
  title      plot title
  xtitle     x axis label
  ytitle     y axis label
  psym       symbol used for scatter plot, if negative don't plot points
  grid       if set, show binning grid 
  contur     if set, draw in density contours (default)
  confill    if set, use CONFILL is used to draw contours
  tvim       if set, use TVIM to display the point density function
             if tvim is set to 1 image is smoothed
             if tvim is set to 2 image is not smoothed 
  scale      if set, draw in a color scale      
                 0=> no color scale
                 1=> regular color scale (default)
                 2=> stepped color scale

 EXAMPLE
     x=randomn(is,2000)
     y=4*randomn(is,2000) + x^3
     dens2d,x,y,g,/tvim,/grid

     dens2d,x,y,/tvim,/contur

     dens2d,x,y,psym=-1,/contur

 AUTHOR:     Paul Ricchiazzi,  Earth Space Research Group, sep92

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\dens2d.pro)


DEPENDENCES_OF_FAMILY

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

 PURPOSE:
	This function returns a structure of keys depending on !version.os_family

 CATEGORY:
   PROG_TOOLS

 CALLING SEQUENCE:
   Result=dependences_of_family( )

 OUTPUTS:
  This function returns a structure:
    slash:               The platform depended slash or back slash
    path_separator:      The platform depended : od ;
    two_path_backwards:  The platform depended '../../'  od ...

 EXAMPLE:
   result=dependences_of_family()

 MODIFICATION HISTORY:
 	Written by:	R.Bauer (ICG-1), 1998-Jun-27

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\dependences_of_family.pro)


DEPENDENCY

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		DEPENDENCY
 VERSION:
		4.2
 PURPOSE:
		Locating routines dependent on a given routine.
 CATEGORY:
		Programming utility.
 CALLING SEQUENCE:
		Result = DEPENDENCY( RNAME [, keywords])
 INPUTS:
	RNAME
		Character value resolving to a routine name (no extension).
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
	/GLOBAL
		Switch.  If set, the search is global, default is search in current
		directory.
	DIRPATH
		Directory path, for internal use only (recursive calls).
	NFOUND
		Optional output, see below.
 OUTPUTS:
		Returns a list of addresses for all the routines which are calling
		RNAME.  If none are found, returns null string.
 OPTIONAL OUTPUT PARAMETERS:
	NFOUND
		Returns the number of files satisfying the search criterion.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		None.
 PROCEDURE:
		Straightforward.  Calls itself recursively.  Also calls DEFAULT, SDEP,
		STREQ, STRPARSE_MM and STRVALID_MM, from MIDL.
 MODIFICATION HISTORY:
		Created 10-AUG-2001 by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\dependency.pro)


DES_INH

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

 PURPOSE:
	The include of des_inh will transform the tagnames of the structure inhalt
	to variables.

 CATEGORY:
	DATAFILES/NETCDF

 CALLING SEQUENCE:
   @des_inh

 OUTPUTS:
	all in Structure INHALT defined tagnames as variables


 EXAMPLE:
   ncdf_gr,file='test.nc',name='sin2',inhalr=inhalt
	@des_inh

 MODIFICATION HISTORY:
 	Written by:	R.Bauer (ICG-1), 1996
               R.Bauer Feb.,  26, 1997 areal in type umbenannt
               R.Bauer March, 17, 1997 valid_last_index eingefuegt
               R.Bauer March, 19, 1997 param_stdev, param_accuracy,param_detection_limit,param_high_err,param_low_err

               R.Bauer / F.Rohrer  June, 6, 1997 downgrade to idl 3.6.1
 1998-Jun-30 strmid removed
               R.Bauer 1998-11-16 alt_inhalt_def instead of inhalt_def

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\des_inh.pro)


DETAB

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DETAB
 PURPOSE:
       Replace tab characters by spaces.
 CATEGORY:
 CALLING SEQUENCE:
       out = detab(in)
 INPUTS:
       in = input text string.              in
 KEYWORD PARAMETERS:
       Keywords:
         TAB=tb  number of spaces per tab (def=8).
 OUTPUTS:
       out = processed output text string.  out
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 1995 Nov 3

 Copyright (C) 1995, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\detab.pro)


DIAGOARR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		DIAGOARR
 VERSION
		4.0
 PURPOSE:
		Creates a diagonal square matrix with the elements of a given vector on
		the diagonal.
 CATEGORY:
		Array Manipulation.
 CALLING SEQUENCE:
		Result = DIAGOARR(VEC)
 INPUTS:
	VEC
		Vector.
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
		None.
 OUTPUTS:
		Return a square N*N (N is the vector's dimension) matrix, with the
		elements of VEC on the diagonal and zeroes elsewhere.
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		None.
 PROCEDURE:
		Straightforward.  Calls TYPE from MIDL.
 MODIFICATION HISTORY:
		Created 20-MAY-1993 by Mati Meron.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\diagoarr.pro)


DIAGOVEC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		DIAGOVEC
 VERSION:
		4.0
 PURPOSE:
		Extracts the diagonal of a square matrix as a vector.
 CATEGORY:
		Array Manipulation.
 CALLING SEQUENCE:
		Result = DIAGOVEC(ARR)
 INPUTS:
	ARR
		Array, 2-dimensional, square (a scalar is considered a 1*1 matrix).
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
		None.
 OUTPUTS:
		If ARR is a square matrix, returns the diagonal as a vector, else
		generates an error message.
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		None.
 PROCEDURE:
		Straightforward.
 MODIFICATION HISTORY:
		Created 20-DEC-1991 by Mati Meron.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
		Modified 25-NOV-2001 by Mati Meron.  Added scalar handling capability.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\diagovec.pro)


DIALOG_CHANGEDIR

[Previous Routine] [Next Routine] [List of Routines]
 USERLEVEL:
   TOPLEVEL

 NAME:
   dialog_changedir

 PURPOSE:
   This function provides a widget directory change

 CATEGORY:
   PROG_TOOLS/FILES

 CALLING SEQUENCE:
   new = DIALOG_CHANGEDIR( [OLDDIR=old] [, /VERBOSE])

 KEYWORD PARAMETERS:
   VERBOSE:    print messages
   OLDDIR:     if set to named variable the previous dir is returned

 OUTPUTS:
   This function returns the selected directory

 EXAMPLE:

 MODIFICATION HISTORY:
   Written by: Theo Brauers, 1999-FEB-25

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\dialog_changedir.pro)


DIALOG_PSSETUP

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

 PURPOSE:
	This function displays a widget to interactively choose the setting for the ps device.
	(Wrapper around the ps_form routine by Craig B. Markwardt)

 CATEGORY:
	PLOT

 CALLING SEQUENCE:
	Result = Dialog_PSSetup(ps_config [,LOCALDEFAULT = local_config] [,CANCEL = canceled] [,/QUIET] )

 OPTIONAL INPUTS:
	ps_config:	structure with a default configuration for the PS device.
					For information about this structure run the routine and set
					ps_config to a named variable.

 KEYWORD PARAMETERS:
	LOCALDEFAULT = local_config: structure with a 2nd default configuration ('local') for the PS device.
	CANCEL = canceled	: 				Set to 1 if dialog was closed with CANCEL button.
	/QUIET:								Don't show the widget; rather return the default ps configuration
	PSFILE = psfile:					Name of the ps file.

 OUTPUTS:
	ps_config:	structure with the configuration of the PS device. This structure
					can be passed into the DEVICE procedure via the _EXTRA keyword.

 EXAMPLE:
		create = Dialog_PSSetup(ps_config, CANCEL = canceled)
		IF NOT canceled THEN HELP, ps_config, /STR

 MODIFICATION HISTORY:
	This routine is a wrapper around the ps_form routine by Craig B. Markwardt and David Fanning
 	Written by:	Frank Holland, 13.11.98
	17.11.98:	QUIET keyword enabled (bug in PS_FORM was fixed by CM)
					Keyword handling improved
	17.02.99:	Changed the header

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\dialog_pssetup.pro)


DIF

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		DIF
 VERSION:
		4.1
 PURPOSE:
		Calculates finite differences for 1D vectors.
 CATEGORY:
		Mathematical, general.
 CALLING SEQUENCE:
		Result = DIF( VEC [, ORD] [, keywords])
 INPUTS:
	VEC
		1-D numeric array (a scalar may be used and ti is treated as a vector
		with length of 1.
 OPTIONAL INPUT PARAMETERS:
	ORD
		The order of the difference.  Default value is 1.
 KEYWORD PARAMETERS:
	/BACKWARD
		Switch.  If set, backward difference is performed, i.e.
		Result[n] = VEC[n] - VEC[n-1].  This is also the default.
	/FORWARD
		Switch.  If set, forward difference is performed, i.e.
		Result[n] = VEC[n+1] - VEC[n].
	/CENTERED
		Switch.  If set, centered difference is performed, i.e.
		Result[n] = (VEC[n+1] - VEC[n-1])/2.

		Note:  Only one of BACKWARD, FORWARD and CENTERED may be set at any
		given call.

	/EDGE_EXTEND
		Switch.  If set, the "beyond the edge" elements which are needed for
		the differences are set equal to the appropriate edge elements.  The
		default operation is to set them to 0.
	/CLIP
		Switch.  If set, the elements (within ORD from either edge) for which
		there is not enough information to determine the result, are set to 0.
 OUTPUTS:
		Returns the difference vector for VEC, of a type determined by the
		keywords.
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		As mentioned above, Only one of BACKWARD/FORWARD/CENTERED may be used.
 PROCEDURE:
		Straightforward.  Calls DEFAULT, ISNUM and ONE_OF from MIDL.
 MODIFICATION HISTORY:
		Created 15-APR-2001 by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\dif.pro)


DIGITIZE

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:    digitize

 PURPOSE:    digitize hardcopy graphical information.

 USEAGE:     digitize,x,y

 INPUT:      none

 KEYWORD INPUT:
   xr        x axis range of hardcopy plot, prompted for if not supplied
   yr        y axis range of hardcopy plot, prompted for if not supplied

 OUTPUT:
   x         vector of x coordinate values
   y         vector of y coordinate values


 PROCEDURE:  1.  make a photo copy of the graph  on tranparency film.

             2.  IDL> DIGITIZE,x,y,xr=xr,yr=yr
                 where xr and yr are the x and y axis range. 

             3.  align the hard copy graph onto the axis drawn by DIGITIZE
                 and use scotch tape to stick the film onto your screen

             4.  click with LMB on the axis end points (will prompt)

             5.  trace over the plot with cursor, LMB adds points, MMB
                 erases points and RMB exits the program

             NOTE: Because the outer glass surface of the screen is not
                   on the same plane as the displayed image their is a 
                   slight parallax effect between the tranparency and the
                   DIGITIZE grid.  The parallax error is minimized by
                   keeping your line of sight normal to the screen.
  
 EXAMPLE:    
             digitize,x,y        ; try it
             plot,x,y

 REVISIONS:

  author:  Paul Ricchiazzi                            sep93
           Institute for Computational Earth System Science
           University of California, Santa Barbara

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\digitize.pro)


DIG_LES

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

 PURPOSE:
       reads ascii-files with 3 columns of data (as made by digitise.exe)

 CATEGORY:
       DATAFILES/FILE

 CALLING SEQUENCE:
       dig_les,file,x,y,z

 INPUTS:
       file: name of ascii inputfile

 OUTPUTS:
       x,y,z : data vectors

 KEYWORD PARAMETERS:
       skip: skip lines 1 to value(skip)

 EXAMPLE:
       dig_les,'test.txt',x,y,z,skip=1

 REVISION HISTORY:
       Written         Franz Rohrer, May 1997
       Corrected       FR 12.08.1998

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\dig_les.pro)


DIR

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

 PURPOSE:
       Simple procedure that can be executed within an interactive session of IDL to print
       the filesystem contents of the current working directory to the output log.

 CATEGORY:
       Utilities

 CALLING SEQUENCE:
       dir

 INPUT PARAMETERS:
       None.

 KEYWORD PARAMETERS:
       None.

 OUTPUTS:
       None.

 COMMON BLOCKS:
       None.

 MODIFICATION HISTORY:
       Written by: AEB, 4/03.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\CODEBANK\dir.pro)


DIR2HTMLFILE

[Previous Routine] [Next Routine] [List of Routines]
 USERLEVEL:
   TOPLEVEL

 NAME:
   dir2htmlfile

 PURPOSE:
   writes the informations about a directory to a html file

 CATEGORY:
   PROG_TOOLS/HTML

 CALLING SEQUENCE:
   Result=DIR2HTMLFILE(Dirname)

 INPUTS:
   dirname : directory name or string array of dir-names to be searched for

 KEYWORD PARAMETERS:
   HTMLFILE: a name for the html file ( default: 'dir2html.html' )

 OUTPUTS:
   This function returns the names of the htmlfiles with path.

 EXAMPLE:
     x = dir2htmlfile( ['/home3/ich388','/home3/ich388/IDL'] $
    , CAPTION='test', HTMLFILE='a.html', INFO='info' $
    , /FIXED, /SMALL, ALIGN=0.5 )

 MODIFICATION HISTORY:
   Written by:       Theo Brauers, Marsy Lisken  july 1998
                     R.Bauer bug with no write access removed

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\dir2htmlfile.pro)


DIR2HTMLTABLE

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

 PURPOSE:
   writes the informations about the current directory to a html table

 CATEGORY:
   PROG_TOOLS/HTML

 CALLING SEQUENCE:
   Result = DIR2HTMLTABLE( )

 OPTIONAL INPUTS:
   Search:     Search pattern for findfile, if not given *.* is assumed

 KEYWORD PARAMETERS:
   EXCLUDE:   string array of file search patterns to be excluded
                   (in lowercase characters)
   INCLUDE:   string array of file search patterns to be included
                   (only these files will be considered for search)
   HTMLFILE:  a name for the html file ( default: 'dir2html.html' )
                   (written later in dir2htmlfile)
   REVERSE:   if keyword set the order of files will be reversed
   MIXEDCASE: if keyword set no forcing to lower case is done
   LAST_EXTENSION: if keyword set only last extendion is separated

 OUTPUTS:
   This routines returns the html code for a directory table

 EXAMPLE:
   x = dir2htmltable('a*.*', EXCLUDE='*.bak', /FIXED, /SMALL)

 MODIFICATION HISTORY:
   Written by:         Theo Brauers / Marsy Lisken  july 1998
   modified by         Franz Rohrer, Sep98, reverse keyword included
   Revised:            Theo Brauers Sep 1998
 2000-05-23 : last_extension added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\dir2htmltable.pro)


DIRMEM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DIRMEM
 PURPOSE:
       Update a directory list for easy access.
 CATEGORY:
 CALLING SEQUENCE:
       out_list = dirmem( entry)
 INPUTS:
       entry = potential new list entry.                 in
         Directory followed by an optional alias:
         /users/images/lunar/gif  Moon GIFS
 KEYWORD PARAMETERS:
       Keywords:
         READ=rf  Initialization text file: one directory/alias
           pair per line.  Comments allowed (start with * or ;).
           Over-rides any given list.
         WRITE=wf File to save updated list in.
         LIST=lst Text array with dir/alias pairs.  In/out.
         /ALIAS  Means use aliases for out_list (display list).
           Default is use directories.  ALIAS=2 means use both.
        MAX_ENTRIES=m  Max size of list.  Def=size of init file
          or 5 if that is not available.
 OUTPUTS:
       out_list = Display list.                          out
         Directories, aliases, or both.
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 1994 Feb 14

 Copyright (C) 1994, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dirmem.pro)


DIRTREE2HTMLFILE

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

 PURPOSE:
   This procedure writes a directory tree to a html tree

 CATEGORY:
   PROG_TOOLS/STRUCTURES

 CALLING SEQUENCE:
  dirtree2htmlfile,file_name,path,[level=level]

 INPUTS:
   file_name: the name of the file to write to
   path: the start directory for get_dir_tree

 KEYWORD PARAMETERS:
  _extra: to add keywords to get_dir_tree


 EXAMPLE:
  dirtree2htmlfile,'S:\links\daten\experiments\stream1998.html','S:\links\daten\experiments\stream1998',level=10


 MODIFICATION HISTORY:
       Written by:     R.Bauer (ICG-1), 2000-MAR-05

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\dirtree2htmlfile.pro)


DIRTREEARRAY2HTML

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

 PURPOSE:
   makes the html-table of a directory tree

 CATEGORY:
   PROG_TOOLS/HTML

 CALLING SEQUENCE:
   array=DIRTREEARRAY2HTML(dirarray,nfiles)

 INPUTS:
     dirpath  : path specification of directory
     dirarray : array of directory names output of GET_DIR_TREE (without path)
     nfiles   : integer array with number of files for each directory output of GET_NFILES

 KEYWORD PARAMETERS:
     DIR2HTMLFILE: name of the html-file, which contains the table of informations
                   about the directories (default=dir2html.html)
     _EXTRA      : BORDER=border (default), CAPTION=dirpath (default) see array2htmltable for details

 OUTPUTS:
   This function returns a string array which contains the html-table: array(cx,lev+1)
                          cx :number of directories (output of GET_DIR_TREE)
                          lev:number of directory levels

 EXAMPLE:
       dirpath='/home3/ich388/IDL'
       dirarray=get_dir_tree(dirpath,LEVEL=-1,count=cdx)
       dirarrayplus=dirpath+dirarray
       nfiles  =get_nfiles(dirarrayplus)
       array   =DIRARRAY2HTML(dirpath,dirarray,nfiles)

 MODIFICATION HISTORY:
   Written by:      Marsy Lisken  august 1998

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\dirtreearray2html.pro)


DISKCENTER

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DISKCENTER
 PURPOSE:
       Find center and radius of a disk in an image.
 CATEGORY:
 CALLING SEQUENCE:
       diskcenter, img, xc, yc, rd
 INPUTS:
       img = input image containing the disk.   in
 KEYWORD PARAMETERS:
       Keywords:
         /GRID plots fit to disk.
 OUTPUTS:
       xc, yc = array indices of disk center.   out
       rd = estimated radius of disk in pixels. out
 COMMON BLOCKS:
 NOTES:
       Note: Image is assumed 0 outside disk, non-zero inside.
         Also center of array must be inside the disk.
 MODIFICATION HISTORY:
       R. Sterner, 21 Feb, 1991

 Copyright (C) 1991, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\diskcenter.pro)


DISPLAY_HELP

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

 PURPOSE:
   This procedure displays parts of the template on screen

 CATEGORY:
   CASE_TOOLS

 CALLING SEQUENCE:
   display_help, file_name

 INPUTS:
   file_name: The name of an IDL Source File

 OUTPUTS:
   This procedure displays on the screen a short description of a routine

 EXAMPLE:
   display_help,'ncdf_gr.pro'

 MODIFICATION HISTORY:
 	Written by:	R.Bauer (ICG-1), June 23 1997
   1999-Nov-06 help added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\display_help.pro)


DISTRIBUTE

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

 PURPOSE:
        collect all the routine names and file names that are
        used in a given program.

 CATEGORY:
        Administrative Tools

 CALLING SEQUENCE:
        DISTRIBUTE,ROUTINENAME

 INPUTS:
        ROUTINENAME --> The name of the routine to be searched.

 KEYWORD PARAMETERS:
        OUTFILE --> name of an output file where the output will be saved.

 OUTPUTS:
        A list of filenames with full pathnames and a list of routinenames
        together with the filenames where they can be found.
        Sorry, for local files, no pathname is provided.

 SUBROUTINES:

 REQUIREMENTS:

 NOTES:
        Unfortunately there is no way to figure out which routines
        really belong to a given routinenname, so DISTRIBUTE will always
        return too many routinenames and filenames, including itself
        and FILE_EXIST, as well as a couple of IDL standard library
        routines (The latter can be left out with the keyword NO_IDL).
        In order to get the closest results, run DISTRIBUTE only at the
        start of an IDL session.

        With routine_info /source, there should now be a way to
        overcome the previously mentioned handicap!!

 EXAMPLE:
        get all routines that belong to ITERATE.PRO:

            DISTRIBUTE,'iterate'

        A subsequent call with routinename 'create_master' will return
        both, the routines for create_master and the routines for iterate.

 MODIFICATION HISTORY:
        mgs, 16 Nov 1997: VERSION 1.00
        mgs, 20 Nov 1997: - added OUTFILE and NO_IDL keywords
        mgs, 23 Aug 2000: - changed copyright to open source
                          - reverted to IDL routine resolve_all
                            instead of own modification resolve_every.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\distribute.pro)


DIST_SCALE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DIST_SCALE
 PURPOSE:
       Display a distance scale on an image.
 CATEGORY:
 CALLING SEQUENCE:
       dist_scale, x0, y0
 INPUTS:
       x0, y0 = pixel coordinates of the center of scale.  in
 KEYWORD PARAMETERS:
       Keywords:
         SCALE=sc    Number of units per pixels (like 12.5 m).
         LENGTH=len  length of scale in units given in SCALE.
         HEIGHT=ht   height of scale in units given in SCALE.
         TITLE=txt   Scale title text (like 10 km).
         SIZE=sz     Text size (def=1).
         COLOR=clr   Color of scale (def=!p.color).
         BACKGROUND=bclr   Background color (def=!p.background).
         THICK=thk   Scale thickness.
 OUTPUTS:
 COMMON BLOCKS:
       dist_scale_com
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 26 Jul, 1993

 Copyright (C) 1993, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dist_scale.pro)


DIST_SCALE2

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DIST_SCALE2
 PURPOSE:
       Display a distance scale on an image.
 CATEGORY:
 CALLING SEQUENCE:
       dist_scale, x0, y0
 INPUTS:
       x0, y0 = pixel coordinates of the center of scale.  in
 KEYWORD PARAMETERS:
       Keywords:
         SCALE=sc    Number of units per pixels (like 12.5 m).
         LENGTH=len  length of scale in units given in SCALE.
         HEIGHT=ht   height of scale in units given in SCALE.
         TITLE=txt   Scale title text (like 10 km).
         SIZE=sz     Text size (def=1).
         COLOR=clr   Color of scale (def=!p.color).
         BACKGROUND=bclr   Background color (def=!p.background).
         THICK=thk   Text thickness.
         BORDER=brd  Border thickness.
 OUTPUTS:
 COMMON BLOCKS:
       dist_scale_com
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 1997 Mar 7

 Copyright (C) 1997, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dist_scale2.pro)


DIURNAL_STATISTICS

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

 PURPOSE:
		This function returns statistics on time-averaged data sets.

 CATEGORY:
		TIME

 CALLING SEQUENCE:
		result = diurnal_statistics(time, data)

 INPUTS:
		time: Vector of time data in Js.
		data: Data vector.

 KEYWORD PARAMETERS:
		TIME_STEP = ts: averaging time window in seconds (default: 86400D0).
		FIRST_DAY = fd: dd.mm.yy - Date of first day to be considered
			(default: first day in data set).
		LAST_DAY = ld: dd.mm.yy - Date of last day to be considered
			(default: last day in data set).
		MISSING_VALUE = miss_value: Missing data value (Skalar must be of same type as y-data value).
		/MAKE_PLOT: If set the result of the time-averaging process is plotted.
		_EXTRA = e: Any valid plot_2c keyword parameters can be passed into the
			plot_2c procedure.

 OUTPUTS:
		This function returns a structure of arrays where the
		array dimension n is equal to the number of time bins in the density function.
		For each bin the start time and the statistical parameters mean, stdev, sterr,
		n, and median are returned (tag names: time, mean, stdev, sterr, n, median). The
		time step is returned as well (tag name: time_step).
		If a quantity is not defined (e.g. stdev for only one point in the bin),
		the value !VALUES.F_NAN is returned.

 EXAMPLE:
		a = DINDGEN(100)
		t = a * 3600.D
		result = diurnal_statistics(t, a, /MAKE_PLOT)

		--> a time axis plot should appear

		HELP, result, /STR

		** Structure <1859af0>, 9 tags, length=192, refs=1:
		   TIME            DOUBLE    Array[5]
		   MEAN            FLOAT     Array[5]
		   STDEV           FLOAT     Array[5]
		   STERR           FLOAT     Array[5]
		   N               LONG      Array[5]
		   MEDIAN          FLOAT     Array[5]
		   MIN             FLOAT     Array[5]
		   MAX             FLOAT     Array[5]
		   TIME_STEP       DOUBLE           86400.000

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 02.06.1999
	14.06.1999:	Added keyword parameter MISSING_VALUE = miss_value.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\diurnal_statistics.pro)


DL_VMS

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

 PURPOSE:
	Dummy procedure for preventing idl to search by resolve_all for rsi vms code 

 CATEGORY:
	CASE_TOOLS

 CALLING SEQUENCE:
	DL_VMS		;For prompting.
	DL_VMS, Name	;Extract documentation for procedure Name using
				the current !PATH.

 INPUTS:
	Name:   A string containing the name of the procedure.

 KEYWORDS:
	FILE:   If this keyword is set, the output is sent to the file
		"userlib.doc", in the current directory.

	PRINT:  If set, this keyword sends the  output of DL_VMS to lpr.

	PATH:   An optional directory/library search path.  This keyword uses
		the same format and semantics as !PATH.  If omitted, !PATH is
		used.
 OUTPUTS:
	Documentation is output to terminal or printer.

 COMMON BLOCKS:
	None.

 SIDE EFFECTS:
	Output is produced on terminal or printer.

 RESTRICTIONS:
	None.

 PROCEDURE:
	Straightforward.

 MODIFICATION HISTORY:
	Written, DMS, Sept, 1982.
	Added library param, Jul 1987.
	Unix version, Feb, 1988.
	Revised for VMS Version 2, 15 December 1989
	Modified by Jim Pendleton, GRO/OSSE NU, July 30, 1992 to handle
		!PATH's gt 255 characters.
	AB, 21 September 1992, renamed from DOC_LIB_VMS to DL_VMS to
		avoid DOS filename limitations.
	ACY, 25 January 1993, file should be written with stream mode
 1998-07-30 R.Bauer, all lines between PRO and END removed because of preventing idl in non vms
              to search for special vms functions  

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\dl_vms.pro)


DMS2D

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DMS2D
 PURPOSE:
       Convert from Degrees, MInutes, and seconds to degrees.
 CATEGORY:
 CALLING SEQUENCE:
       d = dms2d(s)
 INPUTS:
       s = input text string with deg, min, sec.    in
         Ex: "3d 08m 30s" or "3 8 30".
 KEYWORD PARAMETERS:
 OUTPUTS:
       d = returned angle in degrees.               out
 COMMON BLOCKS:
 NOTES:
       Notes: scalar value only.  Units symbols ignored,
         first item assumed deg, 2nd minutes, 3rd seconds.
 MODIFICATION HISTORY:
       R. Sterner, 1998 Feb 3

 Copyright (C) 1998, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dms2d.pro)


DMS_FORM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DMS_FORM
 PURPOSE:
       Convert degrees to a deg, min, sec vector font string.
 CATEGORY:
 CALLING SEQUENCE:
       dms = dms_form(deg)
 INPUTS:
       deg = degrees and decimal fraction.    in
 KEYWORD PARAMETERS:
       Keywords:
         /NOSEC     Means suppress seconds.
         DEGREES=n  Force n digits in degrees, fill with 0s.
         FONT=fnt   Specify font string (def=!17).
 OUTPUTS:
       dms = string to be printed by xyouts   out
         using vector font.
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 22 Sep, 1992

 Copyright (C) 1992, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dms_form.pro)


DMYHMS2JS

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

 PURPOSE:
   convert date (d.m.y) and time (h:m:s) to JulianSeconds,
   works with string array input

 CATEGORY:
   TIME

 CALLING SEQUENCE:
   Result= DMYHMS2JS(date_time)

 INPUTS:
   date_time:   string ('d.m.y h:m:s')

 KEYWORD PARAMETERS:
   NO_SEC: if this keyword is set the sec of the string
           are ignored, works with 'd.m.y h:m'
   NOW:    returns actual time instead

 OUTPUTS:
   julian sec: double

 RESTRICTIONS:
   1.1.70 ... 31.12.69 = 1.1.1970 ... 31.12.2069
   only seperators matter, spaces and zeros ignored
   the string array must contain all entries: 'd.m.y h:m:s'

 EXAMPLE:
   dt=['1.1.95 10:11:03', '1.1.96 1:11:36', '1.1.05 1:11:3']
   jsec=dmyhms2js(dt)

   dt=['1.1.95 10:11', '1.1.96 1:11', '1.1.05 1:11']
   jsec=dmyhms2js(dt, /no_sec)

 REVISION HISTORY:
   Written     Theo Brauers, Nov 1997
   Modified    T.B. bug with array and no_sec removed
               T.B. bug with year  < 1969 removed

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\dmyhms2js.pro)


DOC

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:    doc

 PURPOSE:    find and display help for a named procedure

 USEAGE:     doc,'name'

 INPUT: 
   name      name of idl .pro file.  Asterisk characters, "*", in NAME
             specify wild card matches to 1 or more arbitrary characters.


 PROCEDURE:  DOC searches through the files /local/idl/help/*.help 
             trying to find matches for the file specification, NAME.  

             if there are no matches a brief failure message is displayed
                  and control returns to the terminal

             if 1 match is found, help for the specified procedure is 
                  displayed and control returns to the terminal

             if 2 or more matches are found a menu is generated 
                  from which selections can be made.  Control returns to 
                  the terminal when the DONE button of the MENUW widget
                  is pressed.


 EXAMPLE:
             doc,'legend'            ; exact match found in ESRG_LOCAL
             
             doc,'tv*'               ; many matches found, browse through
                                     ; choices.  Notice that all procedure
                                     ; libraries are searched


  author:  Paul Ricchiazzi                            may94
           Institute for Computational Earth System Science
           University of California, Santa Barbara

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\doc.pro)


DOCKEY

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:    dockey

 PURPOSE:    display help documententation of file headers which
             contain matches for specified keywords

 USEAGE:     dockey,'name',keyword=keyword,all=all,minmatch=minmatch

 INPUT: 
   keywords  keyword string. Keywords withing the KEYWORDS must be
             separated by blanks. 

 KEYWORD_INPUT

   minmatch  the minimum number of keyword hits required for a procedure
             to be listed in the hit-list menu. 

 PROCEDURE:  DOCKEY searches through the helpfiles in subdirectory
             /local/idl/help, trying to find matches for the keywords.
             If more than one file match is found a menu of procedure
             names is displayed from which the desired procedure
             can be selected.  The parenthisized number next to each
             procedure name is the number of keyword matches, which
             can vary between one to the total number of keywords in
             KEYWORDS. 

             MAN_PROC is used to display the text

 EXAMPLE:
             dockey,'simpson rule integration';  pick group 'numerical'
            
             dockey,'polar orthographic'      ;  pick group 'esrg'

             dockey,'color key image',m=2     ;  pick group 'color'

; 


  author:  Paul Ricchiazzi                            may94
           Institute for Computational Earth System Science
           University of California, Santa Barbara

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\dockey.pro)


DOT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DOT
 PURPOSE:
       Used by SUN_SHADE for dot prod. of surf. normal & sun vect.
 CATEGORY:
 CALLING SEQUENCE:
       r = dot(s,[azi,alt])
 INPUTS:
       s = Surface array to be shaded.                    in
       azi = Light azimuth (deg, def = 135).              in
       alt = Light altitude (deg, def = 60).              in
 KEYWORD PARAMETERS:
 OUTPUTS:
       r = dot products: surface normals and sun vector.  out
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner. 8 Mar, 1989.
       R. Sterner, 27 Jan, 1993 --- dropped reference to array.
       Slightly modified version of routine by J. Culbertson.
       Johns Hopkins University Applied Physics Laboratory.

 Copyright (C) 1989, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dot.pro)


DO_LINK

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

 PURPOSE:
   This procedure did the links of "good" files to the defined flightday directories
   of the icg-1 datalibrary.
   The link name ist always the lowercase experiment name +'.nc'

 CATEGORY:
   DATAFILES/FILE

 CALLING SEQUENCE:
   do_link,[/month]

 KEYWORD PARAMETERS:
  month: to link the data to month instead of flightday directories

 RESTRICTIONS:
 will at the moment only work whith icg1's data-base

 EXAMPLE:
   do_link,'stream1997'

 MODIFICATION HISTORY:
 	Written by:	R.Bauer (ICG-1),August 1997

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\do_link.pro)


DO_PAGE_TITLE

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

 PURPOSE:
   This procedure is used to write a centered title on a plot page

 CATEGORY:
   PLOT

 CALLING SEQUENCE:
   do_page_title,plot,text,[charsize=charsize],[color=color]

 INPUTS:
   plot: The by pl_init defined plot structure
   text: The text you want to show on the page

 OPTIONAL INPUTS:
   charsize: The charsize ot the text (default is 1)
   color:    The color of the text    (default is black)


 EXAMPLE:
   do_page_title,plot,'TEST'

 MODIFICATION HISTORY:
 	Written by:	R.Bauer (ICG-1), 5. Oct. 1997
   1999-10-14 alignment added
   1999-Nov-06 help added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\do_page_title.pro)


DO_PL2D

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

 PURPOSE:
       This procedure is an example routine for the use of the procedures
       do_pl2d_define and do_pl2d_plot.
       You can use it (with all keywords specified) or you can copy it and modify it in
       the form which you want.
       After the do_pl2d_define-call there is a comment, which substructures you can now use.

 CATEGORY:
       PLOT/PLOT2D

 CALLING SEQUENCE:
       do_pl2d,spec

 INPUTS:
       spec : the netCDF-variable which you want to plot.
       some control keywords

 OUTPUTS:
       A contour plot with the variable, specified in plotstr.values.z, plotted against the x- and y-values.

 EXAMPLE:
       do_pl2d,'PV',f_name =file_search('box_970227_nh.nc',/use_path),dir='./'
       Result: a plot of the species PV on a map-background with cylindrical projection
       

MODIFICATION HISTORY: Written by: Juergen Ankenbrand , 11.5.98

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\ja_lib\do_pl2d.pro)


DO_PL2D_DEFINE

[Previous Routine] [Next Routine] [List of Routines]
 NAME: 
       do_pl2d_define 
 
 PURPOSE: 
       This procedure defines some substructures of the ICG - plot-structure. 
       It reads the variables, which the user wants, from a netCDF-file and  
       creates them as components of the plotstructure. 
       Some control attributes of the netCDF-file become components, too.  
 
 CATEGORY: 
       PLOT/PLOT2D 
 
 CALLING SEQUENCE: 
 
       do_pl2d_define,plot 
 
 INPUTS: 
       plot: Plotstructure of the ICG plot-environment, which has to have 
             a new subcomponent 'names', which must contain the components  
             'file'       : the netcdf-filename 
             'paramnames' : a stringarray, which contains the names of the  
                            variables of the netCDF-file, which should be read 
                            from the file 
             'spec'       : the name of the variable, which is later used as  
                            z variable 
             'con'        : if 1, then the spec-values are multiplicated with the 
                            values of netCDF-variable 'TND' 
 
 OUTPUTS: 
       plot: The input Plotstructure has some new components:   
             'control' with the components: 
                      'missing_value': the missing_value-attribute of the netCDF-file 
                      'nparts'       : the number of trajectories 
                      'time'         : the time dimension 
                      'unit'         : a string, where you can set later e.g. 'ppm' 
                      'dim'          : a component where you can set the dimension for a later defp2d - 
                                       call; default value 21 
                      'maxval'       : a component for a defp2d - call, too 
                      'minval'       : a component for a defp2d - call, too 
                      'map'          : a string, where you can later chose a map projection 
 
             'paramvalues' with the components: 
                      'spec'         : the values of the z-variable, which has been  
                                       declared in plot.names.spec,eventually multiplied 
                                       with TND 
                      the names declared in plot.names.paramvalues: the values of these 
                                       netCDF-variables 
                        
 SIDE EFFECTS: 
       The input-plot-structure has some new subcomponents. 
 
 
 EXAMPLE: 
 
@init  
            ;initialize Reimar Bauer's plotstructure 
 
   paramnames = ['LONG','LAT','LEVEL','time','TND']   
            ;a stringarray with the names of the variables ,which are to read 
    
   my_struct1 = create_struct('file','test.nc','paramnames',paramnames,'spec','PV','con',0) 
            ;create a new structure 
 
   plot=create_struct(plot,'names',my_struct1) 
            ;and it becomes a substructure of the plot-structure 
 
   do_pl2d_define,plot 
           ; now you have account of e.g. plot.paramvalues.spec, plot.paramvalues.LONG 
 
 MODIFICATION HISTORY: 
       Written by:     Juergen Ankenbrand, 5.5.1998. 

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\ja_lib\do_pl2d_define.pro)


DO_PL2D_PLOT

[Previous Routine] [Next Routine] [List of Routines]
 NAME: 
       do_pl2d_plot 
 
 PURPOSE: 
       This procedure calls the 'plot2d' procedure of Reimar Bauer. 
       Before, it searchs for x- and y-ranges of the axes-variables. 
       If you want, you can lay a map in the background. 
       If you have irregular values, which are in a regular gather, 
       these values can be transformed to a regular gather. 
 
 CATEGORY: 
       PLOT/PLOT2D 
 
 CALLING SEQUENCE: 
       do_pl2d_plot,plotstr 
 
 INPUTS: 
       plotstr: Plotstructure of the ICG plot-environment, which has to have 
                a new subcomponent 'names', which must contain the components: 
                'values': a new subcomponent with the components: 
                          'x': an array with the x-values (mostly longitude) 
                          'y': an array with the y-values (mostly latitude) 
                          'z': an array with the z-values, the variable, 
                               which will be plotted 
                'control' with the components(if ther has been a do_pl2d_define - call this 
                                              component already exists): 
                          'missing_value': the missing_value-attribute of the netCDF-file 
                          'nparts'       : the number of trajectories 
                          'time'         : the time dimension 
                          'unit'         : a string, where you can set later e.g. 'ppm' 
                          'dim'          : a component where you can set the dimension for a later defp2d - 
                                           call; default value 21 
                          'maxval'       : a component for a defp2d - call, too 
                          'minval'       : a component for a defp2d - call, too 
                          'map'          : a string, where you can later chose a map projection 
                          'regular'      : default 0 ; must be set later to not 0 if there are pseudoregular values 
                          'm','n'        : the sizes of the pseudoregular transformation 
 
 OUTPUTS: 
       A contour plot with the variable, specified in plotstr.values.z, plotted against the x- and y-values. 
       If plotstr.control.map is set to 1, a cylindrical map is plotted in the background, if plotstr.control.map 
       is 2 a polarstereographical map is plotted, else no map is plotted. 
 
 EXAMPLE: 
       (for the first 5 lines see the 'do_pl2D_define' - description,too) 
@init 
        paramnames = ['LONG','LAT','LEVEL','time','TND'] 
        my_struct1 = create_struct('file','test.nc','paramnames',paramnames,'spec','PV','con',0) 
        plot=create_struct(plot,'names',my_struct1) 
        do_pl2d_define,plot 
 
        my_struct4 = create_struct('Z',plot.paramvalues.spec,'X',plot.paramvalues.long,'Y',plot.paramvalues.lat,
                                   'contour'contour) 
                    ;Longitude is defined as x-axes, Latitude as y-axes and PV will be plotted. 
 
        plot = create_struct(plot,'values',my_struct4) 
                    ;values becomes a subcomponent of the 'plot' -structure 
 
        do_pl2d_plot,plot 
                    ;PV is plotted in a contour plot against longitude and latitude 
 
 MODIFICATION HISTORY: 
       Written by:  Juergen Ankenbrand , 11.5.98, 
       14.6.98: P. Konopka, new switch plot.values.contour:
        plot.values.contour=1: contour plots
        plot.values.contour=0: Air parcels are plotted as small filled circles

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\ja_lib\do_pl2d_plot.pro)


DO_PLXY

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

 PURPOSE:
   Using the plotxy environment possible types of plots are
   1X-1Y, 2X-1Y, 1X-2Y, 2X-2Y
   For more information look at the example do_plxy_instructions.

 CATEGORY:
   PLOT

 CALLING SEQUENCE:
   do_plxy, instruction_file

 INPUTS:
   instruction_file: an idl Script which holds the instruction how to make a plot

 OUTPUTS:
   belonging on the instruction file on screen or file

 EXAMPLE:
   do_plxy,'do_plxy_instructions'

   PRO do_plxy_instructions,pict,init

       ct_ncdf,color
       seiten =1
       zeilen =2
       spalten =2
       plot_width=15.60
       plot_height=10.85
       plot_width=20.
       landscape=1
       psflag = 0
       psfile = 'idl'
       init = {$
               spalten:spalten,$
               zeilen:zeilen,$
               plot_width:plot_width,$
               plot_height:plot_height,$
               psflag:psflag,$
               psfile:psfile,$
               landscape:landscape,$
               page_title:''$
               }
       pict = replicate({use:'plotxy',$
                         file:'',$
                         title:'',$
                         x:strarr(2),$
                         y:strarr(2),$
                         psym:[(0),(108)],$
                         color:[color.red,color.green],$
                         symsize:[1.,1.],$
                         linestyle:[0,0],$
                         thick:[1.,1.],$
                         timeformat:['!h$:m$:s$@!d$.nn$.Y$','!h$:m$:s$@!d$.nn$.Y$'],$
                         x_array_index:intarr(2),$
                         y_array_index:intarr(2)},$
                         zeilen*spalten*seiten)


        pict[0].file='S:/links/idl_source/idl_work/rb_lib/examples/do_plxy.nc'
        pict[0].x = ['time','time']
        pict[0].y = ['LAT','LAT']
        pict[0].x_array_index = [0,0]
        pict[0].y_array_index = [0,1]

        pict.file='S:/links/idl_source/idl_work/rb_lib/examples/do_plxy.nc'

        pict[1].x = ['time','']
        pict[1].y = ['LAT','LON']
        pict[1].x_array_index = [0,0]
        pict[1].y_array_index = [1,1]

        pict[2].file='S:/links/idl_source/idl_work/rb_lib/examples/do_plxy.nc'
        pict[2].x = ['time','']
        pict[2].y = ['LAT','']
        pict[2].x_array_index = [0,0]
        pict[2].y_array_index = [2,2]

        pict[3].file='S:/links/idl_source/idl_work/rb_lib/examples/do_plxy.nc'
        pict[3].x = ['time','time']
        pict[3].y = ['LAT','']
        pict[3].x_array_index = [0,0]
        pict[3].y_array_index = [0,1]

 END
 

MODIFICATION HISTORY: Written by: R.Bauer (ICG-1), 13-Oct-1997 15.10 Part 1X 1Y corrected 22.10 ytitle corrected 1998-Jan-15 plot.xgap sey to 8640000.d 1998-Mar-03 the case of 1X and 1Y axis is corrected in case of plot.x_array_index and y_array_index 1999-Nov-06 help added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\do_plxy.pro)


DO_PLXY_INSTRUCTIONS

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

 PURPOSE:
   This is an instructions file for do_plxy

 CATEGORY:
   EXAMPLES/PLOT/PLOTXY

 CALLING SEQUENCE:
   do_plxy_instructions,pict,init

 OUTPUTS:
   pict: an array of structures holding the informations for the plot
   init: a structure holding the informations to initialize a plot

 EXAMPLE:
   do_plxy,'do_plxy_instructions'
  gif picture 


 MODIFICATION HISTORY:
 	Written by:	R.Bauer (ICG-1), 13-Oct-1997

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\examples\plot\plotxy\do_plxy_instructions.pro)


DRAW

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DRAW
 PURPOSE:
       Graphics draw from last point to given point.
 CATEGORY:
 CALLING SEQUENCE:
       draw, x, y
 INPUTS:
       x,y = scalar coordinates of point to draw to.   in
 KEYWORD PARAMETERS:
       Keywords:
         COLOR=c color of line from last point.
 OUTPUTS:
 COMMON BLOCKS:
       move_com
 NOTES:
       Note: see move.
 MODIFICATION HISTORY:
       R. Sterner, 22 Jan, 1990

 Copyright (C) 1990, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\draw.pro)


DRAWCOLORS

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

 FILENAME:

   drawcolors__define.pro

 PURPOSE:

   The purpose of this object program is provide a flexible way
   to handle and select drawing colors. The program combines
   features of two previous programs: GetColor and PickColor,
   as well as adding features of its own. Sixteen original
   colors are supplied, but users can create any color they
   wish using the tools provided.

   By default, these 16 colors are defined: Black, Magenta, Cyan, Yellow,
   Green, Red, Blue, Navy, Aqua, Pink, Orchid, Sky, Beige, Charcoal, Gray, White.

 AUTHOR:
   FANNING SOFTWARE CONSULTING
   David Fanning, Ph.D.
   2642 Bradbury Court
   Fort Collins, CO 80521 USA
   Phone: 970-221-0438
   E-mail: davidf@dfanning.com
   Coyote's Guide to IDL Programming: http://www.dfanning.com/

 CATEGORY:

   General programming.

 CALLING SEQUENCE:

   colors = Obj_New('DRAWCOLORS')

 OPTIONAL INPUT PARAMETERS:

      IDL> colors = Obj_New('DRAWCOLORS', red, green, blue, names)

   RED -- A 16-element byte vector of red values for the drawing colors.

   GREEN -- A 16-element byte vector of green values for the drawing colors.

   BLUE -- A 16-element byte vector of blue values for the drawing colors.

   NAMES -- A 16-element string vector of names for the drawing colors.

   By default, these colors are defined: Black, Magenta, Cyan, Yellow,
   Green, Red, Blue, Navy, Aqua, Pink, Orchid, Sky, Beige, Charcoal, Gray, White.

 COMMON BLOCKS:

   None.

 RESTRICTIONS:

   If you are going to use the XCOLORS method, you will need
   the XColors program from the Coyote library:

     http://www.dfanning.com/programs/xcolors.pro

   The program is set up to handle 16 drawing colors. You may
   modify the program to have a different number, but you will
   have to modify the code in two places: (1) in the drawcolors__define
   module and (2) in the INIT method.

 FUNCTION METHODS:

   COLOR24 ***************************************************************************

      Purpose:

       Turns a color triple into the equivalent 24-bit color integer value that
       can be decomposed into the color.

      Definition:

          FUNCTION DrawColors::Color24, theColor

     Parameters:

        theColor -- A 3-element vector, representing a color triple.

     Example:

        yellow = colors->GetColor("yellow")
        yellow24 = colors->Color24(yellow)


   GETCOLOR ***************************************************************************

      Purpose:

       Returns the color triple, color index number, or the
       24-bit integer representation, of the asked for color. In
       normal operation, the colors are: Black, Magenta, Cyan, Yellow,
       Green, Red, Blue, Navy, Aqua, Pink, Orchid, Sky, Beige, Charcoal,
       Gray, and White.

      Definition:

          FUNCTION DrawColors::GetColor, theColor, startIndex, INDEXNUMBER=indexnumber, $
             TRUECOLOR=truecolor, AutoDetermine=autodetermine

     Parameters:

        theColor -- A string representing the "name" of the color. If the name
              can't be resolved or found, the first color is returned.

        startIndex -- If present, and INDEXNUMBER is set, the colors are loaded at
              this index number. Otherwise, the self.startIndex is used.

     Keywords:

        AUTODETERMINE -- If this keyword is set. the state of DECOMPOSITION is
             determined (IDL 5.2 and higher) and either the INDEXNUMBER or
             TRUECOLOR keyword is set appropriately. If the decomposition state
             cannot be determined, the INDEXNUMBER keyword is set.

        INDEXNUMBER -- If this keyword is set the colors are loaded and the
             index number of the color is returned.

        TRUECOLOR -- If this keyword is set, the color triple is converted into
             a 24-bit integer before being returned. This keyword is ignored
             if the INDEXNUMBER keyword is set.

     Examples:

        drawColor = colors->GetColor("yellow")
        drawColor = colors->GetColor("blue", /Indexnumber)
        drawColor = colors->GetColor("sky", /Truecolor)


   GETCOLORS **************************************************************************

      Purpose:

       Returns the color triples, the color index numbers of, or the
       24-bit integer representations of, all the colors.

      Definition:

          FUNCTION DrawColors::GetColors, startindex, INDEXNUMBER=indexnumber, $
             TRUECOLOR=truecolor, Structure=structure

      Parameters:

        startIndex -- If present, and INDEXNUMBER is set, the colors are loaded at
              this index number. If absent, startIndex = self.startIndex.

     Keywords:

        INDEXNUMBER -- If this keyword is set the colors are loaded and the
             index numbers of all the colors are returned.

        STRUCTURE -- If this keyword is set, the return value is a structure,
             where each field of the structure is a color name and the value
             of each field is either a color triple, an index number, or a
             24-bit color value, depending upon the state of other keywords.

        TRUECOLOR -- If this keyword is set, the color triples are converted to
             24-bit integers before being returned. This keyword is ignored
             if the INDEXNUMBER keyword is set.

     Examples:

        drawColors = colors->GetColors()  ; drawColors is a 16-by-3 byte array.
        drawColors = colors->GetColors(/IndexNumber) ; drawColors is a 16-element array of color indices.
        drawColors = colors->GetColors(/TrueColor) ; drawColors is a 16-element array of 24-bit integers.
        drawColors = colors->GetColors(/IndexNumber, /Structure) ; drawColors is a structure of index numbers.
        Plot, data, Color=drawColors.yellow, Background=drawColors.charcoal


   SELECT  **************************************************************************

      Purpose:

       Puts up a blocking or modal widget dialog, allowing the user to select
       from one of the 16 predefined colors available, or to mix their own color.
       The user-defined color triple is returned as a result of the function.

      Definition:

          FUNCTION DrawColors::Select, Color=currentColor, StartIndex=startIndex, $
             Title=title, Group_Leader=groupLeader, Cancel=cancelled, TrueColor=truecolor

     Keywords:

        CANCEL -- An output keyword that will return a value of 1 if the CANCEL
             button is selected or if program operation is interrupted in any way.

        COLOR -- The index number in the color table, where the current color
             will be mixed. In other words, this color index will change when
             the program is on the display. It will be restored to its previous
             or entry color when the program exits.

        GROUP_LEADER -- The group leader for the program. This keyword *must*
             be set if calling this method from within a widget program if you
             expect MODAL program operation.

        NAME -- If this keyword is set, the return value of the function is
             the "name" of the color.

        STARTINDEX -- This is the starting index in the color table where the
             16 predetermined colors will be loaded. The original colors will
             be restored when the program exits. By default, this is set to
             !D.Table-Size - (NCOLORS + 1).

        TITLE -- The title of the program. By default: "Pick a Color"

        TRUECOLOR -- If this keyword is set, the return value of the function
            is a 24-bit eqivalent integer rather than the color triple.

     Examples:

        newColor = colors->Select()  ; A blocking widget.
        newColor = color->Select(Group_Leader=event.top, Cancel=cancelled)
        IF NOT cancelled THEN TVLCT, newColor, info.dataColor



 PROCEDURE METHODS:

   GETPROPERTY ***********************************************************************

    Purpose:

       Allows the user to obtain the current properties of the object.

    Definition:

       PRO DrawColors::GetProperty, NAMES=names, RED=red, GREEN=green, BLUE=blue, $
           STARTINDEX=startindex, NCOLORS=ncolors

     Keywords:

        NAMES -- Returns the current names of the colors as a string array.

        RED -- Returns the current red values of the colors.

        GREEN -- Returns the current green values of the colors.

        BLUE -- Returns the current blue values of the colors.

        STARTINDEX -- Returns the current starting index in the color table.

        NCOLORS -- Returns the number of colors.

     Example:

        colors->GetProperty, Names=colorNames
        Print, colorNames


   LOADCOLORS ************************************************************************

      Purpose:

         Loads the predefined colors at a starting index.

      Definition:

         PRO DrawColors::LoadColors, startindex

     Parameters:

        STARTINDEX -- The starting color index in the color table. If not provided,
            is set to !D.Table_Size - (self.ncolors + 1).

     Example:

        colors->LoadColors, 16


   ORIGINALCOLORS *********************************************************************

      Purpose:

         Reloads the original 16 colors and their names

      Definition:

         PRO DrawColors::OriginalColors

     Parameters:

        None

     Example:

        colors->OriginalColors


   REFRESH ***************************************************************************

      Purpose:

         Refreshes the modal GUI with the current drawing colors.

      Definition:

         PRO DrawColors::Refresh

     Parameters:

        None

     Example:

        colors->Refresh


   SETPROPERTY ***********************************************************************

    Purpose:

       Allows the user to set the current properties of the object.

    Definition:

       PRO DrawColors::SetProperty, NAMES=names, RED=red, GREEN=green, BLUE=blue, $
           STARTINDEX=startindex, NCOLORS=ncolors

     Keywords:

        NAMES -- The current names of the colors as a string array.

        RED -- The current red values of the colors.

        GREEN -- The current green values of the colors.

        BLUE -- The current blue values of the colors.

        STARTINDEX -- The current starting index in the color table.

        NCOLORS -- The number of colors.

     Example:

        colorNames = 'Color ' + StrTrim(SIndGen(16),2)
        colors->SetProperty, Names=colorNames


   XCOLORS ***************************************************************************

      Purpose:

         Allows the user to select 16 new colors for the program by
         using the XCOLORS program. The XColors program must be
         somewhere in your !PATH.

      Definition:

         PRO DrawColors::XColors

     Parameters:

        None

     Example:

        colors->XColors

 TUTORIAL:

   Here is a short tutorial in how this object can be used. Note
   that this doesn't exhaust all the possibilities.

  1. Create the object.

     IDL> colors = Obj_New("DrawColors")

  2. Find out what colors it knows about.

     IDL> colors->GetProperty, Names=colorNames
     IDL> Print, colorNames

  3. Ask for a color by name and load it at a color
     index. Draw a plot in that color.

     IDL> yellow = colors->GetColor("yellow")
     IDL> TVLCT, yellow, 200
     IDL> Device, Decomposed=0
     IDL> Plot, Findgen(11), Color=200

  4. Do the same thing, but in DECOMPOSED color.

     IDL> Device, Decomposed=1
     IDL> green = colors->GetColor("green", /TrueColor)
     IDL> Plot, Findgen(11), Color=green

  5. Find the color index number of the sky blue color.

     IDL> Device, Decomposed=0
     IDL> skyIndex = colors->GetColor("sky", /IndexNumber)
     IDL> Plot, Findgen(11), Color=skyIndex

  6. Load all 16 drawing colors at color index 32.

     IDL> colors->LoadColors, 32
     IDL> CIndex ; If them, if you have CINDEX from my library.

  7. Get a structure of colors, with each field set to
     the appropriate index number of its associated color.

     IDL> Device, Decomposed=0
     IDL> col = colors->GetColors(/IndexNumber, /Structure)
     IDL> Plot, Findgen(11), Color=col.yellow, Background=col.charcoal

  8. Allow the user to select a color from a GUI, then
     load it and use it.

     IDL> Device, Decomposed=0
     IDL> theColor = colors->Select(Cancel=cancelled)
     IDL> IF NOT cancelled THEN TVLCT, theColor, 10
     IDL> Plot, Findgen(11), Color=10

  9. Allow the user to choose 16 new drawing colors.
     (Requires my XCOLORS program.)

     IDL> colors->XColors
     IDL> theseColors = colors->Select()

 10. Let the object decide according to the device decomposition
     state whether to return an index number or 24-bit value
     for the color.

     IDL> Plot, Findgen(11), Color=colors->GetColor('beige', /Autodetermine)

 11. Call the GUI from within a widget program and load the
     new color.

     newcolor = info.colors->Select(Group_Leader=event.top, $
        Cancel=cancelled)
     IF NOT cancelled THEN TVLCT, newcolor, info.drawColor

 12. Destroy the object.

     IDL> Obj_Destroy, colors


 MODIFICATION HISTORY:

   Written by: David Fanning, 9 NOV 1999.
   Added AUTODETERMINE keyword to the GetColor method. 10 NOV 1999. DWF.
   Added NAME keyword to SELECT method. 18 MAR 2000. DWF.
   Fixed a small bug in choosing the current color. 20 April 2000. DWF.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\drawcolors__define.pro)


DRAWPOLY

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DRAWPOLY
 PURPOSE:
       Draw a polygon using mouse.
 CATEGORY:
 CALLING SEQUENCE:
       drawpoly, x, y
 INPUTS:
 KEYWORD PARAMETERS:
       Keywords:
         /CURVE draw a curve instead of a polygon.
         /DEVICE use device coordinates (def).
         /DATA use data coordinates.
         /NORMAL use normalized coordinates.
         /NOPLOT erase on exit (def=plot).
         COLOR=c outline or curve color (def=!p.color).
         THICK=t outline or curve thickness (def=0).
         LINESTYLE=s outline or curve line style (def=0).
         FILL=f polygon fill color (def= -1 = no fill).
 OUTPUTS:
       x,y = polygon vertices.        out
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 2 Oct, 1990
       R. Sterner, 23 Oct, 1990 --- added some keywords.
       R. Sterner, 26 Feb, 1991 --- renamed from draw_polygon.pro
       R. Sterner, 1994 Mar 17 --- Default color=!p.color.

 Copyright (C) 1990, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\drawpoly.pro)


DRAW_AXIS

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

 PURPOSE:
  This procedure draws the axes over an oplot. Normally this routines is used by plotxy, plot2d etc.
  if they are called after set_frame procedure

 CATEGORY:
  PLOT/PLOTXY

 CALLING SEQUENCE:
    draw_axis,PLOT,pl_xy,time=time,xrange=xrange,yrange=yrange,xstyle=xstyle

 INPUTS:
       plot:   The plot structure defined by pl_init
       pl_xy:  the siues structure
       time:   if set timeaxis is drawn
       xrange: submitted at the moment xrange to draw
       yrange: submitted at the moment yrange to draw
       xstyle: submitted at the moment xstyle to use

 PROCEDURE:
  This procedure is under construction



 MODIFICATION HISTORY:
  Written by: R.Bauer (ICG-1) 2000-Apr-25

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\draw_axis.pro)


DROP_COMMENTS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DROP_COMMENTS
 PURPOSE:
       Drop comment and null lines from a text array.
 CATEGORY:
 CALLING SEQUENCE:
       out = drop_comments(in)
 INPUTS:
       in = input text array.          in
 KEYWORD PARAMETERS:
       Keywords:
         IGNORE=ig  Text string of allowed comment characters.
           Default is ';*', so lines starting with the characters'
           * or ; in column 1 are considered comments and dropped.
         /NOTRIM  means don't do a strtrim on text array.
           By default any line with white space but no text is
           considered a null line and dropped.  If /NOTRIM is
           specified only true null lines are dropped.
         /TRAILING  means drop any trailing comments on each line.
           Be careful of the default comment characters for this.
         ERROR=err  Error flag: 0=OK, 1=All lines dropped.
         /QUIET  Means suppress error messages.
         INDEX=indx  Indices in original input of retained lines.
 OUTPUTS:
       out = processed text array.     out
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 18 May, 1993
       R. Sterner, 1995 Jun 26 --- added keyword INDEX=indx.
       R. Sterner, 1995 Oct 27 --- added keyword /TRAILING.

 Copyright (C) 1993, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\drop_comments.pro)


DTIME2JS

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

 PURPOSE:
	This function translates the year ,month, day, hour, minute, second, millisecond to Julian Seconds or a
   string like 'YYYY-MM-DD HH:MM:SS mSc'

 CATEGORY:
   TIME

 CALLING SEQUENCE:
   Result = dtime2js(y,m,d,s,hh,mm,ss,mi) or  Result = dtime2js('1997-06-13 13:31:13 313')

 INPUTS:
	y:  four digits for the year
       if y is a string the script goes in the char mode
	m:  the month
   d:  the day
   hh: the hours
   mm: the minutes
   ss: the seconds
   mi: the milliseconds

 OPTIONAL INPUTS:
	datstr:[obsolete] A string with the day time information
           Format is: 'YYYY-MM-DD hh:mm:ss mi'
           needed in the past to submit a string


 KEYWORD PARAMETERS:
	char: [obsolete] switch for the function to convert a string defined day time information
         was used in the past to switch between integer and string input


 OUTPUTS:
	This function returns the Julian Seconds of a day time Information


 EXAMPLE:
   Result = dtime2js(1997,6,13,13,31,13,313)
   Result=  -80476126.687D

   Result=dtime2js('1997-06-13 13:31:13 313')
   Result=  -80476126.687D


 MODIFICATION HISTORY:
 	Written by:	R.Bauer,  Sep., 18, 1996
               R.Bauer,  Jan.,  7, 1997 /char option added
               R.Bauer,  Aug., 14  1997 /Sep 2 easier handling of strings
               R.Bauer,  Mar.,  8  1998 internal variable y changed to yy


(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\dtime2js.pro)


DT_TM_BRK

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DT_TM_BRK
 PURPOSE:
       Break a date and time string into separate date and time.
 CATEGORY:
 CALLING SEQUENCE:
       dt_tm_brk, txt, date, time
 INPUTS:
       txt = Input date and time string.               in
         May be an array.
 KEYWORD PARAMETERS:
 OUTPUTS:
       date = returned date string, null if no date.   out
       time = returned time string, null if no time.   out
 COMMON BLOCKS:
 NOTES:
       Note: works for systime: dt_tm_brk, systime(), dt, tm
         The word NOW (case insensitive) is replaced
         by the current sysem time.
 MODIFICATION HISTORY:
       R. Sterner. 21 Nov, 1988.
       RES 18 Sep, 1989 --- converted to SUN.
       R. Sterner, 26 Feb, 1991 --- renamed from brk_date_time.pro
       R. Sterner, 26 Feb, 1991 --- renamed from brk_dt_tm.pro
       R. Sterner, 1994 Mar 29 --- Allowed arrays.

 Copyright (C) 1988, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dt_tm_brk.pro)


DT_TM_CHK

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DT_TM_CHK
 PURPOSE:
       Check date & time string that both parts exist & are valid.
 CATEGORY:
 CALLING SEQUENCE:
       status = dt_tm_chk(txt)
 INPUTS:
       txt = Input data and time string.             in
 KEYWORD PARAMETERS:
 OUTPUTS:
       status = 1 if ok (true), 0 if error (false).  out
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner. 13 Apr, 1989.
       R. Sterner, 26 Feb, 1991 --- renamed from chk_date_time.pro
       R. Sterner, 27 Feb, 1991 --- renamed from chk_dt_tm.pro

 Copyright (C) 1989, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dt_tm_chk.pro)


DT_TM_DIF

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DT_TM_DIF
 PURPOSE:
       Find time interval in seconds between two date/time strings.
 CATEGORY:
 CALLING SEQUENCE:
       sec = dt_tm_dif(t1, t2)
 INPUTS:
       t1, t2 = date and time strings.        in
 KEYWORD PARAMETERS:
 OUTPUTS:
       sec = Time in seconds from t1 to t2.   out
 COMMON BLOCKS:
 NOTES:
       Note: date and time strings are strings like 21-Jan-1989 14:43:03
       The format of the date and time strings is flexable, see date2ymd.
 MODIFICATION HISTORY:
       R. Sterner. 12 Apr, 1989.
       Johns Hopkins University Applied Physics Laboratory.
       RES 18 Sep, 1989 --- converted to SUN
       R. Sterner, 26 Feb, 1991 --- Renamed from interval_sec.pro
       R. Sterner, 27 Feb, 1991 --- Renamed from interv_sec.pro

 Copyright (C) 1989, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dt_tm_dif.pro)


DT_TM_FROMCR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DT_TM_FROMCR
 PURPOSE:
       Convert from Carrington Rotation Number to Date/Time.
 CATEGORY:
 CALLING SEQUENCE:
       dt_tm = dt_tm_fromcr(cr)
 INPUTS:
       cr = Carrington Rotation Number.   in
 KEYWORD PARAMETERS:
       Keywords:
         /JS means return Julian Seconds, not date/time string.
 OUTPUTS:
       dt_tm = date/time string.          out
 COMMON BLOCKS:
 NOTES:
       Notes: Time is Ephemeris Time which is almost UT.
         Ref: Astronomical Algorithms, Jean Meeus.
 MODIFICATION HISTORY:
       R. Sterner, 1996 Jun 21

 Copyright (C) 1996, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dt_tm_fromcr.pro)


DT_TM_FROMJS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DT_TM_FROMJS
 PURPOSE:
       Convert "Julian Seconds" to a date/time string.
 CATEGORY:
 CALLING SEQUENCE:
       dt = dt_tm_fromjs(js)
 INPUTS:
       js = "Julian Seconds".      in
 KEYWORD PARAMETERS:
       Keywords: 
         FORMAT=fmt format for dt (see dt_tm_mak).
           Def = "Y$ n$ d$ h$:m$:s$ w$"
         /FRACTION displays fraction of second in default format.
         DECIMAL=dp  Number of decimal places to use for fraction of
           second (def=3) for f$ in format.  f4 will include dec pt.
         DENOMINATOR=den If given then fraction is listed as nnn/ddd
           ddd is given by den.  Over-rides DECIMAL keyword.  Ex:
           DENOM=1000 might give 087/1000 for f$ in format.
         DDECIMAL=ddp  Number of decimal places to use in day
           of year (if doy$ included in format, def=none).
         YEAR=yy returns extracted year.
         MONTH=mm returns extracted month.
         DAY=dd returns extracted day.
         SECOND=ss returns extracted seconds after midnight.
         JD=jd  returns extracted Julian Day of date.
         NUMBERS=st Returned structure with numeric values.
 OUTPUTS:
       dt = date/time string.      out
 COMMON BLOCKS:
 NOTES:
       Notes: Julian seconds (not an official unit) serve the
         same purpose as Julian Days, interval computations.
         The zero point is 0:00 1 Jan 2000, so js < 0 before then.
         Julian Seconds are double precision and have a precision
         better than 1 millisecond over a span of +/- 1000 years.
       
       See also dt_tm_tojs, ymds2js, js2ymds, jscheck.
 MODIFICATION HISTORY:
       R. Sterner, 3 Sep, 1992
       R. Sterner, 18 Aug, 1993 --- Added JD keyword.
       R. Sterner, 2 Dec, 1993 --- Changed default format.
       R. Sterner, 1998 Apr 15 --- Returned NUMBERS structure.

 Copyright (C) 1992, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dt_tm_fromjs.pro)


DT_TM_FULL

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DT_TM_FULL
 PURPOSE:
       Add missing parts of date to get a full date/time string.
 CATEGORY:
 CALLING SEQUENCE:
       out = dt_tm_full(in,miss)
 INPUTS:
       in = input date/time string.                     in
          May have missing date info: '12:34' 'May 7 7:00'
       miss = Desired year, month, day in that order.   in
          Like '1996 May 12'.  Default=current date.
 KEYWORD PARAMETERS:
       Keywords:
         ERROR=err  0 if ok, 1 if result is not a valid date/time.
 OUTPUTS:
       out = Full date/time string.                     out
          Like '1996 May 12 12:34' or '1996 May 7 7:00'
 COMMON BLOCKS:
 NOTES:
       Notes: for scalar value only.  Does only limited error
         checking.
 MODIFICATION HISTORY:
       R. Sterner, 1997 Jul 10

 Copyright (C) 1997, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dt_tm_full.pro)


DT_TM_INC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DT_TM_INC
 PURPOSE:
       Increment a date/time by a given number of seconds.
 CATEGORY:
 CALLING SEQUENCE:
       dt_tm_inc, t, s
 INPUTS:
       s = Time in seconds to add.      in
 KEYWORD PARAMETERS:
       Keywords:
         FORMAT = format string.  Allows output date to be customized.
         The default format string is 'y$ n$ d$ h$:m$:s$'
            The following substitutions take place in the format string:
         Y$ = 4 digit year.
         y$ = 2 digit year.
         N$ = full month name.
         n$ = 3 letter month name.
         d$ = day of month number.
         W$ = full weekday name.
         w$ = 3 letter week day name.
         h$ = hour.
         m$ = minute.
         s$ = second.
         @  = Carriage Return.
         !  = Line feed.
         Some examples: 'h$:m$:s$' -> 09:12:04,
         'd$ n$ Y$' -> 12 Jan 1991, 'd$D h$h' -> 3D 2h, ...
 OUTPUTS:
       t = date and time string.        in, out
         date/time strings are strings like 21-Jan-1989 14:43:03
         The format of the date and time strings is flexible, see date2ymd.
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner. 18 Apr, 1989.
       RES 25 Oct, 1991 --- renamed and rewrote from incsec_datetime.
       Johns Hopkins University Applied Physics Laboratory.

 Copyright (C) 1989, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dt_tm_inc.pro)


DT_TM_MAK

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DT_TM_MAK
 PURPOSE:
       Set up a time and date string from reference JD and offset.
 CATEGORY:
 CALLING SEQUENCE:
       s = dt_tm_mak(jd0, [sec])
 INPUTS:
       jd0 = Julian Date of a reference date (0:00 hr).  in
       sec = Seconds since JD0 at 0:00.                  in
 KEYWORD PARAMETERS:
       Keywords:
         NUMBERS=st Structure with numeric values, useful at times.
         FORMAT = format string.  Allows output date to be customized.
         The default format string is 'Y$ n$ d$ h$:m$:s$ w$'
            The following substitutions take place in the format string:
         Y$ = 4 digit year.
         y$ = 2 digit year.
         N$ = full month name.
         n$ = 3 letter month name.
         0n$= month as a 2 digit number: Jan=1, Feb=2, Dec=12.
         d$ = day of month number.
         0d$= 2 digit day of month number.
         doy$= 3 digit day of year (see DDECIMAL below).
         W$ = full weekday name.
         w$ = 3 letter week day name.
         0w$ = week day number: Sun=1, Mon=2, ... Sat=7.
         h$ = hour.
         m$ = minute.
         s$ = second.
         f$ = fraction of second (see DECIMAL, DENOMINATOR below).
         I$ = time interval in days to 2 decimal places.
         i$ = time interval in days as an integer.
           I$ and i$ apply to sec in dt_tm_mak only.
         H$ = time interval in integer hours.
         sam$ = Time in seconds after midnight (DECIMAL works here).
         @  = Carriage Return.
         !  = Line feed.
        DECIMAL=dp  Number of decimal places to use for fraction of
          second (def=3) for f$ in format.  f$ will include dec pt.
          Also applies to fraction shown in sam$.
        DENOMINATOR=den If given then fraction is listed as nnn/ddd
          ddd is given by den.  Over-rides DECIMAL keyword.  Ex:
          DENOM=1000 might give 087/1000 for f$ in format.
        DDECIMAL=ddp Num of dec places in Day of Year (def=none).
 OUTPUTS:
       s = resulting string.                             out
 COMMON BLOCKS:
 NOTES:
       Notes: Some examples: 'h$:m$:s$' -> 09:12:04,
         'd$ n$ Y$' -> 12 Jan 1991, 'd$D h$h' -> 3D 2h, ...
 MODIFICATION HISTORY:
       R. Sterner.  17 Nov, 1988.
       Johns Hopkins University Applied Physics Laboratory.
       RES  20 Apr, 1989 --- 2 digit year.
       R. Sterner, 26 Feb, 1991 --- Renamed from time_date_str.pro
       R. Sterner, 27 Feb, 1991 --- Renamed from tm_dt_str.pro
       R. Sterner, 28 Feb, 1991 --- changed format.
       R. Sterner, 17 Jun, 1992 --- fixed a bug for large sec.
       R. Sterner, 27 Sep, 1993 --- Modified to handle arrays.
       R. Sterner,  2 Dec, 1993 --- Slightly modified def format.
       R. Sterner, 1994 Jun 15 --- Added fraction of second.
       R. Sterner, 1995 Mar  8 --- Added i$ format.
       R. Sterner, 1995 Jul  6 --- Added 0d$ format.
       R. Sterner, 1997 Feb  3 --- Added new keywords 0n$ and doy$ to
       give month as 2 digit number and day of year.
       Matthew Savoie, Systems Technology Associates --- 1997 Feb 5
       fixed a bug by adding floor to: days = long(floor(idays)).
       R. Sterner, 1997 Dec 18 --- Added DDECIMAL=ddec for number of
       decimal places in Day of Year.
       R. Sterner, 1998 Apr 14 --- added sam$ format.
       R. Sterner, 1998 Apr 15 --- Added returned numeric structure.
       R. Sterner, 1998 May 21 --- Fixed a bug found by Dave Watts and
       Damian Murphy that caused a lost second sometimes.
       R. Sterner, 1998 Jul 15 --- A bug was fixed by Tami Kovalick,
       Raytheon STX, 2 digit years failed beyond 1999.
       R. Sterner, 1998 Aug 10 --- Fixed a bug in the way structures are
       indexed for single values.
       R. Sterner, 2000 Jan 03 --- Fixed a problem that came up when year
       ended in 0.  Might even be a touch faster.

 Copyright (C) 1988, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dt_tm_mak.pro)


DT_TM_RANGE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DT_TM_RANGE
 PURPOSE:
       Extract date/time range from string with two date/times.
 CATEGORY:
 CALLING SEQUENCE:
       dt_tm_range, in,js1,js2
 INPUTS:
       in = input string with 2 date/time strings.         in
         Must both have same form (at least same length).
 KEYWORD PARAMETERS:
       Keywords:
         MISSING=def  Defaults for missing date values:
           Must be string with year, month, day in that order.
           Ex: miss='1996 May 12'
           Default for MISSING is current day.
           ERROR=err  Error flag: 0=ok.
 OUTPUTS:
       js1, js2 = returned times as Julian Seconds.        out
 COMMON BLOCKS:
 NOTES:
       Notes: Tries to split input string into 2 equal parts.
         Missing year, month, or day may be added from default.
         If second time is before first then 1 day is added.
         This allows time ranges with only times, default
         applies to first day.
 MODIFICATION HISTORY:
       R. Sterner, 1996 Nov 4

 Copyright (C) 1996, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dt_tm_range.pro)


DT_TM_TOCR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DT_TM_TOCR
 PURPOSE:
       Convert from Date/Time to Carrington Rotation Number.
 CATEGORY:
 CALLING SEQUENCE:
       cr = dt_tm_tocr(dt_tm)
 INPUTS:
       dt_tm = date/time string (or JS).  in
 KEYWORD PARAMETERS:
 OUTPUTS:
       cr = Carrington Rotation Number.   out
 COMMON BLOCKS:
 NOTES:
       Notes: Time is Ephemeris Time which is almost UT.
 MODIFICATION HISTORY:
       R. Sterner, 1996 Jun 21

 Copyright (C) 1996, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dt_tm_tocr.pro)


DT_TM_TOJS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       DT_TM_TOJS
 PURPOSE:
       Convert a date/time string to "Julian Seconds".
 CATEGORY:
 CALLING SEQUENCE:
       js = dt_tm_tojs( dt)
 INPUTS:
       dt = date/time string (may be array).   in
            (see date2ymd for format)
 KEYWORD PARAMETERS:
       Keywords:
         ERROR=err  Error flag: 0=ok, else error.
         /QUIET means inhibit error message.
 OUTPUTS:
       js = "Julian Seconds".                  out
 COMMON BLOCKS:
 NOTES:
       Notes: Julian seconds (not an official unit) serve the
         same purpose as Julian Days, interval computations.
         The zero point is 0:00 1 Jan 2000, so js < 0 before then.
         Julian Seconds are double precision and have a precision
         better than 1 millisecond over a span of +/- 1000 years.
       
         2 digit years (like 17 or 92) are changed to the closest
         corresponding 4 digit year.
       
       See also dt_tm_fromjs, ymds2js, js2ymds, jscheck.
 MODIFICATION HISTORY:
       R. Sterner, 23 Jul, 1992
       R. Sterner, 1994 Mar 29 --- Modified to handle arrays.
       R. Sterner, 1999 aug 04 --- Improved 2 digit year case.
       R. Sterner, 2000 aug 17 --- Added /QUIET

 Copyright (C) 1992, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dt_tm_tojs.pro)


DUMP2FILE

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

 PURPOSE:
	This procedure writes a variable into an ascii file

 CATEGORY:
	DATAFILES

 CALLING SEQUENCE:
	Dump2File, var, file, [/APPEND], [FORMAT = fmt]

 INPUTS:
	var:	variable which should be written to an ascii file
	file:	name of ascii file

 KEYWORD PARAMETERS:
	/APPEND: If set var will be appended to file
	FORMAT = fmt: Format string for formatted output of var

 EXAMPLE:
	a = findgen(10)
	Dump2File, TRANSPOSE(a), 'test.txt', FORMAT = '(5X, F4.1)'

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 03. Sep. 1998
	21.01.99:	debug statement removed
					'Data were dumped into file ' message removed

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\dump2file.pro)


DXBREAK

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

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

 PURPOSE:
   Sets an IDL breakpoint

 CALLING SEQUENCE:
   DXBREAK, LINE                        ; current procedure (OR)"
   DXBREAK, 'PROCNAME', LINE            ; named procedure (OR)"
   DXBREAK, 'path/procname.pro', LINE   ; procedure path (OR)"
   DXBREAK, PROCNAME, LINE              ; without quotes"

 DESCRIPTION: 

   DXBREAK is a convenience routine for setting IDL breakpoints.

   The benefits over the built-in IDL procedure BREAKPOINT are:
     * fewer characters to type;
     * full pathname not required, just a procedure name; and
     * for breakpoints within the current procedure, the file name 
       is not needed.

   To clear breakpoints, use either DXCLEAR or BREAKPOINT, /CLEAR.

 INPUTS:

   LINE - the line number where the breakpoint is to be set.  This
          value is required.

   PROCNAME - the procedure name in which the breakpoint is to be
              set.  Note that IDL requires that a procedure be
              compiled on disk -- console-compiled or .RUN files
              cannot have breakpoints set.

              The name is one of:
                * the procedure or function name;
                * the full path to the procedure or function; OR
                * an unquoted procedure or function name.

              DXBREAK will search your path to find the correct
              procedure.  The first file found will be used.


 KEYWORDS:

   ONCE - if set, then the breakpoint will only occur once.  The same
          as the ONCE keyword to BREAKPOINT.

   IS_FUNCTION - if set, and there is an ambiguity between whether
                 PROCNAME is a procedure or a function, then DXBREAK
                 will assume that it is a function.

 EXAMPLE:

   dxbreak, 'myfunc', 50

   Set breakpoint in MYFUNC at line 50.

 SEE ALSO:

   BREAKPOINT, DXCLEAR

 MODIFICATION HISTORY:
   Written, 15 Apr 2000
   Addition of NOCATCH keyword for internal testing, 21 Sep 2000, CM
   Made mostly compatible with IDL v4, 21 Sep 2000, CM
   Added AFTER keyword, 13 Dec 2000, CM
   Removed AFTER, use _EXTRA instead, 08 Apr 2001, CM

  $Id: dxbreak.pro,v 1.4 2001/04/08 16:59:55 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxbreak.pro)


DXCLEAR

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

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

 PURPOSE:
   Clears an IDL breakpoint

 CALLING SEQUENCE:
   DXCLEAR, INDEX

 DESCRIPTION: 

   DXBREAK is a convenience routine for clearing IDL breakpoints.
   Its primary benefits are that it is symmetric with DXBREAK, and it
   requires fewer characters to type.

 INPUTS:

   INDEX - the breakpoint number, as listed by HELP, /BREAKPOINT.


 EXAMPLE:

   dxclear, 0

   Clear breakpoint number 0

 SEE ALSO:

   BREAKPOINT, DXBREAK

 MODIFICATION HISTORY:
   Written, 15 Apr 2000


  $Id: dxclear.pro,v 1.2 2001/02/09 04:57:15 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxclear.pro)


DXCOMMON

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

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

 PURPOSE:
   Defines DEBUG_LEVEL common block (INTERNAL)

 DESCRIPTION: 

   This code fragment defines the DEBUG_LEVEL common block.  This
   common is internal to the debugging procedures.

  $Id: dxcommon.pro,v 1.2 2001/02/09 04:57:15 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxcommon.pro)


DXDOWN

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

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

 PURPOSE:
   Move the debugging focus deeper down the IDL call stack

 CALLING SEQUENCE:
   DXDOWN [ , NLEVELS ]

 DESCRIPTION: 

   DXDOWN moves the debugging "focus" deeper down the IDL call stack.
   By using this procedure and DXUP, one can navigate up and down an
   existing call stack, and examine and set variables at various
   levels.

   While IDL always keeps the command line at the deepest call level
   (i.e., where the breakpoint occurred), DXDOWN and its related
   debugging procedures maintain a separate notion of which part of
   the call stack they are examining -- the debugging "focus."

   DXDOWN moves the debugging focus deeper by at least one level, but
   never beyond the deepest level.

 INPUTS:

   NLEVELS - option number of levels to move.  Default (and minimum)
             value is 1.

 EXAMPLE:

   dxdown

   Move the debugging focus down one level.

 SEE ALSO:

   DXUP, DXDOWN, DXGET, DXSET

 MODIFICATION HISTORY:
   Written, 15 Apr 2000

  $Id: dxdown.pro,v 1.2 2001/02/09 04:57:16 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxdown.pro)


DXFINISH

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

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

 PURPOSE:
   Sets an IDL breakpoint to stop upon return of the current procedure

 CALLING SEQUENCE:
   DXFINISH [ , NLEVELS ]

 DESCRIPTION: 

   DXFINISH is a convenience routine for setting IDL breakpoints.

   DXFINISH sets a breakpoint so that when the current procedure
   finishes, execution will stop.  Often when debugging one wants to
   let the current procedure complete but stop at the next level.
   DXFINISH does exactly that.

   DXFINISH examines the state of the current IDL call stack,
   determines at what point the current procedure will return, and
   sets a breakpoint there.  Note that the procedure in which the
   breakpoint is set must be compiled and on disk.

   By default the breakpoint is set with the ONCE keyword.

 INPUTS:

   NLEVELS - Number of call levels up to set breakpoint.  Default is
             1.

 KEYWORDS:

   ONCE - if set, then the breakpoint will only occur once.  Default
          value is SET, so ONCE=0 must be passed explicitly to
          disable this function.

 EXAMPLE:

   dxfinish

   Set breakpoint in calling procedure.

 SEE ALSO:

   BREAKPOINT, DXBREAK, DXCLEAR

 MODIFICATION HISTORY:
   Written, 15 Apr 2000

  $Id: dxfinish.pro,v 1.2 2001/02/09 04:57:16 craigm Exp $
  

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxfinish.pro)


DXGET

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

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

 PURPOSE:
   Gets IDL variable from a different IDL call level

 CALLING SEQUENCE:
   RESULT = DXGET('NAME')  ; quoted variable name (OR)
   RESULT = DXGET(NAME)    ; unquoted variable name

 DESCRIPTION: 

   DXGET retrieves a variable value from any point in the IDL call
   stack.  The DXGET and DXSET routines allow any variable at any
   level to be examined and changed.

   The call level to be examined is determined by the current
   debugging "focus."  By default this is the deepest level in the
   call stack -- where the breakpoint occurred.  However, this level
   can be changed by using the DXUP and DXDOWN procedures.

   If the variable doesn't exist, then an error message is reported.

 INPUTS:

   NAME - the name of the variable, either quoted or unquoted.

 KEYWORDS:

   LEVEL - the call level to be examined, if not the current
           debugging focus.

 EXAMPLE:

   value = dxget('a')

   Retrieve the value of the variable A from the debugged call level.

 SEE ALSO:

   DXGET, DXSET, DXUP, DXDOWN

 MODIFICATION HISTORY:
   Written, 15 Apr 2000

  $Id: dxget.pro,v 1.2 2001/02/09 04:57:16 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxget.pro)


DXHELP

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

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

 PURPOSE:
   Perform HELP equivalent at any point in IDL call stack

 CALLING SEQUENCE:
   DXHELP, X0, X1, ..., [ LEVEL=LEVEL ]

 DESCRIPTION: 

   DXHELP performs the equivalent of HELP for the variables at any
   level in the IDL call stack.

   The call level to be examined is determined by the current
   debugging "focus."  By default this is the deepest level in the
   call stack -- where the breakpoint occurred.  However, this level
   can be changed by using the DXUP and DXDOWN procedures.

   If the ALL keyword is set, then all variables are examined.

 INPUTS:

   Xi - variables to be examined, either quoted or unquoted.
        Non-string expressions are diagnosed, but of course refer to
        the deepest call level.  If the ALL keyword is set then the
        Xi parameters are ignored.

 KEYWORDS:

   LEVEL - the call level to be examined, if not the current
           debugging focus.

   ALL - if set, then all variables at the current focus level are
         examined.


 EXAMPLE:

   dxhelp

   Print all variables at current debugging focus level

 SEE ALSO:

   DXUP, DXDOWN, DXHELP, DXPRINT

 MODIFICATION HISTORY:
   Written, 15 Apr 2000
   Added ALL keyword; changed N_PARAMS() EQ 0 behavior, CM 17 Apr
     2000
   DXHELP_VALUE now prints correct string and byte values, CM 23 Apr
     2000
   Add support for printing structures with FULL_STRUCT, CM 08 Feb
     2001
   Added forward_function for DXHELPFORM, CM 08 Apr 2001
   Print more info about POINTER type, CM 30 Apr 2001
   

   $Id: dxhelp.pro,v 1.5 2001/04/30 15:26:53 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxhelp.pro)


DXLRESET

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

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

 PURPOSE:
   Reset the current debugging focus level (INTERNAL)

 CALLING SEQUENCE:
   DXLRESET

 DESCRIPTION: 

   DXLRESET resets the current debugging focus level, if it has
   changed.  This routine is internal to the debugging procedures.

 SEE ALSO:

   DXUP, DXDOWN, DXGET, DXSET

 MODIFICATION HISTORY:
   Written, 15 Apr 2000

  $Id: dxlreset.pro,v 1.2 2001/02/09 04:57:16 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxlreset.pro)


DXPLEVEL

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

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

 PURPOSE:
   Print the current call stack (INTERNAL)

 CALLING SEQUENCE:
   DXPLEVEL

 DESCRIPTION: 

   DXLRESET prints the current call stack, and highlights the
   debugging focus level.This routine is internal to the debugging
   procedures.

 SEE ALSO:

   DXUP, DXDOWN, DXGET, DXSET

 MODIFICATION HISTORY:
   Written, 15 Apr 2000

  $Id: dxplevel.pro,v 1.2 2001/02/09 04:57:17 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxplevel.pro)


DXPRINT

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

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

 PURPOSE:
   Perform HELP equivalent at any point in IDL call stack

 CALLING SEQUENCE:
   DXPRINT, X0, X1, ... [, LEVEL=LEVEL, FORMAT=FORMAT ]

 DESCRIPTION: 

   DXPRINT prints the values of variables from any level in the IDL
   call stack.

   The call level to be examined is determined by the current
   debugging "focus."  By default this is the deepest level in the
   call stack -- where the breakpoint occurred.  However, this level
   can be changed by using the DXUP and DXDOWN procedures.

 INPUTS:

   Xi - variables to be printed, unquoted.  Non-string expressions
        are printed, but of course refer to the deepest call level.

 KEYWORDS:

   LEVEL - the call level to be examined, if not the current
           debugging focus.

   FORMAT - format string to be applied to data values.


 EXAMPLE:

   dxprint, a, b

   Print A and B from the current debugging focus level

 SEE ALSO:

   DXUP, DXDOWN, DXHELP, DXPRINT

 MODIFICATION HISTORY:
   Written, 15 Apr 2000
   Corrected FORMAT statement, 30 Jun 2001

  $Id: dxprint.pro,v 1.3 2001/06/30 19:56:04 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxprint.pro)


DXPTRACE

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

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

 PURPOSE:
   Parse the current call stack (INTERNAL)

 CALLING SEQUENCE:
   RESULT = DXPTRACE(STRING)

 DESCRIPTION: 

   DXPTRACE is a function which parses the call stack, as returned by
   HELP, /CALL.  It is internal to the debugging routines.

 SEE ALSO:

   DXUP, DXDOWN, DXGET, DXSET

 MODIFICATION HISTORY:
   Written, 15 Apr 2000

  $Id: dxptrace.pro,v 1.2 2001/02/09 04:57:17 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxptrace.pro)


DXSET

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

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

 PURPOSE:
   Sets IDL variable in a different IDL call level

 CALLING SEQUENCE:
   DXSET, 'NAME', VALUE    ; quoted variable name (OR)
   DXSET,  NAME,  VALUE    ; unquoted variable name

 DESCRIPTION: 

   DXSET sets a variable value at any point in the IDL call stack.
   The DXGET and DXSET routines allow any variable at any level to be
   examined and changed.

   The call level to be examined is determined by the current
   debugging "focus."  By default this is the deepest level in the
   call stack -- where the breakpoint occurred.  However, this level
   can be changed by using the DXUP and DXDOWN procedures.

   If the variable doesn't exist, then an error message is reported,
   and the variable is not set.

 INPUTS:

   NAME - the name of the variable, either quoted or unquoted.

   VALUE - the new value of the variable.

 KEYWORDS:

   LEVEL - the call level to be examined, if not the current
           debugging focus.

 EXAMPLE:

   dxset, 'a', 5

   Set the value of the variable A to 5 in the currently debugged
   call level.

 SEE ALSO:

   DXGET, DXSET, DXUP, DXDOWN

 MODIFICATION HISTORY:
   Written, 15 Apr 2000

  $Id: dxset.pro,v 1.2 2001/02/09 04:57:18 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxset.pro)


DXUP

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

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

 PURPOSE:
   Move the debugging focus higher up the IDL call stack

 CALLING SEQUENCE:
   DXUP [ , NLEVELS ]

 DESCRIPTION: 

   DXUP moves the debugging "focus" higher up the IDL call stack.  By
   using this procedure and DXDOWN, one can navigate up and down an
   existing call stack, and examine and set variables at various
   levels.

   While IDL always keeps the command line at the deepest call level
   (i.e., where the breakpoint occurred), DXUP and its related
   debugging procedures maintain a separate notion of which part of
   the call stack they are examining -- the debugging "focus."

   DXUP moves the debugging focus higher by at least one level, but
   never beyond the "root" $MAIN$ level.

 INPUTS:

   NLEVELS - option number of levels to move.  Default (and minimum)
             value is 1.

 EXAMPLE:

   dxup

   Move the debugging focus up one level.

 SEE ALSO:

   DXUP, DXDOWN, DXGET, DXSET

 MODIFICATION HISTORY:
   Written, 15 Apr 2000

  $Id: dxup.pro,v 1.2 2001/02/09 04:57:18 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxup.pro)


DYDX

[Previous Routine] [Next Routine] [List of Routines]
 ROUTINE:    dydx

 PURPOSE:    compute numerical derivative accurate to second order. 
             In most cases this should be more accurate than the 
             IDL userlib procedure DERIV.

 USEAGE:     dydx(x,y)

 INPUT:
    x        vector of independent variable (monitonic)
    y        vector of dependent variable

 KEYWORD INPUT:
   lin_end   if set, use a one sided linear approximation for end points

 OUTPUT:     numerical derivative dy/dx

 EXAMPLE:    
     !p.multi=[0,1,2]
     x=[0.,1.,3.,8.,10.,13.,17.,19.,22.,25.]
     y=x*(25-x) & yp=25-2*x & labels=['analytic','dydx','deriv']
     plot,x,y,title='quadratic [dydx(x,y) is exact in this case]'
     plot,x,yp & oplot,x,dydx(x,y),psym=2 & oplot,x,deriv(x,y),psym=4
     legend,labels,li=[0,0,0],psym=[0,2,4],pos=[0.5,0.7,0.75,0.98]

     x=[0.0,0.5,1.5,2.,3.,3.6,4.0,5.,6.,6.3]
     y=sin(x) & yp=cos(x) 
     plot,x,y,title='sin(x)'
     plot,x,yp & oplot,x,dydx(x,y),psym=2 & oplot,x,deriv(x,y),psym=4
     legend,labels,li=[0,0,0],psym=[0,2,4],pos=[0.25,0.7,0.50,0.98]

     x=[-2.,-1.,-.7,-.3,-.1,0.,.1,.3,.7,1.,2]
     y=exp(-x^2) & yp=-2*x*y
     plot,x,y,title='gausian'
     plot,x,yp & oplot,x,dydx(x,y),psym=2 & oplot,x,deriv(x,y),psym=4
     legend,labels,li=[0,0,0],psym=[0,2,4],pos=[0.5,0.7,0.75,0.98]
             

 REVISIONS:

  author:  Paul Ricchiazzi                            jan94
           Institute for Computational Earth System Science
           University of California, Santa Barbara

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\dydx.pro)


EARTHDIST

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

 PURPOSE:
       Calculate the great circle distance (in km) based on lats and lons.  

 CALLING SEQUENCE:
       dist = earthdist(lat1,lon1,lat2,lon2)

 INPUTS:
      lat1        latitude of first point
      lon1        longitude of first point
      lat2        latitude of second point
      lon2        longitude of second point

 KEYWORD INPUTS:

 OPTIONAL INPUTS:

 OUTPUTS:
       Distance along great circle returned.

 OPTIONAL OUTPUTS:

 EXAMPLE:
  
      print,earthdist(0,0,0,1)
      111.189

 PROCEDURE

 COMMON BLOCKS:
       None.

 NOTES

 REFERENCES
 
 AUTHOR and DATE:
     Jeff Hicke     Earth Space Research Group, UCSB  4/05/94

 MODIFICATION HISTORY:

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\earthdist.pro)


EARTHRAD

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       EARTHRAD
 PURPOSE:
       Return earth radius in specified units.
 CATEGORY:
 CALLING SEQUENCE:
       r = earthrad(units)
 INPUTS:
       units = Units for earth radius (def='radians').   in
 KEYWORD PARAMETERS:
 OUTPUTS:
       r = returned earth radius in requested units.     out
 COMMON BLOCKS:
 NOTES:
       Notes: Available units (use 2 letters min):
         'radians' Radians (default).
         'degrees' Degrees.
         'nmiles'  Nautical miles.
         'miles'   Statute miles.
         'kms'     Kilometers.
         'meters'  Meters.
         'yards'   Yards.
         'feet'    Feet.
 MODIFICATION HISTORY:
       R. Sterner, 1996 Sep 03

 Copyright (C) 1996, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\earthrad.pro)


EASY_GET_AIX_SETTING

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

 PURPOSE:
   This procedure will type the contents of the file 'aix_setting.txt' into the log-window.

 CATEGORY:
   CASE_TOOLS

 CALLING SEQUENCE:
   easy_get_aix_setting

 OUTPUTS:
   result: correct combination of path and file

 EXAMPLE:
   easy_get_aix_setting

 MODIFICATION HISTORY:
   Written by Franz Rohrer Jan 1999

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\easy_get_aix_setting.pro)


EASY_PLOT_COMPLEX_EXAMPLE

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

 PURPOSE:
   This is a complex example to show the capabilities of easy_plot

 CATEGORY:
   EXAMPLES

 CALLING SEQUENCE:
   easy_plot_complex_example

 MODIFICATION HISTORY:
   Written by: Frank Holland, 15. Nov. 98.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\examples\easy_plot_complex_example.pro)


EASY_PLOT_SIMPLE_EXAMPLE

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

 PURPOSE:
   This is a simple example to show the capabilities of easy_plot

 CATEGORY:
   EXAMPLES

 CALLING SEQUENCE:
   easy_plot_simple_example

 MODIFICATION HISTORY:
   Written by: Frank Holland, 15. Nov. 98.
		17.02.99:	Added a 2nd example

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\examples\easy_plot_simple_example.pro)


EI

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

 PURPOSE:
       Set the system variable to allow for large pasting of data using
       X.  Only necessary for the alphas.  This has the side effect of 
       not allowing use of the editing (arrow) keys.  This procedure
       toggles this ability on and off.  NOTE:  This is probably a bug
       in IDL and therefore the need for this procedure will disappear in
       the near future.

 CALLING SEQUENCE:
       ei

 INPUTS:

 OPTIONAL INPUTS:

 OUTPUTS:

 EXAMPLE:
     ei
     ... paste in large amts of data ...
     ei

 PROCEDURE

 COMMON BLOCKS:
       None.

 NOTES

 REFERENCES
 
 AUTHOR and DATE:
     Jeff Hicke     Earth Space Research Group, UCSB  1/04/94

 MODIFICATION HISTORY:

     Added change of prompt  Jeff Hicke   05/20/94

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\ei.pro)


ELECTRON_MFP

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

 PURPOSE:
 
	This function returns the elastic mean-free-path for electrons
	of energy E, in a material having density N, and atomic number Z.

 CALLING SEQUENCE:
 
	Result = ELECTRON_MFP(Z,A,RHO,E)

 INPUTS:
	
	Z = Atomic number
	
	A = Atomic weight (g/mole)
	
	RHO = Density (g/cm3)
	
	E = electron energy in keV

 OUTPUTS:
 
	This function returns the elastic mean-free-path, in angstroms.

 EXAMPLE:

       The elastic mean-free-path of tungsten (Z=74, Rho=19.35) at an
       electron energy of 100 keV = ELECTRON_MFP(74,183.85,19.35,100.)

 MODIFICATION HISTORY:
 
	Written by D. L. Windt, Bell Labs, June 1994
	windt@bell-labs.com

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\windt\electron_mfp.pro)


ELLFIT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ELLFIT
 PURPOSE:
       Fit an ellipse to a 2-d probability distribution.
 CATEGORY:
 CALLING SEQUENCE:
       ellfit, pd, xm, ym, ang, ecc, a, b
 INPUTS:
       pd = 2-d probability distribution.                  in
 KEYWORD PARAMETERS:
 OUTPUTS:
       xm, ym = Mean X and Y coordinates (array indices).  out
       ang = angle of major axis (deg).                    out
       ecc = eccentricity of fitted ellipse.               out
       a, b = semimajor, semiminor axis of fitted ellipse. out
 COMMON BLOCKS:
 NOTES:
       Notes: An ellipse is fit by matching its moment of inertia
         to the given array.  A threshold image should be
         normalized to 1 before doing the fit, otherwise the
         ellipse will not be the correct size.
         See also genellipse.
         Here is a simple example:
           loadct,13
           d = rebin(shift(dist(200),100,100),200,400)
           z = rot(d,30) lt 50
           tvscl,z
           ellfit,z,xm,ym,ang,ecc,a,b
           genellipse,xm,ym,ang,a,b,x,y
           plots,x,y,/dev,color=!d.n_colors/2
 MODIFICATION HISTORY:
       R. Sterner.  10 June, 1986.

 Copyright (C) 1986, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\ellfit.pro)


ELLIPSE[1]

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ELLIPSE
 PURPOSE:
       Plot specified ellipse on the current plot device.
 CATEGORY:
 CALLING SEQUENCE:
       ellipse, a, b, tilt, a1, a2, [x0, y0]
 INPUTS:
       a = semi-major axis of ellipse (data units).                 in
       b = semi-minor axis of ellipse (data units).                 in
	[tilt] = angle of major axis (deg CCW from X axis, def=0).   in
       [a1] = Start angle of arc (deg CCW from major axis, def=0).  in
       [a2] = End angle of arc (deg CCW from major axis, def=360).  in
       [x0, y0] = optional arc center (def=0,0).                    in
 KEYWORD PARAMETERS:
       Keywords:
         /DEVICE means use device coordinates .
         /DATA means use data coordinates (default).
         /NORM means use normalized coordinates.
         COLOR=c  plot color (scalar or array).
         LINESTYLE=l  linestyle (scalar or array).
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
       Note: all parameters may be scalars or arrays.
 MODIFICATION HISTORY:
	D P Steele, ISR, 27 Oct. 1994: modified from ARCS.PRO by R. Sterner.
	Department of Physics and Astronomy
	The University of Calgary

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\ellipse.pro)


ELLIPSE[2]

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		ELLIPSE
 VERSION:
		4.0
 PURPOSE:
		Draws an ellipse, around CENTER, with radii given by RADII, optionally
		rotating it by angle ROT.  The drawing is done in the currently
		defined plot area.  Alternatively, a *SHAPE* representation (see
		SHAPE_VER for definition) of the ellipse may be returned through the
		SHAPEOUT keyword.  DATA coordinate system is assumed unless specified
		otherwise by one of the keywords /DEVICE or /NORMAL.
 CATEGORY:
		General Graphics.
 CALLING SEQUENCE:
		ELLIPSE, CENTER = CENT, RADII = RD, [, optional keywords]
 INPUTS:
		None.
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
	CENTER
		2 dimensional vector, ellipse center location, format [x,y], mandatory.
	RADII
		2 dimensional vector, contains the x and y radii (in order), mandatory.
	ARC
		Optional.  Allows to draw an elliptical arc.  Accepts a vector of
		length 2 containing the start and end angles for the arc.  If only one
		value is provided, the arc is drown from angle 0 to this value if it is
		positive, or from this value to 0 if it is negative.  The angles are
		assumed to be in radians unless DEGREES is set.
	/DEGREES
		Switch.  Specifies that the rotation (and arc) angles are given in
		degrees.
	ROTATE
		Optional.  Angle of rotation in the mathematical positive direction.
		Assumed in radians, unless DEGREES is set.
	ROTATION_CENTER
		Optional.  Accepts a two element vector specifying the center of
		rotation.  Ignored if ROTATE is not given.  Defaults to center of shape.
	/FILL
		Switch.  Causes the ellipse to be filled with a solid pattern.
	/DEVICE
		Standard IDL plotting interpretation.
	/NORMAL
		Ditto.
	/NO_SHOW
		Switch.  If set, no plotting is done, but the shape is generated and
		may be returned through SHAPEOUT.
	SHAPEOUT
		Optional output, see below.
	_EXTRA
		A formal keyword used to pass all plotting keywords.  Not to be used
		directly.  See comment in RESTRICTIONS.
 OUTPUTS:
		None.
 OPTIONAL OUTPUT PARAMETERS:
	SHAPEOUT
		When provided with the name of a variable,on return the variable
		contains the *SHAPE* representation of the ellipse.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		If the DATA coordinate system is used and the plot area is defined with
		nonlinear (logarithmic) axes, the shape won't look like an ellipse.
		ELLIPSE calls either PLOTS or (when /FILL is used) POLYFILL.  Since
		some graphics keywords work only with PLOTS, or only with POLYFILL,
		some care must be exercised.
 PROCEDURE:
		Uses calls to DEFAULT, ONE_OF, SHAPE_COCON and SHAPE_TRANS from MIDL.
		Generates a (2,N) array containing a sufficient number of ellipse
		points to yield a smooth curve.  N is variable, depending both on the
		ellipse size and on the pixel size of the current output device.
 MODIFICATION HISTORY:
		Created 15-JUL-1991 by Mati Meron.
		Modified 15-DEC-1991 by Mati Meron.  Added size and device dependence
		of the number of plot points.
		Modified 15-OCT-1992 by Mati Meron.  Added rotation.
		Modified 15-DEC-1993 by Mati Meron.  Now ELLIPSE takes advantage of the
		keyword inheritance property and accepts all IDL plotting keywords.
		Modified 1-MAY-1995 by Mati Meron.  Added capability to draw an
		elliptical arc.
		Modified 25-JUL-1999 by Mati Meron.  Added keyword SHAPEOUT.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\ellipse.pro)


EMBED

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       EMBED
 PURPOSE:
       Embed an array in a larger array.
 CATEGORY:
 CALLING SEQUENCE:
       b = embed(a,w)
 INPUTS:
       a = input array (2-d).                      in
       w = number of elements to add around edge.  in
 KEYWORD PARAMETERS:
       Keywords:
         VALUE=v.  Value for added border (def=0).
 OUTPUTS:
       b = resulting larger array with a centered. out
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 13 Dec, 1990

 Copyright (C) 1990, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\embed.pro)


EMBEDSTR

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

 PURPOSE:
   This function attachs one stringarray to another stringarray reducing posibble n-dimensional fields to a vector

 CATEGORY:
   PROG_TOOLS/STRINGS

 CALLING SEQUENCE:
	Result=embedstr(string1=string1,string2=string2)

 INPUTS:
   String1: first string array
   String2: second string array

 OUTPUTS:
   The function returns a stringarray where stringarray 1 is concatenaded
   to stringarray 2


 EXAMPLE:
   test1=sindgen(2,2)
   test2=sindgen(3)
   Result=embedstr(string1=test1,string2=test2)
   print,result
           0            1            2            3            0            1            2


 MODIFICATION HISTORY:
 	Written by:	R.Bauer (ICG-1), Jan. 3 1997
   1999-Nov-06 help added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\embedstr.pro)


EMENSCH

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

 PURPOSE:
  This function can be used by 'axis' to define axis-labels in a better readable format

 CATEGORY:
  PLOT/PLOTXY

 CALLING SEQUENCE:
       emensch,axis,index,t

 INPUTS:
      axis  : for future use
      index : for future use
      t     : the value which should be formatted


 EXAMPLE:
       axis,xaxis=1,/xtype,xrange=[1e-4,10],xstyle=1,/save,xtickformat='emensch'

 MODIFICATION HISTORY:
  Written by: Franz Rohrer April 1997

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\emensch.pro)


ENDIAN

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ENDIAN
 PURPOSE:
       Function indicating which endian the current machine uses.
 CATEGORY:
 CALLING SEQUENCE:
       f = endian()
 INPUTS:
 KEYWORD PARAMETERS:
       Keywords:
         /LIST means list result to screen.
         /TEXT means return /LIST text.
 OUTPUTS:
       f = 0 if little, 1 if big.     out
 COMMON BLOCKS:
 NOTES:
       Note: this is the order the bytes are for multibyte
         numeric values.  Use the IDL procedure BYTEORDER
        to switch endian (use /LSWAP for 4 byte integers,
        /L64SWAP for 8 byte integers).
 MODIFICATION HISTORY:
       R. Sterner, 1999 Dec 13
       R. Sterner, 2000 Apr 11 --- Added /TEXT

 Copyright (C) 1999, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\endian.pro)


ENDPS

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

 PURPOSE:
         close postscript file, reopen display

 CALLING SEQUENCE:
       ENDPS

 INPUTS:

 KEYWORD INPUTS:
        notime     don't timestamp

 OPTIONAL INPUTS:

 OUTPUTS:

 OPTIONAL OUTPUTS:

 EXAMPLE:

 PROCEDURE

 COMMON BLOCKS:
       None.

 NOTES

 REFERENCES
 
 AUTHOR and DATE:
     Jeff Hicke     Earth Space Research Group, UCSB  9/22/92

 MODIFICATION HISTORY:

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\endps.pro)


END_MPLOT

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

 PURPOSE:
   Restores default values of
   !P.MULTI, !X.OMARGIN, !Y.OMARGIN, !X.MARGIN, !Y.MARGIN
   which were changed in init_mplot

 CATEGORY:
   PLOT/MPLOT

 CALLING SEQUENCE:
   end_mplot [, save_sysvar]

 OPTIONAL INPUTS:
   save_sysvar: structure with the following tags (from init_mplot):
      pm:  !P.MULTI
      xom: !X.OMARGIN
      yom: !Y.OMARGIN
      xm:  !X.MARGIN
      ym:  !Y.MARGIN

      The system variables will be restored to these data.

 REVISION HISTORY:
       Written Theo Brauers, Frank Holland, June 1997
       02.02.2000: Added input parameter save_sysvar (FH)

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\end_mplot.pro)


ENTER

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ENTER
 PURPOSE:
       Prompted entries allowing defaults. Help, IDL/DCL commands.
 CATEGORY:
 CALLING SEQUENCE:
       value = enter(type, prompt, default, [exit_flag, help_text])
 INPUTS:
       type = Data type to return.                     in
          Allowed types are:
          'STRING' = string
          'BYTE' = byte
          'INTEGER' = integer
          'LONG' = long integer
          'FLOAT' = float
          'DOUBLE' = double float
       prompt = prompt string.                         in
          Any occurence of $DEF in the prompt string
          is replaced by the default value, so the
          prompt message may display the default.
       default = default value.                        in
       help_text = text to display for ? command.      in
          String or string array for multiple lines.
          $DEF in the help string is replaced by
          the def. value.
 KEYWORD PARAMETERS:
 OUTPUTS:
       exit_flag = exit status flag.                   out
          Valid values are:
           0 = normal exit.
           1 = quit on return.
          -1 = backup to last entry.
          11 = invalid data type.
          12 = def. val. cannot convert to desired
               data type.
       value = returned value of desired type.         out
 COMMON BLOCKS:
 NOTES:
       Notes: The following commands are allowed as ENTER entries:
         Value requested.
         Null entry. Gives default value
           (for calling error may return error flag).
         Expressions. Processes given IDL expression.
         Q. Returns quit value (1) in exit flag.
         B. Returns backup value (-1) in exit flag.
         IDL statment. Executes given IDL statement.
         $ statement. Executes given shell statement.
 MODIFICATION HISTORY:
       R. Sterner.  17 Oct, 1986.
       RES 9 OCT, 1989 --- CONVERTED TO SUN.
       RES 13 Nov, 1989 --- put $DEF in prompt and help_text.
       R. Sterner, 27 Jan, 1993 --- dropped reference to array.

 Copyright (C) 1986, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\enter.pro)


ENVELOPE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ENVELOPE
 PURPOSE:
       Return the min/max envelope of a time series.
 CATEGORY:
 CALLING SEQUENCE:
       envelope, y, w, mn, mx, ind
 INPUTS:
       y = time series signal.                 in
       w = window width in samples.            in
 KEYWORD PARAMETERS:
 OUTPUTS:
       mn = array of mins in each window.      out
       mx = array of maxes in each window.     out
       ind = array of window midpoint indices. out
 COMMON BLOCKS:
 NOTES:
       Notes: data type of mn and mx are the same as
         input array y.
         To overplot envelope do:
           oplot,ind,mn & oplot,ind,mx
         To polyfill the envelope do:
           polyfill, [ind,reverse(ind)],[mn,reverse(mx)]
 MODIFICATION HISTORY:
       R. Sterner, 19 Sep, 1991

 Copyright (C) 1991, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\envelope.pro)


ENZ2HTML

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

 PURPOSE:
   write a html file with info of about an enzfile, produce
   overview plots of the datasets.

 CATEGORY:
   DATAFILES/ZCHN

 CALLING SEQUENCE:
   ENZ2HTML, file_name, html_name, ps_name

 INPUTS:
   file_name: the name of the enz data File

 OUTPUTS:
   ps_name: the name of the ps graph
   html_name: the name of the htmlfile

 MODIFICATION HISTORY:
   Written by: T.Brauers

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\enz2html.pro)


ENZTIME2JS

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

 PURPOSE:
   converts time info in ENZ/ZEICHN file to julsec

 CATEGORY:
   DATAFILES/ZCHN

 CALLING SEQUENCE:
   Result = ENZTIME2JS(dvalue, ix, ref)

 INPUTS:
   dvalue:   array of values (output of IRZN)
   ix:       number of records (output of IRZN)
   ref:      reference date

 OUTPUTS:
   array with julian seconds

 EXAMPLE:
   IRZN, 'TEST.ZEICHN', dvalue, ix, iy, fb, text, header, err
   ref = text[0]
   js  = ENZTIME2JS(dvalue, ix, ref)

 REVISION HISTORY:
   Written         Theo Brauers, June 1997
   Corrected
   Revised     T.B. Sep 1997
   Revised     T.B. Oct 1997, renamed to enztime2js
   Modified    T.B. Feb 1999, new keywords Reference and nomessage
                              different interpretation reference date

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\enztime2js.pro)


ENZ_GET_PARAM

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

 PURPOSE:
   to read one parameter from a enz/zus-file and return the result as a ncdf-like structure

 CATEGORY:
   DATAFILES/ZCHN

 CALLING SEQUENCE:
   enz_get_param,file=file,name=name,inhalt=inhalt[,zus=zus][,fill_value=fill_value][,nocache=nocache]

 INPUTS:
   file   : file name
   name   : parameter name

 KEYWORD PARAMETERS:
    zus        : 0: enz-file (default)   1: zus-file
    fill_value : fill_value for irzn
    nocache    : to suppress caching of enz/zus-file

 OUTPUTS:
   inhalt : ncdf-like structure

 COMMENT:
   Has to be improved to handle other ncdf-tags as defined in ncdf-header

 EXAMPLE:

 MODIFICATION HISTORY:
   Written by:     Franz Rohrer  Aug 1998
   Modified   7.10.98  FR nocache included

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\enz_get_param.pro)


ENZ_HEADER2NCDF_STRUCTURE

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

 PURPOSE:
	This procedure converts the header of an enz file into ncdf structures

 CATEGORY:
	DATAFILES/FILTER

 CALLING SEQUENCE:
	enz_header2ncdf_structure, header, global_struc, time_struc, param_struc

 INPUTS:
	header: header of enz file as returned by cache_enz

 KEYWORD PARAMETERS:
	/NO_TIME_FLAG: If set time_struc will be returned without flag: 'INTERVAL_T'
	/VERBOSE: Informational messages will be issued by this program

 OUTPUTS:
	global_struc: structure with global attributes of the dataset as
		defined for the ICG structure. Also includes experiment specific information.
	time_struc: structure with time attributes of the dataset as
		defined for the ICG structure.
	param_struc: structure with parameter attributes of the dataset as
		defined for the ICG structure.

 RESTRICTIONS:
	The translation of the enz header into ncdf structures requires the
	following structure of the enz header:

	------------------------snip-------------------------------------------
	...							; any information (not considered)
	X_HEADER=NETCDF_GLOBAL
	...							; any entry (KEYWORD=VALUE) in this section
	...							; is translated into global_struc
	...							; if KEYWORD is identified as a valid global keyword.
	X_HEADER=NETCDF_EXPERIMENT
	...							; any entry (EXP_NAME: KEYWORD=VALUE) in this section
	...							; is translated into exp_struc which will be returned
	...							; as tag of global_struc.
	X_HEADER=NETCDF_TIME
	...							; any entry (KEYWORD=VALUE) in this section
	...							; is translated into time_struc
	...							; if KEYWORD is identified as a valid time keyword.
	X_HEADER=NETCDF_PARAMETER
	...							; any entry (KEYWORD=VALUE) in this section
	...							; is translated into param_struc
	...							; if KEYWORD is identified as a valid parameter keyword.
	X_HEADER=ENZ
	...							; any information (not considered)
	------------------------snip-------------------------------------------

 EXAMPLE:
	see ex_enz_header2ncdf_structure

 MODIFICATION HISTORY:
 	Written by:	Frank Holland, 24.06.1999
	25.06.1999: Kommentar eingefügt
	09.08.1999:	New keyword parameter NO_TIME_FLAG
	10.08.1999:	New keyword parameter VERBOSE
	25.10.1999: Bug removed if pstruc was not defined
	18.11.1999:	Bug removed if enz file was written by write_enz [() entries in header]
	10.03.2000:	Added X_HEADER = NETCDF_EXPERIMENT section for experiment specific information
	27.03.2000:	Extract allowed tag names from nc_def_... routines (code not activated yet)
	28.03.2000:	Added alias time tags

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\enz_header2ncdf_structure.pro)


ENZ_INFO

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

 PURPOSE:
       returns a structure with info about
       a ZEICHN file (KFA ICG3 data format)

 CATEGORY:
       DATAFILES/ZCHN

 CALLING SEQUENCE:
       file_info=ENZ_INFO(dvalue,ix,iy,fb,text,header,filename)

 INPUTS:
       the output of the irzn

 KEYWORD PARAMETERS:
   Keywords:
      fill_value: do not process data equal fill_value

 OPTIONAL INPUTS:

 OUTPUTS:
    a structure of info about a ncdf-file see create_info_struct for details
      .file_info.name           : name of file
      .file_info.filetype       : 'zus'
      .file_info.filedate       : date of file
      .record_info.jstime[0] : start-time in julian seconds (double)
      .record_info.jstime[1] : end-time in julian seconds   (double)
      .record_info.ntime[0]  : start-time in normal date and time (string)
      .record_info.ntime[1]  : end-time in normal date and time   (string)
      .record_info.n_records :number of rows
      .record_info.n_sets    :number of columns
      .pi.pi_name   :
      .pi.email     :
      .pi.phone_number :
      .pi.organisation :
      .hrefs.ps   : 'ps'  (reference to ps-file: filename+.ps )
      .hrefs.data : 'data'
      .hrefs.html : 'html' (reference to html-file: filename + .savinfo.html )
      .data.text   :string-array : description of a data columnstring-array
      .data.nvalid :array containing the number of valid values of a column
      .data.mean   :array containing the avarage values of a data column
      .data.median :array containing the median values of a data column
      .data.stdev  :array containing the standard deviation of a column
      .data.minimum:array containing the lowest values of a data column
      .data.maximum:array containing the greatest values of a data column
      .header.text :string array containing the header of the file (like output of IRZN)
      .experiment.text  :containing the text of structure experiment

 EXAMPLE:
       IRZN, filename, dvalue, ix, iy, fb, text, header, err
       file_info=ENZ_INFO(dvalue,ix,iy,fb,text,header,filename)

 REVISION HISTORY:
       Written         Marsy Lisken, June 1998
       Corrected                  10.7. 1998
       Revised

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\enz_info.pro)


ENZ_NCDF

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

 PURPOSE:
     This Procedure generates the structure INHALT for an ENZ-file
     and writes it to a ncdf-file

 CATEGORY:
     DATAFILES/ZCHN

 CALLING SEQUENCE:
     enz_ncdf,fname,new_fname,fillvalue=xl,err,errmess=errmess,options

 INPUTS:
     fname:     the name of the ENZ-file (string-var)
     new_fname: the name of the ncdf-file (string-var)
                optional, default: new_fname=fname.nc
     options:   optional

 KEYWORD PARAMETERS:
     fillvalue: the numeric value for '====' input
                default: -12345
     errmess:   returns a error message
     nowrite:   no netcdf file will be written

 OUTPUTS:
     err:       flag indicating error  err=1 : no parameter
                                       err=2 : filesize <0      (output of IRZN)
                                       err=3 : no header found        (  "     )
                                       err=4 : number of columns=0    (  "     )
                                       err=5 : overwriting label      (  "     )
 OPTIONAL OUTPUTS:
 inhalt: the defined structure inhalt

 SIDE EFFECTS:
     uses the procedures IRZN, RPL_STR, HEADKEYS, ZCHN_KEYS
                         TENZ2JS,JS2INST
                         JD2YMD (Ray Sterner Lib)
                         @gen_inh2, NCDF_W, NCDF_CH

 EXAMPLE:
     ENZ_NCDF,'t.enz','test.nc',err

     result=f_history('test.nc') ---> (history contains the whole header)

 MODIFICATION HISTORY:
     Written       Theo Brauers, June 1997
     Completed     Marsy Lisken, January 1998
     Revised

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\enz_ncdf.pro)


EOPDATA

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

 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:
   Read and interpolate tabulated earth orientation parameters

 MAJOR TOPICS:
   Geometry

 CALLING SEQUENCE:
   EOPDATA, JDUTC, PMX, PMY, UT1_UTC, DPSI, DEPS, $
        /RESET, FILENAME=, ANGUNITS=, TBASE=

 DESCRIPTION:

  The procedure EOPDATA reads, interpolates and returns Earth
  orientation parameters used for precision earth-base astronomy
  applications.

  ** NOTE: The user is responsible for downloading and maintaining an
  up-to-date file of earth orientation parameters from the
  International Earth Rotation Service.  See below. **

  This interface is somewhat provisional.  See OPEN QUESTIONS below.

  The values returned are described below.  These descriptions are
  taken from the Explanatory Supplement to IERS Bulletins A and B.

    * PMX and PMY, the coordinates of the Celestial Ephemeris Pole
      (CEP) relative to the earth-fixed International Reference Pole
      (IRP).  The x-axis is in the direction of the IERS Reference
      Meridian (IRM), the y-axis is in the direction 90 degrees West
      longitude.  The time series of PMX and PMY is referred to as
      "polar motion."

      These are the coordinates of the earth rotation pole, as seen
      in an *earth-fixed* coordinate system.  A station whose
      coordinates are given in earth-fixed coordinates referred to
      the ITRS can be transformed to the earth-fixed coordinates
      referred to the true rotation pole of date using the following
      matrix transformation:
            
             R_TRUE = RX(PMY) ## RY(PMX) ## R_ITRS

      where the matrices RX and RY are defined below.

    * UT1, the the rotation angle about the pole. It is related to
      the Greenwich mean sidereal time (GMST) by a conventional
      relationship (Aoki et al., 1982).  It gives access to the
      direction of the International Reference Meridian IRM in the
      ICRS, reckoned around the CEP axis. It is expressed as the
      difference UT1-UTC.  Thus, the value of UT1 is computed as:

          UT1 = UT1_UTC + UTC

      where UTC is the UTC time, expressed in seconds.

    * DPSI and DEPS are the offsets in longitude and obliquity of the
      celestial pole with respect to its direction defined using the
      conventional IAU precession/nutation theory.  An a priori
      correction model is available in the IERS Conventions (1996),
      (McCarthy, 1996).  The expressions to compute the nutation
      angles are:

          DEPS_TRUE = DEPS_1980 + DEPS    ;; Nutation in obliquity
          DPSI_TRUE = DPSI_1980 + DPSI    ;; Nutation in longitude

      where DPSI_1980 and DEPS_1980 are the nutation values
      determined from the IAU 1980 Nutation Theory; and DPSI_TRUE and
      DEPS_TRUE are the nutations to be used as arguments to further
      precession and nutation computations.

  For requested times which are between tabular values, a linear
  interpolation is performed.  This is not exactly the correct
  procedure, and can result in errors of +/- 0.1 mas in the earth
  polar motion and 1 usec in UT1 (see McCarthy & Gambis 1997).


 DATA FILES and MAINTENANCE

   The user is responsible for downloading and maintaining the earth
   orientation parameters file as supplied by the IERS.  The format
   of the files is the "Final" EOP data ASCII format.  They can be
   downloaded here:

      ftp://maia.usno.navy.mil/ser7/finals.all   ;; from May 1976-present
      ftp://maia.usno.navy.mil/ser7/finals.data  ;; from Jan 1992-present
   
   The user must place this file in a known location, and in *at
   least the first call*, this filename must be passed using the
   FILENAME keyword.

   EOPDATA will load the data once on the first call, and keep a
   cached copy for subsequent calls.  On a daily basis the file will
   be reloaded in case the quantities have been updated from the
   server.  A reload of data can be forced using the RESET keyword.

 ROTATION MATRICES

   The rotation matrices RX(T) and RY(T) mentioned above in relation
   to polar motion are:

      RX(T) =EQ= [[1,0,0], [0,cos(T),sin(T)], [0,-sin(T),cos(T)]]
      RY(T) =EQ= [[cos(T),0,-sin(T)], [0,1,0], [sin(T),0,cos(T)]]
      RZ(T) =EQ= [[cos(T),sin(T),0], [-sin(T),cos(T),0], [0,0,1]]

   and are meant to be applied to a vector R as, RX(T) ## R.


 OPEN QUESTIONS

   How will the transition to a new IERS EOP series be accomplished?
   Using a keyword?

   Should there be a quality flag?  The EOP file contains a
   "predicted" flag, and also there are rows which contain no value
   at all.  These should probably be flagged somehow.


 INPUTS:

   JDUTC - a vector or scalar, the UTC time for which earth
           orientation parameters are requested, expressed in Julian
           Days.  The value of the keyword TBASE is added to this
           quantity to arrive at the actual Julian date.

 OUTPUTS:

   PMX, PMY - the earth-fixed angular coordinates of the celestial
              ephemeris pole, measured in ANGUNITS units.

   UT1_UTC - the value of UT1 - UTC, expressed in seconds.

   DPSI, DEPS - the corrections to the IAU 1980 theory of Nutation,
                for nutation in longitude and obliquity, expressed in
                ANGUNITS units.

 KEYWORD PARAMETERS:

   FILENAME - scalar string, on the first call, the name of the file
              from which earth orientation parameters will be read.
              Default value: (none)

   TBASE - a fixed epoch time (Julian days) to be added to each value
           of JDUTC.  Since subtraction of large numbers occurs with
           TBASE first, the greatest precision is achieved when TBASE
           is expressed as a nearby julian epoch, JDUTC is expressed
           as a small offset from the fixed epoch.
           Default: 0

   ANGUNITS - scalar string, output units of angular parameters.
              Possible values are 'ARCSEC' or 'RADIAN'.
              Default value: 'RADIAN'

   RESET - if set, forces EOP file to be re-read.


 EXAMPLE:


 SEE ALSO:

   HPRNUTANG, TAI_UTC (Markwardt Library)
   PRECESS, PREMAT, JPRECESS, BPRECESS (IDL Astronomy Library)


 REFERENCES:

   Aoki, S., Guinot, B., Kaplan, G.H., Kinoshita, H., McCarthy, D.D.,
     Seidelmann, P.K., 1982: Astron. Astrophys., 105, 359-361.

   McCarthy, D. D. (ed.) 1996: IERS Conventions, IERS T.N. 21.
     http://maia.usno.navy.mil/conventions.html

   McCarthy, D. \& Gambis, D. 1997, "Interpolating the IERS Earth
     Orientation Data," IERS Gazette No. 13, 
     http://maia.usno.navy.mil/iers-gaz13
     Instructions for high precision EOP data interpolation, not done
     in this procedure.

   Ray, J. & Gambis, D. 2001, "Explanatory Supplement to IERS
     Bulletins A and B,"
     http://hpiers.obspm.fr/iers/bul/bulb/explanatory.html

     Explains meanings of earth orientation parameters used and
     returned by this procedure.

   Definition of Final EOP data format
     ftp://maia.usno.navy.mil/ser7/readme.finals

 MODIFICATION HISTORY:
   Written, 30 Jan 2002, CM
   Documented, 14 Feb 2002, CM
   Add default message, 01 Mar 2002, CM
   More robust handling of input file, 10 Mar 2002, CM

  $Id: eopdata.pro,v 1.4 2002/03/17 18:46:16 craigm Exp $

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\eopdata.pro)


EPSINIT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       EPSINIT
 PURPOSE:
       Redirect plots and images to Encapsulated Postscript File.
 CATEGORY:
 CALLING SEQUENCE:
       epsinit, outfile
 INPUTS:
       outfile = EPS file name (def=idl.eps).          in
 KEYWORD PARAMETERS:
       Keywords:
         XSIZE=xsz  Plot size in X (def=6).
         YSIZE=xsz  Plot size in Y (def=6).
         /CM    Means size units are cm (else inches).
         /COLOR means do color PostScript (def is B&W).
         /VECTOR to use vector fonts instead of postscript fonts.
         /QUIET turns off epsinit messages.
 OUTPUTS:
 COMMON BLOCKS:
       eps_com,xsv,ysv,psv,dsv,ou
 NOTES:
       Notes: 8 bit gray scale or color is set.  Times Roman
         font is used.  To over-ride just use a call to device
         after epsinit to set desired values.
 MODIFICATION HISTORY:
       R. Sterner, 1996 Aug 2

 Copyright (C) 1996, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\epsinit.pro)


EPSTERM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       EPSTERM
 PURPOSE:
       Terminate Encapsulated Postscript plotting.
 CATEGORY:
 CALLING SEQUENCE:
       epsterm
 INPUTS:
 KEYWORD PARAMETERS:
       Keywords:
         /QUIET turns off epsterm messages.
 OUTPUTS:
 COMMON BLOCKS:
       eps_com,xsv,ysv,psv,dsv
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 1996 Aug 2

 Copyright (C) 1996, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\epsterm.pro)


EPS_GET_BOUNDINGBOX

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

 PURPOSE:
   This function returns the boundingbox of an eps file

 CATEGORY:
   PROG_TOOLS/EPS

 CALLING SEQUENCE:
  result=eps_get_boundingbox(eps_txt)

 INPUTS:
   eps_txt: This is the text of a eps file


 EXAMPLE:
  result=eps_get_boundingbox(get_file('idl.eps'))

 MODIFICATION HISTORY:
   Written by:	R.Bauer (ICG-1), 1999-Oct-05

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\eps_get_boundingbox.pro)


EPS_SET_BOUNDINGBOX

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

 PURPOSE:
   This Routine exchanges the boundingbox variable of an eps file

 CATEGORY:
   PROG_TOOLS/EPS

 CALLING SEQUENCE:
  eps_set_boundingbox,eps_txt,boundingbox

 INPUTS:
   eps_txt: This is the text of a eps file
   boundingbox: the boundingbox to set

 OUTPUTS:
   This routine replaces the boundingbox

 EXAMPLE:
   txt=eps_set_boundingbox(get_file('idl.eps'),[20, 100, 551, 525])

 MODIFICATION HISTORY:
   Written by:	R.Bauer (ICG-1), 1999-Sep-18

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\eps_set_boundingbox.pro)


EQV

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       EQV
 PURPOSE:
       Interactive equation viewer and curve fitter.
 CATEGORY:
 CALLING SEQUENCE:
       eqv
 INPUTS:
 KEYWORD PARAMETERS:
       Keywords:
         FILE=filename  Name of equation file to view.
         LIST=list  List of equation file names.  If LIST is
           given then FILE is ignored.
         XS=x, YS=y  Optional arrays of scatterplot points.
           Useful for interactive curve fitting.
         PSYM=p  Scatter plot symbol (def=2 (*)).
         SNAPSHOT=file  name of snapshot file (def=snapshot.eqv).
         TITLE=tt  plot title (over-rides value from eqv file).
         XTITLE=tx  X axis title (over-rides value from eqv file).
         YTITLE=ty  Y axis title (over-rides value from eqv file).
 OUTPUTS:
 COMMON BLOCKS:
 NOTES:
 MODIFICATION HISTORY:
       R. Sterner, 26 Oct, 1993
	R. Sterner, 1998 Jan 15 --- Dropped use of !d.n_colors.

 Copyright (C) 1993, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\eqv.pro)


EQV2

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       EQV2
 PURPOSE:
       Interactively plot a function on current plot.
 CATEGORY:
 CALLING SEQUENCE:
       eqv2, file
 INPUTS:
       file = equation file.   in
 KEYWORD PARAMETERS:
       Keywords:
         COLOR=clr  Plot color (def=!p.color).
         TOP=top    Returns widget ID of top level base.
           Use widget_control to retrieve or store info structure.
         OK=wid  Given ID of widget to notify when OK button pressed.
           If not given no OK button is displayed.
         WID_OK=wid  Widget ID of the OK button.
           Can use to set /input_focus.
         GROUP_LEADER=grp  Set group leader.
 OUTPUTS:
 COMMON BLOCKS:
       eqv2_help_com
       eqv2_help_com
 NOTES:
       Note: The QUIT button allows burning in the final curve and lists its
         values.  The LIST button lists the current curve parameters.
       
       Equation file format: This file defines the equation, the x range
       and range of each adjustable parameter. The file is a text file with
       certain tags. Null and comment lines (* in first column) are allowed.
       The tags are shown by an example:
          eq: y = a + b*x + c*x^2
          title:  Parabola
          xrange:  -10 10
          n_points:  100
          par:  a -50 50 0
          par:  b -50 50 0
          par:  c -10 10 1
       
       The parameter tags are followed by 4 items:  Parameter name (as in the
       equation), min value, max value, initial value.  An optional 5th item
       may be the word int to force an integer value (for flags or harmonics).
 MODIFICATION HISTORY:
       R. Sterner, 1998 Feb 24
       R. Sterner, 1998 Apr  1 --- Added /NO_BLOCK to xmanager.
       R. Sterner, 1998 May 12 --- Added plot color.  Also added TOP=top.
       R. Sterner, 1998 May 13 --- Added OK button to signal other program.
       Also GROUP_LEADER.
       R. Sterner, 1998 May 14 --- Added LOCK=lck and UNLOCK=ulck to
       eqv2_set_val and eqv2_get_val.  Locks parameters.
       R. Sterner, 1998 Oct 27 --- Fixed bug added by the plot color addition.

 Copyright (C) 1998, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\eqv2.pro)


EQV3

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       EQV3
 PURPOSE:
       Execute IDL code using interactively varied parameters.
 CATEGORY:
 CALLING SEQUENCE:
       eqv3, file
 INPUTS:
       file = equation file.   in
         Instead of file name the contents of the file may be
         given in a text array (same format).
 KEYWORD PARAMETERS:
       Keywords:
         P1=var1, P2=var2, ... P5=var5  Up to 5 variables.
           may be passed into the program using these keywords.
           May reference p1, p2, ... in the IDL code to execute.
         /WAIT means wait until the routine is exited instead
            returning right after startup.
         PARVALS=pv Structure with parameter names and values.
            Must be used with /WAIT or pv will be undefined.
         EXITCODE=excd 0=normal, 1=cancel.  Must use with /WAIT.
         RES=res  Returned widget ID of an unused top level
            base that will on exit from EQV3 contain a structure
            with parameter names and final values.
              widget_control,res,get_uval=s,/dest
              s.name and s.val are arrays of names and values.
         TOP=top    Returns widget ID of top level base.
           Use widget_control to retrieve or store info structure.
         OK=wid  ID of widget to notify when OK button pressed.
           If not given no OK button is displayed.
           Useful to allow a higher level widget routine to call
           EQV3.  The OK button then sends an event to the higher
           level widget which can then destroy the eqv3 widget.
         WID_OK=wid  Returned widget ID of the OK button.
           Can use to set /input_focus.
         GROUP_LEADER=grp  Set group leader.
         XOFFSET=xoff, YOFFSET=yoff Widget position.
       
 OUTPUTS:
 COMMON BLOCKS:
       eqv3_var_com
       eqv3_var_com
       eqv3_help_com
       eqv3_var_com
       eqv3_help_com
 NOTES:
       Notes:  Use the Help button for more details.
       Equation file format: This text file defines the IDL code,
       and range of each adjustable parameter.
       Null and comment lines (* in first column) are allowed.
       The tags are shown by an example:
          title: Parabola
          eqv: x=maken(-10,10,100) & plot,a + b*x + c*x^2
          par:  a -50 50 0
          par:  b -50 50 0
          par:  c -10 10 1
       
       The parameter tags are followed by 4 items:  Parameter name (as in the
       equation), min value, max value, initial value.  An optional 5th item
       may be the word int to force an integer value (for flags or harmonics).
 MODIFICATION HISTORY:
       R. Sterner, 2000 May 11 --- From EQV2.
       R. Sterner, 2000 Aug 21 --- Added XOFFSET, YOFFSET.

 Copyright (C) 2000, 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.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\eqv3.pro)


ERFINT_MM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		ERFINT_MM
 VERSION:
		4.3
 PURPOSE:
		Calculates a definite integral of the error function.
 CATEGORY:
		Mathematical function (general).
 CALLING SEQUENCE:
		Result = ERFINT_MM (Y [,X])
 INPUTS:
	Y
		Numeric, otherwise arbitrary.  Upper integration limit.
 OPTIONAL INPUT PARAMETERS:
	X
		Numeric, otherwise arbitrary.  Lower integration limit.  Defaults to 0.
 KEYWORD PARAMETERS:
		None.
 OUTPUTS:
		Returns an integral of the error function between X and Y.
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		If both X and Y are arrays, they need to have same number of elements.
		Scalar-scalar and scalar-array combinations are permitted.
 PROCEDURE:
		Straightforward.  Uses CALCTYPE, CAST, DEFAULT and ERRORF_MM from MIDL.
 MODIFICATION HISTORY:
		Created 10-MAY-2002 by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\erfint_mm.pro)


ERRBARS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		ERRBARS
 VEERSION:
		4.0
 PURPOSE:
		Overplots error bars over an existing plot.  More general than the
		library routines ERRPLOT and PLOTERR, since it allows to independently
		vary both X and Y errors, and allows for nonsymmetric error bars.
 CATEGORY:
		Plotting.
 CALLING SEQUENCE:
		ERRBARS, [X,] Y [, XERR = XER, YERR = YER]
 INPUTS:
	X, Y
		Vectors containing the data points' coordinates.  If only one is given
		it is taken to be Y, same as in the PLOT command.
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
	XERR
		Either a vector or a (2,N) array where N is the number of the data
		points.  Contains the X-errors.  If given as a 2 dimensional array, the
		entries XERR(0,i) and XERR(1,i) are taken as the errors of X(i) in the
		negative and positive directions, respectively.  If given as a vector,
		the entry XERR(i) serves as both the negative and positive error of
		X(i) and therefore symmetric error bars are drawn.  If not provided,
		the default is no X-errors.
	YERR
		Same as above, for the Y-errors.
	_EXTRA
		A formal keyword used to pass all plotting keywords.  Not to be used
		directly.  See comment in RESTRICTIONS.
 OUTPUTS:
		None.
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		The keywords passed through _EXTRA are transferred to the PLOTS
		routine.  No keyword verification is performed by ERRBARS.
 PROCEDURE:
		Straightforward.  Uses DEFAULT from MIDL.
 MODIFICATION HISTORY:
		Created 10-DEC-1991 by Mati Meron.
		Modified 15-DEC-1993 by Mati Meron.  Now ERRBARS takes advantage of the
		keyword inheritance property and accepts most of IDL plotting keywords.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\errbars.pro)


ERRORF_MM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
		ERRORF_MM
 VERSION:
		4.0
 PURPOSE:
		Calculates the error function.  Replacement for the IDL ERRORF function
		which accepts only real input.
 CATEGORY:
		Mathematical function (general).
 CALLING SEQUENCE:
		Result = ERRORF_MM (X [, /COMPLEMENTARY)]
 INPUTS:
	X
		Numeric, otherwise arbitrary.
 OPTIONAL INPUT PARAMETERS:
		None.
 KEYWORD PARAMETERS:
	/COMPLEMENTARY
		Switch.  If set, 1 - ERRORF(X) is returned.
 OUTPUTS:
		Returns the error function of X or, if /COMPLEMENTARY is set,
		1 - error_function.
 OPTIONAL OUTPUT PARAMETERS:
		None.
 COMMON BLOCKS:
		None.
 SIDE EFFECTS:
		None.
 RESTRICTIONS:
		For very large (in absolute value) complex values of x, with
			pi/4 < |abs(phase(x))| < 3*pi/4
		the results may be meaningless.  A warning will be issued in this case.
 PROCEDURE:
		Uses CAST IGAMMA_MM and IMAGINARY_MM from MIDL.
 MODIFICATION HISTORY:
		Created 20-MAR-1996 by Mati Meron as M_ERRORF.
		Renamed 25-SEP-1999 by Mati Meron, to ERRORF_MM.
		Checked for operation under Windows, 25-JAN-2001, by Mati Meron.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\errorf_mm.pro)


ERROR_MESSAGE

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

 PURPOSE:

    The purpose of this function  is to have a device-independent
    error messaging function. The error message is reported
    to the user by using DIALOG_MESSAGE if widgets are
    supported and MESSAGE otherwise.

 AUTHOR:

   FANNING SOFTWARE CONSULTING
   David Fanning, Ph.D.
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: davidf@dfanning.com
   Coyote's Guide to IDL Programming: http://www.dfanning.com/

 CATEGORY:

    Utility.

 CALLING SEQUENCE:

    ok = Error_Message(the_Error_Message)

 INPUTS:

    the_Error_Message: This is a string argument containing the error
       message you want reported. If undefined, this variable is set
       to the string in the !Error_State.Msg system variable.

 KEYWORDS:

    NONAME: If this keyword is set the name of the calling routine
       is not printed along with the message.

    TRACEBACK: Setting this keyword results in an error traceback
       being printed to standard output with the PRINT command.

    In addition, any keyword appropriate for the MESSAGE or DIALOG_MESSAGE
    routines can also be used.

 OUTPUTS:

    Currently the only output from the function is the string "OK".

 RESTRICTIONS:

    The "Warning" Dialog_Message dialog is used by default. Use keywords
    /ERROR or /INFORMATION to select other dialog behaviors.

 EXAMPLE:

    To handle an undefined variable error:

    IF N_Elements(variable) EQ 0 THEN $
       ok = Error_Message('Variable is undefined', /Traceback)

 MODIFICATION HISTORY:

    Written by: David Fanning, 27 April 1999.
    Added the calling routine's name in the message and NoName keyword. 31 Jan 2000. DWF.
    Added _Extra keyword. 10 February 2000. DWF.
    Forgot to add _Extra everywhere. Fixed for MAIN errors. 8 AUG 2000. DWF.
    Adding call routine's name to Traceback Report. 8 AUG 2000. DWF.
    Switched default value for Dialog_Message to "Error" from "Warning". 7 OCT 2000. DWF.

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\error_message.pro)


ERROR_PLOT

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

 PURPOSE:
   Over-plot data points with accompanying X or Y error bars.
   For use instead of PLOTERR or OPLOT or oploterr when the plotting system has already been
   defined.

 CATEGORY:
  PLOT/PLOTXY

 CALLING SEQUENCE:
   error_plot,  x,  y, [x_err=x_err], [y_err=yerr], [s_hatlength=s_hatlength] ,
        [s_thick=s_thick] , [s_linestyle=s_linestyle], [s_color =s_color ],  [/s_hat],[/s_background],[s_nskip]
 INPUTS:
   plot : the by pl_init defined structure
   X:  array of abcissae, any datatype except string
   Y:  array of Y values, any datatype except string

 OPTIONAL INPUTS:
   X_ERR : vector of error bar values (along X)
   Y_ERR : vector of error bar values (along Y)
   For both: if only an element is submitted a vector with make_array will be builded
   s_hatlength:  the lengt of the hat
   s_thick:      the tickness of the error bar lines
   s_linestyle:  the linestyle of the error bar lines
   s_color:      the color of the error bar lines

 KEYWORD PARAMETERS:
  s_hat: 1 the error bar has an hat else 0 no hat
  s_background: 1 error bar at background  else 0 foreground
  s_nskip: 1 no skip ; 0 skip

 PROCEDURE:
   A plot of X versus Y with error bars drawn from Y - YERR to Y + YERR
   and optionally from X - XERR to X + XERR is written to the output device

   if sx or sy is a two dimensional array they have to be defined as min, max error
   in this case it could be an asymmetrical error plotted.

 WARNING:
   This an enhanced version of a procedure that already exists in the
   standard IDL V4.0 distribution. Any call to the standard IDL version
   should also work with this version, but the reverse is not true.


 MODIFICATION HISTORY:
   Adapted from the most recent version of PLOTERR.  M. R. Greason,
       Hughes STX, 11 August 1992.
       Removed spurious keywords for IDL V3.0.0  W. Landsman Jan. 1993
   Added ability to plot a single point W. Landsman   July 1993
   Added COLOR keyword option to error bars W. Landsman   November 1993
   Remove CHANNEL call for V4.0 compatibility W. Landsman June 1995
   Add ERRCOLOR, use _EXTRA keyword,           W. Landsman, July 1995
   Remove spurious call to PLOT_KEYWORDS     W. Landsman, August 1995
   OPLOT more than 32767 error bars          W. Landsman, Feb 1996
   Added NSKIP keyword                       W. Landsman, Dec 1996
   ==============================================================================
   1998-Apr-04 R.Bauer
   Adapted from olpoterr submitted by the astro lib
   All is done by _extra
   No symbol will be plotted only the error bars
   An important difference is that's you are able to submit x, y data and x_err or (and) y_err

   03.03.2000: (FH) Removed cause of the following IDL error message:
               % Program caused arithmetic error: Floating illegal operand
               % Detected at  ERROR_PLOT        121 S:\links\idl_source\idl_work\rb_lib\error_plot.pro
   05.04.2000: (FH) Set s_hat to 1 if not provided in structure pkey

 EXAMPLE:

 result=set_range([1,2,3,4],[10,20,30,40],xrange=[0,4],yrange=[0,40],sx=transpose([[0.9,1.8,2.9,3.5],[1.1,2.01,3.1,4.2]]))
 plot,result.x,result.y,psym=4
 error_plot,result.x,result.y,x_err=result.sx,s_color=5

 x=[1,2,3,4] & y=[10,20,30,40] &sx=[0.1,0.12,0.1,0.1] & sy=[1.1,2.12,1.1,1.1]
 plot,result.x,result.y,psym=4
 error_plot,x,y,x_err=sx,y_err=sy,s_color=5
   1999-Nov-06 help added

(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\error_plot.pro)


ETC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ETC
 PURPOSE:
       Return estimated time to completion in seconds.
 CATEGORY:
 CALLING SEQUENCE:
       stc = etc( fr )
 INPUTS:
       fr = fraction of work done.             in
 KEYWORD PARAMETERS:
       Keywords:
        DELTA=d  interval in seconds for rate estimation (def=10).
          DELTA must be given on each call.
        /STATUS means display job status (at [10,12]).
        STATUS=[x,y] display at column x, line y (from 1 at top).
 OUTPUTS:
       stc = estimated seconds t