Documentation for /eve_analysis/ssw/ssw/sdo/eve/idl/

Generated by IDLdoc

single page | use frames     summary     class     fields     routine details     file attributes

./

eve_read_whole_fits.pro


Routines

result = eve_rwf_REPCHR(OLD, C1, C2, help=help)

NAME: REPCHR PURPOSE: Replace all occurrences of one character with another in a text string.

eve_rwf_fits_info, filename, SILENT=SILENT, TEXTOUT=TEXTOUT, N_ext=N_ext, extname=extname

NAME: FITS_INFO PURPOSE: Provide information about the contents of a FITS file EXPLANATION: Information includes number of header records and size of data array.

result = eve_rwf_FXMOVE(UNIT, EXTEN, SILENT=SILENT, EXT_NO=EXT_NO, ERRMSG=ERRMSG)

NAME: FXMOVE PURPOSE: Skip to a specified extension number or name in a FITS file

result = eve_rwf_FXPOSIT(XFILE, EXT_NO, readonly=readonly, COMPRESS=COMPRESS, SILENT=SILENT, EXTNUM=EXTNUM, ERRMSG=ERRMSG, LUNIT=LUNIT, UNIXPIPE=UNIXPIPE, FPACK=FPACK, NO_FPACK=NO_FPACK, HEADERONLY=HEADERONLY)

NAME: FXPOSIT PURPOSE: Return the unit number of a FITS file positioned at specified extension EXPLANATION: The FITS file will be ready to be read at the beginning of the specified extension.

eve_rwf_mrd_hread, unit, header, status, SILENT=SILENT, FIRSTBLOCK=FIRSTBLOCK, ERRMSG=ERRMSG, SKIPDATA=SKIPDATA

NAME: MRD_HREAD

eve_rwf_mrd_fxpar, hdr, xten, nfld, nrow, rsize, fnames, fforms, scales, offsets
result = eve_rwf_mrd_dofn(name, index, use_colnum, alias=alias)

Get a tag name give the column name and index

eve_rwf_mrd_doff, form, dim, type

; Parse the TFORM keyword and return the type and dimension of the data.

result = eve_rwf_mrd_chkfn(name, namelist, index)

Check that this name is unique with regard to other column names.

result = eve_rwf_mrd_unsigned_offset(type)

Find the appropriate offset for a given unsigned type.

result = eve_rwf_mrd_chkunsigned(bitpix, scale, zero, unsigned=unsigned)

Can we treat this data as unsigned?

result = eve_rwf_mrd_unsignedtype(data)

Is this one of the IDL unsigned types?

result = eve_rwf_mrd_version()

Return the currrent version string for MRDFITS

eve_rwf_mrd_atype, form, type, slen

Parse the TFORM keyword and return the type and dimension of the data.

eve_rwf_mrd_read_ascii, unit, range, nbytes, nrows, nfld, typarr, posarr, lenarr, nullarr, table, old_struct=old_struct, rows=rows

Read in the table information.

eve_rwf_mrd_ascii, header, structyp, use_colnum, range, table, nbytes, nrows, nfld, typarr, posarr, lenarr, nullarr, fnames, fvalues, scales, offsets, scaling, status, rows=rows, silent=silent, columns=columns, alias=alias, outalias=outalias

Define a structure to hold a FITS ASCII table.

eve_rwf_mrd_columns, table, columns, fnames, fvalues, vcls, vtpes, scales, offsets, scaling, structyp=structyp, silent=silent

Eliminate columns from the table that do not match the user specification.

eve_rwf_mrd_read_image, unit, range, maxd, rsize, table, rows=rows, status=status, unixpipe=unixpipe

Read in the image information.

eve_rwf_mrd_axes_trunc, naxis, dims, silent

Truncate superfluous axes.

eve_rwf_mrd_image, header, range, maxd, rsize, table, scales, offsets, scaling, status, silent=silent, unsigned=unsigned, rows=rows

Define structure/array to hold a FITS image.

eve_rwf_mrd_ptrscale, array, scale, offset

Scale an array of pointers

eve_rwf_mrd_string, table, header, typarr, fnames, fvalues, nrec, structyp=structyp, silent=silent

; Scale a FITS array or table.

eve_rwf_mrd_scale, type, scales, offsets, table, header, fnames, fvalues, nrec, dscale=dscale, structyp=structyp, silent=silent

; Scale a FITS array or table.

eve_rwf_mrd_varcolumn, vtype, array, heap, off, siz

Read a variable length column into a pointer array.

eve_rwf_mrd_fixcolumn, vtype, array, heap, off, siz

Read a variable length column into a fixed length array.

eve_rwf_mrd_read_heap, unit, header, range, fnames, fvalues, vcls, vtpes, table, structyp, scaling, scales, offsets, status, silent=silent, columns=columns, rows=rows, pointer_var=pointer_var, fixed_var=fixed_var

Read the heap area to get the actual values of variable length arrays.

eve_rwf_mrd_read_table, unit, range, rsize, structyp, nrows, nfld, typarr, table, rows=rows, unixpipe=unixpipe

Read in the binary table information.

eve_rwf_mrd_tdim, header, index, flen, arrstr, no_tdim=no_tdim

Check the values of TDIM keywords to see that they have valid dimensionalities.

eve_rwf_mrd_table, header, structyp, use_colnum, range, rsize, table, nrows, nfld, typarr, fnames, fvalues, vcls, vtpes, scales, offsets, scaling, status, rows=rows, silent=silent, columns=columns, no_tdim=no_tdim, alias=alias, unsigned=unsigned, outalias=outalias, emptystring=emptystring

Define a structure to hold a FITS binary table.

result = eve_rwf_mrdfits(file, extension, header, structyp=structyp, use_colnum=use_colnum, range=range, dscale=dscale, fscale=fscale, fpack=fpack, no_fpack=no_fpack, silent=silent, columns=columns, no_tdim=no_tdim, error_action=error_action, compress=compress, alias=alias, rows=rows, unsigned=unsigned, version=version, pointer_var=pointer_var, fixed_var=fixed_var, outalias=outalias, emptystring=emptystring, status=status, extnum=extnum)

NAME: MRDFITS

result = eve_rwf_SXPAR(hdr, name, abort, COUNT=COUNT, COMMENT=COMMENT, NoContinue=NoContinue, SILENT=SILENT)

NAME: SXPAR PURPOSE: Obtain the value of a parameter in a FITS header

eve_rwf_FXADDPAR_CONTPAR, VALUE, CONTINUED

This is a utility routine, which splits a parameter into several continuation bits.

eve_rwf_FXADDPAR_CONTWARN, HEADER, NAME

Utility routine to add a warning to the file.

result = eve_rwf_FXPARPOS(KEYWRD, IEND, BEFORE=BEFORE, AFTER=AFTER)

NAME: FXPARPOS() Purpose : Finds position to insert record into FITS header.

eve_rwf_FXADDPAR, HEADER, NAME, VALUE, COMMENT, BEFORE=BEFORE, AFTER=AFTER, FORMAT=FORMAT, NOCONTINUE=NOCONTINUE, ERRMSG=ERRMSG, NOLOGICAL=NOLOGICAL

NAME: FXADDPAR Purpose : Add or modify a parameter in a FITS header array.

result = eve_rwf_FXPAR(HDR, NAME, ABORT, COUNT=COUNT, COMMENT=COMMENT, START=START, PRECHECK=PRECHECK, POSTCHECK=POSTCHECK, NOCONTINUE=NOCONTINUE, DATATYPE=DATATYPE)

NAME: FXPAR() PURPOSE: Obtain the value of a parameter in a FITS header.

result = eve_rwf_DETABIFY(CHAR_STR)

NAME: DETABIFY PURPOSE: Replaces tabs in character strings with appropriate number of spaces EXPLANATION: The number of space characters inserted is calculated to space out to the next effective tab stop, each of which is eight characters apart.

result = eve_rwf_gettok(st, char, exact=exact, notrim=notrim)

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.

eve_rwf_match, a, b, suba, subb, COUNT=COUNT, SORT=SORT, epsilon=epsilon

NAME: MATCH PURPOSE: Routine to match values in two vectors.

eve_rwf_mrd_skip, unit, nskip

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.

eve_rwf_remchar, st, char

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

result = eve_rwf_strn(number, LENGTH=LENGTH, PADTYPE=PADTYPE, PADCHAR=PADCHAR, FORMAT=FORMAT)

NAME: STRN PURPOSE: Convert a number to a string and remove padded blanks.

eve_rwf_textclose, textout=textout

NAME: TEXTCLOSE

eve_rwf_TEXTOPEN, PROGRAM, TEXTOUT=TEXTOUT, STDOUT=STDOUT, MORE_SET=MORE_SET, SILENT=SILENT, WIDTH=WIDTH

NAME: TEXTOPEN PURPOSE: Open a device specified by TEXTOUT with unit !TEXTUNIT EXPLANATION: Procedure to open file for text output.

result = eve_rwf_valid_num(string, value, INTEGER=INTEGER)

NAME: VALID_NUM() PURPOSE: Check if a string is a valid number representation.

result = eve_rwf_mrd_struct(names, values, nrow, no_execute=no_execute, structyp=structyp, tempdir=tempdir, silent=silent, old_struct=old_struct)

NAME: MRD_STRUCT PURPOSE: Return a structure as defined in the names and values data.

result = eve_read_whole_fits(infname_ [, verbose=verbose] [, swap=swap] [, _extra=_extra])

Read all of the HDUs in a FITS file, creating a merged set of structures for the data, and string arrays for the keywords.

Routine details

top source eve_rwf_REPCHRprivate

result = eve_rwf_REPCHR(OLD, C1, C2, help=help)

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.

Parameters

OLD
C1
C2

Keywords

help

top source eve_rwf_fits_infoprivate

eve_rwf_fits_info, filename, SILENT=SILENT, TEXTOUT=TEXTOUT, N_ext=N_ext, extname=extname

NAME: FITS_INFO PURPOSE: Provide information about the contents of a FITS file EXPLANATION: Information includes number of header records and size of data array. Applies to primary header and all extensions. Information can be printed at the terminal and/or stored in a common block

This routine is mostly obsolete, and better results can be usually be performed with FITS_HELP (for display) or FITS_OPEN (to read FITS information into a structure)

