Extended IDL Help pro user_c (Rodenacker)

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: 13.07.2004

List of Routines

Routine Descriptions

ABGRAD

 [Next Routine] [List of Routines] 
 NAME:
	ABGRAD
 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 1.  If provided, it is rounded to an
	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 function DEFAULT from MIDL.
 MODIFICATION HISTORY:
	Created 15-NOV-1991 by Mati Meron.

(See /IDL/pro_src/RODENA/pro/user_c/abgrad.pro)

CAST

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
	CAST
 PURPOSE:
	Generalized type casting.  Converts all variables whose type code is 
	out of the range [LOW,HIGH] into this range.
 CATEGORY:
	Type conversion
 CALLING SEQUENCE:
	Result = CAST( X, LOW [,HIGH])
 INPUTS:
    X
	Numerical, arbitrary, or a character representation of a number(s).
    LOW
	Number representing a type code, range (1:7).  Converted to integer on
	input.  If greater than 7, it is set to 7.  If less then 1, or not
	given, it is set to 1.
 OPTIONAL INPUT PARAMETERS:
    HIGH
	Type code, same as LOW.  Default value is 7.  If provided and less then
	LOW, it is set to LOW.
 KEYWORD PARAMETERS:
	None.
 OUTPUTS:
	If the type of X is < LOW, CAST returns X converted to type LOW.
	If the type of X is > HIGH, CAST returns X converted to type HIGH.
	Otherwise CAST returns X.
 OPTIONAL OUTPUT PARAMETERS:
	None.
 COMMON BLOCKS:
	None.
 SIDE EFFECTS:
	None.
 RESTRICTIONS:
	An attempt to convert a string which is NOT a character representation 
	of a number into a numeric type will result in an error.
 PROCEDURE:
	Identifies the type of X, and if out of the range given by [LOW,HIGH]
	calls the proper conversion routine using the system routine 
	CALL_FUNCTION.  Also uses DEFAULT and TYPE from MIDL.
 MODIFICATION HISTORY:
	Created 25-DEC-1991 by Mati Meron.

(See /IDL/pro_src/RODENA/pro/user_c/cast.pro)

CHK_FILE

 [Previous Routine] [Next Routine] [List of Routines] 
	NAME:
		CHK_FILE
		
FUNCTION CHK_FILE, file

ON_IOERROR, NO_FILE

Get_Lun, file_lun
Openr, file_lun, file
Close, file_lun
free_lun, file_lun
RETURN, 1

NO_FILE:

free_lun, file_lun
RETURN, 0

END

(See /IDL/pro_src/RODENA/pro/user_c/chk_file.pro)

CLEAN.PRO

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
 	CLEAN.PRO

 PURPOSE: Delete all undefined variables

 CATEGORY: Utility Functions

 CALLING SEQUENCE: IDL> clean
 
 INPUTS: none

 OPTIONAL INPUTS: none
	
 KEYWORD PARAMETERS: none

 OUTPUTS: none

 OPTIONAL OUTPUTS: none

 COMMON BLOCKS: none

 SIDE EFFECTS: none

 RESTRICTIONS: Only works on variables in the Main program space.
               Most likely will crash w/ common blocks.  Must be run
               as $MAIN$.

 PROCEDURE: Straigthforward

 MODIFICATION HISTORY:
    v1.0 written by Phil Williams 11/6/1996
              williams@irc.chmcc.org

(See /IDL/pro_src/RODENA/pro/user_c/clean.pro)

