NAME:
	GetFileSpec
 PURPOSE:
	Retrieve file name information from the common block
	set by SetFileSpec.
 CATEGORY:
	I/O, string manipulation
 CALLING SEQUENCE:
	FUNCTION GetFileSpec, setfile, $
	    from	= From	, $
	    upto	= Upto	, $
	    part	= Part	, $
	    strict	= strict, $
	    asfilename	= AsFileName
 INPUTS:
	setfile
	    array; type: string
		array of file names is fed into SetFileSpec before anything
		else is done. If not specified then the information set up by
		a previous call to SetFileSpec is used.
	From, UpTo, Part
	    scalar; type: string
		Any of the following six strings can be used:
		'NODE','DEVICE','DIRECTORY','NAME','TYPE','VERSION'
		(a prefix 'FILE' is permitted, as in 'FILENAME')
		The input is case-insensitive
		Only a unique starting substrings has to be specified
		If From is not specified, From='NODE' is assumed
		If UpTo is not specified, From='VERSION' is assumed
 OPTIONAL INPUT PARAMETERS:
	/AsFileName if UpTo = 'Directory' and AsFileName is set than the
		directory names are returned as file names, i.e.
		in vms a *.DIR name is returned; in Win32 and Unix
		the trailing (back)slash is removed. MacOS is not
		implemented.
 OUTPUTS:
	Result	string array
		The array structure is determined by the input to the
		SetFileSpec call that set up the internal data.
		Includes all FileParts in between and including the
		From and UpTo strings
 INCLUDE:
	@compile_opt.pro	; On error, return to caller
 CALLS: ***
	InitVar, IsType, SetFileSpec, SyncDims, os_separator, strposn
 CALLED BY:
	FUNCTION smeilatest lastorbit, FindAllFiles, FindAllSubDirs, bin_read, bin_write
	do_file, findfile_fix, get_page, gunzip_file, gzip_file, img_read, makemovie, mk_flick
	mpc_body, nso_fe_read, physics_constant, qImage, qImage_Pick, qImage_cw_Property
	qImage_cw_Save, qImage_cw_SmeiMask, qSave2File, qSave2File_Pick, qSave2File_Save
	qView, qView_FileFilter, qView_PickFiles, qView_Save2File, qView_Shortname
	qView_TMO_tracksky, qset_page_pick, qsmei_sky_pick, qvu_pick, set_page, sgp_body
	smei_TimePosn, smei_base_testcase, smei_buf, smei_buf_getframe, smei_buf_prep
	smei_buf_splitfile, smei_filename, smei_findcrazy, smei_frm_cp, smei_frm_cvhdr
	smei_frm_read, smei_frm_smoothdark, smei_frm_update, smei_frm_write
	smei_getfile, smei_hdr_make, smei_mkcal, smei_mkorb, smei_mkzldresidue
	smei_orbit_stats, smei_property, smei_sky_cleanedge_map, smei_star_cleanup
	smei_star_fitone, smei_star_list, smei_star_remove, smei_star_split
	smei_star_writepnt, smei_time, smei_www_skymaps, smei_zld_remove [1]
	smei_zld_remove [2], timeposn, unhide_env, usno_body, vu_check, vu_coronagraph
	vu_earthskymap, vu_extract, vu_get_page, vu_getdata, vu_header, vu_image
	vu_insitu_raw, vu_movie, vu_quick_movie, vu_remoteview, vu_vox_sequence
	vu_vox_write, vu_write, who_am_i, wso_read, wso_write, www_help_crosslinks
	www_help_files, www_help_get_header, www_help_get_info
 EXAMPLE:
	SetFileSpec, 'ud1:[test]file.txt'	Establishes internal data
	print, GetFileSpec()			Prints: ud1:[test]file.txt
	print, GetFileSpec(upto='dir')		Prints: ud1:[test]
	print, GetFileSpec(from='name') 	Prints: file.txt
	print, GetFileSpect(from='dev',upto='dev') Prints: ud1:
 INCLUDE:
	@filespec_common.pro	; Common block with arrays File and Parts
 SIDE EFFECTS:
 >	Input is converted to uppercase
 RESTRICTIONS:
 >	Internal data must have been set up by SetFileSpec
 PROCEDURE:
	Extracts data from common block set by SetFileSpec
 MODIFICATION HISTORY:
	DEC-1997, Paul Hick
	JAN-2001, Paul Hick (UCSD/CASS)
	    Added part keyword
	OCT-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
	    Added setfile keyword

 NAME:
	grd_read
 PURPOSE:
	Very provisional reader for .grd files
 CATEGORY:
	gen/idl/util
 CALLING SEQUENCE:
	FUNCTION grd_read, InFile, data , $
	    dimension	= dimension	, $
	    norow	= norow 	, $
	    errormessage= errormessage	, $
	    silent	= silent
 INPUTS:
	file	    scalar; type: string
			fully-qualified file name
 OPTIONAL INPUT PARAMETERS:
	/dimension  is set then only the array dimension from the header
			is returned
 OUTPUTS:
	result	    scalar; type: integer
			always 1
	data		array[n,m]; type: float
			data array
		    array[2]: type: integer
			(only if /dimension is set)
			Size of array (i.e. values of n and m)
 OPTIONAL OUTPUT PARAMETERS:
	error_message=error_message
		    scalar; type: string
			always null-string
 INCLUDE:
	@compile_opt.pro	; On error, return to caller
 CALLS: ***
	InitVar, IsType, destroyvar, do_file, flt_string, gunzip_file, hide_env
 CALLED BY:
	img_read, makemovie, smei_mkglare, smei_mksidereal, smei_mkstarmask
	smei_mkstdstar, smei_mkzldresidue
 SEE ALSO:
 PROCEDURE:
 MODIFICATION HISTORY:
	JUL-2003, Paul Hick (UCSD/CASS)
	SEP-2003, Paul Hick (UCSD/CASS)
	    Added /dimension keyword
	SEP-2003, Paul Hick (UCSD/CASS)
	    Added /norow keyword
	APR-2008, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
	    Added code to handle binary grd files in addition
	    to ascii.

 NAME:
	gridgen
 PURPOSE:
	Generate array of x,y,z coordinates for a multi-dim area
 CALLING SEQUENCE:
	FUNCTION gridgen, nn, yy, zz, $
	    unit    = unit	, $
	    merge   = merge	, $
	    origin  = origin	, $
	    edge    = edge	, $
	    open    = open	, $
	    one     = one	, $
	    range   = range	, $
	    multid  = multid	, $
	    double  = double
 INPUTS:
	n	    array[ndim]; type: integer
		    (ndim = 1,2,3)
		    dimensions of area in x, x-y, or x-y-z directions
 OPTIONAL INPUT PARAMETERS:
	/one	    if set, scales output array to range [0,1] in all dimensions
	one=one     array[ndim]; type: integer with value 0 or 1
		    set scaling for each of the dimension in 'n' separately

	/open	    if set, then the pixel centers for the 'pixel edges' [0,n]
		    is returned
	open=open   array[ndim]; type: integer with value 0 or 1
		    set 'open' status for each of the dimensions separately
		    This is the same as gridgen1d(n, origin=-0.5)
		    The origin=0.5 is added to the origin specified in keyword
		    origin.

	/edge	    if set, then coordinates for the 'pixel edges' of pixels
		    [0,..n-1] is returned
	edge=edge   array[ndim]; type: integer with value 0 or 1
		    set 'edge' status for each of the dimensions separately
		    This is the same as gridgen(n+1, origin=0.5)
		    The origin=0.5 is added to the origin specified in keyword
		    origin.

 CALLED BY:
	EarthSky3DLoc, EarthTransit3DLoc, GetColors, PlotBars, PlotCoronagraph
	PlotEarthSkymap, PlotEloTimeMap, PlotPlanarCut, PlotPolarSkymap, PlotSolarDisk
	PlotSphereCut, PlotSynopticMap, RemoteView, RemoteView_CMEDensity
	RemoteView_CubeFrame, RemoteView_CurrentSheet, RemoteView_Display2D
	RemoteView_FOV_xyz, RemoteView_VertexSphere, RemoteView_rgbo, TMO_skymotion
	TMO_tracksky, ThomsonLOSStep, TimeXAxis, big_orbit, cvsmei, even_light
	even_light_figures, even_light_pedestal, even_light_platescale, jpl_test
	plot3darc, qGlitch_Run, qImage_cw_BoxCosine, qImage_cw_SmeiMask
	qImage_cw_ZEllipse, qView_PlotSeries, qvu_draw, sgp4_orbit_axis, smei_ccd2sky
	smei_hdr_plot, smei_mkmask, smei_sky, smei_sky_cleanedge_fov, smei_sky_getmask
	smei_sky_read, smei_star_box, smei_star_standard, smei_zld_model
	smei_zld_remove [1], smei_zld_remove [2], smei_zldsky, sphere_great_arc
	sphere_smooth, vu_coronagraph, vu_elotime, vu_extract, vu_get, vu_insitu
	vu_insitucurve, vu_movie, vu_planarcut, vu_solardisk, vu_spherecut, vu_syncgrid
	vu_synopticmap, vu_timeseries, vu_type_skymap, vu_vox_drawelatitude
	vu_vox_drawelongitude, vu_vox_drawhlatitude, vu_vox_drawhlongitude
	vu_vox_draworbit, vu_vox_drawsphere, vu_vox_write, wedge_content, wso_read
		    Example: gridgen(5, /edge) = [-0.5,0.5,1.5,2.5,3.5, 4.5]
	origin=origin
		    array[ndim]; type: float
		    defines the origin in units of output grid
		    (i.e. usually in array indices; but if /one or range are
		    used then it is in units of the data range)

	range=range scalar, array[ndim] or array[2,ndim]
		    if scalar then the output array is scaled to the range
			[0,range] in every dimension
		    if array[ndim] then the output array is scaled to the ranges
			[0,range[i]], i=0,ndim-1, in each dimension
		    if array[2,ndim] then the output array is scaled to the ranges
			[range[0,i],range[1,i]], i=0,ndim-1 in each dimension

	/multid     (only in ndim > 1) reforms output array to [ndim,n] array.
		    The default is a two-dim array of size
			[ndim,n[0]*n[1]*..*n[ndim-1]]
 OUTPUTS:
	Result	    array[ndim,n[0],n[1],..,n[ndim-1]]; type: long integer or float
			coordinates across the area
			a float array is returned if keywords /one or /range
			are used.
 CALLS: ***
	InitVar, IsTime, IsType, SuperArray, TimeOp, TimeSet, TimeUnit, gridgen1d
 INCLUDE:
	@compile_opt.pro	    ; On error, return to caller
 RESTRICTIONS:
	For time structures only 1-dim arrays can be generated
 PROCEDURE:
 >	The origin is subtracted after applying the scaling implied by
	keywords /one and range=range
 >	Combination of 'replicate' function and matrix multiplication #

 >	Create 1-dim time grids:
	gridgen(10,TimeUnit(/day))
	    10-element grid of time differences with 1-day time steps
	gridgen(10,TimeUnit(/day),range='2008_001'
	gridgen(10,range=['2008_001','2008_009'])
	    10-element grid with 1-day steps starting at 2008_001
 MODIFICATION HISTORY:
	OCT-2000, Paul Hick (UCSD/CASS)
	    Result of merging indgen1d, indgen2d, and indgen3d
	JAN-2002, Paul Hick (UCSD/CASS)
	    Change all replicate(1.0,n) statements to replicate(1L,n) in the
	    last case block.
	    Using 1.0 will always return a float array even when an integer
	    return would be acceptable.
	NOV-2005, Paul Hick (UCSD/CASS)
	    Added 4D version
	SEP-2006, Paul Hick (UCSD/CASS)
	    Substantial rewrite: generalized to work for any number
	    of dimensions (memory permitting)
	OCT-2008, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
	    Added argument 'unit' and allowed keywords 'origin' and
	    'range' to be standard structures. This allows setting up
	    1-dim arrays of times.

 NAME:
	gridgen1d
 PURPOSE:
	(For internal use by gridgen only)
 CALLING SEQUENCE:
	FUNCTION gridgen1d, nn, unit, $
	    origin  = origin, $     ; Could be time
	    edge    = edge  , $
	    open    = open  , $
	    one     = one   , $
	    range   = range , $     ; Could be time range
	    double  = double
 INPUTS:
	nn	scalar; type: integer
		    number of elements in grid
 OPTIONAL INPUTS:
	origin=origin
		scalar; type: any numerical type
		the origin is shifted AFTER
		applying keywords one or range.
	/open
	/edge	return edges of bins
	/one	same as range=[0,1]
	range=range
		array[2]; type: any numerical type
		scale array to this range
		If range is of type integer then the grid
		also will be type integer unless integer
		truncation occurs.
	/double if set return double precision grid
 INCLUDE:
	@compile_opt.pro	; On error, return to caller
 CALLS: ***
	InitVar, IsTime, IsType, TimeOp, TimeSet, TimeUnit
 CALLED BY:
	gridgen
 EXAMPLE:
	gridgen(5)		= [0,1,2,3,4]
	gridgen(5,/open)	= [0.5,1.5,2.5,3.5,4.5]
	gridgen(5,/open,/edge)	= [0,1,2,3,4,5]
	gridgen(5,/one) 	= [0.0,0.25,0.5,0.75,1.0]
	gridgen(5,/one,orig=0.5)= [-0.5,-0.25,0.0,0.25,0.5]
 PROCEDURE
	Sets up 1-dim grid. BE CAREFUL MIXING KEYWORDS.
 MODIFICATION HISTORY:
	OCT-2000, Paul Hick (UCSD/CASS)
	SEP-2006, Paul Hick (UCSD/CASS)
	    If range is specified as integer then the return
	    array is returned as integer array also, after
	    checking that integer truncation has not occurred.
	    Keyword origin is now applied after processing
	    keywords one and range (if present).
	JUN-2008, Paul Hick (UCSD/CASS)
	    Added code to handle n=1 without error messages
	OCT-2008, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
	    Added code to create 1-d time grids

 NAME:
	GuessRecs
 PURPOSE:
	Guess number of records and record length for binary file
 CATEGORY:
	Tricks
 CALLING SEQUENCE:
	FUNCTION GuessRecs, iu, approx_recl, range, recl=recl
 INPUTS:
	iu	    scalar; type: integer
			logical unit number of open file
	approx_recl scalar; type: integer
			approximate record length in bytes
 OPTIONAL INPUT PARAMETERS:
	range	    scalar: type: integer: default: 1
			range of recordlength tested is approx_recl +/- range
 OUTPUTS:
	Results     scalar; type: integer
			guess at # records (-1 if not succesful)
 OPTIONAL OUTPUT PARAMETERS:
	recl = recl scalar: type: integer
			guess at record length in bytes (= file size/# records)
			(-1 if not succesful)
 INCLUDE:
	@compile_opt.pro	; On error, return to caller
 CALLS: ***
	InitVar
 CALLED BY:
	txt_read
 PROCEDURE:
	The approximate record length specified as input does not include record
	terminators (such as CR or CR+LF combinations).
	If the approximate record length specified is L and the range is R then
	for all values i=[L-R,L+R] the procedures checks whether i+1 or i+2 are factors
	of the file size. The largest i that satisfies this criterion is used to set
	the number of records in the file. The record length returned is the ratio of
	file size and number of records (i.e. it includes the record terminators).
 MODIFICATION HISTORY:
	MAR-2000, Paul Hick (UCSD/CASS)
	SEP-2003, Paul Hick (UCSD/CASS)
	    Fixed order in which record lengths are tested.
	    approx_recl is tested first.
	    Then record lenghts increasingly different from approx_recl:
	    approx_recl-1, approx_recl+1, approx_recl-2, approx_recl+2, etc.
	APR-2008, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
	    For an empty file now nrec=recl=0 is returned,
	    instead of nrec=recl=-1.

 NAME:
	gunzip_file
 PURPOSE:
	Unzip .gz. file
 CATEGORY:
	gen/idl/util
 CALLING SEQUENCE:
	FUNCTION gunzip_file, zipfile, rawfile, check=check, isgz=isgz, ramdisk=ramdisk
 INPUTS:
	zipfile scalar; type: string
			file to be unzipped
 OPTIONAL INPUT PARAMETERS:
	/check	    if set then check whether the file exists
	/ramdisk    by default the unzipped file is written to $TUB
		    if /ramdisk is set the environment variable $ramdisk
		    is tried first.
 OUTPUTS:
	status	    0: unzip not successfull
		    1: file succesfully unzipped into file 'rawfile'
	rawfile     scalar; type: string
			name of unzipped file (if status=1) or the blank
			string (if status=0)
 OPTIONAL OUTPUTS:
	isgz=isgz   1 if input file was .gz file; 0 if not.
 INCLUDE:
	@compile_opt.pro	; On error, return to caller
 CALLS: ***
	FILEPATH, GetFileSpec, InitVar, SetFileSpec
 CALLED BY:
	bin_read, flt_read, grd_read, img_read, smei_fts_read, smei_star_readpnt, txt_read
	vox_read
 PROCEDURE:
	If the input file 'zipfile' does not exist or is not a .gz file then
	status = 0 is returned.

	The unzipped output file has the same name as the input file with
	the prefix _tmp_ added and the .gz stripped.
	By default the file is written to $TUB. If /ramdisk is set then
	$ramdisk is used (if the env var exists). Usually $ramdisk will point
	to a ramdisk. Note that the user should set up the ramdisk and make
	sure it is big enough to hold the unzipped file.
 MODIFICATION HISTORY:
	APR-2003, Paul Hick (UCSD/CASS)
	JUL-2004, Paul Hick (UCSD/CASS)
	    Added /ramdisk keyword.
	DEC-2007, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
	    Change name of temp file from _tmp_* to _tmp##_*, where ## is
	    a number less than 10. The number is the lowest number that
	    make a file name for a non-existent files. This was added to
	    avoid conflicts with other program trying the same file
	    (the conflicting program might delete the temp file before it
	    is read).

 NAME:
	gzip_file
 PURPOSE:
	Unzip .gz. file
 CATEGORY:
	gen/idl/util
 CALLING SEQUENCE:
	status = gzip_file( file, zipfile)
 INPUTS:
	file	scalar; type: string
			file to be unzipped
 OPTIONAL INPUT PARAMETERS:
	/check	    if set then check whether the file exists
	/nozip	    skip the actual zipping; only return the name
		    of the zipped file if it had been zipped
	/force	    force gzip if file already exists
 OUTPUTS:
	status	    0: zip not successfull
		    1: file succesfully zipped into file 'zipfile'
	zipfile     scalar; type: string
			name of zipped file (if status=1) or the blank
			string (if status=0)
 OPTIONAL OUTPUTS:
	isgz=isgz   1 if input file was .gz file; 0 if not.
 INCLUDE:
	@compile_opt.pro	; On error, return to caller
 CALLS: ***
	FILEPATH, GetFileSpec, InitVar
 CALLED BY:
	smei_mksidereal, smei_mkstdstar, smei_star_remove, smei_zld_remove [1]
	smei_zld_remove [2], vu_write
 PROCEDURE:
	If the input file 'zipfile' does not exist or is not a .gz file then
	status = 0 is returned.
 MODIFICATION HISTORY:
	OCT-2003, Paul Hick (UCSD/CASS)
	NOV-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
	    Added /nozip keyword