This page was created by the IDL library routine `mk_html_help2`.

Last modified: Wed Sep 10 18:16:51 2025.

# Directory Listing of Routines

# external/astron/fits_misc

- BLKSHIFT
  Shift a block of data to a new position in a file (possibly overlapping)
- CHECKSUM32
  To compute the 32bit checksum of an array (ones-complement arithmetic)
- FDECOMP
  Routine to decompose file name(s) for any operating system.
- GETTOK
  Retrieve the first part of a (vector) string up to a specified character
- HPRINT
  Display a FITS header (or other string array)
- MRD_SKIP
  Skip a number of bytes from the current location in a file or a pipe
- MRD_STRUCT
  Return a structure as defined in the names and values data.
- N_BYTES()
  To return the total number of bytes in data element
- REMCHAR
  Remove all appearances of character (char) from string (st)
- REPCHR[1]
  Replace all occurrences of one character with another in a text string.
- SPEC_DIR()
  Complete a file specification by appending the default disk or directory
- STRN
  Convert a number to a string and remove padded blanks.
- TEXTCLOSE
  Close a text outpu file previously opened with TEXTOPEN
- TEXTOPEN
  Open a device specified by TEXTOUT with unit !TEXTUNIT
- TO_HEX
  Translate a non-negative decimal integer to a hexadecimal string
- VALID_NUM()
  Check if a string is a valid number representation.
- XDISPSTR
  Display a string array in a text widget with a simple search capability.

# Routine Descriptions

## BLKSHIFT

[Next Routine] [List of Routines]

     NAME:
       BLKSHIFT

     PURPOSE:
       Shift a block of data to a new position in a file (possibly overlapping)

     CALLING SEQUENCE:

       BLKSHIFT, UNIT, POS, [ DELTA, TO=TO, /NOZERO, ERRMSG=ERRMSG,
                 BUFFERSIZE=BUFFERSIZE ]

     DESCRIPTION:

      BLKSHIFT moves a block of data forward or backward, to a new
      position in a data file.  The old and new positions of the block
      can overlap safely.

      The new position can be specified with either the DELTA parameter,
      which gives the number of bytes to move forward (positive delta) or
      backward (negative delta); or the TO keyword, which give the new
      absolute starting position of the block.

      The block can be moved beyond the current end of file point, in
      which case the intervening gap is filled with zeros (optionally).
      The gap left at the old position of the block is also optionally
      zero-filled.    If a set of data up to the end of the file is being
      moved forward (thus making the file smaller) then
      the file is truncated at the new end.using TRUNCATE_LUN.

     INPUTS:

       UNIT - a logical unit number, opened for reading and writing.

       POS - POS[0] is the position of the block in the file, in bytes,
             before moving.  POS[1], if present, is the size of the block
             in bytes.  If POS[1] is not given, then the block is from
             POS[0] to the end of the file.

       DELTA - the (optional) offset in bytes between the old and new
               positions, from the start of the block.  Positive values
               indicate moving the data forward (toward the end of file),
               and negative values indicate moving the data backward
               (toward the beginning of the file).  One of DELTA and TO
               must be specified; DELTA overrides the TO keyword.

               Attempts to move the block beyond the end of the file will
               succeed.  A block can never be moved beyond the beginning
               of the file; it will be moved to the beginning instead.

     KEYWORD PARAMETERS:

       TO - the absolute file offset in bytes for the new start of the
            block.  One of DELTA and TO must be specified; DELTA
            overrides the TO keyword.

       /NOZERO - if set, then newly created gaps will not be explicitly
                zeroed.   Note that in same systems (e.g. MacOS) the gaps will
                always be zeroed whether or not /NOZERO is set.

       ERRMSG - If defined and passed, 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.

    			BLKSHIFT, UNIT, POS, DElTA, ERRMSG=ERRMSG, ...
    			IF ERRMSG NE '' THEN ...

       BUFFERSIZE - the maximum buffer size for transfers, in bytes.
                    Larger values of this keyword impose larger memory
                    requirements on the application; smaller values will
                    lead to more transfer operations.
                    Default: 32768 (bytes)

     ORIGINAL AUTHOR:
       Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
       craig.markwardt@nasa.gov

     MODIFICATION HISTORY:

       Written, CM, Apr 2000
       Documented and re-written, CM, 20 Jul 2000
       Renamed from FXSHIFT to BLKSHIFT, CM, 21 Jul 2000
       Documentation, CM, 12 Dec 2002
       Truncate if moving data block forward from  the end of file
                 using TRUNCATE_LUN   W. Landsman Feb. 2005
       Assume since V5.5, remove VMS support  W. Landsman  Sep 2006
       Assume since V5.6, TRUNCATE_LUN available  W. Landsman Sep 2006
       MacOS can point beyond EOF    W. Landsman   Aug 2009
       Use V6.0 notation  W. Landsman Aprl 2014