CW_MSGBOX

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
	CW_MSGBOX
		- message box compound widget.	

 PURPOSE:
	This compound widget function creates a message box to display information
	and to get a simple response from the user.  This function can be used to
	display error messages and other information as well as to get simple
	button activated responses such as "OK", "CANCEL", "SAVE", etc.  In its
	simplest form, this widget displays a message and allows the user to
	acknowledge this message by pressing an "OK" button.  This can be used to
	provide a simple means of displaying error messages.

 CATEGORY:
	Compound Widgets

 CALLING SEQUENCE:
	widget_id = CW_MSGBOX(Parent, Button_values)

 INPUTS:
	Parent:		The ID of the parent widget.
	
 KEYWORD PARAMETERS:
	VALUE:		A string array containing the message to be displayed
			in the message box.  After the message box is created,
			this message can be changed but the new value string 
			array can not have any more elements than the original.
			i.e. the message box will not grow.  Default:  If no
			message is specified, then a snide remark of my choosing
			will be placed in the box instead.  If you really want
			a blank box, then set VALUE="   ".
	BUTTON_VALUES:	A string array, containing one string per button to be
                       displayed for the user's response.  Also, if this
			keyword is specified, then events will be returned by
			the compound widget.  Default:  One "OK"
			button will be displayed if this keyword is not used and
			no events will be returned.
	TITLE:		A title to be displayed in the window's title box.  The
			default is "Message".
	DEFAULT_VALUE:	The value returned in the event sent as a result of the
			widget being destroyed by means other than the normal
			processing sequence.  (i.e. by the window manager, or
			as a result of the group leader being destroyed.)  If
			BUTTON_VALUES is not used, then no events are returned.
			Default:  "DESTROYED"
	RESOURCE_NAME:	X-windows resource name to be given to this widget.
	/INFO_BOX:	Creates a box with no buttons for displaying messages
			only.  Sets /PERSIST and if not overridden by the 
			EVENTS keyword, no events are returned.  BUTTON_VALUES
			is ignored.  The XMANAGER is not called.
	DISPLAY_TIME:	Causes message box to be automatically destroyed after 
			a specified number of seconds.  Overrides /PERSIST
			keyword and turns it off.  Seconds should be specified
			as a floating point value.  This keyword can be used to
			cause an INFO_BOX to display for a specified time.  It
			can also be used to force a user response to a message
			box within a specific time period.  If the user doesn't
			respond, then the DEFAULT_VALUE is returned with any
			events sent back to the parent.  Default is for no 
			timeout period.
	EVENTS:		1 => events are returned.  0 => events are not returned.
			If present, this keyword overrides any other features
			that cause events to be or not to be returned.
			Default:  Dependent on BUTTON_VALUES.
	/SENSITIVE:	Causes the widget hierarchy rooted at Parent to remain
			sensitive to events.  Default:  The hierarchy rooted at
			Parent is desensitized.  For example:  An error message
			box may have the top level base as its Parent.  Thus,
			the entire window would be desensitized.
	/PERSIST:	The first button press does not cause the message box to
			be destroyed.  It will hang around until explicitly 
			destroyed.  Default:  The message box is destroyed after
			the first button press.
	/BELL:		A bell sounds when the box is created and any time the
			value is changed.  Default: no bell is sounded.
	UVALUE:		A user value to give to the widget.
	FONT:		A font to use when creating the widget.
	XOFFSET:	The X offset of the widget relative to its parent.
			default: based on xsize and position of parent's top 
			level base.
	YOFFSET:	The Y offset of the widget relative to its parent.
			default: based on ysize and position of parent's top 
			level base.

 OUTPUTS:
	The ID of the created widget is returned.

 SIDE EFFECTS:

	This routine starts the XMANAGER if it isn't already running unless INFO_BOX
	is specified.

	This widget may generate events with the following structure definition:

	event = {ID:parent, TOP:tlbase, HANDLER:0L, ORIGIN:cw_msgbox_id, $
			 VALUE:0 [,UVALUE:0]}

	VALUE is the string value of the button that was pressed.  If /PERSIST
	is not specified, then the user value of the compound widget will be
	returned as part of the event structure.
	NOTE:  If BUTTON_VALUES is not specified, then no events are returned,
	rather, when the single "OK" button is pressed, the message box is 
	destroyed, and the event handler returns without generating events.

                                   WARNING!

	Prior to IDL 4.0:
	When a modal widget is registered with the XMANAGER, it starts a second
	event processing loop.  Any further calls to the XMANAGER to register
	a widget (modal or non-modal) will cause the XMANAGER to start another
	loop.  Furthermore, the third, fourth, etc. loops don't end until all
	of the widgets registered after the modal widget and the original modal
	widget itself is destroyed.  Because of this effect, CW_MSGBOX should not
	be used if a modal widget is registered.  If it is used under these
	circumstances, then it won't return to the calling program until after
	all of the modal widgets are destroyed.  This can cause weird things
	to happen with your program.


 PROCEDURE:
	EXAMPLE:

	message = CW_MSGBOX(Parent, $
			VALUE=['File not saved', $
			'Exit anyway?'], $
			BUTTON_VALUES=['OK', 'CANCEL'], $
			TITLE='Warning')

	Produces:

       --------------------------------------
      | - |          Warning             |o|O|
      |--------------------------------------|
      |                                      |
      |          File not saved.             |
      |           Exit anyway?               |
      |                                      |
      |     ---------     --------------     |
      |    |  OK     |   |   CANCEL     |    |
      |     ---------     --------------     |
       --------------------------------------

	or some reasonable facsimile thereof, desensitizes the parent,
	disappears when one of the buttons is pressed, and sends an event
	to parent.

 MODIFICATION HISTORY:
 	Written by:	Ken Knighton
			knighton@gav.gat.com
			Fusion Division
			General Atomics
			San Diego, CA

	Date:		2/6/95

	2/16/95	KEK	Added /INFO_BOX keyword.

	2/20/95 KEK	Added EVENTS keyword.

	4/10/95 KEK	Added DISPLAY_TIME keyword.

	4/20/95 KEK	Put XMANAGER call at very end of CW_MSGBOX procedure

	4/25/95 KEK	Changed so that XMANAGER is not called if /INFO_BOX is
			specified.

	5/9/95  KEK	Added RESOURCE_NAME keyword