CALLING SEQUENCE: FITS_INFO, Filename, [ /SILENT , TEXTOUT = , N_ext =, EXTNAME= ]

INPUT: Filename - Scalar string giving the name of the FITS file(s) Can include wildcards such as '*.fits', or regular expressions allowed by the FILE_SEARCH() function. One can also search gzip compressed FITS files, but their extension must end in .gz or .ftz. OPTIONAL INPUT KEYWORDS: /SILENT - If set, then the display of the file description on the terminal will be suppressed

TEXTOUT - specifies output device. textout=1 TERMINAL using /more option textout=2 TERMINAL without /more option textout=3 <program>.prt textout=4 laser.tmp textout=5 user must open file, see TEXTOPEN textout=7 append to existing <program.prt> file textout = filename (default extension of .prt)

If TEXTOUT is not supplied, then !TEXTOUT is used OPTIONAL OUTPUT KEYWORDS: N_ext - Returns an integer scalar giving the number of extensions in the FITS file extname - returns a list containing the EXTNAME keywords for each extension.

COMMON BLOCKS DESCRIPTOR = File descriptor string of the form N_hdrrec Naxis IDL_type Naxis1 Naxis2 ... Naxisn [N_hdrrec table_type Naxis IDL_type Naxis1 ... Naxisn] (repeated for each extension) For example, the following descriptor 167 2 4 3839 4 55 BINTABLE 2 1 89 5

indicates that the primary header containing 167 lines, and the primary (2D) floating point image (IDL type 4) is of size 3839 x 4. The first extension header contains 55 lines, and the byte (IDL type 1) table array is of size 89 x 5.

The DESCRIPTOR is *only* computed if /SILENT is set. EXAMPLE: Display info about all FITS files of the form '*.fit' in the current directory

IDL> fits_info, '*.fit'

Any time a *.fit file is found which is *not* in FITS format, an error message is displayed at the terminal and the program continues

PROCEDURES USED: GETTOK(), MRD_SKIP, STRN(), SXPAR(), TEXTOPEN, TEXTCLOSE

SYSTEM VARIABLES: The non-standard system variables !TEXTOUT and !TEXTUNIT will be created by FITS_INFO if they are not previously defined.

DEFSYSV,'!TEXTOUT',1 DEFSYSV,'!TEXTUNIT',0

See TEXTOPEN.PRO for more info MODIFICATION HISTORY: Written, K. Venkatakrishna, Hughes STX, May 1992 Added N_ext keyword, and table_name info, G. Reichert Work on *very* large FITS files October 92 More checks to recognize corrupted FITS files February, 1993 Proper check for END keyword December 1994 Correctly size variable length binary tables WBL December 1994 EXTNAME keyword can be anywhere in extension header WBL January 1998 Correctly skip past extensions with no data WBL April 1998 Converted to IDL V5.0, W. Landsman, April 1998 No need for !TEXTOUT if /SILENT D.Finkbeiner February 2002 Define !TEXTOUT if needed. R. Sterner, 2002 Aug 27 Work on gzip compressed files for V5.3 or later W. Landsman 2003 Jan Improve speed by only reading first 36 lines of header Count headers with more than 32767 lines W. Landsman Feb. 2003 Assume since V5.3 (OPENR,/COMPRESS) W. Landsman Feb 2004 EXTNAME keyword can be anywhere in extension header again WBL/S. Bansal Dec 2004 Read more than 200 extensions WBL March 2005 Work for FITS files with SIMPLE=F WBL July 2005 Assume since V5.4, fstat.compress available WBL April 2006 Added EXTNAME as an IDL keyword to return values. M. Perrin Dec 2007 make Ndata a long64 to deal with large files. E. Hivon Mar 2008 For GDL compatibility, first check if file is compressed before using OPENR,/COMPRESS B. Roukema/WL Apr 2010

Parameters

filename

Keywords

SILENT
TEXTOUT
N_ext
extname

top source eve_rwf_FXMOVEprivate

result = eve_rwf_FXMOVE(UNIT, EXTEN, SILENT=SILENT, EXT_NO=EXT_NO, ERRMSG=ERRMSG)

NAME: FXMOVE PURPOSE: Skip to a specified extension number or name in a FITS file

CALLING SEQUENCE: STATUS=FXMOVE(UNIT, EXT, /Silent) STATUS=FXMOVE(UNIT, EXTNAME, /Silent, EXT_NO=, ERRMSG= )

INPUT PARAMETERS: UNIT = An open unit descriptor for a FITS data stream. EXTEN = Number of extensions to skip. or Scalar string giving extension name (in the EXTNAME keyword) OPTIONAL INPUT PARAMETER: /SILENT - If set, then any messages about invalid characters in the FITS file are suppressed. OPTIONAL OUTPUT PARAMETER: 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.

RETURNS: 0 if successful. -1 if an error is encountered.

COMMON BLOCKS: None. SIDE EFFECTS: Repositions the file pointer. PROCEDURE: Each FITS header is read in and parsed, and the file pointer is moved to where the next FITS extension header until the desired extension is reached. PROCEDURE CALLS: FXPAR(), MRD_HREAD, MRD_SKIP MODIFICATION HISTORY: Extracted from FXPOSIT 8-March-2000 by T. McGlynn Added /SILENT keyword 14-Dec-2000 by W. Landsman Save time by not reading the full header W. Landsman Feb. 2003 Allow extension name to be specified, added EXT_NO, ERRMSG keywords W. Landsman December 2006 Make search for EXTNAME case-independent W.Landsman March 2007 Avoid round-off error for very large extensions N. Piskunov Dec 2007 Assume since V6.1 (/INTEGER keyword available to PRODUCT() ) Dec 2007 Capture error message from MRD_HREAD (must be used with post-June 2009 version of MRD-HREAD) W. Landsman July 2009 + NAME: FITS_INFO PURPOSE: Provide information about the contents of a FITS file EXPLANATION: Information includes number of header records and size of data array. Applies to primary header and all extensions. Information can be printed at the terminal and/or stored in a common block

This routine is mostly obsolete, and better results can be usually be performed with FITS_HELP (for display) or FITS_OPEN (to read FITS information into a structure)

CALLING SEQUENCE: FITS_INFO, Filename, [ /SILENT , TEXTOUT = , N_ext =, EXTNAME= ]

INPUT: Filename - Scalar string giving the name of the FITS file(s) Can include wildcards such as '*.fits', or regular expressions allowed by the FILE_SEARCH() function. One can also search gzip compressed FITS files, but their extension must end in .gz or .ftz. OPTIONAL INPUT KEYWORDS: /SILENT - If set, then the display of the file description on the terminal will be suppressed

TEXTOUT - specifies output device. textout=1 TERMINAL using /more option textout=2 TERMINAL without /more option textout=3 <program>.prt textout=4 laser.tmp textout=5 user must open file, see TEXTOPEN textout=7 append to existing <program.prt> file textout = filename (default extension of .prt)

If TEXTOUT is not supplied, then !TEXTOUT is used OPTIONAL OUTPUT KEYWORDS: N_ext - Returns an integer scalar giving the number of extensions in the FITS file extname - returns a list containing the EXTNAME keywords for each extension.

COMMON BLOCKS DESCRIPTOR = File descriptor string of the form N_hdrrec Naxis IDL_type Naxis1 Naxis2 ... Naxisn [N_hdrrec table_type Naxis IDL_type Naxis1 ... Naxisn] (repeated for each extension) For example, the following descriptor 167 2 4 3839 4 55 BINTABLE 2 1 89 5

indicates that the primary header containing 167 lines, and the primary (2D) floating point image (IDL type 4) is of size 3839 x 4. The first extension header contains 55 lines, and the byte (IDL type 1) table array is of size 89 x 5.

The DESCRIPTOR is *only* computed if /SILENT is set. EXAMPLE: Display info about all FITS files of the form '*.fit' in the current directory

IDL> fits_info, '*.fit'

Any time a *.fit file is found which is *not* in FITS format, an error message is displayed at the terminal and the program continues

PROCEDURES USED: GETTOK(), MRD_SKIP, STRN(), SXPAR(), TEXTOPEN, TEXTCLOSE

SYSTEM VARIABLES: The non-standard system variables !TEXTOUT and !TEXTUNIT will be created by FITS_INFO if they are not previously defined.

DEFSYSV,'!TEXTOUT',1 DEFSYSV,'!TEXTUNIT',0

See TEXTOPEN.PRO for more info MODIFICATION HISTORY: Written, K. Venkatakrishna, Hughes STX, May 1992 Added N_ext keyword, and table_name info, G. Reichert Work on *very* large FITS files October 92 More checks to recognize corrupted FITS files February, 1993 Proper check for END keyword December 1994 Correctly size variable length binary tables WBL December 1994 EXTNAME keyword can be anywhere in extension header WBL January 1998 Correctly skip past extensions with no data WBL April 1998 Converted to IDL V5.0, W. Landsman, April 1998 No need for !TEXTOUT if /SILENT D.Finkbeiner February 2002 Define !TEXTOUT if needed. R. Sterner, 2002 Aug 27 Work on gzip compressed files for V5.3 or later W. Landsman 2003 Jan Improve speed by only reading first 36 lines of header Count headers with more than 32767 lines W. Landsman Feb. 2003 Assume since V5.3 (OPENR,/COMPRESS) W. Landsman Feb 2004 EXTNAME keyword can be anywhere in extension header again WBL/S. Bansal Dec 2004 Read more than 200 extensions WBL March 2005 Work for FITS files with SIMPLE=F WBL July 2005 Assume since V5.4, fstat.compress available WBL April 2006 Added EXTNAME as an IDL keyword to return values. M. Perrin Dec 2007 make Ndata a long64 to deal with large files. E. Hivon Mar 2008 For GDL compatibility, first check if file is compressed before using OPENR,/COMPRESS B. Roukema/WL Apr 2010

Parameters

UNIT
EXTEN

Keywords

SILENT
EXT_NO
ERRMSG

top source eve_rwf_FXPOSITprivate