(See external/astron/fits_misc/blkshift.pro)

## CHECKSUM32

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

     NAME:
           CHECKSUM32

     PURPOSE:
           To compute the 32bit checksum of an array (ones-complement arithmetic)

     EXPLANATION:
           The 32bit checksum is adopted in the FITS Checksum convention
           http://fits.gsfc.nasa.gov/registry/checksum.html

     CALLING SEQUENCE:
           CHECKSUM32, array, checksum, [/FROM_IEEE, /NoSAVE, /Incremental]

     INPUTS:
           array - any numeric idl array.  If the number of bytes in the array is
                   not a multiple of four then it is padded with zeros internally
                   (the array is returned unchanged).   Convert a string array
                   (e.g. a FITS header) to bytes prior to calling CHECKSUM32.

     INPUT-OUTPUT:
           checksum - unsigned long scalar, giving sum of array elements using
                    ones-complement arithmetic.    This is normally an output
                    parameter, but can also be an input parameter if /Incremental
                    is set.
     OPTIONAL INPUT KEYWORD:

          /FROM_IEEE - If this keyword is set, then the input is assumed to be in
               big endian format (e.g. an untranslated FITS array).   This keyword
               only has an effect on little endian machines (e.g. Linux boxes).

          /Incremental - If this keyword is set, use the checksum
               parameter as input of a partial checksum from a previous
               call, allowing checksums for large arrays to be calculated
               incrementally.

          /NoSAVE - if set, then the input array is not saved upon exiting.   Use
               the /NoSave keyword to save time if the input array is not needed
               in further computations.
     METHOD:
           Uses TOTAL() to sum the array into an unsigned integer variable.  The
           overflow bits beyond 2^32 are then shifted back to the least significant
           bits.    The summing is done in chunks of 2^31 numbers to avoid loss
          of precision.    Adapted from FORTRAN code in
          heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/general/checksum/node30.html

     RESTRICTIONS:
           (1) Not valid for object or pointer data types
     EXAMPLE:
            (1) Find the 32 bit checksum of the array x = findgen(35)

           IDL> checksum32, x, s    ===> s =  2920022024

            (2) Find the checksum of an array too large to fit in memory at one time
                by breaking it up into 15 pieces.

           IDL> a = randomn(seed,100,100, 15)
    		IDL> for i=0,14 do checksum32,a[*, *,i], checksum_incr, /incremental

     FUNCTION CALLED:
           HOST_TO_IEEE, IS_IEEE_BIG(), N_BYTES()
     MODIFICATION HISTORY:
           Written    W. Landsman          June 2001
           Work correctly on little endian machines, added /FROM_IEEE and /NoSave
                      W. Landsman          November 2002
           Pad with zeros when array size not a multiple of 4 W.Landsman Aug 2003
           Always copy to new array, somewhat slower but more robust algorithm
               especially for Linux boxes   W. Landsman Sep. 2004
           Sep. 2004 update not implemented correctly (sigh) W. Landsman Dec 2004
           No need to byteswap 4 byte datatypes on little endian W. L. May 2009
           Use /INTEGER keyword to TOTAL() function W.L. June 2009
           Allow incremental calculation of checksums. Mats Löfdahl July 2019.

(See external/astron/fits_misc/checksum32.pro)

## FDECOMP

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

     NAME:
         FDECOMP
     PURPOSE:
         Routine to decompose file name(s) for any operating system.

     CALLING SEQUENCE:
         FDECOMP, filename, disk, dir, name, qual, [OSFamily = ]

     INPUT:
         filename - string file name(s), scalar or vector

     OUTPUTS:
         All the output parameters will have the same number of elements as
           input filename

           disk - disk name, always '' on a Unix machine, scalar or vector string
           dir - directory name, scalar or vector string
           name - file name, scalar or vector string
           qual - qualifier, set equal to the characters beyond the last "."

     OPTIONAL INPUT KEYWORD:
         OSFamily -  scalar string specifying the operating system, must be either
                 'Windows' or 'unix'.    If not supplied,
                 then !VERSION.OS_FAMILY is used to determine the OS.
     EXAMPLES:
         Consider the following file names

         unix:    file = '/itt/idl71/avg.pro'
         Windows: file =  'd:\itt\idl71\avg.pro'

         then IDL> FDECOMP,  file, disk, dir, name, qual
           will return the following

                     Disk             Dir          Name        Qual
           Unix:      ''            '/itt/idl71/'  'avg'       'pro'
           Windows:    'd:'         \itt\idl71\    'avg'       'pro'

     NOTES:
         (1) The period is removed between the name and qualifier
         (2) Unlike the intrinsic FILE_BASENAME() and FILE_DIRNAME() functions,
             one can use FDECOMP to decompose a Windows file name on a Unix machine
             or a Unix filename on a Windows machine.

     ROUTINES CALLED:
         None.
     HISTORY
         version 1  D. Lindler  Oct 1986
         Include VMS DECNET machine name in disk    W. Landsman  HSTX  Feb. 94
         Converted to Mac IDL, I. Freedman HSTX March 1994
         Major rewrite to accept vector filenames V5.3   W. Landsman June 2000
         Fix cases where disk name not always present  W. Landsman  Sep. 2000
         Make sure version defined for Windows  W. Landsman April 2004
         Include final delimiter in directory under Windows as advertised
                    W. Landsman   May 2006
         Remove VMS support, W. Landsman    September 2006
         Remove MacOS branch (same as Unix) W. Landsman  August 2009

