PDS 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: Wed Aug 30 10:54:51 2017.

• BROWSE_PDS
• CONVERT_CODES
• CREATE_TABLESTRUC
• GETTAGSBYNAME
• GET_TAGS
• HEADER2HASH
• HEADERTOHASH
• LABEL2HASH
• PARAMSTOSTRUCT
• PARSE_PARAMETER
• PDS_OPEN
• PDS_TRANSLATE
• PRETTYHASHOFHASH
• PRETTYXML
• READFILE
• READ_PDS
• READ_VOTABLE
• READ_VOTABLE8
• READ_XML
• READ_XML8
• RMELEMENT
• STR_CLEAN
• TVIT
• XML2IDL
• XML2IDL8
• XMLDOCUMENT__DEFINE

Routine Descriptions

 NAME:
       BROWSE_PDS

 PURPOSE:
	Browse PDS4 data using a widget to display both metadata and data 
	and output all the data or some
	subset of it.  One can view images in an attached IDL window.

 CATEGORY:
       Datafile handling; PDS

 CALLING SEQUENCE:
       data_struct = BROWSE_PDS([filename])

 INPUTS:
 filename - Name of PDS XML document that describes the data and datafiles.  
            It is optional; if one uses no input parameters, then a file 
            selection window appears to allow convenient selection of the 
            PDS XML file.

 OUTPUTS:
 data_struct - Any subset of the data or metadata

 KEYWORDS:
       NO_REORIENT - Do not use display_direction directives to reorient the
				image.
        
 PROCEDURES USED:
        READ_PDS, TV1

 PACKAGE LOCATION:
         http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar


 IDL VERSIONS TESTED: 8.4

 MODIFICATION HISTORY:
 Written by Ed Shaya / U. of Maryland[Sept. 25, 2012]. 
   Major rewrite: increased speed, reduced lines of code, most data text
   nodes do not need to open a new window, arrays of length 1 now
   show up.  addleaf2tree.pro no longer needed. (ES-7/29/15)

(See PDS/browse/browse_pds.pro)

 NAME:  
	CONVERT_CODES

 PURPOSE: 
	Convert C-printf-Style format code to Fortran format code

 CATEGORY: 
	PDS processing

 CALLING SEQUENCE:
	result = convert_codes(codein)

 INPUTS:
	codein -  a string or string array of C-style format codes.

 OUTPUTS:
	Returns a string or string array of Fortran style format codes 
	(for use in IDL readf and printf statements).

 PROCEDURES USED: 
	Built-in, only.

 PACKAGE LOCATION: 
 	http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

 MODIFICATION HISTORY:
	Written by Ed Shaya / U. of Maryland [Nov. 7, 2013]

(See PDS/convert_codes.pro)

 NAME: 
	CREATE_TABLESTRUC

 PURPOSE:
	Creates a structure to hold a table.

 CATEGORY:  
	PDS Processing

 CALLING SEQUENCE:
	Result =  CREATE_TABLESTRUC(tags, datatype, repetitions, field_length, tabletype)

 INPUTS:
	tags - Names of the fields of the table. Expects all tags are IDL valid variable 
	names and are unique.
	datatype - PDS standard names for field datatypes.
	repetitions - (Nfields,3) dimensioned integer array.  For each field,there is an 
             (N,M,L) to provide the dimension of array.  If field is just an 
             array then it will be (N,0,0). (N,M,0) for 2-d array. (N,M,L) for 3-d array
	field_length - Length of each cell in the field.
	tabletype -  This just needs to be set to "BINARY", if table is binary type

 OUTPUTS:
	Result -  An IDL Structure to hold a table.

 KEYWORDS: 
	None.

 PACKAGE LOCATION:  
	http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

 MODIFICATION HISTORY:
	Written by Ed Shaya / U. of Maryland [Nov. 7, 2013]
	Added ASCII_DATE DOY, YMD, and UTC types (March 26, 2015, EJS).
	Change ASCII_Numeric_Base2 to be read into strings and ASCII_Numeric_Base8 
	  and _Base16 to be read into Longs.  (March 28, 2015, EJS).
 	Fixed bug in reading ASCII array within a Binary Table (ES/July 9, 2015)

