Project : SOHO - CDS
Name :
FXADDPAR
Purpose :
Add or modify a parameter in a FITS header array.
Explanation :
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.
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.
Calls :
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.
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 :
Version 1, 12 April 1993.
(See /usr/local/idl/lib/zastron/fits_bintable/fxaddpar.pro)
Project : SOHO - CDS Name : FXBADDCOL Purpose : Adds a column to a binary table extension. Explanation : Modify a basic FITS binary table extension (BINTABLE) header array to define a column. Use : FXBADDCOL, INDEX, HEADER, ARRAY [, TTYPE ] Inputs : HEADER = String array containing FITS extension header. ARRAY = IDL variable used to determine the data size and type associated with the column. If the column is defined as containing variable length arrays, then ARRAY must be of the maximum size to be stored in the column. Opt. Inputs : TTYPE = Column label. COMMENT = Comment for TTYPE Outputs : INDEX = Index (1-999) of the created column. HEADER = The header is modified to reflect the added column. Opt. Outputs: None. Keywords : VARIABLE= If set, then the column is defined to contain pointers to variable length arrays in the heap area. DCOMPLEX= If set, and ARRAY is complex, with the first dimension being two (real and imaginary parts), then the column is defined as double-precision complex (type "M"). BIT = If passed, and ARRAY is of type byte, then the column is defined as containg bit mask arrays (type "X"), with the value of BIT being equal to the number of mask bits. LOGICAL = If set, and array is of type byte, then the column is defined as containing logical arrays (type "L"). NO_TDIM = If set, then the TDIMn keyword is not written out to the header. No TDIMn keywords are written for columns containing variable length arrays. TUNIT = If passed, then corresponding keyword is added to header. TSCAL = Same. TZERO = Same. TNULL = Same. TDISP = Same. TDMIN = Same. TDMAX = Same. TDESC = Same. TROTA = Same. TRPIX = Same. TRVAL = Same. TDELT = Same. Calls : FXADDPAR, FXPAR Common : None. Restrictions: Warning: No checking is done of any of the parameters defining the values of optional FITS keywords. FXBHMAKE must first be called to initialize the header. If ARRAY is of type character, then it must be of the maximum length expected for this column. If a character string array, then the largest string in the array is used to determine the maximum length. The DCOMPLEX keyword is ignored if ARRAY is not double-precision. ARRAY must also have a first dimension of two representing the real and imaginary parts. The BIT and LOGICAL keywords are ignored if ARRAY is not of type byte. BIT takes precedence over LOGICAL. Side effects: If the data array is multidimensional, then a TDIM keyword is added to the header, unless either NO_TDIM or VARIABLE is set. No TDIMn keywords are written out for bit arrays (format 'X'), since the dimensions would refer to bits, not bytes. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan 1992. W. Thompson, Feb 1992, changed from function to procedure. W. Thompson, Feb 1992, modified to support variable length arrays. 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.
(See /usr/local/idl/lib/zastron/fits_bintable/fxbaddcol.pro)
Project : SOHO - CDS Name : FXBCLOSE Purpose : Close a FITS binary table extension opened for read. Explanation : Closes a FITS binary table extension that had been opened for read by FXBOPEN. Use : FXBCLOSE, UNIT Inputs : UNIT = Logical unit number of the file. Opt. Inputs : None. Outputs : None. Opt. Outputs: None. Keywords : None. Calls : None. Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The file must have been opened with FXBOPEN. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Feb. 1992. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993.
(See /usr/local/idl/lib/zastron/fits_bintable/fxbclose.pro)
Project : SOHO - CDS Name : FXBCOLNUM() Purpose : Returns a binary table column number. Explanation : Given a column specified either by number or name, this routine will return the appropriate column number. Use : Result = FXBCOLNUM( UNIT, COL ) Inputs : UNIT = Logical unit number corresponding to the file containing the binary table. COL = Column in the binary table, given either as a character string containing a column label (TTYPE), or as a numerical column index starting from column one. Opt. Inputs : None. Outputs : The result of the function is the number of the column specified, or zero if no column is found (when passed by name). Opt. Outputs: None. Keywords : None. Calls : None. Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The binary table file must have been opened with FXBOPEN. If COL is passed as a number, rather than as a name, then it must be consistent with the number of columns in the table. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : None. Written : William Thompson, GSFC, 2 July 1993. Modified : Version 1, William Thompson, GSFC, 2 July 1993. Version 2, William Thompson, GSFC, 29 October 1993. Added error message for not finding column by name. Version : Version 2, 29 October 1993.
(See /usr/local/idl/lib/zastron/fits_bintable/fxbcolnum.pro)
Project : SOHO - CDS Name : FXBCREATE Purpose : Open a new binary table at the end of a FITS file. Explanation : Write a binary table extension header to the end of a disk FITS file, and leave it open to receive the data. The FITS file is opened, and the pointer is positioned just after the last 2880 byte record. Then the binary header is appended. Calls to FXBWRITE will append the binary data to this file, and then FXBFINISH will close the file. Use : FXBCREATE, UNIT, FILENAME, HEADER Inputs : FILENAME = Name of FITS file to be opened. HEADER = String array containing the FITS binary table extension header. Opt. Inputs : None. Outputs : UNIT = Logical unit number of the opened file. Opt. Outputs: None. Keywords : None. Calls : FXADDPAR, FXBFINDLUN, FXBPARSE, FXFINDEND Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The primary FITS data unit must already be written to a file. The binary table extension header must already be defined (FXBHMAKE), and must match the data that will be written to the file. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Jan 1992, based on WRITEFITS by J. Woffard and W. Landsman. W. Thompson, Feb 1992, changed from function to procedure. W. Thompson, Feb 1992, removed all references to temporary files. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 July 1993. Fixed bug with variable length arrays. Version : Version 2, 21 July 1993.
(See /usr/local/idl/lib/zastron/fits_bintable/fxbcreate.pro)
Project : SOHO - CDS Name : FXBFIND Purpose : Find column keywords in a FITS binary table header. Explanation : Finds the value of a column keyword for all the columns in the binary table for which it is set. For example, FXBFIND, UNIT, 'TTYPE', COLUMNS, VALUES, N_FOUND Would find all instances of the keywords TTYPE1, TTYPE2, etc. The array COLUMNS would contain the column numbers for which a TTYPEn keyword was found, and VALUES would contain the values. N_FOUND would contain the total number of instances found. Use : FXBFIND, [UNIT or HEADER], KEYWORD, COLUMNS, VALUES, N_FOUND [, DEFAULT ] Inputs : Either UNIT or HEADER must be passed. UNIT = Logical unit number of file opened by FXBOPEN. HEADER = FITS binary table header. KEYWORD = Prefix to a series of FITS binary table column keywords. The keywords to be searched for are formed by combining this prefix with the numbers 1 through the value of TFIELDS in the header. Opt. Inputs : DEFAULT = Default value to use for any column keywords that aren't found. If passed, then COLUMNS and VALUES will contain entries for every column. Otherwise, COLUMNS and VALUES only contain entries for columns where values were found. Outputs : COLUMNS = Array containing the column numbers for which values of the requested keyword series were found. VALUES = Array containing the found values. N_FOUND = Number of values found. The value of this parameter is unaffected by whether or not DEFAULT is passed. Opt. Outputs: None. Keywords : None. Calls : FXBFINDLUN, FXPAR Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: If UNIT is passed, then the file must have been opened with FXBOPEN. If HEADER is passed, then it must be a legal FITS binary table header. The type of DEFAULT must be consistent with the values of the requested keywords, i.e. both most be either of string or numerical type. The KEYWORD prefix must not have more than five characters to leave room for the three digits allowed for the column numbers. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Feb. 1992. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993.
(See /usr/local/idl/lib/zastron/fits_bintable/fxbfind.pro)
Project : SOHO - CDS Name : FXBFINDLUN() Purpose : Find logical unit number UNIT in FXBINTABLE common block. Explanation : Finds the proper index to use for getting information about the logical unit number UNIT in the arrays stored in the FXBINTABLE common block. Called from FXBCREATE and FXBOPEN. Use : Result = FXBFINDLUN( UNIT ) Inputs : UNIT = Logical unit number. Opt. Inputs : None. Outputs : The result of the function is an index into the FXBINTABLE common block. Opt. Outputs: None. Keywords : None. Calls : None. Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: None. Side effects: If UNIT is not found in the common block, then it is added to the common block. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Feb. 1992. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 July 1993. Added DHEAP variable to fix bug with variable length arrays. Version : Version 2, 21 July 1993.
(See /usr/local/idl/lib/zastron/fits_bintable/fxbfindlun.pro)
Project : SOHO - CDS Name : FXBFINISH Purpose : Close a FITS binary table extension file opened for write. Explanation : Closes a FITS binary table extension file that had been opened for write by FXBCREATE. Use : FXBFINISH, UNIT Inputs : UNIT = Logical unit number of the file. Opt. Inputs : None. Outputs : None. Opt. Outputs: None. Keywords : None. Calls : None. Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The file must have been opened with FXBCREATE, and written with FXBWRITE. Side effects: Any bytes needed to pad the file out to an integral multiple of 2880 bytes are written out to the file. Then, the file is closed. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Jan 1992. W. Thompson, Feb 1992, modified to support variable length arrays. W. Thompson, Feb 1992, removed all references to temporary files. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 July 1993. Fixed bug with variable length arrays. Version : Version 2, 21 July 1993.
(See /usr/local/idl/lib/zastron/fits_bintable/fxbfinish.pro)
Project : SOHO - CDS Name : FXBHEADER() Purpose : Returns the header of an open FITS binary table. Explanation : This procedure returns the FITS extension header of a FITS binary table opened for read with the command FXBOPEN. Use : Result = FXBHEADER(UNIT) Inputs : UNIT = Logical unit number returned by FXBOPEN routine. Must be a scalar integer. Opt. Inputs : None. Outputs : The result of the function is a string array containing the header for the FITS binary table that UNIT points to. Opt. Outputs: None. Keywords : None. Calls : FXBFINDLUN Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: None. Side effects: The string array returned always has as many elements as the largest header read by FXBOPEN. Any extra elements beyond the true header are blank or null strings. The header will be returned whether or not the table is still open or not. If UNIT does not point to a binary table, then a string array of nulls is returned. If UNIT is an undefined variable, then the null string is returned. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : None. Written : William Thompson, GSFC, 1 July 1993. Modified : Version 1, William Thompson, GSFC, 1 July 1993. Version : Version 1, 1 July 1993.
(See /usr/local/idl/lib/zastron/fits_bintable/fxbheader.pro)
Project : SOHO - CDS Name : FXBHELP Purpose : Prints short description of columns in a FITS binary table. Explanation : Prints a short description of the columns in a FITS binary table to the terminal screen. Use : FXBHELP, UNIT Inputs : UNIT = Logical unit number of file opened by FXBOPEN. Opt. Inputs : None. Outputs : None. Opt. Outputs: None. Keywords : None. Calls : FXBFIND, FXBFINDLUN, FXPAR Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The file must have been opened with FXBOPEN. Side effects: Certain fields may be truncated in the display. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Feb. 1992, from TBHELP by W. Landsman. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 12 May 1993. Modified to not write to a logical unit number assigned to the terminal. This makes it compatible with IDL for Windows. Version : Version 2, 12 May 1993.
(See /usr/local/idl/lib/zastron/fits_bintable/fxbhelp.pro)
Project : SOHO - CDS Name : FXBHMAKE Purpose : Create basic FITS binary table extension (BINTABLE) header. Explanation : Creates a basic header array with all the required keywords, but with none of the table columns defined. This defines a basic structure which can then be added to or modified by other routines. Use : FXBHMAKE, HEADER, NROWS [, EXTNAME [, COMMENT ]] Inputs : NROWS = Number of rows in the binary table. Opt. Inputs : EXTNAME = If passed, then the EXTNAME record is added with this value. COMMENT = Comment to go along with EXTNAME. Outputs : HEADER = String array containing FITS extension header. Opt. Outputs: None. Keywords : INITIALIZE = If set, then the header is completely initialized, and any previous entries are lost. DATE = If set, then the DATE keyword is added to the header. EXTVER = Extension version number (integer). EXTLEVEL = Extension level number (integer). Calls : GET_DATE, FXADDPAR, FXHCLEAN Common : None. Restrictions: Warning: No checking is done of any of the parameters. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan 1992. William Thompson, Sep 1992, added EXTVER and EXTLEVEL keywords. 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.
(See /usr/local/idl/lib/zastron/fits_bintable/fxbhmake.pro)
Project : SOHO - CDS Name : FXBINTABLE Purpose : Common block FXBINTABLE used by "FXB" routines. Explanation : This is not an IDL routine as such, but contains the definition of the common block FXBINTABLE for inclusion into other routines. By defining the common block in one place, the problem of conflicting definitions is avoided. This file is included into routines that need this common block with the single line (left justified) @fxbintable FXBINTABLE contains the following arrays: LUN = An array of logical unit numbers of currently (or previously) opened binary table files. STATE = Array containing the state of the FITS files associated with the logical unit numbers, where 0=closed, 1=open for read, and 2=open for write. HEAD = FITS binary table headers. MHEADER = Array containing the positions of the first data byte of the header for each file referenced by array LUN. NHEADER = Array containing the positions of the first data byte after the header for each file referenced by array LUN. NAXIS1 = Values of NAXIS1 from the binary table headers. NAXIS2 = Values of NAXIS2 from the binary table headers. TFIELDS = Values of TFIELDS from the binary table headers. HEAP = The start of the first byte of the heap area for variable length arrays. DHEAP = The start of the first byte of the next variable length array, if writing. BYTOFF = Byte offset from the beginning of the row for each column in the binary table headers. TTYPE = Values of TTYPE for each column in the binary table headers. FORMAT = Character code formats of the various columns. IDLTYPE = IDL type code for each column in the binary table headers. N_ELEM = Number of elements for each column in the binary table headers. TSCAL = Scale factors for the individual columns. TZERO = Zero offsets for the individual columns. MAXVAL = For variable length arrays, contains the maximum number of elements for each column in the binary table headers. N_DIMS = Number of dimensions, and array of dimensions for each column of type string in the binary table headers. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Feb 1992. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 July 1993. Added DHEAP variable to fix bug with variable length arrays. Version : Version 2, 21 July 1993.
(See /usr/local/idl/lib/zastron/fits_bintable/fxbintable.pro)
Project : SOHO - CDS Name : FXBISOPEN() Purpose : Returns true if UNIT points to an open FITS binary table. Explanation : This procedure checks to see if the logical unit number given by the variable UNIT corresponds to a FITS binary table opened for read with the command FXBOPEN, and which has not yet been closed with FXBCLOSE. Use : Result = FXBISOPEN(UNIT) If FXBISOPEN(UNIT) THEN ... Inputs : UNIT = Logical unit number returned by FXBOPEN routine. Must be a scalar integer. Opt. Inputs : None. Outputs : The result of the function is either True (1) or False (0), depending on whether UNIT points to an open binary table or not. Opt. Outputs: None. Keywords : None. Calls : FXBFINDLUN Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: None. Side effects: If UNIT is an undefined variable, then False (0) is returned. If UNIT points to a FITS binary table file that is opened for write, then False (0) is returned. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : None. Written : William Thompson, GSFC, 1 July 1993. Modified : Version 1, William Thompson, GSFC, 1 July 1993. Version : Version 1, 1 July 1993.
(See /usr/local/idl/lib/zastron/fits_bintable/fxbisopen.pro)
Project : SOHO - CDS Name : FXBOPEN Purpose : Open binary table extension in a disk FITS file for reading. Explanation : Opens a binary table extension in a disk FITS file for reading. The columns are then read using FXBREAD, and the file is closed when done with FXBCLOSE. Use : FXBOPEN, UNIT, FILENAME, EXTENSION [, HEADER ] Inputs : FILENAME = Name of FITS file to be opened. EXTENSION = Either the number of the FITS extension, starting with the first extension after the primary data unit being one; or a character string containing the value of EXTNAME to search for. Opt. Inputs : None. Outputs : UNIT = Logical unit number of the opened file. Opt. Outputs: HEADER = String array containing the FITS binary table extension header. Keywords : NO_TDIM = If set, then any TDIMn keywords found in the header are ignored. Calls : FXBFINDLUN, FXBPARSE, FXHREAD, FXPAR Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The file must be a valid FITS file. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Feb 1992, based on READFITS by J. Woffard and W. Landsman. W. Thompson, Feb 1992, changed from function to procedure. W. Thompson, June 1992, fixed up error handling. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993.
(See /usr/local/idl/lib/zastron/fits_bintable/fxbopen.pro)
Project : SOHO - CDS Name : FXBPARSE Purpose : Parse the binary table extension header. Explanation : Parses the binary table extension header, and store the information about the format of the binary table in the FXBINTABLE common block--called from FXBCREATE and FXBOPEN. Use : FXBPARSE, ILUN, UNIT, HEADER Inputs : ILUN = Index into the arrays in the FXBINTABLE common block. HEADER = FITS binary table extension header. Opt. Inputs : None. Outputs : None. Opt. Outputs: None. Keywords : NO_TDIM = If set, then any TDIMn keywords found in the header are ignored. Calls : FXBFIND, FXBTDIM, FXBTFORM, FXPAR Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: None. Side effects: Any TDIMn keywords found for bit arrays (format 'X') are ignored, since the dimensions would refer to bits, not bytes. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Feb. 1992. William Thompson, Jan. 1993, modified for renamed FXBTFORM and FXBTDIM. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993.
(See /usr/local/idl/lib/zastron/fits_bintable/fxbparse.pro)
Project : SOHO - CDS Name : FXBREAD Purpose : Read a data array from a disk FITS binary table file. Explanation : Each call to FXBREAD will read the data from one column and one row from the FITS data file, which should already have been opened by FXBOPEN. One needs to call this routine for every column and every row in the binary table. FXBCLOSE will then close the FITS data file. Use : FXBREAD, UNIT, DATA, COL [, ROW ] Inputs : UNIT = Logical unit number corresponding to the file containing the binary table. COL = Column in the binary table to read data from, either as a character string containing a column label (TTYPE), or as a numerical column index starting from column one. Opt. Inputs : ROW = Either row number in the binary table to read data from, starting from row one, or a two element array containing a range of row numbers to read. If not passed, then the entire column is read in. Row must be passed for variable length arrays. Outputs : DATA = IDL data array to be read from the file. Opt. Outputs: None. Keywords : NOSCALE = If set, then the ouput data will not be scaled using the optional TSCAL and TZERO keywords in the FITS header. Default is to scale. VIRTUAL = If set, and COL is passed as a name rather than a number, then if the program can't find a column with that name, it will then look for a keyword with that name in the header. Such a keyword would then act as a "virtual column", with the same value for every row. DIMENSIONS = Vector array containing the dimensions to be used to read in the data. Bypasses any dimensioning information stored in the header. Ignored for bit arrays. If the data type is double-precision complex, then an extra dimension of 2 is prepended to the dimensions passed by the user. NANVALUE= Value signalling data dropout. All points corresponding to IEEE NaN (not-a-number) are converted to this number. Ignored unless DATA is of type float, double-precision or complex. Calls : IEEE_TO_HOST, FXPAR, WHERENAN Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The binary table file must have been opened with FXBOPEN. The data must be consistent with the column definition in the binary table header. The row number must be consistent with the number of rows stored in the binary table header. The number of elements implied by the dimensions keyword must not exceed the number of elements stored in the file. Side effects: If the DIMENSIONS keyword is used, then the number of data points read in may be less than the number of points stored in the table. If there are no elements to read in (the number of elements is zero), then the program sets !ERR to -1, and DATA is unmodified. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Jan 1992. W. Thompson, Feb 1992, modified to support variable length arrays. W. Thompson, Jun 1992, modified way that row ranges are read in. No longer works reiteratively. W. Thompson, Jun 1992, fixed bug where NANVALUE would be modified by TSCAL and TZERO keywords. W. Thompson, Jun 1992, fixed bug when reading character strings. Treats dimensions better when reading multiple rows. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 30 June 1993. Added overwrite keyword to REFORM call to speed up. Version 3, William Thompson, GSFC, 21 July 1993. Fixed bug with variable length arrays. Version 4, William Thompson, GSFC, 29 October 1993. Added error message for not finding column by name. Version : Version 4, 29 October 1993.
(See /usr/local/idl/lib/zastron/fits_bintable/fxbread.pro)
Project : SOHO - CDS Name : FXBSTATE() Purpose : Returns the state of a FITS binary table. Explanation : This procedure returns the state of a FITS binary table that was either opened for read with the command FXBOPEN, or for write with the command FXBCREATE. Use : Result = FXBSTATE(UNIT) Inputs : UNIT = Logical unit number returned by FXBOPEN routine. Must be a scalar integer. Opt. Inputs : None. Outputs : The result of the function is the state of the FITS binary table that UNIT points to. This can be one of three values: 0 = Closed 1 = Open for read 2 = Open for write Opt. Outputs: None. Keywords : None. Calls : FXBFINDLUN Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: None. Side effects: If UNIT is an undefined variable, then 0 (closed) is returned. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : None. Written : William Thompson, GSFC, 1 July 1993. Modified : Version 1, William Thompson, GSFC, 1 July 1993. Version : Version 1, 1 July 1993.
(See /usr/local/idl/lib/zastron/fits_bintable/fxbstate.pro)
Project : SOHO - CDS Name : FXBTDIM() Purpose : Parse TDIM-like kwywords. Explanation : Parses the value of a TDIM-like keyword (e.g. TDIMnnn, TDESC, etc.) to return the separate elements contained within. Use : Result = FXBTDIM( TDIM_KEYWORD ) Inputs : TDIM_KEYWORD = The value of a TDIM-like keyword. Must be a character string of the form "(value1,value2,...)". If the parentheses characters are missing, then the string is simply returned as is, without any further processing. Opt. Inputs : None. Outputs : The result of the function is a character string array containing the values contained within the keyword parameter. If a numerical result is desired, then simply call, e.g. Result = FIX( FXBTDIM( TDIM_KEYWORD )) Opt. Outputs: None. Keywords : None. Calls : GETTOK Common : None. Restrictions: The input parameter must have the proper format. The separate values must not contain the comma character. TDIM_KEYWORD must not be an array. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan. 1992. William Thompson, Jan. 1993, renamed to be compatible with DOS limitations. 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.
(See /usr/local/idl/lib/zastron/fits_bintable/fxbtdim.pro)
Project : SOHO - CDS Name : FXBTFORM Purpose : Returns information about FITS binary table columns. Explanation : Procedure to return information about the format of the various columns in a FITS binary table. Use : FXBTFORM,HEADER,TBCOL,IDLTYPE,FORMAT,NUMVAL,MAXVAL Inputs : HEADER = Fits binary table header. Opt. Inputs : None. Outputs : TBCOL = Array of starting column positions in bytes. IDLTYPE = IDL data types of columns. FORMAT = Character code defining the data types of the columns. NUMVAL = Number of elements of the data arrays in the columns. MAXVAL = Maximum number of elements for columns containing variable length arrays, or zero otherwise. Opt. Outputs: None. Keywords : None. Calls : FXPAR Common : None. Restrictions: None. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Feb. 1992, from TBINFO by D. Lindler. W. Thompson, Jan. 1993, renamed to be compatible with DOS limitations. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993.
(See /usr/local/idl/lib/zastron/fits_bintable/fxbtform.pro)
Project : SOHO - CDS Name : FXBWRITE Purpose : Write a binary data array to a disk FITS binary table file. Explanation : Each call to FXBWRITE will write to the data file, which should already have been created and opened by FXBCREATE. One needs to call this routine for every column and every row in the binary table. FXBFINISH will then close the file. Use : FXBWRITE, UNIT, DATA, COL, ROW Inputs : UNIT = Logical unit number corresponding to the file containing the binary table. DATA = IDL data array to be written to the file. COL = Column in the binary table to place data in, starting from column one. ROW = Row in the binary table to place data in, starting from row one. Opt. Inputs : None. Outputs : None. Opt. Outputs: None. Keywords : BIT = Number of bits in bit mask arrays (type "X"). Only used if the column is of variable size. NANVALUE= Value signalling data dropout. All points corresponding to this value are set to be IEEE NaN (not-a-number). Ignored unless DATA is of type float, double-precision or complex. Calls : HOST_TO_IEEE Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The binary table file must have been opened with FXBCREATE. The data must be consistent with the column definition in the binary table header. The row number must be consistent with the number of rows stored in the binary table header. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Jan 1992, based on WRITEFITS by J. Woffard and W. Landsman. W. Thompson, Feb 1992, modified to support variable length arrays. W. Thompson, Feb 1992, removed all references to temporary files. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 July 1993. Fixed bug with variable length arrays. Version : Version 2, 21 July 1993.
(See /usr/local/idl/lib/zastron/fits_bintable/fxbwrite.pro)
Project : SOHO - CDS Name : FXFINDEND Purpose : Find the end of a FITS file. Explanation : This routine finds the end of the last logical record in a FITS file, which may be different from that of the physical end of the file. Each FITS header is read in and parsed, and the file pointer is moved to where the next FITS extension header would be if there is one, or to the end of the file if not. Use : FXFINDEND, UNIT Inputs : UNIT = Logical unit number for the opened file. Opt. Inputs : None. Outputs : None. Opt. Outputs: None. Keywords : None. Calls : FXHREAD, FXPAR Common : None. Restrictions: The file must have been opened for block I/O. There must not be any FITS "special records" at the end of the file. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Feb. 1992. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993.
(See /usr/local/idl/lib/zastron/fits_bintable/fxfindend.pro)
Project : SOHO - CDS Name : FXHCLEAN Purpose : Removes required keywords from FITS header. Explanation : Removes any keywords relevant to array structure from a FITS header, preparatory to recreating it with the proper values. Use : FXHCLEAN, HEADER Inputs : HEADER = FITS header to be cleaned. Opt. Inputs : None. Outputs : HEADER = The cleaned FITS header is returned in place of the input array. Opt. Outputs: None. Keywords : None. Calls : SXDELPAR, FXPAR Common : None. Restrictions: HEADER must be a string array containing a properly formatted FITS header. Side effects: Warning: when cleaning a binary table extension header, not all of the keywords pertaining to columns in the table may be removed. 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.
(See /usr/local/idl/lib/zastron/fits_bintable/fxhclean.pro)
Project : SOHO - CDS Name : FXHMAKE Purpose : Create a basic FITS header array. Explanation : Creates a basic header array with all the required keywords. This defines a basic structure which can then be added to or modified by other routines. Use : FXHMAKE, HEADER [, DATA ] Inputs : None required. Opt. Inputs : DATA = IDL data array to be written to file in the primary data unit (not in an extension). This is used to determine the values of the BITPIX and NAXIS, etc. keywords. If not passed, then BITPIX is set to eight, NAXIS is set to zero, and no NAXISnnn keywords are included in this preliminary header. Outputs : HEADER = String array containing FITS header. Opt. Outputs: None. Keywords : INITIALIZE = If set, then the header is completely initialized, and any previous entries are lost. EXTEND = If set, then the keyword EXTEND is inserted into the file, with the value of "T" (true). DATE = If set, then the DATE keyword is added to the header. Calls : GET_DATE, FXADDPAR, FXHCLEAN Common : None. Restrictions: Groups are not currently supported. Side effects: BITPIX, NAXIS, etc. are defined such that complex arrays are stored as floating point, with an extra first dimension of two elements (real and imaginary parts). Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan 1992, from FXHMAKE by D. Lindler and M. Greason. Differences include: * Use of FITS standard (negative BITPIX) to signal floating point numbers instead of (SDAS/Geis) DATATYPE keyword. * Storage of complex numbers as pairs of real numbers. * Support for EXTEND keyword, and for cases where there is no primary data array. * Insertion of DATE record made optional. Only required FITS keywords are inserted automatically. 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.
(See /usr/local/idl/lib/zastron/fits_bintable/fxhmake.pro)
Project : SOHO - CDS
Name :
FXHREAD
Purpose :
Reads a FITS header from an opened disk file.
Explanation :
Reads a FITS header from an opened disk file.
Use :
FXHREAD, UNIT, HEADER [, STATUS ]
Inputs :
UNIT = Logical unit number.
Opt. Inputs :
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 !ERR if an error occurs, or if the
first byte of the header is zero (ASCII null).
Keywords :
None.
Calls :
None.
Common :
None.
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.
Category :
Data Handling, I/O, FITS, Generic.
Prev. Hist. :
W. Thompson, Feb 1992, from READFITS by J. Woffard and W. Landsman.
W. Thompson, Aug 1992, added test for SIMPLE keyword.
Written :
William Thompson, GSFC, February 1992.
Modified :
Version 1, William Thompson, GSFC, 12 April 1993.
Incorporated into CDS library.
Version :
Version 1, 12 April 1993.
(See /usr/local/idl/lib/zastron/fits_bintable/fxhread.pro)
Project : SOHO - CDS
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.
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
Use :
Result = FXPAR( HDR, NAME [, ABORT ] )
Result = FXPAR(HEADER,'DATE') ;Finds the value of DATE
Result = FXPAR(HEADER,'NAXIS*') ;Returns array dimensions as
;vector
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.
Opt. Inputs :
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.
Outputs :
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.
Opt. Outputs:
None.
Keywords :
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.
Calls :
GETTOK, STRNUMBER
Common :
None.
Restrictions:
None.
Side effects:
Keyword COUNT returns the number of parameters found.
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.
Category :
Data Handling, I/O, FITS, Generic.
Prev. Hist. :
DMS, May, 1983, 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, Oct. 1992, rewrote to change strategy for extracting
values to allow for non-standard formats and renamed to FXPAR.
Added COMMENT keyword.
Written :
David M. Stern, RSI, May 1983.
Modified :
Version 1, William Thompson, GSFC, 12 April 1993.
Incorporated into CDS library.
Version :
Version 1, 12 April 1993.
(See /usr/local/idl/lib/zastron/fits_bintable/fxpar.pro)
Project : SOHO - CDS 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.
(See /usr/local/idl/lib/zastron/fits_bintable/fxparpos.pro)
Project : SOHO - CDS Name : FXREAD Purpose : Read basic FITS files. Explanation : Read the primary array from a disk FITS file. Optionally allows the user to read in only a subarray and/or every Nth pixel. Use : FXREAD, FILENAME, DATA [, HEADER [, I1, I2 [, J1, J2 ]] [, STEP ]] Inputs : FILENAME = String containing the name of the file to be read. Opt. Inputs : I1,I2 = Data range to read in the first dimension. If passed, then HEADER must also be passed. If not passed, or set to 0,0 then the entire range is read. J1,J2 = Data range to read in the second dimension. If passed, then HEADER and I1,J2 must also be passed. If not passed, or set to 0,0 then the entire range is read. STEP = Step size to use in reading the data. If passed, then HEADER must also be passed. Default value is 1. Ignored if less than 1. Outputs : DATA = Data array to be read from the file. Opt. Outputs: HEADER = String array containing the header for the FITS file. Keywords : NANVALUE = Value signalling data dropout. All points corresponding to IEEE NaN (not-a-number) are set to this value. Ignored unless DATA is of type float or double-precision. PROMPT = If set, then the optional parameters are prompted for at the keyboard. AVERAGE = If set, then the array size is reduced by averaging pixels together rather than by subselecting pixels. Ignored unless STEP is nontrivial. Note: this is much slower. YSTEP = If passed, then STEP is the step size in the 1st dimension, and YSTEP is the step size in the 2nd dimension. Otherwise, STEP applies to both directions. NOSCALE = If set, then the output data will not be scaled using the optional BSCALE and BZERO keywords in the FITS header. Default is to scale, if and only if BSCALE and BZERO are present and nontrivial. NOUPDATE = If set, then the optional BSCALE and BZERO keywords in the optional HEADER array will not be changed. The default is to reset these keywords to BSCALE=1, BZERO=0. Ignored if NOSCALE is set. Calls : GET_DATE, IEEE_TO_HOST, FXADDPAR, FXHREAD, FXPAR, WHERENAN Common : None. Restrictions: Groups are not supported. The optional parameters I1, I2, and STEP only work with one or two-dimensional arrays. J1 and J2 only work with two-dimensional arrays. Use of the AVERAGE keyword is not compatible with arrays with missing pixels. Side effects: If the keywords BSCALE and BZERO are present in the FITS header, and have non-trivial values, then the returned array DATA is formed by the equation DATA = BSCALE*original + BZERO However, this behavior can overridden by using the /NOSCALE keyword. If the data is scaled, then the optional HEADER array is changed so that BSCALE=1 and BZERO=0. This is so that these scaling parameters are not applied to the data a second time by another routine. Also, history records are added storing the original values of these constants. Note that only the returned array is modified--the header in the FITS file itself is untouched. If the /NOUPDATE keyword is set, however, then the BSCALE and BZERO keywords are not changed. It is then the user's responsibility to ensure that these parameters are not reapplied to the data. In particular, these keywords should not be present in any header when writing another FITS file, unless the user wants their values to be applied when the file is read back in. Otherwise, FITS readers will read in the wrong values for the data array. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, May 1992, based in part on READFITS by W. Landsman, and STSUB by M. Greason and K. Venkatakrishna. W. Thompson, Jun 1992, added code to interpret BSCALE and BZERO records, and added NOSCALE and NOUPDATE keywords. W. Thompson, Aug 1992, changed to call FXHREAD, and to add history records for BZERO, BSCALE. Written : William Thompson, GSFC, May 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 17 November 1993. Corrected bug with AVERAGE keyword on non-IEEE compatible machines. Corrected bug with subsampling on VAX machines. Version : Version 2, 17 November 1993.
(See /usr/local/idl/lib/zastron/fits_bintable/fxread.pro)
Project : SOHO - CDS Name : FXWRITE Purpose : Write a disk FITS file. Explanation : Creates a disk FITS file and writes a FITS primary header, and optionally a primary data array. Use : FXWRITE, FILENAME, HEADER [, DATA ] Inputs : FILENAME = String containing the name of the file to be written. HEADER = String array containing the header for the FITS file. Opt. Inputs : DATA = IDL data array to be written to the file. If not passed, then it is assumed that extensions will be added to the file. Outputs : None. Opt. Outputs: None. Keywords : NANVALUE = Value signalling data dropout. All points corresponding to this value are set to be IEEE NaN (not-a-number). Ignored unless DATA is of type float, double-precision or complex. NOUPDATE = If set, then the optional BSCALE and BZERO keywords in the HEADER array will not be changed. The default is to reset these keywords to BSCALE=1, BZERO=0. Calls : CHECK_FITS, GET_DATE, HOST_TO_IEEE, FXADDPAR, FXPAR Common : None. Restrictions: If DATA is passed, then HEADER must be consistent with it. If no data array is being written to the file, then HEADER must also be consistent with that. The routine FXHMAKE can be used to create a FITS header. If found, then the optional keywords BSCALE and BZERO in the HEADER array is changed so that BSCALE=1 and BZERO=0. This is so that these scaling parameters are not applied to the data a second time by another routine. Also, history records are added storing the original values of these constants. If the /NOUPDATE keyword is set, however, then the BSCALE and BZERO keywords are not changed. The user should then be aware that FITS readers will apply these numbers to the data, even if the data is already converted to floating point form. Groups are not supported. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Jan 1992, from WRITEFITS by J. Woffard and W. Landsman. Differences include: * Made DATA array optional, and HEADER array mandatory. * Changed order of HEADER and DATA parameters. * No attempt made to fix HEADER array. W. Thompson, May 1992, changed open statement to force 2880 byte fixed length records (VMS). The software here does not depend on this file configuration, but other FITS readers might. W. Thompson, Aug 1992, added code to reset BSCALE and BZERO records, and added the NOUPDATE keyword. 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.
(See /usr/local/idl/lib/zastron/fits_bintable/fxwrite.pro)