(See external/astron/fits_misc/fdecomp.pro)

## GETTOK

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

     NAME:
    	GETTOK
     PURPOSE:
    	Retrieve the first part of a (vector) string up to a specified character
     EXPLANATION:
    	GET TOKen - Retrieve first part of string until the character char
    	is encountered.

     CALLING SEQUENCE:
    	token = gettok( st, char, [ /EXACT, /NOTRIM ] )

     INPUT:
    	char - character separating tokens, scalar string

     INPUT-OUTPUT:
    	st - string to get token from (on output token is removed unless
                /NOTRIM is set), scalar or vector

     OUTPUT:
    	token - extracted string value is returned, same dimensions as st
     OPTIONAL INPUT KEYWORD:
           /EXACT -  The default behaviour of GETTOK is to remove any leading
                  blanks and (if the token is a blank) convert tabs to blanks.
                  Set the /EXACT keyword to skip these steps and leave the
                  input string unchanged before searching for the  character
                  tokens.

          /NOTRIM - if set, then the input string is left unaltered
     EXAMPLE:
    	If ST is ['abc=999','x=3.4234'] then gettok(ST,'=') would return
    	['abc','x'] and ST would be left as ['999','3.4234']

     PROCEDURE CALLS:
           REPCHR()
     HISTORY
    	version 1  by D. Lindler APR,86
    	Remove leading blanks    W. Landsman (from JKF)    Aug. 1991
           V5.3 version, accept vector input   W. Landsman February 2000
           Slightly faster implementation  W. Landsman   February 2001
           Added EXACT keyword  W. Landsman March 2004
           Assume since V5.4, Use COMPLEMENT keyword to WHERE W. Landsman Apr 2006
           Added NOTRIM keyword W. L. March 2011

(See external/astron/fits_misc/gettok.pro)

## HPRINT

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

     NAME:
           HPRINT
     PURPOSE:
           Display a FITS header (or other string array)
     EXPLANATION:
           On a GUI terminal, the string array is displayed using XDISPSTR.
           If printing at a non-GUI terminal, the string array is  printed 1 line
           at a  time, to make sure that each element of the string array is
           displayed on a separate line.

     CALLING SEQUENCE:
           HPRINT, h, [ firstline ]

     INPUTS:
           H - FITS header (or any other string array).

     OPTIONAL INPUT:
           FIRSTLINE - scalar integer specifying the first line to begin
                   displaying.   The default is FIRSTLINE = 1, i.e. display
                   all the lines.     If Firstline is negative, then the first
                   line to be printed is counted backward from the last line.

     NOTES:
           When displaying at the terminal, HPRINT has the following differences
           from the intrinsic PRINT procedure

           (1) Arrays are printed one line at a time to avoid a space between 80
                   character lines
           (2) Lines are trimmed with STRTRIM before being printed to speed up
                   display
           (3) The /more option is used for output.

     EXAMPLE:
           Read the header from a FITS file named 'test.fits' and display it at the
           terminal beginning with line 50

           IDL> h = headfits( 'test.fits')         ;Read FITS header
           IDL> hprint, h, 50                      ;Display starting at line 50

           To print the last 25 lines of the header

           IDL> hprint, h, -25

     REVISION HISTORY:
           Written W. Landsman                     July, 1990
           Added test for user quit                July, 1991
           Added optional FIRSTLINE parameter      November, 1992
           Modified for when STDOUT is not a TTY W. Landsman  September 1995
           Converted to IDL V5.0   W. Landsman   September 1997
           Fixed printing in IDLDE, C. Gehman      August, 1998
           Skip PRINTF if IDL in demo mode  W. Landsman  October 2004
           Fixed bug on non-terminals, William Thompson, 18-Oct-2004
           Assume since V5.4 Use BREAK instead of GOTO  W. Landsman Apr 2006
           Call XDISPSTR on a GUI terminal  W. Landsman Jun 2006