(See /IDL/pro_src/RODENA/pro/user_c/cw_msgbox.pro)

DEFAULT

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
	DEFAULT
 PURPOSE:
	Provides an automatic default value for nondefined parameters.
 CATEGORY:
	Programming.
 CALLING SEQUENCE:
	Result = DEFAULT( X, Y [, TYPE = TYP])
 INPUTS:
    X, Y
	Arbitrary, at least one needs to be defined.
 OPTIONAL INPUT PARAMETERS:
	None.
 KEYWORD PARAMETERS:
    TYPE
	Number between 1 to 8.  If provided, it is compared to the type-value 
	of X and X is considered defined only if the two values match.  For
	example, if TYPE = 7 then X has to be a character value.
 OUTPUTS:
	X if it is defined, otherwise Y.
 OPTIONAL OUTPUT PARAMETERS:
	None.
 COMMON BLOCKS:
	None.
 SIDE EFFECTS:
	None.
 RESTRICTIONS:
	None.
 PROCEDURE:
	Uses the function TYPE from MIDL.
 MODIFICATION HISTORY:
	Created 15-JUL-1991 by Mati Meron.

(See /IDL/pro_src/RODENA/pro/user_c/default.pro)

DIREXIST

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

 PURPOSE: Determine which elements in list are directories.

 CATEGORY: File I/O

 CALLING SEQUENCE: result = direxist(list)
 
 INPUTS:
    list : a list of files (i.e. the result from list = FINDFILE())

 OPTIONAL INPUTS: none

 OUTPUTS: An array of the appropriate size. 1 indicates list(i) is a
          directory. 0 indicates that list(i) is a file.

 PROCEDURE:
   Get a file list
      IDL> list = findfile()
      IDL> dirs = direxist(list)
   Print which elements in list are directories
      IDL> print,where(dirs eq 1)
           1           6          14          22

 MODIFICATION HISTORY:
   27 Dec 96 Initial coding. PMW
     Use direxist.pro from David Fanning as a starting point.
   28 Dec 96 Fixed bug. Now checking last entry in list. PMW
   30 Dec 96 Fixed bug with last entry check. PMW

(See /IDL/pro_src/RODENA/pro/user_c/direxist.pro)

FILEEXISTS

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

 PURPOSE: Determines the existence of a file.

 CATEGORY: File I/O

 CALLING SEQUENCE: result = fileExists(file[, path, /follow_dir, /get_path])
 
 INPUTS:
    file : a string containing the file name

 OPTIONAL INPUTS:
   path : The given path to search. If not given then searching
          begins at the current directory
	
 KEYWORD PARAMETERS:
  FOLLOW_DIR : If set then subdirectories are recursively searched.
  GET_PATH   : If set and file exists then the path to the file is
               returned.
 OUTPUTS:
   If GET_PATH is specified and the search was successful then the
   path to the file is returned. Otherwise 1 is returned if the file
   exists and 0 if the file does not.

 OPTIONAL OUTPUTS: none

 COMMON BLOCKS: none.

 SIDE EFFECTS: none.

 RESTRICTIONS: none.

 PROCEDURE:
    IDL> t = fileExists('file.pro',/follow,/get)

 MODIFICATION HISTORY:
    13 Dec 96 Initial Coding. PMW
    29 Dec 96 Added FOLLOW_DIR keyword for recursive searches
    30 Dec 96 Added GET_PATH keyword to return path if file is found.

(See /IDL/pro_src/RODENA/pro/user_c/fileexists.pro)