result = eve_rwf_FXPOSIT(XFILE, EXT_NO, readonly=readonly, COMPRESS=COMPRESS, SILENT=SILENT, EXTNUM=EXTNUM, ERRMSG=ERRMSG, LUNIT=LUNIT, UNIXPIPE=UNIXPIPE, FPACK=FPACK, NO_FPACK=NO_FPACK, HEADERONLY=HEADERONLY)

NAME: FXPOSIT PURPOSE: Return the unit number of a FITS file positioned at specified extension EXPLANATION: The FITS file will be ready to be read at the beginning of the specified extension. Either an extension number or extension name can be specified. Called by headfits.pro, mrdfits.pro

Modified in March 2009 to set the /SWAP_IF_LITTLE_ENDIAN keyword when opening a file, and **may not be compatible with earlier versions** CALLING SEQUENCE: unit=FXPOSIT(FILE, EXT_NO_OR_NAME, /READONLY, COMPRESS=program, UNIXPIPE=, ERRMSG= , EXTNUM= , UNIT=, /SILENT /FPACK, /NO_FPACK

INPUT PARAMETERS: FILE = FITS file name, scalar string. If an empty string is supplied then the user will be prompted for the file name. The user will also be prompted if a wild card is supplied, and more than one file matches the wildcard. EXT_NO_OR_NAME = Either the extension to be moved to (scalar nonnegative integer) or the name of the extension to read (scalar string)

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 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 FITS stream. If the keyword is not 1, then use its value as a string giving the command needed for decompression. /FPACK - Signal that the file is compressed with the FPACK software. http://heasarc.gsfc.nasa.gov/fitsio/fpack/ ) By default, (FXPOSIT will assume that if the file name extension ends in .fz that it is fpack compressed.) The FPACK software must be installed on the system /NO_FPACK - The unit will only be used to read the FITS header. In that case FPACK compressed files need not be uncompressed. LUNIT - Integer giving the file unit number. Use this keyword if you want to override the default use of GET_LUN to obtain a unit number. /READONLY - If this keyword is set and non-zero, then OPENR rather than OPENU will be used to open the FITS file. Note that compressed files are always set to /READONLY /SILENT If set, then suppress any messages about invalid characters in the FITS file.

OPTIONAL OUTPUT KEYWORDS: EXTNUM - Nonnegative integer give the extension number actually read Useful only if the extension was specified by name. 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. UNIXPIPE - If set to 1, then the FITS file was opened with a UNIX pipe rather than with the OPENR command. This is only required when reading a FPACK, bzip or Unix compressed file. Note that automatic byteswapping cannnot be set for a Unix pipe, since the SWAP_IF_LITTLE_ENDIAN keyword is only available for the OPEN command, and it is the responsibilty of the calling routine to perform the byteswapping. SIDE EFFECTS: Opens and returns a file unit. PROCEDURE: Open the appropriate file, or spawn a command and intercept the output. Call FXMOVE to get to the appropriate extension. PROCEDURE CALLS: FXMOVE() MODIFICATION HISTORY: Derived from William Thompson's FXFINDEND routine. Modified by T.McGlynn, 5-October-1994. Modified by T.McGlynn, 25-Feb-1995 to handle compressed files. Pipes cannot be accessed using FXHREAD so MRD_HREAD was written. W. Landsman 23-Apr-1997 Force the /bin/sh shell when uncompressing T. McGlynn 03-June-1999 Use /noshell option to get rid of processes left by spawn. Use findfile to retain ability to use wildcards W. Landsman 03-Aug-1999 Use EXPAND_TILDE under Unix to find file T. McGlynn 04-Apr-2000 Put reading code into FXMOVE, additional support for compression from D.Palmer. W. Landsman/D.Zarro 04-Jul-2000 Added test for !VERSION.OS EQ 'Win32' (WinNT) W. Landsman 12-Dec-2000 Added /SILENT keyword W. Landsman April 2002 Use FILE_SEARCH for V5.5 or later W. Landsman Feb 2004 Assume since V5.3 (OPENR,/COMPRESS available) W. Landsman,W. Thompson, 2-Mar-2004, Add support for BZIP2 W. Landsman Don't leave open file if an error occurs W. Landsman Sep 2004 Treat FTZ extension as gzip compressed W. Landsman Feb 2006 Removed leading spaces (prior to V5.5) W. Landsman Nov 2006 Allow specification of extension name Added EXTNUM, ERRMSG keywords W. Landsman/N.Piskunov Dec 2007 Added LUNIT keyword W. Landsman Mar 2009 OPEN with /SWAP_IF_LITTLE_ENDIAN Added UNIXPIPE output keyword N. Rich May 2009 Check if filename is an empty string W. Landsman May 2009 Support FPACK compressed files Added /FPACK, /HEADERONLY keywords W.Landsman July 2009 Deprecated /HEADERONLY add /NO_FPACK W.Landsman July 2011 Check for SIMPLE in first 8 chars Use gunzip to decompress Unix. Z file since compress utility often not installed anymore) + NAME: FXPOSIT PURPOSE: Return the unit number of a FITS file positioned at specified extension EXPLANATION: The FITS file will be ready to be read at the beginning of the specified extension. Either an extension number or extension name can be specified. Called by headfits.pro, mrdfits.pro

Modified in March 2009 to set the /SWAP_IF_LITTLE_ENDIAN keyword when opening a file, and **may not be compatible with earlier versions** CALLING SEQUENCE: unit=FXPOSIT(FILE, EXT_NO_OR_NAME, /READONLY, COMPRESS=program, UNIXPIPE=, ERRMSG= , EXTNUM= , UNIT=, /SILENT /FPACK, /NO_FPACK

INPUT PARAMETERS: FILE = FITS file name, scalar string. If an empty string is supplied then the user will be prompted for the file name. The user will also be prompted if a wild card is supplied, and more than one file matches the wildcard. EXT_NO_OR_NAME = Either the extension to be moved to (scalar nonnegative integer) or the name of the extension to read (scalar string)

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 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 FITS stream. If the keyword is not 1, then use its value as a string giving the command needed for decompression. /FPACK - Signal that the file is compressed with the FPACK software. http://heasarc.gsfc.nasa.gov/fitsio/fpack/ ) By default, (FXPOSIT will assume that if the file name extension ends in .fz that it is fpack compressed.) The FPACK software must be installed on the system /NO_FPACK - The unit will only be used to read the FITS header. In that case FPACK compressed files need not be uncompressed. LUNIT - Integer giving the file unit number. Use this keyword if you want to override the default use of GET_LUN to obtain a unit number. /READONLY - If this keyword is set and non-zero, then OPENR rather than OPENU will be used to open the FITS file. Note that compressed files are always set to /READONLY /SILENT If set, then suppress any messages about invalid characters in the FITS file.

OPTIONAL OUTPUT KEYWORDS: EXTNUM - Nonnegative integer give the extension number actually read Useful only if the extension was specified by name. 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. UNIXPIPE - If set to 1, then the FITS file was opened with a UNIX pipe rather than with the OPENR command. This is only required when reading a FPACK, bzip or Unix compressed file. Note that automatic byteswapping cannnot be set for a Unix pipe, since the SWAP_IF_LITTLE_ENDIAN keyword is only available for the OPEN command, and it is the responsibilty of the calling routine to perform the byteswapping. SIDE EFFECTS: Opens and returns a file unit. PROCEDURE: Open the appropriate file, or spawn a command and intercept the output. Call FXMOVE to get to the appropriate extension. PROCEDURE CALLS: FXMOVE() MODIFICATION HISTORY: Derived from William Thompson's FXFINDEND routine. Modified by T.McGlynn, 5-October-1994. Modified by T.McGlynn, 25-Feb-1995 to handle compressed files. Pipes cannot be accessed using FXHREAD so MRD_HREAD was written. W. Landsman 23-Apr-1997 Force the /bin/sh shell when uncompressing T. McGlynn 03-June-1999 Use /noshell option to get rid of processes left by spawn. Use findfile to retain ability to use wildcards W. Landsman 03-Aug-1999 Use EXPAND_TILDE under Unix to find file T. McGlynn 04-Apr-2000 Put reading code into FXMOVE, additional support for compression from D.Palmer. W. Landsman/D.Zarro 04-Jul-2000 Added test for !VERSION.OS EQ 'Win32' (WinNT) W. Landsman 12-Dec-2000 Added /SILENT keyword W. Landsman April 2002 Use FILE_SEARCH for V5.5 or later W. Landsman Feb 2004 Assume since V5.3 (OPENR,/COMPRESS available) W. Landsman,W. Thompson, 2-Mar-2004, Add support for BZIP2 W. Landsman Don't leave open file if an error occurs W. Landsman Sep 2004 Treat FTZ extension as gzip compressed W. Landsman Feb 2006 Removed leading spaces (prior to V5.5) W. Landsman Nov 2006 Allow specification of extension name Added EXTNUM, ERRMSG keywords W. Landsman/N.Piskunov Dec 2007 Added LUNIT keyword W. Landsman Mar 2009 OPEN with /SWAP_IF_LITTLE_ENDIAN Added UNIXPIPE output keyword N. Rich May 2009 Check if filename is an empty string W. Landsman May 2009 Support FPACK compressed files Added /FPACK, /HEADERONLY keywords W.Landsman July 2009 Deprecated /HEADERONLY add /NO_FPACK W.Landsman July 2011 Check for SIMPLE in first 8 chars Use gunzip to decompress Unix. Z file since compress utility often not installed anymore)

Parameters

XFILE
EXT_NO

Keywords

readonly
COMPRESS
SILENT
EXTNUM
ERRMSG
LUNIT
UNIXPIPE
FPACK
NO_FPACK
HEADERONLY

top source eve_rwf_mrd_hreadprivate

eve_rwf_mrd_hread, unit, header, status, SILENT=SILENT, FIRSTBLOCK=FIRSTBLOCK, ERRMSG=ERRMSG, SKIPDATA=SKIPDATA

NAME: MRD_HREAD

PURPOSE: Reads a FITS header from an opened disk file or Unix pipe EXPLANATION: Like FXHREAD but also works with compressed Unix files