(See PDS/create_tablestruc.pro)

 NAME:
	GetTagsByName

 PURPOSE:
	Get an array of tagnames in a structure matching name expression.
	Can use full regex in the name (See Learning About Regular Expressions in IDL Help).
	Will return an array of the values of the variables in the structure
	corresponding to these tagnames, if /getvalues is set.

 CATEGORY:
	structure processing

 CALLING SEQUENCE:
	Result = GETTAGSBYNAME(structure,tagname,[/getvalues, root=root, settags=settags, count=count]) 

 INPUTS:
	structure - An IDL structure

	tagname - expression to match with the tagname string
             Regular Expression Examples:
		'\.name1$' -  Search for final tag 'name1' exactly.
		'\.name1\.[^.]+$' -  Search for only direct children of 'name1'.
		'name1\.name2$' -  Search for tags ending in 'name1.name2'.
		'\^.name1\.name2(__[1-9])?$' - Search for top level name1 with child 'name2' or
			'name2__1', 'name2__2', ... 'name2__9'.

 OUTPUTS:
	Returns a string array of full names for tags containing tagname in 
	the structure.  If no matches then result[0] = '-1'
	If getvalues is set, then result is a string array of values of 
	those tags in the structure.  If no values return, then 
	result[0] = '-1'.  

 KEYWORDS:
	getvalues - set to 1 to get values, set to 0 to get tagnames.  Will only work
	if value is scalar or an array, but not a list of structures.

	root - Optionally can use name of structure as prefix to tagnames

	settags - If you already know the tags in the structure, then you can 
       improve efficiency.  Program will not perform another get_tags.  
	Can also use this to restrict search to certain tags.

	count - Number of matches found

 PROCEDURES USED:
	GET_TAGS

 PACKAGE LOCATION:
	http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

 MODIFICATION HISTORY:
	Written by Ed Shaya / U. of Maryland [May 8, 2012]

(See PDS/gettagsbyname.pro)

 NAME: 
	GET_TAGS

 PURPOSE:
	This function returns the names of all tags in the structure as a string 
	array. The names are given from the root structure name,
	which can be passed in along with the structure itself.

 CATEGORY:
	structure processing

 CALLING SEQUENCE:
	Result =  GET_TAGS(structure [, rootname])

 INPUTS:
	structure - Name of structure that will be searched for tagnames

 OUTPUTS:
	result - Names of all tags in the structure.  IDL procedure tag_name only provides
	top level structure tag names

 Optional Input:
	rootname - The name of the structure, provides the rootname if you want the 
	result names to start with it.

 PROCEDURES USED:
	TAG_PTRS

 PACKAGE LOCATION:  
	http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

 MODIFICATION HISTORY:
	Written by Ed Shaya / U. of Maryland [Nov. 9, 2013]

(See PDS/get_tags.pro)

 NAME:
	HEADER2HASH

 PURPOSE:
	Transform a FITS like header (string array) into two IDL ordered hashes. 
	One hash for the values and one for the line comments or keyword definitions.
	Also outputs separate arrays of comments and history.

 CATEGORY:
	Datafile handling; FITS, PDS

 CALLING SEQUENCE:
	hhash = header2hash(header[,comments=comments,history=history,keydefs=keydefs])

 INPUTS:
	header - A string array representing a fits header.

 OUTPUTS:
	 Returns an ordered hash with keys being the FITS keywords and values are 
	their values. Optionally, the keydefs hash with the comments in fits cards at the end
	of many lines (after '/') that usually give the definition of the keyword.

	Optionally, a string array of all the COMMENT cards

	Optionally, a string array of all of the HISTORY cards

 KEYWORDS:
	keydefs - allows the keyword comments to be returned in a hash 
	with same keywords as in the returned value hash.
        
	comments - String array return of the COMMENTS cards.

	history - String array return of the HISTORY cards

 PACKAGE LOCATION:
	http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

 IDL VERSIONS TESTED: 
	8.3

 MODIFICATION HISTORY:
	Written by Ed Shaya / U. of Maryland [Oct 5, 2013]. 
	Major rewrite ES April 27, 2015. No longer relies on sxpar and other 
	fits routines in astron library.