GMTIME

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
 		GMTIME
	
 PURPOSE:	This function converts the time in seconds since 
		January 1 1970 to something more useful.

 CATEGORY:	Timing

 CALLING SEQUENCE:	Result= GMTIME( Timeinseconds )

 INPUTS:	
	Timeinseconds	a scalar value or array containing the number of
			seconds since Jan 1 1970 (This should be a long
			integer) OR a structure or array of structures of
			type {GMTIME} (see below)	
				
 KEYWORD PARAMETERS:
	ASCTIME		If this keyword is set, then the returned value
			is a string (or array of strings) containing the
			time in standard format (see OUTPUTS).


 OUTPUTS:	The default behaviour for this function is to return
		a structure of the form:

	{GMTime,	sec:0B,		;seconds 0-59
			min:0B,		;minutes 0-59
			hour:0B,	;hours	0-23
			mday:0B,	;day of month 1-31
			mon:0B,		;month 0-11
			year:0,		;years since 1900
			wday:0B,	;day of week 0-6 ,Sunday is 0
			yday:0,		;day of year 0-356
			long_sec:0L}	;seconds since Jan 1 1970			

	unless the keyword /ASCTIME was set, in which case the result will be
	of type string, with the form

				Thu Jan 01 00:00:00 1970

 RESTRICTIONS:	Won't work for negative times, ie. nothing before 1970.  
		No attempt is made to correct for daylight savings time,
		 or offset from UT.

 EXAMPLE:  
	time0= SYSTIME(0)		;current time, date etc.
	time1= SYSTIME(1)		;time in seconds since Jan 1 1970
	gm= GMTIME( time1,/ASCTIME )	;this should be within a second of
					;time0, NOT INCLUDING OFFSET FROM UT!

 MODIFICATION HISTORY:	Brian Jackel	March 27 1994
			University of Western Ontario

(See /IDL/pro_src/RODENA/pro/user_c/gmtime.pro)

LPF_ALL

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

 PURPOSE:
       This function performs Low Pass Filtering (smoothing) on one,
       two, and three dimensional arrays.   This function is similar
       to the "Smooth" function except that it smoothes ALL the array
       elements (even at the edges of the array).   The "Smooth" function
       does NOT smooth array elements that are within band/2 of any edge
       of the array (where band is the width of the smoothing window).
       When smoothing a two dimensional array, Lpf_All can optionally
       smooth in one of three ways : rectangular, cylindrical, and
       spherical.   When smoothing a one dimensional array, Lpf_All
       can smooth in either linear or circular mode.

 CATEGORY:
       Filtering.

 CALLING SEQUENCE:
       lpf_array = LPF_ALL(Array, Band)

 INPUTS:
       Array:      The array to smooth.
                   Data type : Any one, two, or three dimensional array
                   except string or structure.
       Band:       The width of the smoothing window.
                   Data type : Int

 KEYWORD PARAMETERS:
       Wrap_Mode:  The smoothing mode.   If Array has three dimensions,
                   then Wrap_Mode is ignored.   If Array has two dimensions,
                   then specify Wrap_Mode=0 for rectangular smoothing,
                   Wrap_Mode=1 for cylindrical smoothing, and Wrap_Mode=2
                   for spherical smoothing.   In the cylindrical and
                   spherical cases, smoothing is performed across the first
                   and last columns of Array.   In the spherical case,
                   smoothing is also performed across all the elements in the
                   top row, and across all the elements in the bottom row.
                   If Array has one dimension, then specify Wrap_Mode=0 for
                   linear smoothing, and Wrap_mode=1 for circular smoothing.
                   In the circular case, smoothing is performed across the
                   first and last elements in Array.   The default is zero.

 OUTPUTS:
       Lpf_Array:  The low pass filtered array.
                   Data type : Same as input Array.

 PROCEDURE :
       This function smoothes the edges of the array by extrapolating the
       values at the edges of the array to a distance of band/2.

 EXAMPLE:
       Smooth a two dimensional array in spherical mode.

          ; *** Create data to smooth.
          array = REBIN(RANDOMU(s, 8, 8), 512, 512)
          ; *** Smooth the array in spherical mode.
          lpf_array = LPF_ALL(array, 64, Wrap_Mode=2)

 MODIFICATION HISTORY:
       Written by:     Daniel Carr. Mon Aug 23 12:46:31 MDT 1993

(See /IDL/pro_src/RODENA/pro/user_c/lpf_all.pro)