CALLING SEQUENCE: MRD_HREAD, UNIT, HEADER [, STATUS, /SILENT, ERRMSG =, /FIRSTBLOCK ] INPUTS: UNIT = Logical unit number of an open FITS file OUTPUTS: HEADER = String array containing the FITS header. OPT. OUTPUTS: STATUS = Condition code giving the status of the read. Normally, this is zero, but is set to -1 if an error occurs, or if the first byte of the header is zero (ASCII null). OPTIONAL KEYWORD INPUT: /FIRSTBLOCK - If set, then only the first block (36 lines or less) of the FITS header are read into the output variable. If only size information (e.g. BITPIX, NAXIS) is needed from the header, then the use of this keyword can save time. The file pointer is still positioned at the end of the header, even if the /FIRSTBLOCK keyword is supplied. /SILENT - If set, then warning messages about any invalid characters in the header are suppressed. /SKIPDATA - If set, then the file point is positioned at the end of the HDU after the header is read, i.e. the following data block is skipped. Useful, when one wants to the read the headers of multiple extensions. OPTIONAL OUTPUT PARAMETER: 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. RESTRICTIONS: The file must already be positioned at the start of the header. It must be a proper FITS file. SIDE EFFECTS: The file ends by being positioned at the end of the FITS header, unless an error occurs. REVISION HISTORY: Written, Thomas McGlynn August 1995 Modified, Thomas McGlynn January 1996 Changed MRD_HREAD to handle Headers which have null characters A warning message is printed out but the program continues. Previously MRD_HREAD would fail if the null characters were not in the last 2880 byte block of the header. Note that such characters are illegal in the header but frequently are produced by poor FITS writers. Added /SILENT keyword W. Landsman December 2000 Added /FIRSTBLOCK keyword W. Landsman February 2003 Added ERRMSG, SKIPDATA keyword W. Landsman April 2009 Close file unit even after error message W.L. October 2010

Parameters

unit
header
status

Keywords

SILENT
FIRSTBLOCK
ERRMSG
SKIPDATA

top source eve_rwf_mrd_fxparprivate

eve_rwf_mrd_fxpar, hdr, xten, nfld, nrow, rsize, fnames, fforms, scales, offsets

Parameters

hdr
xten
nfld
nrow
rsize
fnames
fforms
scales
offsets

top source eve_rwf_mrd_dofnprivate

result = eve_rwf_mrd_dofn(name, index, use_colnum, alias=alias)

Get a tag name give the column name and index

Parameters

name
index
use_colnum

Keywords

alias

top source eve_rwf_mrd_doffprivate

eve_rwf_mrd_doff, form, dim, type

; Parse the TFORM keyword and return the type and dimension of the data.

Parameters

form
dim
type

top source eve_rwf_mrd_chkfnprivate

result = eve_rwf_mrd_chkfn(name, namelist, index)

Check that this name is unique with regard to other column names.

Parameters

name
namelist
index

top source eve_rwf_mrd_unsigned_offsetprivate

result = eve_rwf_mrd_unsigned_offset(type)

Find the appropriate offset for a given unsigned type. The type may be given as the bitpix value or the IDL variable type.

Parameters

type

top source eve_rwf_mrd_chkunsignedprivate

result = eve_rwf_mrd_chkunsigned(bitpix, scale, zero, unsigned=unsigned)

Can we treat this data as unsigned?

Parameters

bitpix
scale
zero

Keywords

unsigned

top source eve_rwf_mrd_unsignedtypeprivate

result = eve_rwf_mrd_unsignedtype(data)

Is this one of the IDL unsigned types?

Parameters

data

top source eve_rwf_mrd_versionprivate

result = eve_rwf_mrd_version()

Return the currrent version string for MRDFITS

top source eve_rwf_mrd_atypeprivate

eve_rwf_mrd_atype, form, type, slen

Parse the TFORM keyword and return the type and dimension of the data.

Parameters

form
type
slen

top source eve_rwf_mrd_read_asciiprivate

eve_rwf_mrd_read_ascii, unit, range, nbytes, nrows, nfld, typarr, posarr, lenarr, nullarr, table, old_struct=old_struct, rows=rows

Read in the table information.

Parameters

unit
range
nbytes
nrows
nfld
typarr
posarr
lenarr
nullarr
table

Keywords

old_struct
rows

top source eve_rwf_mrd_asciiprivate

eve_rwf_mrd_ascii, header, structyp, use_colnum, range, table, nbytes, nrows, nfld, typarr, posarr, lenarr, nullarr, fnames, fvalues, scales, offsets, scaling, status, rows=rows, silent=silent, columns=columns, alias=alias, outalias=outalias

Define a structure to hold a FITS ASCII table.

Parameters

header
structyp
use_colnum
range
table
nbytes
nrows
nfld
typarr
posarr
lenarr
nullarr
fnames
fvalues
scales
offsets
scaling
status

Keywords

rows
silent
columns
alias
outalias

top source eve_rwf_mrd_columnsprivate

eve_rwf_mrd_columns, table, columns, fnames, fvalues, vcls, vtpes, scales, offsets, scaling, structyp=structyp, silent=silent

Eliminate columns from the table that do not match the user specification.

Parameters

table
columns
fnames
fvalues
vcls
vtpes
scales
offsets
scaling

Keywords

structyp
silent

top source eve_rwf_mrd_read_imageprivate

eve_rwf_mrd_read_image, unit, range, maxd, rsize, table, rows=rows, status=status, unixpipe=unixpipe

Read in the image information.

Parameters

unit
range
maxd
rsize
table

Keywords

rows
status
unixpipe

top source eve_rwf_mrd_axes_truncprivate

eve_rwf_mrd_axes_trunc, naxis, dims, silent

Truncate superfluous axes.

Parameters

naxis
dims
silent

top source eve_rwf_mrd_imageprivate

eve_rwf_mrd_image, header, range, maxd, rsize, table, scales, offsets, scaling, status, silent=silent, unsigned=unsigned, rows=rows

Define structure/array to hold a FITS image.

Parameters

header
range
maxd
rsize
table
scales
offsets
scaling
status

Keywords

silent
unsigned
rows

top source eve_rwf_mrd_ptrscaleprivate

eve_rwf_mrd_ptrscale, array, scale, offset

Scale an array of pointers

Parameters

array
scale
offset

top source eve_rwf_mrd_stringprivate

eve_rwf_mrd_string, table, header, typarr, fnames, fvalues, nrec, structyp=structyp, silent=silent

; Scale a FITS array or table.

Parameters

table
header
typarr
fnames
fvalues
nrec

Keywords

structyp
silent

top source eve_rwf_mrd_scaleprivate

eve_rwf_mrd_scale, type, scales, offsets, table, header, fnames, fvalues, nrec, dscale=dscale, structyp=structyp, silent=silent

; Scale a FITS array or table.

Parameters

type
scales
offsets
table
header
fnames
fvalues
nrec

Keywords

dscale
structyp
silent

top source eve_rwf_mrd_varcolumnprivate

eve_rwf_mrd_varcolumn, vtype, array, heap, off, siz

Read a variable length column into a pointer array.

Parameters

vtype
array
heap
off
siz

top source eve_rwf_mrd_fixcolumnprivate

eve_rwf_mrd_fixcolumn, vtype, array, heap, off, siz

Read a variable length column into a fixed length array.

Parameters

vtype
array
heap
off
siz

top source eve_rwf_mrd_read_heapprivate

eve_rwf_mrd_read_heap, unit, header, range, fnames, fvalues, vcls, vtpes, table, structyp, scaling, scales, offsets, status, silent=silent, columns=columns, rows=rows, pointer_var=pointer_var, fixed_var=fixed_var

Read the heap area to get the actual values of variable length arrays.

Parameters

unit
header
range
fnames
fvalues
vcls
vtpes
table
structyp
scaling
scales
offsets
status

Keywords

silent
columns
rows
pointer_var
fixed_var

top source eve_rwf_mrd_read_tableprivate

eve_rwf_mrd_read_table, unit, range, rsize, structyp, nrows, nfld, typarr, table, rows=rows, unixpipe=unixpipe

Read in the binary table information.

Parameters

unit
range
rsize
structyp
nrows
nfld
typarr
table

Keywords

rows
unixpipe

top source eve_rwf_mrd_tdimprivate

eve_rwf_mrd_tdim, header, index, flen, arrstr, no_tdim=no_tdim

Check the values of TDIM keywords to see that they have valid dimensionalities. If the TDIM keyword is not present or valid then the a one-dimensional array with a size given in the TFORM keyword is used.

Parameters

header
index
flen
arrstr

Keywords

no_tdim

top source eve_rwf_mrd_tableprivate

eve_rwf_mrd_table, header, structyp, use_colnum, range, rsize, table, nrows, nfld, typarr, fnames, fvalues, vcls, vtpes, scales, offsets, scaling, status, rows=rows, silent=silent, columns=columns, no_tdim=no_tdim, alias=alias, unsigned=unsigned, outalias=outalias, emptystring=emptystring

Define a structure to hold a FITS binary table.

Parameters

header
structyp
use_colnum
range
rsize
table
nrows
nfld
typarr
fnames
fvalues
vcls
vtpes
scales
offsets
scaling
status

Keywords

rows
silent
columns
no_tdim
alias
unsigned
outalias
emptystring

top source eve_rwf_mrdfitsprivate

result = eve_rwf_mrdfits(file, extension, header, structyp=structyp, use_colnum=use_colnum, range=range, dscale=dscale, fscale=fscale, fpack=fpack, no_fpack=no_fpack, silent=silent, columns=columns, no_tdim=no_tdim, error_action=error_action, compress=compress, alias=alias, rows=rows, unsigned=unsigned, version=version, pointer_var=pointer_var, fixed_var=fixed_var, outalias=outalias, emptystring=emptystring, status=status, extnum=extnum)

NAME: MRDFITS

PURPOSE: Read all standard FITS data types into arrays or structures.

EXPLANATION: Further information on MRDFITS is available at http://idlastro.gsfc.nasa.gov/mrdfits.html

**This version requires a post March 2009 version of fxposit.pro** CALLING SEQUENCE: Result = MRDFITS( Filename/FileUnit,[Exten_no/Exten_name, Header], /FPACK, /NO_FPACK, /FSCALE , /DSCALE , /UNSIGNED, ALIAS=strarr[2,n], /USE_COLNUM, /NO_TDIM, ROWS = [a,b,...], $ /POINTER_VAR, /FIXED_VAR, EXTNUM= RANGE=[a,b], COLUMNS=[a,b,...]), ERROR_ACTION=x, COMPRESS=comp_prog, STATUS=status, /VERSION, /EMPTYSTRING )