(See PDS/header2hash.pro)

 NAME:
       HEADERTOHASH

 PURPOSE:
      Transform a FITS like header (string array) into two IDL hashes.  One hash for the values and one for the comments.

 CATEGORY:
       Datafile handling; FITS, PDS

 CALLING SEQUENCE:
       hhash = headertohash(header,comments=comments

 INPUTS:
 header - A string array holding the information from a fits header (or something resembling it)

 OUTPUTS:
      A hash with keys being the parameter keywords and values are fits values

 KEYWORDS:
        comments - allows the comments to be returned in a hash as well with keys being the parameter keywords.
        
 PROCEDURES USED:
        NONE

 PACKAGE LOCATION:
        http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

 IDL VERSIONS TESTED: 8.2

 MODIFICATION HISTORY:
 Written by Ed Shaya / U. of Maryland [Oct 5, 2013]. 

(See PDS/headertohash.pro)

 NAME:
	LABEL2HASH 

 PURPOSE:
	Read in a PDS3 label into an ordered hash.
Category:
	Datafile Handling: XML, PDS

 CALLING SEQUENCE:
	Return =  label2hash(file)
	  Or 
	Return = label2hash() 

 INPUTS:
	file - filename of .lbl file.  If no input then a Widget opens to help select lbl file
	
 Outputs:
	Return is ordered hash of label keywords and values
 Keywords:
	None

 Example: 
	IDL> file = 'dbcp.lbl'
	IDL> hh=label2hash(file) 
	IDL> print,hh
	PDS_VERSION_ID: PDS3
	RECORD_TYPE: FIXED_LENGTH
	RECORD_BYTES: 240
	FILE_RECORDS: 2653
	^TABLE: DBCP.TAB
	DATA_SET_ID: EAR-C-COMPIL-5-DB-COMET-POLARIMETRY-V1.0
	PRODUCT_NAME: DATABASE OF COMET POLARIMETRY
	PRODUCT_ID: DBCP_TAB
	INSTRUMENT_HOST_NAME: PUBLISHED LITERATURE
	INSTRUMENT_NAME: COMPILATION
	TARGET_NAME: COMET
	TARGET_TYPE: COMET
	START_TIME: 1940-11-26
	STOP_TIME: 2005-07-03
	PRODUCT_CREATION_TIME: 2006-07-05
	TABLELIST: LIST  


	IDL> hh['TABLELIST',0,'COLUMNLIST',4].keys()
[
    "COLUMN_NUMBER",
    "NAME",
    "START_BYTE",
    "BYTES",
    "DATA_TYPE",
    "FORMAT",
    "DESCRIPTION",
    "END_OBJECT"
]

          
 Procedures Used:
	rmelement.pro, readfile.pro

PACKAGE LOCATION: 
	http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

 Modification History
	Written by Ed Shaya / U. of Maryland [JULY 11, 2014]
	Substantial rewrite to keep carriage returns in a long
	multiline value.  Now, the label is converted into an IDL LIST
	and then that list is turned into an IDL ORDEREDHASH. [5/6/2015]

(See PDS/label2hash.pro)

 NAME:
	paramsToStruct

 PURPOSE:
	Converts a parameter string array (eg, header for FITS files) into
	an IDL Structure where each keyword is a tag of a structure and
	each of these structures contain a value and a comment. The values
	should by datatyped (float, int, string, etc) correctly.  
	Logical T is transformed to 1byte and F to 0byte.
	Does not work on PDS labels because it requires unique keynames 
	and OBJECT and END_OBJECT can be repeated.

 CATEGORY:
	Datafile handling; PDS; FITS

 CALLING SEQUENCE:
	struct = paramsToStruct(paramArray,commentChar=commentChar)

 INPUTS:
	paramArr - A string consisting of 'key = value'.  Value can have 
	spaces. Comments (which describe the keyvalue) are on the same line and 
	after the value and start with the commentChar character.
	(eg, '   keyword = 17.3   / A keyword with floating point value')

 OUTPUTS:
	struct - A structure in which each keyword is a tag holding a structure.
	Each of these structure hold a value and a comment.

 KEYWORDS:
	commentChar - Character that begins the comment on each line.  Default is '/'.

 PROCEDURES USED:
	PARSE_PARAMETER

 PACKAGE LOCATION:
	http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

 MODIFICATION HISTORY:
	Written by Ed Shaya / U. of Maryland [June 27, 2012] ;

(See PDS/paramstostruct.pro)

 NAME:
       PARSE_PARAMETER

 PURPOSE:
	Given a string from a parameter/header ('key = value'), returns key and 
	value of a parameter as two element array by basically splitting on an 
	equal sign. If commentChar is set to the delimiter for start of a 
	comment, then it returns a 3 element array [key, value, comment].
	Keyword "pos" returns position of beginning of key.
	If there is no equal sign, then it returns [strtrim(line,2),''] and 
	pos = -1.

 CATEGORY:
	Datafile handling; PDS

 CALLING SEQUENCE: 
	keyval = PARSE_PARAMETER(line, pos=pos, commentChar=commentChar)

 INPUTS:
	line - A string consisting of 'key = value'.  Value can have spaces.

 OUTPUTS:
	keyval -  2 element array with [key,value] as strings or 3 element 

	array, if commentChar keyword is set, with [key,value,comment]

 KEYWORDS:
	pos - position of first character of key in paramArr 

	commentChar - character that begins a comment or description

 PROCEDURES USED:
	IDL built-in procedures

 PACKAGE LOCATION:
	http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

 MODIFICATION HISTORY:
	Written by Ed Shaya / U. of Maryland [April 27, 2012]

(See PDS/parse_parameter.pro)

 NAME:
	PDS_OPEN

 PURPOSE:
	Opens and return the unit number of a file positioned at a specified 
	offset in bytes

 EXPLANATION:
	A normal file is just opened (readonly, if specified) and skips to an 
	offset.  For a compressed file, it can determine the type of uncompression
	and sets up a pipe to uncompress the stream.

 CALLING SEQUENCE:
	unit=PDS_OPEN(FILE,OFFSET,READONLY=,COMPRESS=,PIPE=,ERRMSG= ,SILENT=)
            

 INPUT PARAMETERS:
	FILE    = file name, scalar string

	OFFSET  = offset from the beginning of the file to start read or write

 RETURNS:
	Unit number of file or -1 if an error is detected.

 OPTIONAL INPUT KEYWORD PARAMETER:
	COMPRESS - If this keyword is set and non-zero, then treat
	the file as compressed.  If 1 assume a gzipped file.
	and use IDLs internal decompression facility.    For Unix 
	compressed or bzip2 compressed files spawn off a process to 
	decompress and use its output as the stream.  If the 
	keyword is not 1, then use its value as a string giving the 
	command needed for decompression.

	READONLY - If this keyword is set and non-zero, then OPENR rather 
	than OPENU will be used to open the file.    Note that
	compressed files are always set to /READONLY

	SILENT -  If set, then suppress any messages about invalid characters.

 OPTIONAL OUTPUT KEYWORDS:
	ERRMSG  = If this keyword is present, then any error messages will be
	returned to the user in this parameter rather than
	depending on the MESSAGE routine in IDL.  If no errors are
	encountered, then a null string is returned.

	PIPE - If set to 1, then the file was opened with a pipe
	rather than with the OPENR command.    This is only required 
	when reading a bzip or Unix compressed file.   

 SIDE EFFECTS:
	Opens and returns a file unit.
      
 PROCEDURE:
	Open the appropriate file, or spawn a command and intercept the output.
	Call MRD_SKIP to get to the appropriate extension.
      
 PROCEDURE CALLS:
	MRD_SKIP() (from astron package)
      
 PACKAGE LOCATION:
	http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

 MODIFICATION HISTORY:
	Derived from William Thompson's FXFINDEND routine.
	Modified by T.McGlynn, 1994 - 1999 as MXPOSIT
	Modified by  W. Landsman 23-Apr-1997   - 2009 as MXPOSIT 
	Rewritten by Ed Shaya for PDS data / U. of Maryland Sept-2013 for use in PDS4

(See PDS/pds_open.pro)

 NAME:
       PDS_TRANSLATE

 PURPOSE:
       Translate paramArr (label) by making substitutions for either keywords or values
        across the entire array

 CATEGORY:
       Datafile handling; PDS

 CALLING SEQUENCE:
       paramArr3 = PDS_TRANSLATE(paramArr)

 INPUTS:
       paramArr - A PDS like label (basically keyword = value) , string array

 OUTPUTS:
       paramArr3 - PDS label after translating terms, (string array)

 KEYWORDS:
       NONE 

 PROCEDURES USED:
        PARSE_PARAMETER

 RESTRICTIONS:
	Requires two files holding translation word pairs.  One for keyword to substitute the 
	other for value terms to subsitute.  Format is "oldword = newword"

	Example, 
	pds4keysto3.txt has pairs of keywords (pds4 = pds3), and the file
	pds4valsto3.txt has pairs of values.

 PACKAGE LOCATION:
        http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

 MODIFICATION HISTORY:
	Written by Ed Shaya [April 27, 2012]

(See PDS/pds_translate.pro)

 NAME:
	PRETTYHASHOFHASH

 PURPOSE:
       Procedure to make pretty text printout of a hash of hashes or lists with
 	increasing indents at each level of the hierarchy.  It prints out both
	the keywords and the values or leaves of the data tree.
       Mostly used now for seeing a hash produced when reading in XML with 
	read_xml8.pro.

 CATEGORY:
       Datafile handling; XML; General IDL HASH/LIST

 CALLING SEQUENCE:
          
	prettyhashofhash,hash,[unit=unit,level=level]

 INPUTS:
       HASH - IDL version 8 or above hash.  The hash could contain IDL native 
	values, hashes, IDL lists

 Keywords:
	UNIT - If unit is set, it will print to file handled by UNIT.  
		Otherwise, it prints to screen.
       LEVEL - This is only used for recursion (ie internally)

 PACKAGE LOCATION:
         http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar


 IDL VERSIONS TESTED: 8.2

 MODIFICATION HISTORY:
       Written Nov. 7, 2013 by Ed Shaya / U. of Maryland 

(See PDS/prettyhashofhash.pro)

 NAME:
	PRETTYXML

 PURPOSE:
	Print contents of an XML file with indentation indicating depth of node
Category:
      Datafile Handling: XML

 CALLING SEQUENCE:
	prettyxml,filename
 INPUTS:
	XML filename
 Outputs:
	None
 Keywords:
	None
 Procedures Used:
	IDL built-in Document DOM handling routines
 Modification History
	Written by Ed Shaya / U. of Maryland [Feb 5, 2014]

(See PDS/prettyxml.pro)

 NAME
	READFILE

 PURPOSE
	Read a text file into a string array

 CALLING SEQUENCE:
	return = readfile([file,filter=filter])
               
 INPUTS
	file - name of file to read

	filter - string to be used to filter files when using pickfile widget to select file.

 PACKAGE LOCATION
	http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

 MODIFICATION HISTORY
	Written by Ed Shaya (UMd) [May 3, 2012]

(See PDS/readfile.pro)

 NAME:
	READ_PDS

 PURPOSE:
	This reads metadata from PDS version 4 XML documents, using READ_XML, and
	then reads the data in the datafile into an IDL structure.

 CATEGORY:
	Datafile handling; PDS

 CALLING SEQUENCE:
	data_struct = READ_PDS([file, datastatus=datastatus, metadata=metadata, 
                                     dscale=dscale, version=version])

 INPUTS:
	file - Name and path, if not current directory, of PDS XML document that
	describes the data and datafiles.
	However, if there is no file parameter, then a file selection 
	window pops up to allow convenient selection of the PDS XML file.

 OUTPUTS:
	data_struct - The data.  If the data is held in a FITS data file the output
	is a structure holding pairs of headers and images/data. 
	It also handles fixed format tables (TABLE_CHARACTER) by returning
	a structure that is an array of structures.  
	Each row (record) in the table is an element of the array with tagnames
	given by the names given in the metadata.


 KEYWORDS:
	datastatus - Relays error flags from the routines that read the data.

	metadata - All of the metadata in the PDS XML documents.
	
	noNANs - Set this on if NANs are not wanted in real and double fields.

	version - Prints out version of the code and continues.

	dscale - Ensures scaling (scale_factor and value_offset) is done in double precision.

	no_reorient - Set this flag on to prevent images from being reoriented 
	according to sample_ and line_display_direction, so that they 
	are displayed properly with the TV command.  Default reorients.
 
 PROCEDURES USED:
	READ_XML, XML2IDL, getTagsByName, PDS_READ_TABLE, PDS_OPEN, PDS_RD_IMAGE, PDS_RD_READ_IMAGE
        
 PACKAGE LOCATION:
	http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

 IDL VERSIONS TESTED: 
	8.2

 MODIFICATION HISTORY:
	Written by Ed Shaya / U. of Maryland [July 19, 2012].  Not yet complete.
	Add Delimited Tables [Aug 20, 2012].
	Add BINARY Tables [May 29, 2013].
	Substantial rewrite to ensure info from XML is used
	rather than headers.  Ed Shaya / U. of Maryland Oct. 22, 2013
	Removed path keyword.  Now filename should contain path if needed Feb 4, 2014.
	Sep 6, 2014 - Allow for groups inside of groups to form 2 or 3 dimensional arrays.  ES
	Sep 6, 2014 - Reworked PDS datatype to IDL datatype table. ES
	Sep 9, 2014 - Added scaling for fields in tables. ES
	Sep 10, 2014 - Use local_identifier as structure tag names. ES
	Nov 24, 2014 - Make table_name idl_valid when needed. ES
	Nov 24, 2014 - Fixed a bug that prevented simple arrays in table fields.
	Nov 24, 2014 - Fix for case where headers have no local identifiers
  

(See PDS/read_pds.pro)

 NAME:
	READ_VOTABLE

 PURPOSE:
	READ a VOTable.xml document into IDL (Interactive Data Language, ITT).  
	This function reads the file and parses the XML document 
	It outputs a structure where each tag is an array holding a column
	(field).
	It optionally outputs a structure with all of the metadata in the
	VOTable (fieldname, units, description, datatype) 
	It also optionally outputs a 2D string array holding the table values.
	In metadata, items with text info, such as description, the text is in
	the child element _text.

 CATEGORY:
	Datafile handling; XML, Virtual Observatory

 CALLING SEQUENCE:
	table_struct = READ_VOTABLE(filename,metadata=metadata)

 INPUTS:
	filename  - Name of VOTable.xml file to read (string)

 OUTPUTS:
	table_struct - A structure where each tag is an array holding a column from the table.
	If there is more than one table in the VOTable, then they are all there
	and tagged TABLE1, TABLE2, etc.

 KEYWORDS:
	metadata -  an IDL structure holding all of the info in the VOTable.xml 


 PROCEDURES USED:
	READ_XML, XML2IDL, GET_TAGS

 PACKAGE LOCATION:
	http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

 MODIFICATION HISTORY:
	Ed Shaya / U of Maryland [July 19, 2012]
	Added datatypes (bit, int, boolean) and increased size for long.  Ed Shaya (Nov 8, 2013)
	Nov 24 Fixed a bug for empty elements
	And for these added NaNs for float and double and large negative number for int, long, long64
	

(See PDS/read_votable.pro)

 NAME:
	READ_VOTABLE8

 PURPOSE:
	READ a VOTable.xml document into IDL (Interactive Data Language, ITT).
	It uses IDL Version 8 and above routines for reading the XML.  
	This function reads the file and parses the XML document 
	It outputs a structure where each tag is an array holding a column (field).
	It optionally outputs a structure with all of the metadata in the
	VOTable (fieldname, units, description, datatype).  This will be a hash. 
	It also optionally outputs a 2D string array holding the table values.
	In metadata, items with text info, such as description, the text is in
	the child element _text.
	Missing floats and doubles use IDL NaN !Values and integers get -9999...

 CATEGORY:
	Datafile handling; XML, Virtual Observatory

 CALLING SEQUENCE:
	table_struct = READ_VOTABLE8(filename,metadata=metadata)

 INPUTS:
	filename  - Name of VOTable.xml file to read (string)

 OUTPUTS:
	table_struct - A structure where each tag is an array holding a column from the table.
	If there is more than one table in the VOTable, then they are all there
	and tagged TABLE1, TABLE2, etc.

 KEYWORDS:
	metadata -  an IDL hash holding all of the info in the VOTable.xml 


 PROCEDURES USED:
	READ_XML8

 PACKAGE LOCATION:
	http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

 MODIFICATION HISTORY:
	Ed Shaya / U of Maryland [November 24, 2013]

(See PDS/read_votable8.pro)

 NAME:
	READ_XML

 PURPOSE:
	READ an XML document file into IDL (Interactive Data Language, ITT).  
	Output is either an IDL structure, 
	or an array of parameters (key/value pairs).
	This function reads the file and parses the XML document into a DOM 
	(Document Object Model) object or IDLffXMLDOMDocument.
	It passes oDoc to XML2IDL which walks through the nodes creating the 
	structure or paramArr.  See XML2IDL about the handling of differences 
	between the object models, DOM vs IDL Structure.
	
 CATEGORY:
	Datafile handling; XML

 CALLING SEQUENCE:
	Result = READ_XML(filename, [/toScreen,outFile=outFile,/paramsOut])

 INPUTS:
	filename  - name of XML file to read (string)

 OUTPUTS:
	Result - Either an IDL Structure or a parameter Array (paramArr, 
	string array)
	If paramsOut is not set, then it is a structure.
	
 KEYWORDS:
	toScreen - Write paramArr or the structure's tags to screen

	outFile - If set to a filename, will save paramArr or tags to that file

	paramsOut - If set to 1, Result is paramArr instead of structure.
	
	validation - If set to 1, schema_checking or DTD validation occurs.
                    Schema or DTD need to be on local disk

 PROCEDURES USED:
	PARSE_PARAMETER, PDSPAR, XML2IDL, GET_TAGS

 PACKAGE LOCATION:
	http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

 MODIFICATION HISTORY:
	Written by Ed Shaya/U. of Maryland [April 27, 2012]
	Modified to allow for single and double quotes within a text node.Ed Shaya [May 29, 2012]
	Removed path variable.  Now filename should contain path if needed ES [Dec 3, 2013]
	Fixed a bug which left off an element that had tried but failed to append to 
	array of elements of the same name. [ES/Nov 17, 2014]
	Added  validation flag. But IDL requires schema to be local. [ES/July 8, 2015]
 Fixed bug where text nodes that are quoted got mauled (ES-7/28/15)

(See PDS/read_xml.pro)

 NAME:
	READ_XML8	

 PURPOSE:
	READ an XML document file into IDL (Interactive Data Language, ITT).  
	This function is specifically for IDL version 8 and above because
	it uses both OrderedHashes and Lists which were introduced in version 8.
	Output is an IDL Ordered Hash with Lists for repeating elements.
	This function reads the file and parses the XML document into a DOM
	(Document Object Model) object or IDLffXMLDOMDocument.
	It passes oDoc to XML2IDL8 which walks through the nodes creating the hash.  

 CATEGORY:
	Datafile handling; XML

 CALLING SEQUENCE:
	Result = READ_XML8(filename, [ outFile=outFile, validation = validation ])

 INPUTS:
	filename  - name of XML file to read (string)

 OUTPUTS:
	Result is a hash of hashes or lists that represents the XML file.  
	One can access the various nodes
	by indexing into it, like this:           
	IDL> print, hash[rootname,elname,childname,'_text']
          
	If there are siblings with the same name, then they are pulled together
	in a list which is indexed by number:

	IDL> i++
	IDL> print, hash[rootname,repeatedname,i,childname,'_text'];	
          
	To see what the childnames are for element elnameN:
	
	IDL> print, hash[rootname,elname,...,elnameN].Keys()
	
 KEYWORDS:
	outFile - If set to a filename, will save pretty printout to that file

	validation - Turns on validation of xml file
			The Schema or DTD need to on local disk.
	
 PROCEDURES USED:
	XML2IDL8
	
 PACKAGE LOCATION:
	http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

 MODIFICATION HISTORY:
	Written by Ed Shaya / U. of Maryland [Nov 5, 2013]
	Removed path variable.  Now filename should contain path if needed. ES/Dec 3, 2013.
	Switched to ordered hash so elements stay in order.  Now using
	XML2IDL8.pro.  ES/Oct 10, 2014.
	Removed use of prettyhash (toscreen) since IDL now does this
	natively when you enter the hash name ES/Oct 10, 2014

(See PDS/read_xml8.pro)

 NAME:
	RMELEMENT       

 PURPOSE:
	Remove an element or several elements from an array by their index number

 CATEGORY:
	Array Processing

 CALLING SEQUENCE:
	Result =  rmelement(array,indx)

 INPUTS:
	array - 1 d array which will have some element(s) removed.

	indx - an integer scalar or array with index values of elements to be removed.

 OUTPUTS:
       Returns an array that has fewer elements than the input array.

 PACKAGE LOCATION:
	http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

 MODIFICATION HISTORY:
	Written by Ed Shaya a long long time ago. / U. of Maryland

	Modified to return an empty array when needed.
	Modified to handle zero length index and indx outside array size. 
	And added a sort to the uniq function to ensure uniqueness really happens. [5/7/15]

(See PDS/rmelement.pro)

 NAME: 
	STR_CLEAN
     
 PURPOSE: 
	To remove all unprintable characters from the given string
 
 CALLING SEQUENCE: 
	Result = STR_CLEAN (text, [/SPACE])
 
 INPUTS:
	Text: Scalar string of characters to be cleaned

 OUTPUTS:
	Result: Scalar string of characters removed of all unprintable characters

 OPTIONAL INPUTS:
	SPACE: removes all unprintable characters including all space chars.

 EXAMPLE:
	To remove all unprintable chars except space
	IDL> word = STR_CLEAN ('the [tab]file is [lf][cr]')
	IDL> print, word
	the file is

	To remove all unprintable chars including space
	IDL> word = STR_CLEAN ('the [tab]file is [lf][cr]',/SPACE)
	IDL> print, word
	thefileis

 PACKAGE LOCATION:
	http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

 MODIFICATION HISTORY:
	Written by Puneet Khetarpal, January 15, 2003

(See PDS/str_clean.pro)

 NAME:
	TVIT

 PURPOSE:
	Send a scaled, zoomed/compressed 2-d array to the graphics window
	It resizes the image to fit the window size and rescales the image
	with a new zero point.

 CATEGORY:
	Graphics

 CALLING SEQUENCE:
	TVIT, img, zero, stretchv[, zoomf=zoomf]

 INPUTS:
	img - a 2-d image array

	zero - value in image to be displayed at minimum in color table.

	stretchv - the difference in value between maximum and minimum.

 KEYWORDS:
	zoomf - output of the zoomfactor that is applied to get the array to fit the window.

 PACKAGE LOCATION:
	http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

 MODIFICATION HISTORY:
	Written by Ed Shaya / U. of Maryland [11/1/12]

(See PDS/tvit.pro)

 NAME:
	XML2IDL

 PURPOSE:
	Translate a DOM (Document Object Model) object (read in 
	from an XML file with read_xml.pro) into either an IDL structure
	or a parameter array (see paramArr below) by recursion through the 
	document tree.	For the IDL structure, XML element names become 
	tagnames in the structure.  Elements with non-null text get  a 
	'_text' tag.  comments are attached to parent elements with '_comment' 
	tag.  Attributes are similarly treated with the attribute name as the 
	tagName.  They can be distinguished from element text by the lack of 
	a '_text' tag.
	
	All non-essential whitespace is removed.  IDL variable names are allowed
	to have only the special characters '_','$', and '!', so all other 
	special characters are converted to '_'.
	
	IDL does not accept repeat names as subtags but XML does allow repeats 
	of element names of siblings. Such repeats can often be turned into 
	arrays in IDL, but not always because IDL does not have the concept of 
	a type with optional subcomponents. A decision is made by this program 
	as to whether to handle a repeating element as an array
	or to alter the element name slightly.  If its structure is of 
	identical type as the previous element of same name, then it is 
	appended to an array.  Otherwise, a __1, __2, etc. is added to the name.
	In these cases, no suffix is interpreted as the __0 instance.
	A string of elements of the same name may translate partially into
	arrays and partially into altered names.
	For multiple XML comments on an element, the values are appended into a 
	string array.  They must be consecutive.
	
	In paramArr, an XML element that holds other elements results in a 
	the string "OBJECT = ElementName" before all of its attributes and 
	children and "END_OBJECT = ElementName" after.  Elements which just 
	hold text translate to " Element = textValue ".  
	
 CATEGORY:
	Datafile handling; XML
	
 CALLING SEQUENCE:
	XML2IDL, oNode,level=level,struct=struct, [ paramArr = paramArr ]

 INPUTS:
	oNode -  DOM Document object (IDLffXMLDOMDocument) or top DOM Node 
	(IDLffXMLDOMNode) to convert to string array

 OUTPUTS:

 KEYWORDS:
	level - starting level for indentation, usually set to 0.  As level 
	increases during recursion the amount of indentation grows

	nodeName - returns nodeName of oNode

	nodeVAlue - returns nodeValue of oNode

	struct - If there are children elements, this returns a structure 
	holding information on them

	paramArr - If there are children elements, this returns an array of 
	strings of the form "Element = textValue", if it has text, and
	"OBJECT = ELEMENT" to start an element and 
	"END_OBJECT = ELEMENT" to close it.
	To turn it on, set paramArr = 1 or ['1'].  To turn it off set 
	paramArr = 0 or ['-1'].

 PACKAGE LOCATION:
	http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

 PROCEDURE:
	A number of input parameters and keywords are used internally only.  
	They are used when the program walks through the document tree by 
	recursively calling itself.  These are: paramArr, struct, nodeName, 
	and nodeValue 

 MODIFICATION HISTORY:
	Written by Ed Shaya / U. of Maryland [April 27, 2012]
	Modified by Ed Shaya [May 4, 2012] - 
 Changed the ANDs to &&s to speed it up and to fix a bug when using
   IDL version 6 where index cannot be -1. (ES-7/5/15)
 Fixed bug where text nodes that are quoted got mauled (ES-7/28/15)

(See PDS/xml2idl.pro)

 NAME:
	XML2IDL8

 PURPOSE:
	Translate a DOM (Document Object Model) object (read in
	from an XML file with read_xml.pro) into either an IDL hash
	by recursion through the document tree.	The '8' in the name
	indicates this version is for IDL version 8.3 and above
	as it uses ordered hashes and lists which were introduced to IDL in
	version 8.3.  For the IDL hash, XML element names become
	key names in the hash.  Elements with non-null text get a
	'_text' key.  Comments are attached to parent elements with
	'_comment' key.  Attributes are similarly treated with the
	attribute name as the key.  They can be distinguished from
	element text by the lack of a '_text' key.
	
	All non-essential whitespace is removed.  IDL variable names are allowed
	to have only the special characters '_','$', and '!', so all other
	special characters are converted to '_'.
	
 CATEGORY:
	Datafile handling; XML

 CALLING SEQUENCE:
	myhash = XML2IDL8(oChild,nodeName=childName,nodeValue=childValue) 
       
 INPUTS:
	oNode -  DOM Document object (IDLffXMLDOMDocument) or top DOM Node 
		(IDLffXMLDOMNode) to convert to string array

 OUTPUTS:
	Returns a hash of hashes or lists that represents the XML file.  One can access the various nodes
	by indexing into it, like this:
          
	IDL> print, hash[rootname,elName,childname,'_text']
          
	If there are siblings with the same name, then they are pulled together in a list which
	is indexed by number:
          
	IDL> i++
	IDL> print, hash[rootname,repeatedname,i,childname,'_text']
 
 KEYWORDS:
	nodeName - returns nodeName of oNode

	nodeVAlue - returns nodeValue of oNode
	hash - If there are children elements, this returns a hash 
	holding information on them

 PROCEDURE:
	A number of input parameters and keywords are used internally only.  
	They are used when the program walks through the document tree by 
	recursively calling itself.  These are: paramArr, nodeName, 
	and nodeValue 
	
 MODIFICATION HISTORY:
	Written by Ed Shaya / U. of Maryland [Nov 5, 2013]
	Removed empty _text except for true empty elements ES [Dec 2013]

(See PDS/xml2idl8.pro)

 NAME:
	XMLDocument__define 

 PURPOSE:
	We subclass IDLffDOMDocument to add a convenient SetElement method.  It
	allows one to create a new element with multiple attributes and a text
	node plus place in it the Document tree by naming its parent
	and optionally naming the next sibling.

Category:
	Datafile Handling: XML

 CALLING SEQUENCE:
	oXML = OBJ_NEW('XMLDocument')
	Return = oXML->SetElement(name,parent,atts=atts,attvals=atvals,$
	             text=text, before=before)

 Required INPUTS:
	name - Tag name of the element being created.

	parent - object that holds parent of element
	If parent is the XMLDocument then it is the root node.

 Optional INPUT KEYWORDS:
	atts - string or stringarr of attribute names for element.

	attvals - string or stingarr of values for attributes

	text - string for textnode of element

	before - next sibling.  If not specified, Element is placed as
	last sibling (appended instead of inserted before).

 Outputs:
	Return - Object reference to the element created

 Example: 
	IDL> hh=orderedhash('E1','Text for E1','E2','Text for E2','E3','Text for E3') 
	IDL> atts = ['att1','att2']
	IDL> attvals =['att1 value','att2 value']
	IDL> oXML = OBJ_NEW('XMLDocument')
	IDL> oroot = oXML->SetElement('RootElement',oXML,atts='xmlns',$
	IDL> attvals='somenamespace')
	IDL> keys = hh.keys()
	IDL> ochild1 = oXML->SetElement(keys[0],oroot,$
	IDL>	atts='att1',attvals='att1 value',text=hh[keys[0]]) 
	IDL> ochild2 = oXML->SetElement(keys[1],oroot,$
	IDL>    atts=atts,attvals=attvals,text=hh[keys[1]])
	IDL> ochild3 = oXML->SetElement(keys[2],oroot,text=hh[keys[2]])
	IDL> oXML.save,string=outstring,/pretty_print
	IDL> OBJ_DESTROY, oXML
	IDL> print,outstring
	<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
	<RootElement xmlns="somenamespace">

	<E1 att1="att1 value">Text for E1</E1>

	<E2 att1="att1 value" att2="att2 value">Text for E2</E2>

	<E3>Text for E3</E3>

	</RootElement>
	(Note: lessthan sign was encoded so that it appears correctly on the web)
          
 Procedures Used:
	Just built-in procedures

 PACKAGE LOCATION:
	http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

 Modification History
	Written by Ed Shaya / U. of Maryland [JULY 11, 2014].
	Changed parent from a keyword to a required parameter ES [5/7/15].

(See PDS/XMLDocument__define.pro)