LPRINT

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
 		LPRINT
 		
 PURPOSE:	Close a PostScript file and print it.
 CATEGORY:
 CALLING SEQUENCE:
		lprint
 INPUTS:
 OPTIONAL INPUT PARAMETERS:
 KEYWORD PARAMETERS:
		file=the name of the file to print. Default is idl.ps.
		return = 1 will execute set_plot,getenv('IDL_DEVICE')
 OUTPUTS:
 OPTIONAL OUTPUT PARAMETERS:
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
 PROCEDURE:
 MODIFICATION HISTORY:
		D. L. Windt, AT&T Bell Laboratories, November 1989
		K. Rodenacker, Aug 1997

(See /IDL/pro_src/RODENA/pro/user_c/lprint.pro)

READ_ASCII

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
	READ_ASCII
 PURPOSE:
	Reads data from an ASCII file into an array.  It is assumed that the 
	file contains columns of numbers, with the same number of entries in
	each row.  The numbers may be separated by commas, spaces and/or tabs.
	The file may contain a header.  The first line in which the first
	non-blank character is one of ".+-0123456789" will be considered the
	beginning of the data.  Text lines imbedded in the data are skipped.
 CATEGORY:
	Input/Output.
 CALLING SEQUENCE:
	Result = READ_ASCII( FILNAM [, optional keywords])
 INPUTS:
    FILNAM
	Char. value, the name of the data file.  Default extension is '.DAT'.
 OPTIONAL INPUT PARAMETERS:
	None.
 KEYWORD PARAMETERS:
    /SHOW
	If set, the header (if one exists) will be printed to the screen.
    NPOINTS
	Optional output, see below.
    HEADER
	Optional output, see below.
 OUTPUTS:
	Returns the data in a (NC,NR) floating array, where NC, NR, are the
	numbers of rows and columns respectively.  In case of error returns 0.
 OPTIONAL OUTPUT PARAMETERS:
    NPOINTS
	The name of a 2-dim vector to to receive the values of NC, NR (see 
	above).  Doesn't need to be defined prior to the call.  In case of an
	error returns [0,0]
    HEADER
	The name of a character array to receive the header lines.  Doesn't 
	need to be defined prior to the call.  In case of on error, or if no
	header exists, returns a zero length string.
 COMMON BLOCKS:
	None.
 SIDE EFFECTS:
	None.
 RESTRICTIONS:
	None.
 PROCEDURE:
	Straightforward.  Uses STRPARSE from MIDL.
 MODIFICATION HISTORY:
	Created 25-JAN-1992 by Mati Meron.

(See /IDL/pro_src/RODENA/pro/user_c/read_ascii.pro)

SIGN

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
	SIGN
 PURPOSE:
	Gives the sign of X, i.e. 1 for positive, -1 for negative, 0 for 0.
 CATEGORY:
	Mathematical Function (General)
 CALLING SEQUENCE:
	Result = SIGN(X)
 INPUTS:
    X
	Numerical, otherwise arbitrary.
 OPTIONAL INPUT PARAMETERS:
	None.
 KEYWORD PARAMETERS:
	None.
 OUTPUTS:
	Returns the value of SIGN(X), see above, as an integer.
 OPTIONAL OUTPUT PARAMETERS:
	None.
 COMMON BLOCKS:
	None.
 SIDE EFFECTS:
	None.
 RESTRICTIONS:
	For complex X the result is SIGN(REAL(X)), the imaginary part is ignored
 PROCEDURE:
	Straightforward.  Using CAST from MIDL.
 MODIFICATION HISTORY:
	Created 15-JUL-1991 by Mati Meron.
	Modified 25-DEC-1991 by Mati Meron.

(See /IDL/pro_src/RODENA/pro/user_c/sign.pro)

SP

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
 		SP
 		
 PURPOSE:  Execute Set_plot, and some handy default settings.
 CATEGORY:
 CALLING SEQUENCE:
	    sp,device,n_plots
 INPUTS:
	    device = 0 for set_plot,'SUN' 
		     1 for set_plot,'PS'
		     2 for set_plot,'TEK'
		     3 for set_plot,'X'
	    n_plots = 1 for !p.multi=0
		      2 for !p.multi=[0,1,2]
		      3 for !p.multi=[0,1,3]
		      4 for !p.multi=[0,2,2]
 OPTIONAL INPUT PARAMETERS:
 KEYWORD PARAMETERS:
	    landscape = 1 for landscape mode when device=1.
	    full_page = 1 for full page plotting when device=1.
	    hardware = 1 for hardware fonts.
 OUTPUTS:
 OPTIONAL OUTPUT PARAMETERS:
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
 PROCEDURE:
 MODIFICATION HISTORY:
	    David L. Windt, AT&T Bell Labs November 1989