(See external/astron/fits_misc/hprint.pro)

## MRD_SKIP

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

     NAME:
           MRD_SKIP
     PURPOSE:
           Skip a number of bytes from the current location in a file or a pipe
     EXPLANATION:
           First tries using POINT_LUN and if this doesn't work, perhaps because
           the unit is a pipe or a socket, MRD_SKIP will just read in the
           requisite number  of bytes.
     CALLING SEQUENCE:
           MRD_SKIP, Unit, Nskip

     INPUTS:
           Unit - File unit for the file or pipe in question, integer scalar
           Nskip - Number of bytes to be skipped, positive integer
     NOTES:
           This routine should be used in place of POINT_LUN wherever a pipe
           or socket may be the input unit (see the procedure FXPOSIT for an
           example).   Note that it assumes that it can only work with nskip >= 0
           so it doesn't even try for negative values.

           For reading a pipe, MRD_SKIP currently uses a maximum buffer size
           of 8 MB.   This chunk value can be increased for improved efficiency
           (or decreased if you really have little memory.)
     REVISION HISTORY:
           Written, Thomas A. McGlynn    July 1995
    	Don't even try to skip bytes on a pipe with POINT_LUN, since this
    	might reset the current pointer     W. Landsman        April 1996
           Increase buffer size, check fstat.compress W. Landsman  Jan 2001
           Only a warning if trying read past EOF   W. Landsman   Sep 2001
           Use 64bit longword for skipping in very large files W. Landsman Sep 2003
           Assume since V5.4, fstat.compress available W. Landsman April 2006
           POINT_LUN for compressed files is as fast as any W. Landsman Oct 2006
           Don't try to use POINT_LUN on compressed files W. Landsman Dec. 2006

(See external/astron/fits_misc/mrd_skip.pro)

## MRD_STRUCT

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

     NAME:
           MRD_STRUCT
     PURPOSE:
           Return a structure as defined in the names and values data.
     CALLING SEQUENCE:
           struct = MRD_STRUCT(NAMES, VALUES, NROW, STRUCTYP='name' )
     INPUT PARAMETERS:
           NAMES   = A string array of names of structure fields.
           VALUES  = A string array giving the values of the structure
                     fields.  See examples below.
           NROW    = The number of elements in the structure array.

     RETURNS:
           A structure as described in the parameters or 0 if an error
           is detected.

     OPTIONAL KEYWORD PARAMETERS:
           /NO_EXECUTE - If set then the use of the EXECUTE() statement is avoided.
                      By default, the NO_EXECUTE pathway is used if IDL is
                      running under the Virtual Machine.    Note if  /NO_EXECUTE
                      is set, then the user cannot supply arbitrary values, but
                      all possible values used by MRDFITS will be allowed.
           STRUCTYP = The structure type.  Since IDL does not allow the
                      redefinition of a named structure it is an error
                      to call MRD_STRUCT with different parameters but
                      the same STRUCTYP in the same session.  If this
                      keyword is not set an anonymous structure is created.
     COMMON BLOCKS:
           MRD_COMMON
     SIDE EFFECTS:
           May create a temporary file if the structure definition is too long
           for the EXECUTE function and using old style structures

     RESTRICTIONS:
           By default, the program defines the structure in a long string
           which is executed with CREATE_STRUCT within a single EXECUTE statement.

           If program is being run in the IDL Virtual machine (EXECUTE statement
           not allowed), then a separate CREATE_STRUCT statement is called
           for each tag.   This mode does not have the full capabilities of the
           normal mode, but should be sufficient for use with MRDFITS().
     PROCEDURE:
           A structure definition is created using the parameter values.
           MRD_NSTRUCT is called  and generates the structure in pieces using the
           execute and create_struct keywords.

     EXAMPLES:
           (1) str = mrd_struct(['fld1', 'fld2'], ['0','dblarr(10,10)'],3)
               print, str(0).fld2(3,3)
           Note that "0" is always considered short integer even if the default
           integer is set to long.

           (2) str = mrd_struct(['a','b','c','d'],['1', '1.', '1.d0', "'1'"],1)
                   ; returns a structure with integer, float, double and string
                   ; fields.
     PROCEDURE CALLS:
           GETTOK() - needed for virtual machine mode only
     MODIFICATION HISTORY:
           Created by T. McGlynn October, 1994.
           Modified by T. McGlynn September, 1995.
              Added capability to create substructures so that structure
              may contain up to 4096 distinct elements.  [This can be
              increased by futher iteration of the process used if needed.]
           Removed V4.0 reference to common block  October 1997
           Allowed unlimited number of structure elements if the version
           is greater than 5.0.  Put back in code to handle prior versions.
           The [] will need to be translated back to () for this to
           work.  T. McGlynn December 15 1998.
           Add MRD_NSTRUCT since IDL has mysterious problems compiling
           very large structures.
           Removed TEMPDIR and OLD_STRUCT keywords  W. Landsman October 2003
           Alternate pathway without EXECUTE for V6.0 virtual machine, D. Lindler
           Removed limit on EXECUTE statement.  W. Landsman  October 2003
           Restore EXECUTE limit (sigh...), added NO_EXECUTE keyword
                             W. Landsman July 2004
           Fix use of STRUCTYP with /NO_EXECUTE  W. Landsman June 2005
           Assume since V6.0 (lmgr function available), remove 131 string length
                 limit for execute    W. Landsman Jun 2009
           Restore EXECUTE limit (sigh...)   W. Landsman July 2009
           Make sure "0" is a short integer even with compile_opt idl2  July 2010
           Added "0.0", "0.0d", "0u", "0ul", and "0ull" as valid tags
                 for /NO_EXECUTE  E. Rykoff May 2012
           Fix for create long64 arrays with /no_execute  E. Rykoff Sep 2013