INPUTS: Filename = String containing the name of the file to be read or file number of an open unit. If an empty string is supplied, then user will be prompted for the file name. The user will also be prompted if a wild card is given in the file name, and there is more than one file name match. If the file name ends in .gz or .fz (or .Z on Unix systems) the file will be dynamically decompressed. or FiluUnit = An integer file unit which has already been opened for input. Data will be read from this unit and the unit will be left pointing immediately after the HDU that is read. Thus to read a compressed file with many HDU's a user might do something like: lun=fxposit(filename, 3) ; Skip the first three HDU's repeat begin thisHDU = mrdfits(lun, 0, hdr, status=status) ... process the HDU ... endrep until status lt 0

Exten_no= Extension number to be read, 0 for primary array. Assumed 0 if not specified. If a unit rather than a filename is specified in the first argument, this is the number of HDU's to skip from the current position. Exten_name - Name of the extension to read (as stored in the EXTNAME keyword). This is a slightly slower method then specifying the extension number. OUTPUTS: Result = FITS data array or structure constructed from the designated extension. The format of result depends upon the type of FITS data read. Non-group primary array or IMAGE extension: A simple multidimensional array is returned with the dimensions given in the NAXISn keywords. Grouped image data with PCOUNT=0. As above but with GCOUNT treated as NAXIS(n+1). Grouped image data with PCOUNT>0. The data is returned as an array of structures. Each structure has two elements. The first is a one-dimensional array of the group parameters, the second is a multidimensional array as given by the NAXIS2-n keywords. ASCII and BINARY tables. The data is returned as a structure with one column for each field in the table. The names of the columns are normally taken from the TTYPE keywords (but see USE_COLNUM). Bit field columns are stored in byte arrays of the minimum necessary length. Spaces and invalid characters are replaced by underscores, and other invalid tag names are converted using the IDL_VALIDNAME(/CONVERT_ALL) function. Columns specified as variable length columns are stored with a dimension equal to the largest actual dimension used. Extra values in rows are filled with 0's or blanks. If the size of the variable length column is not a constant, then an additional column is created giving the size used in the current row. This additional column will have a tag name of the form L#_"colname" where # is the column number and colname is the column name of the variable length column. If the length of each element of a variable length column is 0 then the column is deleted.

OPTIONAL OUTPUT: Header = String array containing the header from the FITS extension.