(See /IDL/pro_src/RODENA/pro/user_c/sp.pro)

STREQ

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
	STREQ
 PURPOSE:
	Compares for equality the first LEN characters of STR1, STR2.
	If LEN is 0 the whole strings are compared.
 CATEGORY:
	String Processing
 CALLING SEQUENCE:
	Result = STREQ( STR1, STR2 [,LEN] [, keywords])
 INPUTS:
    STR1, STR2
	character strings, mandatory.
 OPTIONAL INPUT PARAMETERS:
    LEN
	Number of characters to compare.  Default is 0, translating to a full
	comparison.
 KEYWORD PARAMETERS:
    /CASEON
	If set the comparison is case sensitive.  Default is ignore case.
    /WARN
	if set, a warning is issued whenever STR1 or STR2 is not a character
	variable.  Default is no warning.
 OUTPUTS:
	1 for equal, 0 for nonequal.
 OPTIONAL OUTPUT PARAMETERS:
	None.
 COMMON BLOCKS:
	None.
 SIDE EFFECTS:
	None.
 RESTRICTIONS:
	None.
 PROCEDURE:
	Straightforward.  Using DEFAULT and TYPE from MIDL.
 MODIFICATION HISTORY:
	Created 15-JUL-1991 by Mati Meron.

(See /IDL/pro_src/RODENA/pro/user_c/streq.pro)

STRMATCH

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
	STRMATCH
 PURPOSE:
	Compares the string STR with the strings in the array LIST.  Comparison
	is done for the first LEN characters, or all of them if LEN is 0.  If a
	 match is found, STR is replaced by the full string from the list.
 CATEGORY:
	String Processing
 CALLING SEQUENCE:
	Result = STRMATCH( STR, LIST [, LEN] [, /CASEON])
 INPUTS:
    STR
	Character string.
    LIST
	Character array.
 OPTIONAL INPUT PARAMETERS:
    LEN
	The number of characters to compare.  Default is full comparison.
 KEYWORD PARAMETERS:
    /CASEON
	If set, the comparison is case sensitive.  Default is ignore case.
 OUTPUTS:
	Returns the index of the first match, or -1 if no match is found.
 OPTIONAL OUTPUT PARAMETERS:
	None.
 COMMON BLOCKS:
	None.
 SIDE EFFECTS:
	None.
 RESTRICTIONS:
	None.
 PROCEDURE:
	Uses the function STREQ from MIDL.
 MODIFICATION HISTORY:
	Created 15-JUL-1991 by Mati Meron.

(See /IDL/pro_src/RODENA/pro/user_c/strmatch.pro)

STRPARSE

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
	STRPARSE
 PURPOSE:
	Parses the string LINE using the characters in DELIM as delimiters.  
	Puts individual pieces into consecutive locations in LIST.
 CATEGORY:
	String Processing
 CALLING SEQUENCE:
	Result = STRPARSE( LINE, DELIM [, LIST])
 INPUTS:
    LINE
	Character string.
    DELIM
	Character string.  Each Character of DELIM is used as a delimiter.
 OPTIONAL INPUT PARAMETERS:
	None.
 KEYWORD PARAMETERS:
	None.
 OUTPUTS:
	Returns the number of pieces found minus one i.e. the index of the last
	element of LIST if LIST is provided.  If LINE is a null string or not a
	string, the function returns -1.
 OPTIONAL OUTPUT PARAMETERS:
    LIST
	Character array.  If name is provided, the pieces of LINE resulting 
	from the parsing process are returned in consecutive locations in LIST.
 COMMON BLOCKS:
	None.
 SIDE EFFECTS:
	None.
 RESTRICTIONS:
	None.
 PROCEDURE:
	Straightforward.  Using the function TYPE from MIDL.
 MODIFICATION HISTORY:
	Created 15-JUL-1991 by Mati Meron.

(See /IDL/pro_src/RODENA/pro/user_c/strparse.pro)