(See external/astron/fits_misc/mrd_struct.pro)

## N_BYTES()

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

     NAME:
           N_bytes()

     PURPOSE:
           To return the total number of bytes in data element

     CALLING SEQUENCE:
           result = N_bytes(a)

     INPUTS:
           a - any idl data element, scalar or array

     OUTPUTS:
           total number of bytes in a is returned as the function value
           (64bit longword scalar)
     NOTES:
           (1) Not valid for object or pointer data types
           (2) For a string array, the number of bytes is computed after conversion
               with the BYTE() function, i.e. each element has the same length,
               equal to the maximum individual string length.

     MODIFICATION HISTORY:
           Version 1  By D. Lindler  Oct. 1986
           Include new IDL data types    W. Landsman          June 2001
           Now return a 64bit integer    W. Landsman          April 2006

(See external/astron/fits_misc/n_bytes.pro)

## REMCHAR

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

     NAME:
    	REMCHAR
     PURPOSE:
    	Remove all appearances of character (char) from string (st)

     CALLING SEQUENCE:
    	REMCHAR, ST, CHAR

     INPUT-OUTPUT:
    	ST  - String from which character will be removed, scalar or vector
     INPUT:
    	CHAR- Single character to be removed from string or all elements of a
    		string array

     EXAMPLE:
    	If a = 'a,b,c,d,e,f,g' then

    	IDL> remchar,a, ','

          will give a = 'abcdefg'

     REVISIONS HISTORY
    	Written D. Lindler October 1986
    	Test if empty string needs to be returned   W. Landsman  Feb 1991
    	Work on string arrays    W. Landsman   August 1997
    	Avoid 32 bit integer overflow K. Tolbert/W. Landsman Feb 2007

(See external/astron/fits_misc/remchar.pro)

## REPCHR[1]

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

     NAME:
           REPCHR
     PURPOSE:
           Replace all occurrences of one character with another in a text string.
     CATEGORY:
     CALLING SEQUENCE:
           new = repchr(old, c1, [c2])
     INPUTS:
           old = original text string.          in
           c1 = character to replace.           in
           c2 = character to replace it with.   in
                default is space.
     KEYWORD PARAMETERS:
     OUTPUTS:
           new = edited string.                 out
     COMMON BLOCKS:
     NOTES:
     MODIFICATION HISTORY:
           R. Sterner.  28 Oct, 1986.
           Johns Hopkins Applied Physics Lab.
           RES 1 Sep, 1989 --- converted to SUN.
           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.
    	Converted to IDL V5.0   W. Landsman   September 1997

(See external/astron/fits_misc/repchr.pro)