OPTIONAL INPUT KEYWORDS: ALIAS The keyword allows the user to specify the column names to be created when reading FITS data. The value of this keyword should be a 2xn string array. The first value of each pair of strings should be the desired tag name for the IDL column. The second should be the FITS TTYPE value. Note that there are restrictions on valid tag names. The order of the ALIAS keyword is compatible with MWRFITS. COLUMNS - This keyword allows the user to specify that only a subset of columns is to be returned. The columns may be specified either as number 1,... n or by name or some combination of these two. If /USE_COLNUM is specified names should be C1,...Cn. The use of this keyword will not save time or internal memory since the extraction of specified columns is done after all columns have been retrieved from the FITS file. Structure columns are returned in the order supplied in this keyword. COMPRESS - This keyword allows the user to specify a decompression program to use to decompress a file that will not be automatically recognized based upon the file name. /DSCALE - As with FSCALE except that the resulting data is stored in doubles. /EMPTYSTRING - There was a bug in memory management for IDL versions prior to V8.0, causing a memory leak when reading empty strings in a FITS table. Setting /EMPTYSTRING will avoid this problem by first reading strings into bytes and then converting. However, there is a performance penalty. ERROR_ACTION - Set the on_error action to this value (defaults to 2). /FIXED_VAR- Translate variable length columns into fixed length columns and provide a length column for truly varying columns. This was only behavior prior to V2.5 for MRDFITS and remains the default (see /POINTER_VAR) /FPACK - If set, then assume the FITS file uses FPACK compression (http://heasarc.gsfc.nasa.gov/fitsio/fpack/). MRDFITS will automatically detect FPACK compressed files, but it is more efficient to supply the /FPACK keyword. A file with an extension of .fz is assumed to be Fpack compressed. /NO_FPACK - If present, then MRDFITS will not uncompress an extension compressed with FPACK, but will just read the compressed binary stream. /FSCALE - If present and non-zero then scale data to float numbers for arrays and columns which have either non-zero offset or non-unity scale. If scaling parameters are applied, then the corresponding FITS scaling keywords will be modified. NO_TDIM - Disable processing of TDIM keywords. If NO_TDIM is specified MRDFITS will ignore TDIM keywords in binary tables. /POINTER_VAR- Use pointer arrays for variable length columns. In addition to changing the format in which variable length arrays are stored, if the pointer_var keyword is set to any value other than 1 this also disables the deletion of variable length columns. (See /FIXED_VAR) Note that because pointers may be present in the output structure, the user is responsible for memory management when deleting or reassigning the structure (e.g. use HEAP_FREE first). RANGE - A scalar or two element vector giving the start and end rows to be retrieved. For ASCII and BINARY tables this specifies the row number. For GROUPed data this will specify the groups. For array images, this refers to the last non-unity index in the array. E.g., for a 3 D image with NAXIS* values = [100,100,1], the range may be specified as 0:99, since the last axis is suppressed. Note that the range uses IDL indexing So that the first row is row 0. If only a single value, x, is given in the range, the range is assumed to be [0,x-1]. ROWS - A scalar or vector specifying a specific row or rows to read (first row is 0). For example to read rows 0, 12 and 23 only, set ROWS=[0,12,23]. Valid for images, ASCII and binary tables, but not GROUPed data. For images the row numbers refer to the last non-unity index in the array. Note that the use of the ROWS will not improve the speed of MRDFITS since the entire table will be read in, and then subset to the specified rows. Cannot be used at the same time as the RANGE keyword /SILENT - Suppress informative messages. STRUCTYP - The structyp keyword specifies the name to be used for the structure defined when reading ASCII or binary tables. Generally users will not be able to conveniently combine data from multiple files unless the STRUCTYP parameter is specified. An error will occur if the user specifies the same value for the STRUCTYP keyword in calls to MRDFITS in the same IDL session for extensions which have different structures. /UNSIGNED - For integer data with appropriate zero points and scales read the data into unsigned integer arrays. /USE_COLNUM - When creating column names for binary and ASCII tables MRDFITS attempts to use the appropriate TTYPE keyword values. If USE_COLNUM is specified and non-zero then column names will be generated as 'C1, C2, ... 'Cn' for the number of columns in the table. /VERSION Print the current version number

OPTIONAL OUTPUT KEYWORDS: EXTNUM - the number of the extension actually read. Useful if the user specified the extension by name. OUTALIAS - This is a 2xn string array where the first column gives the actual structure tagname, and the second gives the corresponding FITS keyword name (e.g. in the TTYPE keyword). This array can be passed directly to the alias keyword of MWRFITS to recreate the file originally read by MRDFITS. STATUS - A integer status indicating success or failure of the request. A status of >=0 indicates a successful read. Currently 0 -> successful completion -1 -> error -2 -> end of file

EXAMPLES: (1) Read a FITS primary array: a = mrdfits('TEST.FITS') or a = mrdfits('TEST.FITS', 0, header) The second example also retrieves header information.

(2) Read rows 10-100 of the second extension of a FITS file. a = mrdfits('TEST.FITS', 2, header, range=[10,100])

(3) Read a table and ask that any scalings be applied and the scaled data be converted to doubles. Use simple column names, suppress outputs. a = mrdfits('TEST.FITS', 1, /dscale, /use_colnum, /silent)

(4) Read rows 3, 34 and 52 of a binary table and request that variable length columns be stored as a pointer variable in the output structure a = mrdfits('TEST.FITS',1,rows=[3,34,52],/POINTER) RESTRICTIONS: (1) Cannot handle data in non-standard FITS formats. (2) Doesn't do anything with BLANK or NULL values or NaN's. They are just read in. They may be scaled if scaling is applied. NOTES: This multiple format FITS reader is designed to provide a single, simple interface to reading all common types of FITS data. MRDFITS DOES NOT scale data by default. The FSCALE or DSCALE parameters must be used.

Null values in an FITS ASCII table are converted to NaN (floating data), or -2147483647L (longwords) or '...' (strings).

PROCEDURES USED: The following procedures are contained in the main MRDFITS program. MRD_IMAGE -- Generate array/structure for images. MRD_READ_IMAGE -- Read image data. MRD_ASCII -- Generate structure for ASCII tables. MRD_READ_ASCII -- Read an ASCII table. MRD_TABLE -- Generate structure for Binary tables. MRD_READ_TABLE -- Read binary table info. MRD_READ_HEAP -- Read variable length record info. MRD_SCALE -- Apply scaling to data. MRD_COLUMNS -- Extract columns.

Other ASTRON Library routines used FXPAR(), FXADDPAR, FXPOSIT, FXMOVE(), MATCH, MRD_STRUCT(), MRD_SKIP

MODIfICATION HISTORY: V1.0 November 9, 1994 ---- Initial release. Creator: Thomas A. McGlynn V1.1 January 20, 1995 T.A. McGlynn Fixed bug in variable length records. Added TDIM support -- new routine mrd_tdim in MRD_TABLE. V1.2 Added support for dynamic decompression of files. Fixed further bugs in variable length record handling. V1.2a Added NO_TDIM keyword to turn off TDIM processing for those who don't want it. Bug fixes: Handle one row tables correctly, use BZERO rather than BOFFSET. Fix error in scaling of images. V1.2b Changed MRD_HREAD to handle null characters in headers. V2.0 April 1, 1996 -Handles FITS tables with an arbitrary number of columns. -Substantial changes to MRD_STRUCT to allow the use of substructures when more than 127 columns are desired. -All references to table columns are now made through the functions MRD_GETC and MRD_PUTC. See description above. -Use of SILENT will now eliminate compilation messages for temporary functions. -Bugs in handling of variable length columns with either a single row in the table or a maximum of a single element in the column fixed. -Added support for DCOMPLEX numbers in binary tables (M formats) for IDL versions above 4.0. -Created regression test procedure to check in new versions. -Added error_action parameter to allow user to specify on_error action. This should allow better interaction with new CHECK facility. ON_ERROR statements deleted from most called routines. - Modified MRDFITS to read in headers containing null characters with a warning message printed. V2.0a April 16, 1996 - Added IS_IEEE_BIG() checks (and routine) so that we don't worry about IEEE to host conversions if the machine's native format is IEEE Big-endian. V2.1 August 24, 1996 - Use resolve_routine for dynamically defined functions for versions > 4.0 - Fix some processing in random groups format. - Handle cases where the data segment is--legally--null. In this case MRDFITS returns a scalar 0. - Fix bugs with the values for BSCALE and BZERO (and PSCAL and PZERO) parameters set by MRDFITS. V2.1a April 24, 1997 Handle binary tables with zero length columns V2.1b May 13,1997 Remove whitespace from replicate structure definition V2.1c May 28,1997 Less strict parsing of XTENSION keyword V2.1d June 16, 1997 Fixed problem for >32767 entries introduced 24-Apr V2.1e Aug 12, 1997 Fixed problem handling double complex arrays V2.1f Oct 22, 1997 IDL reserved words can't be structure tag names V2.1g Nov 24, 1997 Handle XTENSION keywords with extra blanks. V2.1h Jul 26, 1998 More flexible parsing of TFORM characters V2.2 Dec 14, 1998 Allow fields with longer names for later versions of IDL. Fix handling of arrays in scaling routines. Allow >128 fields in structures for IDL >4.0 Use more efficient structure copying for IDL>5.0 V2.2b June 17, 1999 Fix bug in handling case where all variable length columns are deleted because they are empty. V2.3 March 7, 2000 Allow user to supply file handle rather than file name. Added status field. Now needs FXMOVE routine V2.3b April 4, 2000 Added compress option (from D. Palmer) V2.4 July 4, 2000 Added STATUS=-1 for "File access error" (Zarro/GSFC) V2.4a May 2, 2001 Trim binary format string (W. Landsman) V2.5 December 5, 2001 Add unsigned, alias, 64 bit integers. version, $ /pointer_val, /fixed_var. V2.5a Fix problem when both the first and the last character in a TTYPEnn value are invalid structure tag characters V2.6 February 15, 2002 Fix error in handling unsigned numbers, $ and 64 bit unsigneds. (Thanks to Stephane Beland) V2.6a September 2, 2002 Fix possible conflicting data structure for variable length arrays (W. Landsman) V2.7 July, 2003 Added Rows keyword (W. Landsman) V2.7a September 2003 Convert dimensions to long64 to handle huge files V2.8 October 2003 Use IDL_VALIDNAME() function to ensure valid tag names Removed OLD_STRUCT and TEMPDIR keywords W. Landsman V2.9 February 2004 Added internal MRD_FXPAR procedure for faster processing of binary table headers E. Sheldon V2.9a March 2004 Restore ability to read empty binary table W. Landsman Swallow binary tables with more columns than given in TFIELDS V2.9b Fix to ensure order of TFORMn doesn't matter V2.9c Check if extra degenerate NAXISn keyword are present W.L. Oct 2004 V2.9d Propagate /SILENT to MRD_HREAD, more LONG64 casting W. L. Dec 2004 V2.9e Add typarr[good] to fix a problem reading zero-length columns A.Csillaghy, csillag@ssl.berkeley.edu (RHESSI) V2.9f Fix problem with string variable binary tables, possible math overflow on non-IEEE machines WL Feb. 2005 V2.9g Fix problem when setting /USE_COLNUM WL Feb. 2005 V2.10 Use faster keywords to BYTEORDER WL May 2006 V2.11 Add ON_IOERROR, CATCH, and STATUS keyword to MRD_READ_IMAGE to trap EOF in compressed files DZ Also fix handling of unsigned images when BSCALE not present K Chu/WL June 2006 V2.12 Allow extension to be specified by name, added EXTNUM keyword WL December 2006 V2.12a Convert ASCII table column to DOUBLE if single precision is insufficient V2.12b Fixed problem when both /fscale and /unsigned are set C. Markwardt Aug 2007 V2.13 Use SWAP_ENDIAN_INPLACE instead of IEEE_TO_HOST and IS_IEEE_BIG W. Landsman Nov 2007 V2.13a One element vector allowed for file name W.L. Dec 2007 V2.13b More informative error message when EOF found W.L. Jun 2008 V2.14 Use vector form of VALID_NUM(), added OUTALIAS keyword W.L. Aug 2008 V2.15 Use new FXPOSIT which uses on-the-fly byteswapping W.L. Mar 2009 V2.15a Small efficiency updates to MRD_SCALE W.L. Apr 2009 V2.15b Fixed typo introduced Apr 2009 V2.15c Fix bug introduced Mar 2009 when file unit used W.L. July 2009 V2.16 Handle FPACK compressed files W. L. July 2009 V2.17 Use compile_opt hidden on all routines except mrdfits.pro W.L. July 2009 V2.18 Added /EMPTYSTRING keyword W. Landsman August 2009 V2.18a Fix Columns keyword output, A. Kimball/ W. Landsman Feb 2010 V2.18b Fix bug with /EMPTYSTRING and multidimensional strings S. Baldridge/W.L. August 2010 V2.18c Fix unsigned bug caused by compile_opt idl2 WL Nov 2010 V2.19 Use V6.0 operators WL Nov 2010 V2.19a Fix complex data conversion in variable length tables WL Dec 2010 V2.19b Fix bug with /FSCALE introduced Nov 2010 WL Jan 2011 V2.19c Fix bug with ROWS keyword introduced Nov 2010 WL Mar 2011 V2.20 Convert Nulls in ASCII tables, better check of duplicate keywords

Parameters

file
extension
header

Keywords

structyp
use_colnum
range
dscale
fscale
fpack
no_fpack
silent
columns
no_tdim
error_action
compress
alias
rows
unsigned
version
pointer_var
fixed_var
outalias
emptystring
status
extnum

top source eve_rwf_SXPARprivate

result = eve_rwf_SXPAR(hdr, name, abort, COUNT=COUNT, COMMENT=COMMENT, NoContinue=NoContinue, SILENT=SILENT)

NAME: SXPAR PURPOSE: Obtain the value of a parameter in a FITS header

CALLING SEQUENCE: result = SXPAR( Hdr, Name, [ Abort, COUNT=, COMMENT =, /NoCONTINUE, /SILENT ])

INPUTS: Hdr = FITS header array, (e.g. as returned by READFITS) string array, each element should have a length of 80 characters

Name = String name of the parameter to return. If Name is of the form 'keyword*' then an array is returned containing values of keywordN where N is an integer. The value of keywordN will be placed in RESULT(N-1). The data type of RESULT will be the type of the first valid match of keywordN found.

OPTIONAL INPUTS: ABORT - string specifying that SXPAR should do a RETALL if a parameter is not found. ABORT should contain a string to be printed if the keyword parameter is not found. If not supplied, SXPAR will return quietly with COUNT = 0 (and !ERR = -1) if a keyword is not found.

OPTIONAL INPUT KEYWORDS: /NOCONTINUE = If set, then continuation lines will not be read, even if present in the header /SILENT - Set this keyword to suppress warning messages about duplicate keywords in the FITS header.

OPTIONAL OUTPUT KEYWORDS: COUNT - Optional keyword to return a value equal to the number of parameters found by SXPAR, integer scalar

COMMENT - Array of comments associated with the returned values

OUTPUTS: Function value = value of parameter in header. If parameter is double precision, floating, long or string, the result is of that type. Apostrophes are stripped from strings. If the parameter is logical, 1b is returned for T, and 0b is returned for F. If Name was of form 'keyword*' then a vector of values are returned.

SIDE EFFECTS: !ERR is set to -1 if parameter not found, 0 for a scalar value returned. If a vector is returned it is set to the number of keyword matches found. The use of !ERR is deprecated, and instead the COUNT keyword is preferred

If a keyword (except HISTORY or COMMENT) occurs more than once in a header, a warning is given, and the *last* occurence is used.

EXAMPLES: Given a FITS header, h, return the values of all the NAXISi values into a vector. Then place the history records into a string vector.

IDL> naxisi = sxpar( h ,'NAXIS*') ; Extract NAXISi value IDL> history = sxpar( h, 'HISTORY' ) ; Extract HISTORY records

PROCEDURE: The first 8 chacters of each element of Hdr are searched for a match to Name. The value from the last 20 characters is returned. An error occurs if there is no parameter with the given name.

If a numeric value has no decimal point it is returned as type LONG. If it contains more than 8 numerals, or contains the characters 'D' or 'E', then it is returned as type DOUBLE. Otherwise it is returned as type FLOAT. Very large integer values, outside the range of valid LONG, are returned as DOUBLE.

If the value is too long for one line, it may be continued on to the the next input card, using the OGIP CONTINUE convention. For more info, see http://fits.gsfc.nasa.gov/registry/continue_keyword.html

Complex numbers are recognized as two numbers separated by one or more space characters.

If a numeric value has no decimal point (or E or D) it is returned as type LONG. If it contains more than 8 numerals, or contains the character 'D', then it is returned as type DOUBLE. Otherwise it is returned as type FLOAT. If an integer is too large to be stored as type LONG, then it is returned as DOUBLE.

NOTES: The functions SXPAR() and FXPAR() are nearly identical, although FXPAR() has slightly more sophisticated parsing, and additional keywords to specify positions in the header to search (for speed), and to force the output to a specified data type.. There is no particular reason for having two nearly identical procedures, but both are too widely used to drop either one.

PROCEDURES CALLED: GETTOK(), VALID_NUM() MODIFICATION HISTORY: DMS, May, 1983, STPAR Written. D. Lindler Jan 90 added ABORT input parameter J. Isensee Jul,90 added COUNT keyword W. Thompson, Feb. 1992, added support for FITS complex values. W. Thompson, May 1992, corrected problem with HISTORY/COMMENT/blank keywords, and complex value error correction. W. Landsman, November 1994, fix case where NAME is an empty string W. Landsman, March 1995, Added COMMENT keyword, ability to read values longer than 20 character W. Landsman, July 1995, Removed /NOZERO from MAKE_ARRAY call T. Beck May 1998, Return logical as type BYTE W. Landsman May 1998, Make sure integer values are within range of LONG W. Landsman Feb 1998, Recognize CONTINUE convention W. Landsman Oct 1999, Recognize numbers such as 1E-10 as floating point W. Landsman Jan 2000, Only accept integer N values when name = keywordN W. Landsman Dec 2001, Optional /SILENT keyword to suppress warnings W. Landsman/D. Finkbeiner Mar 2002 Make sure extracted vectors of mixed data type are returned with the highest type. W.Landsman Aug 2008 Use vector form of VALID_NUM() W. Landsman Jul 2009 Eliminate internal recursive call

Parameters

hdr
name
abort

Keywords

COUNT
COMMENT
NoContinue
SILENT

top source eve_rwf_FXADDPAR_CONTPARprivate

eve_rwf_FXADDPAR_CONTPAR, VALUE, CONTINUED

This is a utility routine, which splits a parameter into several continuation bits.

Parameters

VALUE
CONTINUED

top source eve_rwf_FXADDPAR_CONTWARNprivate

eve_rwf_FXADDPAR_CONTWARN, HEADER, NAME

Utility routine to add a warning to the file. The calling routine must ensure that the header is in a consistent state before calling FXADDPAR_CONTWARN because the header will be subsequently modified by calls to FXADDPAR.

Parameters

HEADER
NAME

top source eve_rwf_FXPARPOSprivate

result = eve_rwf_FXPARPOS(KEYWRD, IEND, BEFORE=BEFORE, AFTER=AFTER)

NAME: FXPARPOS() Purpose : Finds position to insert record into FITS header. Explanation : Finds the position to insert a record into a FITS header. Called from FXADDPAR. Use : Result = FXPARPOS(KEYWRD, IEND [, BEFORE=BEFORE ] [, AFTER=AFTER ]) Inputs : KEYWRD = Array of eight-character keywords in header. IEND = Position of END keyword. Opt. Inputs : None. Outputs : Result of function is position to insert record. Opt. Outputs: None. Keywords : BEFORE = Keyword string name. The parameter will be placed before the location of this keyword. For example, if BEFORE='HISTORY' then the parameter will be placed before the first history location. This applies only when adding a new keyword; keywords already in the header are kept in the same position.

AFTER = Same as BEFORE, but the parameter will be placed after the location of this keyword. This keyword takes precedence over BEFORE.

If neither BEFORE or AFTER keywords are passed, then IEND is returned.

Calls : None. Common : None. Restrictions: KEYWRD and IEND must be consistent with the relevant FITS header. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan 1992. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993. Converted to IDL V5.0 W. Landsman September 1997

Parameters

KEYWRD
IEND

Keywords

BEFORE
AFTER

top source eve_rwf_FXADDPARprivate

eve_rwf_FXADDPAR, HEADER, NAME, VALUE, COMMENT, BEFORE=BEFORE, AFTER=AFTER, FORMAT=FORMAT, NOCONTINUE=NOCONTINUE, ERRMSG=ERRMSG, NOLOGICAL=NOLOGICAL

NAME: FXADDPAR Purpose : Add or modify a parameter in a FITS header array. Explanation : This version of FXADDPAR will write string values longer than 68 characters using the FITS continuation convention described at http://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/ofwg_recomm/r13.html Use : FXADDPAR, HEADER, NAME, VALUE, COMMENT Inputs : HEADER = String array containing FITS header. The maximum string length must be equal to 80. If not defined, then FXADDPAR will create an empty FITS header array.

NAME = Name of parameter. If NAME is already in the header the value and possibly comment fields are modified. Otherwise a new record is added to the header. If NAME is equal to either "COMMENT" or "HISTORY" then the value will be added to the record without replacement. In this case the comment parameter is ignored.

VALUE = Value for parameter. The value expression must be of the correct type, e.g. integer, floating or string. String values of 'T' or 'F' are considered logical values unless the /NOLOGICAL keyword is set. If the value is a string and is "long" (more than 69 characters), then it may be continued over more than one line using the OGIP CONTINUE standard.

Opt. Inputs : COMMENT = String field. The '/' is added by this routine. Added starting in position 31. If not supplied, or set equal to '' (the null string), then any previous comment field in the header for that keyword is retained (when found). Outputs : HEADER = Updated header array. Opt. Outputs: None. Keywords : BEFORE = Keyword string name. The parameter will be placed before the location of this keyword. For example, if BEFORE='HISTORY' then the parameter will be placed before the first history location. This applies only when adding a new keyword; keywords already in the header are kept in the same position.

AFTER = Same as BEFORE, but the parameter will be placed after the location of this keyword. This keyword takes precedence over BEFORE.

FORMAT = Specifies FORTRAN-like format for parameter, e.g. "F7.3". A scalar string should be used. For complex numbers the format should be defined so that it can be applied separately to the real and imaginary parts. If not supplied, then the IDL default formatting is used, except that double precision is given a format of G19.12.

/NOCONTINUE = By default, FXADDPAR will break strings longer than 68 characters into multiple lines using the continuation convention. If this keyword is set, then the line will instead be truncated to 68 characters. This was the default behaviour of FXADDPAR prior to December 1999.

/NOLOGICAL = If set, then the values 'T' and 'F' are not interpreted as logical values, and are simply added without interpretation.

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, e.g.

ERRMSG = '' FXADDPAR, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ...

Calls : DETABIFY(), FXPAR(), FXPARPOS() Common : None. Restrictions: Warning -- Parameters and names are not checked against valid FITS parameter names, values and types.

The required FITS keywords SIMPLE (or XTENSION), BITPIX, NAXIS, NAXIS1, NAXIS2, etc., must be entered in order. The actual values of these keywords are not checked for legality and consistency, however.

Side effects: All HISTORY records are inserted in order at the end of the header.

All COMMENT records are also inserted in order at the end of the header, but before the HISTORY records. The BEFORE and AFTER keywords can override this.

All records with no keyword (blank) are inserted in order at the end of the header, but before the COMMENT and HISTORY records. The BEFORE and AFTER keywords can override this.

All other records are inserted before any of the HISTORY, COMMENT, or "blank" records. The BEFORE and AFTER keywords can override this.

String values longer than 68 characters will be split into multiple lines using the OGIP CONTINUE convention, unless the /NOCONTINUE keyword is set. For a description of the CONTINUE convention see http://fits.gsfc.nasa.gov/registry/continue_keyword.html Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan 1992, from SXADDPAR by D. Lindler and J. Isensee. Differences include:

* LOCATION parameter replaced with keywords BEFORE and AFTER. * Support for COMMENT and "blank" FITS keywords. * Better support for standard FITS formatting of string and complex values. * Built-in knowledge of the proper position of required keywords in FITS (although not necessarily SDAS/Geis) primary headers, and in TABLE and BINTABLE extension headers.

William Thompson, May 1992, fixed bug when extending length of header, and new record is COMMENT, HISTORY, or blank. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 5 September 1997 Fixed bug replacing strings that contain "/" character--it interpreted the following characters as a comment. Version 3, Craig Markwardt, GSFC, December 1997 Allow long values to extend over multiple lines Version 4, D. Lindler, March 2000, modified to use capital E instead of a lower case e for exponential format. Version 4.1 W. Landsman April 2000, make user-supplied format uppercase Version 4.2 W. Landsman July 2002, positioning of EXTEND keyword Version 5, 23-April-2007, William Thompson, GSFC Version 6, 02-Aug-2007, WTT, bug fix for OGIP long lines Version 6.1, 10-Feb-2009, W. Landsman, increase default format precision Version 6.2 30-Sep-2009, W. Landsman, added /NOLOGICAL keyword Version : Version 6.2, 30-Sep-2009

Parameters

HEADER
NAME
VALUE
COMMENT

Keywords

BEFORE
AFTER
FORMAT
NOCONTINUE
ERRMSG
NOLOGICAL

top source eve_rwf_FXPARprivate

result = eve_rwf_FXPAR(HDR, NAME, ABORT, COUNT=COUNT, COMMENT=COMMENT, START=START, PRECHECK=PRECHECK, POSTCHECK=POSTCHECK, NOCONTINUE=NOCONTINUE, DATATYPE=DATATYPE)

NAME: FXPAR() PURPOSE: Obtain the value of a parameter in a FITS header. EXPLANATION: The first 8 chacters of each element of HDR are searched for a match to NAME. If the keyword is one of those allowed to take multiple values ("HISTORY", "COMMENT", or " " (blank)), then the value is taken as the next 72 characters. Otherwise, it is assumed that the next character is "=", and the value (and optional comment) is then parsed from the last 71 characters. An error occurs if there is no parameter with the given name.

If the value is too long for one line, it may be continued on to the the next input card, using the CONTINUE Long String Keyword convention. For more info, http://fits.gsfc.nasa.gov/registry/continue_keyword.html

Complex numbers are recognized as two numbers separated by one or more space characters.

If a numeric value has no decimal point (or E or D) it is returned as type LONG. If it contains more than 8 numerals, or contains the character 'D', then it is returned as type DOUBLE. Otherwise it is returned as type FLOAT. If an integer is too large to be stored as type LONG, then it is returned as DOUBLE.

CALLING SEQUENCE: Result = FXPAR( HDR, NAME [, ABORT, COUNT=, COMMENT=, /NOCONTINUE ] )

Result = FXPAR(HEADER,'DATE') ;Finds the value of DATE Result = FXPAR(HEADER,'NAXIS*') ;Returns array dimensions as ;vector REQUIRED INPUTS: HDR = FITS header string array (e.g. as returned by FXREAD). Each element should have a length of 80 characters NAME = String name of the parameter to return. If NAME is of the form 'keyword*' then an array is returned containing values of keywordN where N is an integer. The value of keywordN will be placed in RESULT(N-1). The data type of RESULT will be the type of the first valid match of keywordN found, unless DATATYPE is given. OPTIONAL INPUT: ABORT = String specifying that FXPAR should do a RETALL if a parameter is not found. ABORT should contain a string to be printed if the keyword parameter is not found. If not supplied, FXPAR will return with a negative !err if a keyword is not found. DATATYPE = A scalar value, indicating the type of vector data. All keywords will be cast to this type. Default: based on first keyword. Example: DATATYPE=0.0D (cast data to double precision) START = A best-guess starting position of the sought-after keyword in the header. If specified, then FXPAR first searches for scalar keywords in the header in the index range bounded by START-PRECHECK and START+POSTCHECK. This can speed up keyword searches in large headers. If the keyword is not found, then FXPAR searches the entire header.

If not specified then the entire header is searched. Searches of the form 'keyword*' also search the entire header and ignore START.

Upon return START is changed to be the position of the newly found keyword. Thus the best way to search for a series of keywords is to search for them in the order they appear in the header like this:

START = 0L P1 = FXPAR('P1', START=START) P2 = FXPAR('P2', START=START) PRECHECK = If START is specified, then PRECHECK is the number of keywords preceding START to be searched. Default: 5 POSTCHECK = If START is specified, then POSTCHECK is the number of keywords after START to be searched. Default: 20 OUTPUT: The returned value of the function is the value(s) associated with the requested keyword in the header array.

If the parameter is complex, double precision, floating point, long or string, then the result is of that type. Apostrophes are stripped from strings. If the parameter is logical, 1 is returned for T, and 0 is returned for F.

If NAME was of form 'keyword*' then a vector of values are returned.

OPTIONAL INPUT KEYWORDS: /NOCONTINUE = If set, then continuation lines will not be read, even if present in the header OPTIONAL OUTPUT KEYWORD: COUNT = Optional keyword to return a value equal to the number of parameters found by FXPAR. COMMENTS= Array of comments associated with the returned values.

PROCEDURE CALLS: GETTOK(), VALID_NUM SIDE EFFECTS:

The system variable !err is set to -1 if parameter not found, 0 for a scalar value returned. If a vector is returned it is set to the number of keyword matches found.

If a keyword occurs more than once in a header, a warning is given, and the first occurence is used. However, if the keyword is "HISTORY", "COMMENT", or " " (blank), then multiple values are returned.

NOTES: The functions SXPAR() and FXPAR() are nearly identical, although FXPAR() has slightly more sophisticated parsing. There is no particular reason for having two nearly identical procedures, but both are too widely used to drop either one.

REVISION HISTORY: Version 1, William Thompson, GSFC, 12 April 1993. Adapted from SXPAR Version 2, William Thompson, GSFC, 14 October 1994 Modified to use VALID_NUM instead of STRNUMBER. Inserted additional call to VALID_NUM to trap cases where character strings did not contain quotation marks. Version 3, William Thompson, GSFC, 22 December 1994 Fixed bug with blank keywords, following suggestion by Wayne Landsman. Version 4, Mons Morrison, LMSAL, 9-Jan-98 Made non-trailing ' for string tag just be a warning (not a fatal error). It was needed because "sxaddpar" had an error which did not write tags properly for long strings (over 68 characters) Version 5, Wayne Landsman GSFC, 29 May 1998 Fixed potential problem with overflow of LONG values Version 6, Craig Markwardt, GSFC, 28 Jan 1998, Added CONTINUE parsing Version 7, Craig Markwardt, GSFC, 18 Nov 1999, Added START, PRE/POSTCHECK keywords for better performance Version 8, Craig Markwardt, GSFC, 08 Oct 2003, Added DATATYPE keyword to cast vector keywords type Version 9, Paul Hick, 22 Oct 2003, Corrected bug (NHEADER-1)

Parameters

HDR
NAME
ABORT

Keywords

COUNT
COMMENT
START
PRECHECK
POSTCHECK
NOCONTINUE
DATATYPE

top source eve_rwf_DETABIFYprivate

result = eve_rwf_DETABIFY(CHAR_STR)

NAME: DETABIFY PURPOSE: Replaces tabs in character strings with appropriate number of spaces EXPLANATION: The number of space characters inserted is calculated to space out to the next effective tab stop, each of which is eight characters apart.

CALLING SEQUENCE: Result = DETABIFY( CHAR_STR )

INPUT PARAMETERS: CHAR_STR = Character string variable (or array) to remove tabs from.

OUTPUT: Result of function is CHAR_STR with tabs replaced by spaces.

RESTRICTIONS: CHAR_STR must be a character string variable.

MODIFICATION HISTORY: William Thompson, Feb. 1992. Converted to IDL V5.0 W. Landsman September 1997

Parameters

CHAR_STR

top source eve_rwf_gettokprivate

result = eve_rwf_gettok(st, char, exact=exact, notrim=notrim)

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

Parameters

st
char

Keywords

exact
notrim

top source eve_rwf_matchprivate

eve_rwf_match, a, b, suba, subb, COUNT=COUNT, SORT=SORT, epsilon=epsilon

NAME: MATCH PURPOSE: Routine to match values in two vectors.

CALLING SEQUENCE: match, a, b, suba, subb, [ COUNT =, /SORT, EPSILON = ]

INPUTS: a,b - two vectors to match elements, numeric or string data types

OUTPUTS: suba - subscripts of elements in vector a with a match in vector b subb - subscripts of the positions of the elements in vector b with matchs in vector a.

suba and subb are ordered such that a[suba] equals b[subb]

OPTIONAL INPUT KEYWORD: /SORT - By default, MATCH uses two different algorithm: (1) the /REVERSE_INDICES keyword to HISTOGRAM is used for integer data, while (2) a sorting algorithm is used for non-integer data. The histogram algorithm is usually faster, except when the input vectors are sparse and contain very large numbers, possibly causing memory problems. Use the /SORT keyword to always use the sort algorithm. epsilon - if values are within epsilon, they are considered equal. Used only only for non-integer matching. Note that input vectors should be unique to within epsilon to provide one-to-one mapping.. Default=0.

OPTIONAL KEYWORD OUTPUT: COUNT - set to the number of matches, integer scalar

SIDE EFFECTS: The obsolete system variable !ERR is set to the number of matches; however, the use !ERR is deprecated in favor of the COUNT keyword

RESTRICTIONS: The vectors a and b should not have duplicate values within them. You can use rem_dup function to remove duplicate values in a vector

EXAMPLE: If a = [3,5,7,9,11] & b = [5,6,7,8,9,10] then IDL> match, a, b, suba, subb, COUNT = count

will give suba = [1,2,3], subb = [0,2,4], COUNT = 3 and a[suba] = b[subb] = [5,7,9]

METHOD: For non-integer data types, the two input vectors are combined and sorted and the consecutive equal elements are identified. For integer data types, the /REVERSE_INDICES keyword to HISTOGRAM of each array is used to identify where the two arrays have elements in common. HISTORY: D. Lindler Mar. 1986. Fixed "indgen" call for very large arrays W. Landsman Sep 1991 Added COUNT keyword W. Landsman Sep. 1992 Fixed case where single element array supplied W. Landsman Aug 95 Use a HISTOGRAM algorithm for integer vector inputs for improved performance W. Landsman March 2000 Work again for strings W. Landsman April 2000 Use size(/type) W. Landsman December 2002 Work for scalar integer input W. Landsman June 2003 Assume since V5.4, use COMPLEMENT to WHERE() W. Landsman Apr 2006 Added epsilon keyword Kim Tolbert March 14, 2008

Parameters

a
b
suba
subb

Keywords

COUNT
SORT
epsilon

top source eve_rwf_mrd_skipprivate

eve_rwf_mrd_skip, unit, nskip

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

Parameters

unit
nskip

top source eve_rwf_remcharprivate

eve_rwf_remchar, st, char

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

Parameters

st
char

top source eve_rwf_strnprivate

result = eve_rwf_strn(number, LENGTH=LENGTH, PADTYPE=PADTYPE, PADCHAR=PADCHAR, FORMAT=FORMAT)

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) Converted to IDL V5.0 W. Landsman September 1997