THECOLOR

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
	thecolor
 Purpose:
	Function to rob a color index from the current color table and set
	it to the specified color.  Then return the index.
	Options exist for where in the color table the index is chosen.
	Color names come from the Openwindows colors file, q.v. wrgb.pro.
 Usage:
	plot,x,color=thecolor('red')			; plot is red.
	plot,x,color=thecolor('LightGoldenrod3')	; case insensitive
	plot,x,color=thecolor('red',index=!d.n_color-1)
		; the last index set to red
	plot,x,color=thecolor('red',/first)
		; 1st available at the start of the color table (Default)
	plot,x,color=thecolor('red',/last)
		; ditto except at the end of the color table
	tmp = thecolor(/reset)		; forget all previous thecolor calls
 Inputs:
	name = name of color, a string
 Optional Inputs:
	none
 Keywords:
	/help = flag to print header
	index = force the color index to be this value
	/last = choose index from first available at end of color table
	/first = choose the first available at the bottom. (D)
	rgb = output RGB values for the color
	/noindex = flag to simply return the rgb values, leaving the color
		table unchanged
	/reset = flag to kill all current reserved colors but doesn't restore
		the previous color table. Use loadct,n, tvlct,r,g,b or xloadct.
	/list = list the current colors and their indices
	/show = list all available colors
	/view = show swatches of all available colors; call wrgb widget
 Outputs:
	index = function return
 Optional outputs:
	none (cf. keyword rgb)
 Common blocks:
	thecolor, used to remember available names and info from
	previous calls, containing:
	  thecolors = names of colors stored in previous calls to thecolor
	  thecolorindices = corresponding color table indices (those replaced)
	  thecolornames = list of available color names, read from file
	  thecolorrgb = corresponding rgb triples
	  previousfirstindex = previous index stored at start of color table
	  previouslastindex = previous index stored at end of color table
 Procedure:
	If keyword help is set, call doc_library to print header.
 Restrictions:
	Needs a file where color names and RGB values are found.
	Two files are hardwired; at least one needs to be present.
	The widget xdisplayfile is called if /show is set.
	The widget wrgb is called if /view is set.
 Modification history:
	write, 29 Nov 91, F.K.Knight (knight@ll.mit.edu)
	add keyword noindex to simply return the rgb values and not alter the
	  color table, 27 Apr 92, FKK
	add keyword reset, 30 Jun 92, FKK
	fix bug when /last occurs after /first, 30 Jun 92, FKK
	make a generic file the default, 6 Oct 92, FKK

(See /IDL/pro_src/RODENA/pro/user_c/thecolor.pro)

TYPE

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
	TYPE
 PURPOSE:
	Finds the type class of a variable.
 CATEGORY:
	Programming.
 CALLING SEQUENCE:
	Result = TYPE(X)
 INPUTS:
    X
	Arbitrary, doesn't even need to be defined.
 OPTIONAL INPUT PARAMETERS:
	None.
 KEYWORD PARAMETERS:
	None.
 OUTPUTS:
	Returns the type of X as an integer, in the (0,7) range.
 OPTIONAL OUTPUT PARAMETERS:
	None.
 COMMON BLOCKS:
	None.
 SIDE EFFECTS:
	None.
 RESTRICTIONS:
	None.
 PROCEDURE:
	Extracts information from the SIZE function.
 MODIFICATION HISTORY:
	Created 15-JUL-1991 by Mati Meron.

(See /IDL/pro_src/RODENA/pro/user_c/type.pro)

WRGB

 [Previous Routine] [Next Routine] [List of Routines] 
 NAME:
	wrgb
 Purpose:
	Read and display colors from the rgb table---good
	for choosing X-windows colors and browsing for pleasing hues.
 Usage:
	wrgb[,offset=offset][,dim=dim]
 Optional Inputs:
	offset = starting point in the file; there are about 740 entries.
	dim = length of side (in pixels) of a color square
 Outputs:
	Colors are reported to the terminal if the left or middle
	mouse button is pushed.
 Common blocks:
	wrgb = variables that need to be passed between routines
 Procedure:
	Use IDL widgets.  After setup, xmanager runs the show.  The background
	routine (wrgb_bck) runs like rdpix.pro and reports the color at the
	cursor position to the window.  Pushing the left or middle mouse 
	button records the current color at the terminal, again like rdpix.pro.
	Moving the offset slider forces an update of the color table.
	Pushing the done button kills all the widgets.
 Example:
	IDL> wrgb		; starts widget
 Modification history:
	convert xrgb to widget-based wrgb, 30Sep91, FKK
	fix bugs, e.g. cursor,x,y,2 didn't return on cursor motion, 7Oct91, FKK
	save existing color table at start and reset it at end, 29Jan92, FKK
	add help button, 29 Jul 92, FKK
	use a generic file rather then $OPENWINHOME/lib/rgb.txt, 6 Oct 92, FKK

(See /IDL/pro_src/RODENA/pro/user_c/wrgb.pro)

XANNOUNCE

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

