ISOPHOT Interactive Analysis (PIA): Astrolib

FITS_3DTABLE


List of Routines


Routine Descriptions

TBDELCOL

[Next Routine] [List of Routines]
 NAME:
	TBDELCOL
 PURPOSE:
	Delete a column of data from a FITS 3_D binary table

 CALLING SEQUENCE:
	tbdelcol, h, tab, name

 INPUTS-OUPUTS
	h,tab - FITS table header and data array.  H and TAB will
		be updated with the specified column deleted

 INPUTS:
	name - Either (1) a string giving the name of the column to delete
			or (2) a scalar giving the column number to delete

 EXAMPLE:
	Delete the column "FLUX" from FITS 3D table

	IDL> TBDELCOL, H, TAB, 'FLUX'

 REVISION HISTORY:                                           
	Written   W. Landsman        STX Co.     August, 1988
	Adapted for IDL Version 2, J. Isensee, July, 1990

(See /usr/local/idl/lib/zastron/fits_3dtable/tbdelcol.pro)


TBDELROW

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	TBDELROW
 PURPOSE:
	Delete a row of data from a FITS table

 CALLING SEQUENCE:
	tbdelrow, h, tab, rows

 INPUTS-OUPUTS
	h,tab - FITS table header and data array.  H and TAB will
		be updated on output with the specified row(s) deleted.

	rows  -  scalar or vector, specifying the row numbers to delete
		First row has index 0.   If a vector it will be sorted and
		duplicates removed by TBDELROW

 EXAMPLE:
	Compress a table to include only non-negative flux values

	flux = TBGET(h,tab,'FLUX')       ;Obtain original flux vector
	bad = where(flux lt 0)           ;Find negative fluxes
	TBDELROW,h,tab,bad               ;Delete rows with negative fluxes

 PROCEDURE:
	Specified rows are deleted from the data array, TAB.  The NAXIS2
	keyword in the header is updated.

 REVISION HISTORY:                                           
	Written   W. Landsman        STX Co.     August, 1988
	Checked for IDL Version 2, J. Isensee, July, 1990

(See /usr/local/idl/lib/zastron/fits_3dtable/tbdelrow.pro)


TBDIR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	TBDIR
 PURPOSE:
	Provide a brief description of the disk FITS tables on a directory
	The # of columns and rows, and the name of the first five columns
	are displayed for each table.

 CALLING SEQUENCE:
	tbdir, directory, [ TEXTOUT = ] 

 INPUT PARAMETERS:
	DIRECTORY - String giving the disk or directory to be searched.
		Wildcard directory values are allowed.
		If not given TBDIR searches the default directory.
	In VMS:   Examples of valid strings include 'LINEAR:',
			'UIT$USER2:', 'S*', or '[...]'.  
	In Unix:  Valid strings must include trailing slash for
		a directory specification. EX: '/tables'

 OUTPUT PARAMETERS:
	None.

 OPTIONAL KEYWORD INPUT:
	TEXTOUT - Directs output display (see TEXTOPEN for more info)

		textout=1	TERMINAL using /more option
		textout=2	TERMINAL without /more option
		textout=3	.prt
		textout=4	laser.tmp
		textout=5      user must open file
		textout = filename (default extension of .prt)

 RESTRICTIONS:
	Only files with header extensions *.HHH and with XTENSION keyword
	of BINTABLE or A3DTABLE are searched.

	Certain fields on the output display may be trunctated if they are too
	long.

 METHOD:
	FINDFILE is used to find all *.hhh files on directory.  Each
	header is checked for an XTENSION keyword equal to BINTABLE or A3DTABLE
	The values of the FITS parameters  NAXIS1, NAXIS2, TFIELDS and 
	EXTNAME are printed

 SYSTEM VARIABLES:
	!TEXTOUT is used as a default if the TEXTOUT keyword is not supplied

 PROCEDURES USED:
	SXHREAD, TEXTOPEN,TEXTCLOSE
	Also uses non-standard system variables !TEXTUNIT and !TEXTOUT

 MODIFICATION HISTORY:
	Written, W. Landsman, ST Systems Corporation     February 1988
	Rewritten for Unix compatibility, use EXTNAME keyword  
	W. Landsman                      August 1991

(See /usr/local/idl/lib/zastron/fits_3dtable/tbdir.pro)


TBGET

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	TBGET 
 PURPOSE:
	Function to return value(s) from specified column in a binary
	FITS table

 CALLING SEQUENCE
	values = tbget( h, tab, field, [ rows, nulls ] )

 INPUTS:
	h - Binary FITS header returned by TBREAD
	tab - Binary FITS table array returned by TBREAD
	field - field name or number

 OPTIONAL INPUTS:
	rows -  scalar or vector giving row number(s)
		Row numbers start at 0.  If not supplied or set to
		-1 then values for all rows are returned

 OUTPUTS:
	the values for the row are returned as the function value.
	Null values are set to 0 or blanks for strings.

 OPTIONAL OUTPUT:
	nulls - null value flag of same length as the returned data.
		It is set to 1 at null value positions and 0 elsewhere.
		If supplied then the optional input, rows, must also
		be supplied.

 HISTORY:
       Written  W. Landsman        February, 1991
       Work for string and complex   W. Landsman         April, 1993