Parameters

number

Keywords

LENGTH
PADTYPE
PADCHAR
FORMAT

top source eve_rwf_textcloseprivate

eve_rwf_textclose, textout=textout

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

Keywords

textout

top source eve_rwf_TEXTOPENprivate

eve_rwf_TEXTOPEN, PROGRAM, TEXTOUT=TEXTOUT, STDOUT=STDOUT, MORE_SET=MORE_SET, SILENT=SILENT, WIDTH=WIDTH

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

Parameters

PROGRAM

Keywords

TEXTOUT
STDOUT
MORE_SET
SILENT
WIDTH

top source eve_rwf_valid_numprivate

result = eve_rwf_valid_num(string, value, INTEGER=INTEGER)

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

Parameters

string
value

Keywords

INTEGER

top source eve_rwf_mrd_structprivate

result = eve_rwf_mrd_struct(names, values, nrow, no_execute=no_execute, structyp=structyp, tempdir=tempdir, silent=silent, old_struct=old_struct)

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 arbitary 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

Parameters

names
values
nrow

Keywords

no_execute
structyp
tempdir
silent
old_struct

top source eve_read_whole_fits

User

result = eve_read_whole_fits(infname_ [, verbose=verbose] [, swap=swap] [, _extra=_extra])

Read all of the HDUs in a FITS file, creating a merged set of structures for the data, and string arrays for the keywords.

Return value

a structure that contains structures from each HDU and an associated string array for the keywords

SIDE EFFECTS: Substructure names correspond to the keyword "EXTNAME", if absent, then a default naming convention is used.

RESTRICTIONS: Requires fits_info.pro and mrdfits.pro (with it's own dependencies).

This should be compatible with all OSes, but we only test on Linux and Mac OS X. However, if you encounter problems, try decompressing the FITS files before you call this function.

Parameters

infname_ in required

A scalar string for a FITS file. If comressed with gzip (.gz) MRDFITS is used in compress mode

Keywords

verbose in optional

report information on each HDU read to stdout (nothing is reported normally)

swap in optional

Set this flag to force an endian swap. Otherwise the program tries to detect if one is necesssary automatically, by looking for a timestamp and deciding if it is in a reasonable range, with a swap if not. You can specify swap=0 to force the program to not autodetect and not swap.

_extra in optional

additional parameters to pass to mrdfits (refer to mrdfits.pro)

Examples

: IDL> data=eve_read_whole_fits('EVS_L2_2010120_00_002_01.fit.gz',/verbose)

File attributes

Modification date: Tue Sep 11 00:00:00 2012
Lines: 6,733
Docformat: rst rst