(See /IDL/pro_src/RODENA/pro/user_c/xannounce.pro)

XCD

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

 PURPOSE:
   Change current directory via mouse.

   Two lists are displayed side by side.  The one on the left shows
   directories.  Click on a directory to cd there.  The list
   on the right shows files to help you see where you are.
   (The list on the right does not respond to mouse clicks.)
 CATEGORY:
   Utility.
 CALLING SEQUENCE:
   xcd
 INPUTS:
   None.
 KEYWORD PARAMETERS:
   None
 OUTPUTS:
   None.
 SIDE EFFECTS:
   Your current directory can be changed.
 RESTRICTIONS:
   Windows & OpenVMS & unix platforms only.  Originally written on Windows95.
   Should work on other Windows platforms, but I (Paul) havn't tried it.

   Note that drive names are resolved by procedure GET_DEVICES

 PROCEDURE:
   Xcd creates an object that has a reference to a DirListing, and
   that has widgets for displaying that DirListing.  If the user clicks on a
   sub-directory (or "..\") in the xcd object, or droplist-selects
   a different drive via the xcd object, the xcd object changes
   IDL's current directory to that location, and refreshes with a
   new current-directory DirListing.

 MODIFICATION HISTORY:
   Paul C. Sorenson, July 1997. paulcs@netcom.com.
        Written with IDL 5.0.  The object-oriented design of Xcd is
        based in part on an example authored by Mark Rivers.
   Jim Pendleton, July 1997. jimp@rsinc.com
        Modified for compatability with OpenVMS as a basis for
        platform independent code
   Paul C. Sorenson, July 13 1997.  Changes so that DirListing class
        methods do not return pointers to data members.  (Better
        object-oriented design that way.)
   Karsten Rodenacker, July 16 1997. Changes using my routine GET_DEVICES
	      and additions for unix machines

(See /IDL/pro_src/RODENA/pro/user_c/xcd.pro)

XGETDATA

 [Previous Routine] [List of Routines] 
 NAME:
	XGetData
 PURPOSE:
	Retrieves a data file from the images directory in the main IDL
	directory.  The file can be specified when calling the routine
	or the file can be chosen by the user with a widget that lets them
	make the selection.
 CATEGORY:
	Widgets
 CALLING SEQUENCE:
	XGetData, NEWDATA
 KEYWORD PARAMETERS:
	ASSOC_IT = When set, this keyword forces the routine to return
		an associated variable instead of a standard IDL variable.  
		This is more efficient when loading animations for instance
		as it removes the need to create two copies of the data
		in memory (one for the animation, one for the load data).
	DESCRIPTION = This keyword returns the description of the data
		selected by the XGetData routine (NEWDATA).
	DIMENSIONS = This keyword returns the dimensions of the data
		selected by the XGetData routine.  These dimensions 
		are the dimensions of the NEWDATA variable.
	FILENAME = The name of the file that is to be selected from the
		images subdirectory.  If this keyword is set, no user 
		selection widget is created.
	OFILENAME = name of file selected.
	ONE_DIM = This keyword is set when the routine is to consider
		one dimensional data from the data contained in the
		images subdirectory.
	TWO_DIM = This keyword is set when the routine is to consider
		two dimensional data from the data contained in the
		images subdirectory.  When searching for two dimensional
		data, this routine will use the first slice of any 
		three dimensional data that it encounters.
	THREE_DIM = This keyword is set when the routine is to consider
		three dimensional data from the data contained in the
		images subdirectory.
	TITLE = The string that will appear in the title portion
		of the data selection widget.  If not specified, the
		title will be "Please Select Data".
 OUTPUTS:
	NEWDATA = the variable that is to be filled with the new data.
 COMMON BLOCKS:
	GF - maintains which selection was made when using the data
		selection widget.
 SIDE EFFECTS:
	Desensitizes all the other widgets and is modal in behavior.  It 
	forces the user to make a selection before proceeding with other 
	widget functions.
 RESTRICTIONS:
	Needs to have directory called images in the main IDL directory
	(IDL_DIR) and the directory must contain a file called data.doc
	that describes the contents of the directory.
 PROCEDURE:
	If the FILENAME keyword was not set, determine the file name using
	a widget that lets the user make a selection from the data.doc file
	and then open that file, read the data, dimensions, and description,
	and return the data.
 MODIFICATION HISTORY:
	Written by Steve Richards,	Dec, 1990

(See /IDL/pro_src/RODENA/pro/user_c/xgetdata.pro)