## SPEC_DIR()

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

     NAME:
         SPEC_DIR()
     PURPOSE:
         Complete a file specification by appending the default disk or directory

     CALLING SEQUENCE:
         File_spec = SPEC_DIR( filename, [ extension ] )
     INPUT:
         filename - character string giving partial specification of a file
                   name.  Examples for different operating systems include the
                           following:
                   Unix: 'pro/test.dat', '$IDL_HOME/test','~/subpro'
                   MacOS: ':Programs:test'
                   Windows: '\pro\test.dat','d:\pro\test'

     OPTIONAL INPUT:
         exten - string giving a default file name extension to be used if
                 filename does not contain one.  Do not include the period.

     OUTPUT:
         File_spec - Complete file specification using default disk or
                   directory when necessary.

     EXAMPLE:
          IDL> a = spec_dir('test','dat')

          is equivalent to the commands
          IDL> cd, current=cdir
          IDL> a = cdir + delim + 'test.dat'

          where delim is the OS-dependent separator
     METHOD:
          SPEC_DIR() decomposes the file name using FDECOMP, and appends the
          default directory (obtained from the FILE_EXPAND_PATH) if necessary.

          SPEC_DIR() does not check whether the constructed file name actually
          exists.
     PROCEDURES CALLED:
          FDECOMP, EXPAND_TILDE()
     REVISION HISTORY:
          Written W. Landsman         STX         July, 1987
          Expand Unix tilde if necessary              W. Landsman  September 1997
          Assume since V5.5, use FILE_EXPAND_PATH, remove VMS support
                  W. Landsman   September 2006

(See external/astron/fits_misc/spec_dir.pro)

## STRN

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

     NAME:
    	STRN
     PURPOSE:
    	Convert a number to a string and remove padded blanks.
     EXPLANATION:
    	The main and original purpose of this procedure is to convert a number
    	to an unpadded string (i.e. with no blanks around it.)  However, it
    	has been expanded to be a multi-purpose formatting tool.  You may
    	specify a length for the output string; the returned string is either
    	set to that length or padded to be that length.  You may specify
    	characters to be used in padding and which side to be padded.  Finally,
    	you may also specify a format for the number.  NOTE that the input
    	"number" need not be a number; it may be a string, or anything.  It is
    	converted to string.

     CALLING SEQEUNCE:
    	tmp = STRN( number, [ LENGTH=, PADTYPE=, PADCHAR=, FORMAT = ] )

     INPUT:
    	NUMBER    This is the input variable to be operated on.  Traditionally,
    		 it was a number, but it may be any scalar type.

     OPTIONAL INPUT:
    	LENGTH    This KEYWORD specifies the length of the returned string.
    		If the output would have been longer, it is truncated.  If
    		the output would have been shorter, it is padded to the right
    		length.
    	PADTYPE   This KEYWORD specifies the type of padding to be used, if any.
    		0=Padded at End, 1=Padded at front, 2=Centered (pad front/end)
    		IF not specified, PADTYPE=1
    	PADCHAR   This KEYWORD specifies the character to be used when padding.
    		The default is a space (' ').
    	FORMAT    This keyword allows the FORTRAN type formatting of the input
    		number (e.g. '(f6.2)')

     OUTPUT:
    	tmp       The formatted string

     USEFUL EXAMPLES:
    	print,'Used ',strn(stars),' stars.'  ==> 'Used 22 stars.'
    	print,'Attempted ',strn(ret,leng=6,padt=1,padch='0'),' retries.'
    		==> 'Attempted 000043 retries.'
    	print,strn('M81 Star List',length=80,padtype=2)
    		==> an 80 character line with 'M81 Star List' centered.
    	print,'Error: ',strn(err,format='(f15.2)')
    		==> 'Error: 3.24'     or ==> 'Error: 323535.22'

     HISTORY:
    	03-JUL-90 Version 1 written by Eric W. Deutsch
    	10-JUL-90 Trimming and padding options added         (E. Deutsch)
    	29-JUL-91 Changed to keywords and header spiffed up     (E. Deutsch)
    	Ma7 92 Work correctly for byte values (W. Landsman)
    	19-NOV-92 Added Patch to work around IDL 2.4.0 bug which caused an
    	error when STRN('(123)') was encountered.            (E. Deutsch)
    ;       Handles array input, M. Sullivan March 2014
           Use V6.0 notation W. Landsman April 2014
           Fix problem with vector strings of different length WL Aug 2014

(See external/astron/fits_misc/strn.pro)

## TEXTCLOSE

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

     NAME:
    	TEXTCLOSE

     PURPOSE:
    	Close a text outpu file previously opened with TEXTOPEN
     EXPLANATION:
    	procedure to close file for text output as specifed
    	by the (non-standard) system variable !TEXTOUT.

     CALLING SEQUENCE:
    	textclose, [ TEXTOUT = ]

     KEYWORDS:
    	textout - Indicates output device that was used by
    		TEXTOPEN

     SIDE EFFECTS:
    	if !textout is not equal to 5 and the textunit is
    	opened.   Then unit !textunit is closed and released

     HISTORY:
    	D. Lindler  Dec. 1986  (Replaces PRTOPEN)
    	Test if TEXTOUT is a scalar string   W. Landsman   August 1993
     Can't close unit -1 (Standard Output) I. Freedman  April  1994
    	Converted to IDL V5.0   W. Landsman   September 1997