(See /usr/local/idl/lib/zastron/fits_3dtable/tbget.pro)


TBHELP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	TBHELP
 PURPOSE:
	Routine to print a description of a disk 3D binary FITS table

 CALLING SEQUENCE:
	tbhelp, h

 INPUTS:
	h - FITS header for a binary table, string array

 METHOD:
	FITS 3D Table keywords NAXIS*,EXTNAME,TFIELDS,TTYPE*,TFORM*,TUNIT*,
	are read from the header and displayed at the terminal

	A FITS header is recognized as bein for a binary table if the keyword 
	XTENSION has the value 'BINTABLE' or 'A3DTABLE'

 NOTES:
	Certain fields may be truncated in the display

 HISTORY:
	W. Landsman       February, 1991
	Parsing of a FITS binary header made more robust    May, 1992

(See /usr/local/idl/lib/zastron/fits_3dtable/tbhelp.pro)


TBINFO

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	TBINFO
 PURPOSE:
	Procedure to return information on the specified field 
	in a FITS binary table.

 CALLING SEQUENCE:
	tbinfo, h, tbcol, width, idltype, numval, tunit, tnull, tform, 
		ttype, maxval
 INPUTS:
	h - FITS table header

 OUTPUTS:
	tbcol - starting column position in bytes, integer vector
	width - width of the field in bytes, integer vector
	idltype - idltype of field, byte vector
		7 - string, 4- real*4, 3-integer*4, 5-real*8
	tunit - string unit numbers, string vector
	tnull - null value for the field, string vector
	tform - format for the field, string vector
	ttype - field name, string vector
	maxval- maximum number of elements in a variable length array, long
		vector

 SIDE EFFECTS:
	If there are difficulties interpreting the table then !ERR is set 
	to -1
 HISTORY:
	D. Lindler  July, 1987
	W. Thompson, Feb. 1992, added support for 'B', 'C', and 'M' formats.
	W. Landsman handle formats without repeat counts.    Sep. 1993

(See /usr/local/idl/lib/zastron/fits_3dtable/tbinfo.pro)


TBPRINT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	TBPRINT
  PURPOSE:
	Procedure to print specified columns and rows of a FITS table

 CALLING SEQUENCE:
	tbprint, h, tab, columns, [ rows, TEXTOUT = ]

 INPUTS:
	h - Fits header for table, string array
	tab - table array 
	columns - string giving column names, or vector giving
		column numbers (beginning with 1).  If string 
		supplied then column names should be separated by comma's.
	rows - (optional) vector of row numbers to print.  If
		not supplied or set to scalar, -1, then all rows
		are printed.

 OUTPUTS:
	None
 KEYWORDS:
       TEXTOUT controls the output device; see the procedure TEXTOPEN

 SYSTEM VARIABLES:
	Uses nonstandard system variables !TEXTOUT and !TEXTOPEN
	Set !TEXTOUT = 3 to direct output to a disk file.   The system
	variable is overriden by the value of the keyword TEXTOUT

 EXAMPLES:
       tbprint,h,tab,'STAR ID,RA,DEC'    ;print id,ra,dec for all stars
       tbprint,h,tab,[2,3,4],indgen(100) ;print columns 2-4 for 
                                          first 100 stars
       tbprint,h,tab,text="STARS.DAT"    ;Convert entire FITS table to
                                         ;an ASCII file named STARS.DAT

 PROCEDURES USED:
	TEXTOPEN,TEXTCLOSE,TBSIZE,TBINFO

 RESTRICTIONS: 
	(1) Program does not check whether output length exceeds output
		device capacity (e.g. 80 or 132).
	(2) Column heading may be truncated to fit in space defined by
		the FORMAT specified for the column
	(3) Program does not check for null values

 HISTORY:
	version 1  D. Lindler Feb. 1987

(See /usr/local/idl/lib/zastron/fits_3dtable/tbprint.pro)


TBREAD

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	TBREAD
 PURPOSE:
	Procedure to read an internal FITS binary table file

 CALLING SEQUENCE:
	tbread, fname, h, tab, [ unit ]

 INPUTS:
	fname - name of table header file (if qualifier not supplied
		then .HHH is assummed)

 OUTPUTS:
	h - FITS header, string array
	tab - table array (2-D byte array)

 OPTIONAL INPUTS:
	unit - unit number (1 to 9) to use for I/O (default=1)

 PROCEDURES CALLED:
	ZPARCHECK, SXREAD

 HISTORY:
	Written W. Landsman   February, 1991

(See /usr/local/idl/lib/zastron/fits_3dtable/tbread.pro)


TBSIZE

[Previous Routine] [List of Routines]
 NAME:
	TBSIZE

 PURPOSE:
	Procedure to return the size of a fits table.

 CALLING SEQUENCE:
	tbsize, h, tab, ncols, nrows, tfields, ncols_all, nrows_all

 INPUTS:
	h - FITS table header
	tab - fits table array

 OUTPUTS:
	ncols - number of characters per row in table
	nrows - number of rows in table
	tfields - number of fields per row
	ncols_all - number of characters/row allocated (size of tab)
	nrows_all - number of rows allocated

 HISTORY
	D. Lindler  July, 1987

(See /usr/local/idl/lib/zastron/fits_3dtable/tbsize.pro)