This page was created by the IDL library routine
mk_html_help2.
Last modified: Wed Dec 20 10:37:44 2023.
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)