(See external/astron/fits_misc/textclose.pro)

## TEXTOPEN

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

     NAME:
           TEXTOPEN
     PURPOSE:
           Open a device specified by TEXTOUT with unit !TEXTUNIT
     EXPLANATION:
           Procedure to open file for text output.   The type of output
           device (disk file or terminal screen) is specified by the
           TEXTOUT keyword or the (nonstandard) system variable !TEXTOUT.

     CALLING SEQUENCE:
           textopen, program, [ TEXTOUT =, /STDOUT, /SILENT, MORE_SET=, WIDTH= ]

     INPUTS:
           program - scalar string giving name of program calling textopen

     OPTIONAL INPUT KEYWORDS:
           TEXTOUT - Integer scalar (0-7) specifying output file/device to be
                   opened (see below) or scalar string giving name of output file.
                   If TEXTOUT is not supplied, then the (non-standard) system
                   variable !TEXTOUT is used.
           /SILENT - By default, TEXTOPEN prints an informational message when
                    opening a file for hardcopy output.   Set /SILENT (or !QUIET)
                    to suppress this message.
           /STDOUT - if this keyword is set and non-zero, then the standard output
                   (unit = -1) is used for TEXTOUT=1 or TEXTOUT=2.   The use
                   of STDOUT has  2 possible advantages:
                   (1) the output will appear in a journal file
                   (2) Many Unix machines print spurious control characters when
                   printing to /dev/tty.   These characters are eliminated by
                   setting /STDOUT

                   The disadvantage of /STDOUT is that the /MORE option is not
                   available.

             WIDTH - Specify line width for hardcopy output line wrapping (passed onto OPENW).

     OPTIONAL OUTPUT KEYWORD:
           MORE_SET - Returns 1 if the output unit was opened with /MORE.   This
                   occurs if (1) TEXTOUT = 1 and (2) the device is a tty, and
                   (3) /STDOUT is not set.      User can use the returned value
                    of MORE_SET to determine whether to end output when user
                    presses 'Q'.
     SIDE EFFECTS:
           The following dev/file is opened for output.    Different effects
           occur depending whether the standard output is a GUI (Macintosh,
           Windows, Unix/IDLTool) or a TTY

                   textout=0       Nowhere
                   textout=1       if a TTY then TERMINAL using /more option
                                       otherwise standard (Unit=-1) output
                   textout=2       if a TTY then TERMINAL without /more option
                                       otherwise standard (Unit=-1) output
                   textout=3       <program>.prt
                   textout=4       laser.tmp
                   textout=5      user must open file
                   textout=7      same as 3 but text is appended to <program>.prt
                                   file if it already exists.
                   textout = filename (default extension of .prt)

           The unit to be opened is obtained with the procedure GET_LUN
           unless !TEXTOUT=5.  The unit number is placed in system variable
           !TEXTUNIT.  For !TEXTOUT=5 the user must set !TEXTUNIT to the
           appropriate unit number.

     NOTES:
           When printing to a TTY terminal, the output will *not* appear in an
           IDL JOURNAL session, unlike text printed with the PRINT command.

     NON-STANDARD SYSTEM VARIABLES:
           TEXTOPEN will automatically define the following system variables if
           they are not previously defined:

           DEFSYSV,'!TEXTOUT',1
           DEFSYSV,'!TEXTUNIT',0
     HISTORY:
           D. Lindler  Dec. 1986
           Keyword textout added, J. Isensee, July, 1990
           Made transportable, D. Neill, April, 1991
           Trim input PROGRAM string W. Landsman  Feb 1993
           Don't modify TEXTOUT value   W. Landsman   Aug 1993
           Modified for MacOS  I. Freedman April 1994
           Modified for output terminals without a TTY  W. Landsman  August 1995
           Added /STDOUT keyword   W. Landsman    April 1996
           added textout=7 option, D. Lindler, July, 1996
           Exit with RETURN instead of RETALL  W. Landsman  June 1999
           In IDL V5.4 filepath(/TERMINAL) not allowed in the IDLDE WL August 2001
           Added MORE_SET output keyword   W.Landsman   January 2002
           Added /SILENT keyword  W. Landsman  June 2002
    	Define !TEXTOUT and !TEXTUNIT if needed.  R. Sterner, 2002 Aug 27
           Return Calling Sequence if no parameters supplied W.Landsman Nov 2002
           Remove VMS specific code  W. Landsman Sep 2006
           Make sure MORE_SET is always defined   W. Landsman Jan 2007
           Added WIDTH keyword   J. Bailin Nov 2010
           Use V6.0 notation  W. Landsman April 2011

(See external/astron/fits_misc/textopen.pro)

## TO_HEX

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

     NAME:
           TO_HEX
     PURPOSE:
           Translate a non-negative decimal integer to a hexadecimal string
     CALLING SEQUENCE:
           HEX = TO_HEX( D, [ NCHAR ] )
     INPUTS:
           D - non-negative decimal integer, scalar or vector.  If input as a
               string, (e.g. '32') then all leading blanks are removed.

     OPTIONAL INPUT:
           NCHAR - number of characters in the output hexadecimal string.
                   If not supplied, then the hex string will contain no
                   leading zeros.

     OUTPUT:
           HEX - hexadecimal translation of input integer, string

     EXAMPLES:
           IDL> A = TO_HEX([11,16])    ==>   A = ['B','10']
           IDL> A = TO_HEX(100,3) ==>   A = '064'

     METHOD:
           The hexadecimal format code '(Z)' is used to convert.  No parameter
           checking is done.
     PROCEDURES CALLED:
           None.
     REVISION HISTORY:
           Written   W. Landsman         November, 1990
           Converted to IDL V5.0   W. Landsman   September 1997
           Use FSTRING() for more than 1024 values      March 2000
           Assume since  V5.4, omit FSTRING() call      April 2006

(See external/astron/fits_misc/to_hex.pro)

## VALID_NUM()

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

     NAME:
         VALID_NUM()
     PURPOSE:
         Check if a string is a valid number representation.
     EXPLANATION:
         The input string is parsed for characters that may possibly
         form a valid number.  It is more robust than simply checking
         for an IDL conversion error because that allows strings such
         as '22.3qwert' to be returned as the valid number 22.3

         This function had a major rewrite in August 2008 to use STREGEX
         and allow vector input.    It should be backwards compatible.
     CALLING SEQUENCE:
         IDL> status = valid_num(string  [,value]  [,/integer])

     INPUTS:
         string  -  the string to be tested, scalar or array

     RETURNS
         status - byte scalar or array, same size as the input string
                  set to 1 where the string is a  valid number, 0 for invalid
     OPTIONAL OUTPUT:
         value     - The value the string decodes to, same size as input string.
               This will be returned as a double precision number unless
               /INTEGER is present, in which case a long integer is returned.

     OPTIONAL INPUT KEYWORD:
        /INTEGER   -  if present code checks specifically for an integer.
     EXAMPLES:
         (1) IDL> print,valid_num(3.2,/integer)
            --> 0     ;Since 3.2 is not an integer
         (2) IDL> str =['-0.03','2.3g', '3.2e12']
             IDL> test = valid_num(str,val)
                  test = [1,0,1]    &  val =  [-0.030000000 ,NaN ,3.2000000e+12]
     REVISION HISTORY:
              Version 1, C D Pike, RAL, 24-May-93
              Version 2, William Thompson, GSFC, 14 October 1994
                           Added optional output parameter VALUE to allow
                           VALID_NUM to replace STRNUMBER in FITS routines.
              Version 3 Wayne Landsman rewrite to use STREGEX, vectorize
              Version 4 W.L. (fix from C. Markwardt) Better Stregex expression,
                        was missing numbers like '134.' before Jan 1 2010

(See external/astron/fits_misc/valid_num.pro)

## XDISPSTR

[Previous Routine] [List of Routines]

      NAME:
         XDISPSTR

      PURPOSE:
         Display a string array in a text widget with a simple search capability.

     EXPLANATION:
         Similar to the IDL XDISPLAYFILE procedure but includes a search capbility.
     CALLING SEQUENCE:

         xdispstr, array, [/BLOCK, WIDTH= , HEIGHT=, TITLE=, GROUP_LEADER=, FONT=
                           TOP_LINE=, POS= ]

     INPUT PARAMETER:

         array  - String array (.e.g. FITS header) to be displayed

      OPTIONAL INPUT KEYWORD PARAMETERS:

        block -  Set to 1 to make widget blocking.  Default = block=0

        font  -     Display font for text.

        width, height  - Scalars giving number of characters per line, number
                               of lines.  Default = 80x48

        group_leader  -    Group leader for top level base.

        title  - Scalar Title for outermost base widget.

        pos - 2 element array containing the normalized X and Y position to
                display the widget on the screen.    [0,0] is the upper left
                hand corner.

        top_line - first line in the string array to display (default is 0)

     PROCEDURES USED:
         CGCENTERTLB

      MODIFICATION HISTORY:
         Written by R. S. Hill, RITSS, 17 Nov 2000
         Use cumulative keyword to TOTAL   W. Landsman   May 2006
         Made resizeable, default size now 48 lines  W. Landsman   July 2013
         Added POS keyword W. Landsman  Sep 2013

(See external/astron/fits_misc/xdispstr.pro)