[Previous Routine] [Next Routine] [List of Routines]NAME: DBMATCH PURPOSE: Find the entry number in a database for each element of item values EXPLANATION: DBMATCH() is especially useful for finding a one-to-one correspondence between entries in different databases, and thus to create the vector needed for database pointers. CALLING SEQUENCE: list = DBMATCH( item, values, [ listin, /FULLSTRING ] ) INPUTS: ITEM - Item name or number, scalar VALUES - scalar or vector containing item values to search for. OPTIONAL INPUTS: LISTIN - list of entries to be searched. If not supplied, or set to -1, then all entries are searched OUTPUT: LIST - vector of entry numbers with the same number of elements as VALUES. Contains a value of 0 wherever the corresponding item value was not found. OPTIONAL INPUT: FULLSTRING - By default, one has a match if a search string is included in any part of a database value (substring match). But if /FULLSTRING is set, then all characters in the database value must match the search string (excluding leading and trailing blanks). Both types of string searches are case insensitive. NOTES: DBMATCH is meant to be used for items which do not have duplicate values in a database (e.g. catalog numbers). If more than one entry is found for a particular item value, then only the first one is stored in LIST. When linked databases are opened together, DBMATCH can only be used to search on items in the primary database. EXAMPLE: Make a vector which points from entries in the Yale Bright Star catalog to those in the SAO catalog, using the HD number IDL> dbopen, 'yale_bs' ;Open the Yale Bright star catalog IDL> dbext, -1, 'HD', hd ;Get the HD numbers IDL> dbopen, 'sao' ;Open the SAO catalog IDL> list = dbmatch( 'HD', HD) ;Get entries in SAO catalog ;corresponding to each HD number. REVISION HISTORY: Written, W. Landsman STX February, 1990 Fixed error when list in parameter used May, 1992 Faster algorithm with sorted item when listin parameter supplied Added keyword FULLSTRING,check for empty database, William Thompson, GSFC, 15 March 1995 Work for more than 32767 values, added CATCH W. Landsman July 1997 Converted to IDL V5.0 W. Landsman 25-Nov-1997(See dbmatch.pro)
DBOPEN
[Previous Routine] [Next Routine] [List of Routines]NAME: DBOPEN PURPOSE: Routine to open an IDL database CALLING SEQUENCE: dbopen, name, update INPUTS: name - (Optional) name or names of the data base files to open. It has one of the following forms: 'name' -open single data base file 'name1,name2,...,nameN' - open N files which are connected via pointers. 'name,*' -Open the data base with all data bases connected via pointers '' -Interactively allow selection of the data base files. If not supplied then '' is assumed. name may optionally be a string array with one name per element. update - (Optional) Integer flag specifing openning for update. 0 - Open for read only 1 - Open for update 2 - Open index file for update only !PRIV must be 2 or greater to open a file for update. If a file is opened for update only a single data base can be specified. OUTPUTS: none KEYWORDS: UNAVAIL - If present, a "database doesn't exit" flag is returned through it. 0 = the database exists and was opened (if no other errors arose). 1 = the database doesn't exist. Also if present, the error message for non-existent databases is suppressed. The action, however, remains the same. If specifiying this, be sure that the variable passed exists before the call to DBOPEN. SIDE EFFECTS: The .DBF and .dbx files are opened using unit numbers obtained by GET_LUN. Descriptions of the files are placed in the common block DB_COM. HISTORY: Version 2, D. Lindler, Nov. 1987 For IDL Version 2 W. Landsman May 1990 -- Will require further modfication once SCREEN_SELECT is working Modified to work under Unix, D. Neill, ACC, Feb 1991. UNAVAIL keyword added. M. Greason, Hughes STX, Feb 1993. William Thompson, GSFC/CDS (ARC), 1 June 1994 Added support for external (IEEE) representation. William Thompson, GSFC, 3 November 1994 Modified to allow ZDBASE to be a path string. 8/29/95 JKF/ACC - forces lowercase for input database names. W. Landsman, Use CATCH to catch errors July, 1997 Converted to IDL V5.0 W. Landsman September 1997(See dbopen.pro)
DBPRINT
[Previous Routine] [Next Routine] [List of Routines]NAME: DBPRINT PURPOSE: Procedure to print specified items from a list of database entries CALLING SEQUENCE: dbprint, list, [items, FORMS= , TEXTOUT= , /NoHeader] INPUTS: list - list of entry numbers to be printed, vector or scalar if list = -1, then all entries will be printed. An error message is returned if any entry number is larger than the number of entries in the database OPTIONAL INPUT-OUTPUT: items - items to be printed, specified in any of the following ways: form 1 scalar string giving item(s) as list of names separated by commas form 2 string array giving list of item names form 3 string of form '$filename' giving name of text file containing items (one item per line) form 4 integer scalar giving single item number or integer vector list of item numbers form 5 Null string specifying interactive selection. This is the default if 'items' is not supplied form 6 '*' select all items, printout will be in table format. If items was undefined or a null string on input, then on output it will contain the items interactively selected. OPTIONAL INPUT KEYWORDS: FORMS - The number of printed lines per page. If forms is not present, output assumed to be in PORTRAIT form, and a heading and 47 lines are printed on each page, with a page eject between each page. For LANDSCAPE form with headings on each page, and a page eject between pages, set forms = 34. For a heading only on the first page, and no page eject, set forms = 0. This is the default for output to the terminal. TEXTOUT - Integer (0-7) used to determine output device (see TEXTOPEN for more info). If not present, the !TEXTOUT system variable is used. 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 dbprint.prt (file) textout=4 laser.tmp textout=5 user must open file textout=7 same as 3 but text is appended to.prt textout = filename (default extension of .prt) NOHEADER - If this keyword is set, then the column headers will not be printed SYSTEM VARIABLES: Output device controlled by non-standard system varaible !TEXTOUT, if TEXTOUT keyword is not used. NOTES: Users may want to adjust the default lines_per_page value given at the beginning of the program for their own particular printer. HISTORY: version 2 D. Lindler Nov. 1987 (new db format) Test if user pressed 'Q' in response to /MORE W. Landsman Sep 1991 Apply STRTRIM to free form (table) output W. Landsman Dec 1992 Test for string value of TEXTOUT W. Landsman Feb 1994 William Thompson, GSFC, 3 November 1994 Modified to allow ZDBASE to be a path string. W. Landsman, GSFC, July, 1997, Use CATCH to catch errors Converted to IDL V5.0 W. Landsman September 1997 (See dbprint.pro)
DBPUT
[Previous Routine] [Next Routine] [List of Routines]NAME: DBPUT PURPOSE: Procedure to place a new value for a specified item into a data base file entry. CALLING SEQUENCE: dbput, item, val, entry INPUTS: item - item name or number val - item value(s) INPUT/OUTPUT: entry - entry (byte array) or scalar entry number. if entry is a scalar entry number then the data base file will be updated. Otherwise the change will be only made to the entry array which must be written latter using DBWRT. OPERATIONAL NOTES: If entry is a scalar entry number or the input file name is supplied, the entry in the data base will be updated instead of a supplied entry variable. In this case, !priv must be greater than 1. HISTORY: version 2 D. Lindler Feb 1988 (new db formats) modified to convert blanks into zeros correctly D. Neill Jan 1991 Converted to IDL V5.0 W. Landsman September 1997(See dbput.pro)
DBRD
[Previous Routine] [Next Routine] [List of Routines]NAME: DBRD PURPOSE: procedure to read an entry from a data base file or from linked multiple databases. CALLING SEQUENCE: dbrd, enum, entry, [available, dbno, /NoConvert] INPUTS: enum - entry number to read, integer scalar OUTPUT: entry - byte array containing the entry OPTIONAL OUTPUT: available - byte array with length equal to number of data bases opened. available(i) eq 1 if an entry (pointed to) is available. It always equals 1 for the first data base, otherwise it is an error condition. OPTIONAL INPUT: dbno - specification of the data base number to return. If supplied, only the record for the requested data base number is returned in entry. Normally this input should not be supplied. dbno is numbered for 0 to n-1 and gives the number of the data base opened. The data bases are numbered in the order supplied to dbopen. If dbno is supplied then the entry number refers to that data base and not the primary or first data base. If set to -1, then it means all data bases opened (same as not supplying it) OPTIONAL INPUT KEYWORD: noconvert - if set then don't convert external to host format. Assumes that calling program will take care of this requirement. OPERATIONAL NOTES: If multiple data base files are opened, the records are concatenated with each other HISTORY version 2 D. Lindler Nov. 1987 William Thompson, GSFC/CDS (ARC), 1 June 1994 Added support for external (IEEE) representation. Version 3, Richard Schwartz, GSFC/SDAC, 23-Aug-1996 Add noconvert keyword Converted to IDL V5.0 W. Landsman September 1997(See dbrd.pro)
DBSEARCH
[Previous Routine] [Next Routine] [List of Routines]NAME: DBSEARCH PURPOSE: Subroutine of DBFIND() to search a vector for specified values CALLING SEQUENCE: dbsearch, type, svals, values, good, FULLSTRING = fullstring INPUT: type - type of search (output from dbfparse) svals - search values (output from dbfparse) values - array of values to search OUTPUT: good - indices of good values !err is set to number of good values OPTIONAL INPUT KEYWORD: FULLSTRING - By default, one has a match if a search string is included in any part of a database value (substring match). But if /FULLSTRING is set, then all characters in the database value must match the search string (excluding leading and trailing blanks). Both types of string searches are case insensitive. REVISION HISTORY: D. Lindler July,1987 Converted to IDL V5.0 W. Landsman September 1997(See dbsearch.pro)
DBSORT
[Previous Routine] [Next Routine] [List of Routines]NAME: DBSORT PURPOSE: Routine to sort list of entries in data base CALLING SEQUENCE: result = dbsort( list, items , [ REVERSE = ]) INPUTS: list - list of entry numbers to sort -1 to sort all entries items - list of items to sort (up to 9 items) OUTPUT: result - numeric vector giving input list sorted by items OPTIONAL KEYWORD INPUT: REVERSE - scalar or vector with the same number of elements as the the number of items to sort. If the corresponding element of REVERSE is non-zero then that item is sorted in descending rather than ascending order. EXAMPLE: Sort an astronomical catalog with RA as primary sort, and declination as secondary sort (used when RA values are equal) IDL> NEWLIST = DBSORT( -1, 'RA,DEC' ) If for some reason, one wanted the DEC sorted in descending order, but the RA in ascending order IDL> NEWLIST = DBSORT( -1, 'RA,DEC', REV = [ 0, 1 ] ) METHOD: The list is sorted such that each item is sorted into asscending order starting with the last item. COMMON BLOCKS: DBCOM PROCEDURES USED: ZPARCHECK, BSORT, DB_ITEM HISTORY VERSION 1 D. Lindler Oct. 86 Added REVERSE keyword W. Landsman August, 1991 Converted to IDL V5.0 W. Landsman September 1997(See dbsort.pro)
DBTITLE
[Previous Routine] [Next Routine] [List of Routines]NAME: DBTITLE PURPOSE: function to create title line for routine dbprint CALLING SEQUENCE: result = dbtitle( c, f ) INPUTS: c = string array of titles for each item f = field length of each item OUTPUT: header string returned as function value OPERATIONAL NOTES: this is a subroutine of DBPRINT. HISTORY: version 1 D. Lindler Sept 86 Converted to IDL V5.0 W. Landsman September 1997(See dbtitle.pro)
DBUPDATE
[Previous Routine] [Next Routine] [List of Routines]NAME: DBUPDATE PURPOSE: Update columns of data in a database -- inverse of DBEXT EXPLANATION: Database must be open for update before calling DBUPDATE CALLING SEQUENCE: dbupdate, list, items, v1, [ v2, v3, v4......v14 ] INPUTS: list - entries in database to be updated, scalar or vector If list=-1 then all entries will be updated items -standard list of items that will be updated. v1,v2....v14 - vectors containing values for specified items. The number of vectors supplied must equal the number of items specified. The number of elements in each vector should be the same. EXAMPLES: A database STAR contains RA and DEC in radians, convert to degrees IDL> !PRIV=2 & dbopen,'STAR',1 ;Open database for update IDL> dbext,-1,'RA,DEC',ra,dec ;Extract RA and DEC, all entries IDL> ra = ra*!RADEG & dec=dec*!RADEG ;Convert to degrees IDL> dbupdate,-1,'RA,DEC',ra,dec ;Update database with new values NOTES: It is quicker to update several items simultaneously rather than use repeated calls to DBUPDATE. It is possible to update multiple valued items. In this case, the input vector should be of dimension (NVAL,NLIST) where NVAL is the number of values per item, and NLIST is the number of entries to be updated. This vector will be temporarily transposed by DBUPDATE but will be restored before DBUPDATE exits. REVISION HISTORY Written W. Landsman STX March, 1989 Work for multiple valued items May, 1991 String arrays no longer need to be fixed length December 1992 Transpose multiple array items back on output December 1993 Faster update of external databases on big endian machines November 1997 Converted to IDL V5.0 W. Landsman 24-Nov-1997(See dbupdate.pro)
DBVAL
[Previous Routine] [Next Routine] [List of Routines]NAME: DBVAL PURPOSE: procedure to extract value(s) of the specified item from a data base file entry. CALLING SEQUENCE: result = dbval( entry, item ) INPUTS: entry - byte array containing the entry, or a scalar entry number item - name (string) or number (integer) of the item OUTPUT: the value(s) will be returned as the function value EXAMPLE: Extract a flux vector from entry 28 of the database FARUV ==> flux = dbval(28,'FLUX') HISTORY: version 2 D. Lindler Nov, 1987 (new db format) Converted to IDL V5.0 W. Landsman September 1997(See dbval.pro)
DBWRT
[Previous Routine] [Next Routine] [List of Routines]NAME: DBWRT PURPOSE: procedure to update or add a new entry to a data base CALLING SEQUENCE: dbwrt, entry, [ index, append, /NoConvert ] INPUTS: entry - entry record to be updated or added if first item (entry number=0) OPTIONAL INPUTS: index - optional integer flag, if set to non zero then index file is updated. (default=0, do not update index file) (Updating the index file is time-consuming, and should normally be done after all changes have been made. append - optional integer flag, if set to non-zero the record is appended as a new entry, regardless of what the entry number in the record is. The entry number will be reset to the next entry number in the file. OUTPUTS: data base file is updated. If index is non-zero then the index file is updated. OPTIONAL INPUT KEYWORD: NoConvert - If set then don't convert to host format with an external database. Useful when the calling program decides that conversion isn't needed (i.e. on a big-endian machine), or takes care of the conversion itself. OPERATIONAL NOTES: !PRIV must be greater than 1 to execute HISTORY: version 2 D. Lindler Feb. 1988 (new db format) converted to IDL Version 2. M. Greason, STX, June 1990. William Thompson, GSFC/CDS (ARC), 28 May 1994 Added support for external (IEEE) representation. Converted to IDL V5.0 W. Landsman 24-Nov-1997(See dbwrt.pro)
DBXPUT
[Previous Routine] [Next Routine] [List of Routines]NAME: DBXPUT PURPOSE: routine to replace value of an item in a data base entry CALLING SEQUENCE: dbxput, val, entry, idltype, sbyte, nbytes INPUT: val - value(s) to be placed into entry, string values might be truncated to fit number of allowed bytes in item entry - entry or entries to be updated idltype - idl data type for item (1-7) sbyte - starting byte in record nbytes - total number of bytes in value added OUTPUT: entry - (updated) OPERATIONAL NOTES: This routine assumes that the calling procedure or user knows what he or she is doing. String items are truncated or padded to the fixed size specified by the database but otherwise no validity checks are made. HISTORY: version 1, D. Lindler Aug, 1986 converted to IDL Version 2. M. Greason, STX, June 1990. Work with multiple element string items W. Landsman August 1995 Really work with multiple element string items R. Bergman/W. Landsman July 1996 Work with multiple entries, R. Schwartz, GSFC/SDAC August 1996 Use /overwrite with REFORM() W. Landsman May 1997 Converted to IDL V5.0 W. Landsman September 1997(See dbxput.pro)
DBXVAL
[Previous Routine] [Next Routine] [List of Routines]NAME: DBXVAL PURPOSE: Quickly return a value of the specified item number EXPLANATION: Procedure to quickly return a value of the specified item number from the entry. CALLING SEQUENCE: result = dbxval( entry, idltype, nvalues, sbyte, nbytes ) INPUTS entry - entry or entries from data base (bytarr) idltype - idl data type (obtained with db_item_info) nvalues - number of values to return (obtained with db_item) sbyte - starting byte in the entry (obtained with db_item) nbytes - number of bytes (needed only for string type) (obtained with db_item) OUTPUTS: function value is value of the specified item in entry RESTRICTIONS: To increase speed the routine assumes that entry and item are valid and that the data base is already opened using dbopen. REVISION HISTORY: version 0 D. Lindler Nov. 1987 (for new db format) Version 1, William Thompson, GSFC, 28 March 1994. Incorporated into CDS library. Version 2, Richard Schwartz, GSFC/SDAC, 23 August 1996 Allowed Entry to have 2 dimensions Version 2.1, 22 Feb 1997, JK Feggans, avoid reform for strings arrays. Version 2.2 Use overwrite with REFORM(), W. Landsman, May 1997 Converted to IDL V5.0 W. Landsman September 1997(See dbxval.pro)
DB_ENT2EXT
[Previous Routine] [Next Routine] [List of Routines]NAME: DB_ENT2EXT PURPOSE: Convert a database entry to external (IEEE) data format EXPLANATION: Converts a database entry to external (IEEE) data format prior to writing it. Called from DBWRT. CALLING SEQUENCE: DB_ENT2EXT, ENTRY INPUTS: ENTRY = Byte array containing a single record to be written to the database file. OUTPUTS: ENTRY = The converted array is returned in place of the input array. COMMON BLOCKS: DB_COM HISTORY: Version 1, William Thompson, GSFC/CDS (ARC), 1 June 1994 Version 2, William Thompson, GSFC/CDS (ARC), 15 September 1995 Fixed bug where only the first element in a multidimensional array was converted. Converted to IDL V5.0 W. Landsman September 1997(See db_ent2ext.pro)
DB_ENT2HOST
[Previous Routine] [Next Routine] [List of Routines]NAME: DB_ENT2HOST PURPOSE: Converts a database entry from external data format to host format. EXPLANATION: All items are extracted from the entry, and then converted to host format, and placed back into the entry. Called from DBRD and DBEXT_DBF. CALLING SEQUENCE: DB_ENT2HOST, ENTRY, DBNO INPUTS: ENTRY = Byte array containing a single record read from the database file. DBNO = Number of the opened database file. OUTPUTS: ENTRY = The converted array is returned in place of the input array. COMMON BLOCKS: DB_COM HISTORY: Version 1, William Thompson, GSFC/CDS (ARC), 1 June 1994 Version 2, William Thompson, GSFC/CDS (ARC), 15 September 1995 Fixed bug where only the first element in a multidimensional array was converted. Version 3, Richard Schwartz, GSFC/SDAC, 23 August 1996 Allow 2 dimensional byte arrays for entries to facilitate multiple entry processing. Pass IDLTYPE onto IEEE_TO_HOST Converted to IDL V5.0 W. Landsman September 1997(See db_ent2host.pro)
DB_INFO
[Previous Routine] [Next Routine] [List of Routines]NAME: DB_INFO PURPOSE: Function to obtain information on opened data base file(s) CALLING SEQUENCES: 1) result = db_info(request) 2) result = db_info(request,dbname) INPUTS (calling sequence 1): request - string specifying requested value(s) value of request value returned in result 'open' Flag set to 1 if data base(s) are opened 'number' Number of data base files opened 'items' Total number of items (all db's opened) 'update' update flag (1 if opened for update) 'unit_dbf' Unit number of the .dbf files 'unit_dbx' Unit number of the .dbx files 'entries' Number of entries in the db's 'length' Record lengths for the db's 'external' True if the db's are in external format INPUTS (calling sequence 2): request - string specifying requested value(s) value of request value returned in result 'name' Name of the data base 'number' Sequential number of the db 'items' Number of items for this db 'item1' Position of item1 for this db in item list for all db's 'item2' Position of last item for this db. 'pointer' Number of the item which points to this db. 0 for first or primary db. -1 if link file pointers. 'length' Record length for this db. 'title' Title of the data base 'unit_dbf' Unit number of the .dbf file 'unit_dbx' Unit number of the .dbx file 'entries' Number of entries in the db 'seqnum' Last sequence number used 'alloc' Allocated space (# entries) 'update' 1 if data base opened for update 'external' True if data base in external format dbname - data base name or number OUTPUTS: Requested value(s) are returned as the function value. HISTORY: version 1 D. Lindler Oct. 1987 changed type from 1 to 7 for IDLV2, J. Isensee, Nov., 1990 William Thompson, GSFC/CDS (ARC), 30 May 1994 Added EXTERNAL request type. Converted to IDL V5.0 W. Landsman September 1997(See db_info.pro)
DB_ITEM
[Previous Routine] [Next Routine] [List of Routines]NAME: DB_ITEM PURPOSE: Returns the item numbers and other info. for an item name. EXPLANATION: Procedure to return the item numbers and other information of a specified item name CALLING SEQUENCE: db_item, items, itnum, ivalnum, idltype, sbyte, numvals, nbytes INPUTS: items - item name or number form 1 scalar string giving item(s) as list of names separated by commas form 2 string array giving list of item names form 3 string of form '$filename' giving name of text file containing items (one item per line) form 4 integer scalar giving single item number or integer vector list of item numbers form 5 Null string specifying interactive selection Upon return items will contain selected items in form 1 form 6 '*' select all items OUTPUTS: itnum - item number ivalnum - value(s) number from multiple valued item idltype - data type(s) (1=string,2=byte,4=i*4,...) sbyte - starting byte(s) in entry numvals - number of data values for item(s) It is the full length of a vector item unless a subscript was supplied nbytes - number of bytes for each value All outputs are vectors even if a single item is requested OPTIONAL INPUT KEYWORDS: ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' DB_ITEM, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... PROCEDURE CALLS: DATATYPE, DB_INFO, GETTOK, SCREEN_SELECT, SPEC_DIR REVISION HISTORY: Written : D. Lindler, GSFC/HRS, October 1987 Version 2, William Thompson, GSFC, 17-Mar-1997 Added keyword ERRMSG Converted to IDL V5.0 W. Landsman October 1997(See db_item.pro)
DB_ITEM_INFO
[Previous Routine] [Next Routine] [List of Routines]NAME: DB_ITEM_INFO PURPOSE: routine to return information on selected item(s) in the opened data bases. CALLING SEQUENCE: result = db_item_info( request, itnums) INPUTS: request - string giving the requested information. 'name' - item names 'idltype' - IDL data type (integers) see documentation of intrinsic SIZE funtion 'nvalues' - vector item length (1 for scalar) 'sbyte' - starting byte in .dbf record (use bytepos to get starting byte in record returned by dbrd) 'nbytes' - bytes per data value 'index' - index types 'description' - description of the item 'pflag' - pointer item flags 'pointer' - data bases the items point to 'format' - print formats 'flen' - print field length 'headers' - print headers 'bytepos' - starting byte in dbrd record for the items 'dbnumber' - number of the opened data base 'pnumber' - number of db it points to (if the db is opened) 'itemnumber' - item number in the file itnums -(optional) Item numbers. If not supplied info on all items are returned. OUTPUT: Requested information is returned as a vector. Its type depends on the item requested. HISTORY: version 1 D. Lindler Nov. 1987 Converted to IDL V5.0 W. Landsman September 1997(See db_item_info.pro)
DB_OR
[Previous Routine] [Next Routine] [List of Routines]NAME: DB_OR PURPOSE: Combine two vectors of entry numbers, removing duplicate values. EXPLANATION: DB_OR can also be used to remove duplicate values from any longword vector CALLING SEQUENCE: LIST = DB_OR( LIST1 ) ;Remove duplicate values from LIST1 or LIST = DB_OR( LIST1, LIST2 ) ;Concatenate LIST1 and LIST2, remove dups INPUTS: LIST1, LIST2 - Vectors containing entry numbers, must be non-negative integers or longwords. OUTPUT: LIST - Vector containing entry numbers in either LIST1 or LIST2 METHOD DB_OR returns where the histogram of the entry vectors is non-zero PROCEDURE CALLS ZPARCHECK - checks parameters REVISION HISTORY: Written, W. Landsman February, 1989 Check for degenerate values W.L. February, 1993 Converted to IDL V5.0 W. Landsman September 1997(See db_or.pro)
DB_TITLES
[Previous Routine] [Next Routine] [List of Routines]NAME: DB_TITLES PURPOSE: Print database name and title. Called by DBHELP CALLING SEQUENCE: db_titles, fnames, titles INPUT: fnames - string array of data base names SIDE EFFECT: Database name is printed along with the description in the .dbh file HISTORY: version 2 W. Landsman May, 1989 modified to work under Unix, D. Neill, ACC, Feb 1991. William Thompson, GSFC/CDS (ARC), 1 June 1994 Added support for external (IEEE) representation. William Thompson, GSFC, 3 November 1994 Modified to allow ZDBASE to be a path string. Converted to IDL V5.0 W. Landsman September 1997(See db_titles.pro)
DEF_DIRLIST
[Previous Routine] [Next Routine] [List of Routines]NAME: DEF_DIRLIST PURPOSE: Define directory list using setenv or setlog EXPLANATION: Environment variables which point to a list of directories can end up to be very long. In VMS this can be a problem, because logical names cannot be longer than 256 characters. However, it is possible to get around this in VMS by assigning multiple values to a single logical name--a facility that does not exist in Unix. This routine will define the environment variable as either a delimited string, or as a series of values, whichever is most appropriate. CALLING SEQUENCE: DEF_DIRLIST, EVAR, VALUE INPUTD: EVAR = The name of the environment variable to define. VALUE = The value to give to EVAR. This can be either a single, delimited string, or it can be an array of directory names. The routine will choose for itself how to use this to define the environment variable. EXAMPLES: DIRS = FIND_ALL_DIR('+/data/fits') DEF_DIRLIST, 'FITS_DATA', DIRS PROCEDURE CALLS: SETENV, STR_SEP(), TRIM() Note: The intrinsic SETENV command is available under Unix & Windows only. However, it is available as a Library procedure for VMS. REVISION HISTORY: Version 1, 06-Aug-1996, William Thompson, GSFC Converted to IDL V5.0 June 1998 W. Landsman(See def_dirlist.pro)
DELVARX
[Previous Routine] [Next Routine] [List of Routines]NAME: DELVARX PURPOSE: Delete variables for memory management (can call from routines) EXPLANATION: Like intrinsic DELVAR function, but can be used from any calling level CALLING SEQUENCE: DELVARX, a [,b,c,d,e,f,g,h,i,j] INPUTS: p0, p1...p9 - variables to delete RESTRICTIONS: Can't use recursively due to EXECUTE function METHOD: Uses EXECUTE and TEMPORARY function REVISION HISTORY: Copied from the Solar library, written by slf, 25-Feb-1993 Added to Astronomy Library, September 1995 Converted to IDL V5.0 W. Landsman September 1997(See delvarx.pro)
DEREDD
[Previous Routine] [Next Routine] [List of Routines]NAME: DEREDD PURPOSE: Deredden then Stromgren parameters given for a value of E(b-y) EXPLANATION: See the procedure UVBYBETA for more info. CALLING SEQUENCE: deredd, eby, by, m1, c1, ub, by0, m0, c0, ub0 INPUTS: Eby - color index E(b-y),scalar by - b-y color (observed) m1 - Stromgren line blanketing parameter (observed) c1 - Stromgren Balmer discontinuity parameter (observed) ub - u-b color (observed) OUTPUTS: by0 - b-y color (dereddened) m0 - Line blanketing index (dereddened) c0 - Balmer discontinuity parameter (dereddened) ub0 - u-b color (dereddened) REVISION HISTORY: Adapted from FORTRAN routine DEREDD by T.T. Moon W. Landsman STX Co. April, 1988 Converted to IDL V5.0 W. Landsman September 1997(See deredd.pro)
DETABIFY
[Previous Routine] [Next Routine] [List of Routines]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(See detabify.pro)
DISMOUNT
[Previous Routine] [Next Routine] [List of Routines]NAME: DISMOUNT PURPOSE: Emulates the VMS DISMOUNT function in Unix. EXPLANATION : Emulates the VMS DISMOUNT function in the Unix environment. Although this is not a standard IDL function, it is available as a separate LINKIMAGE routine for VMS. The main purpose of this procedure is to close the file unit open on the tape device, and optionally to unload the tape. Errors can result if the tape is unloaded manually rather than using this routine. **Unix only** CALLING SEQUENCE: DISMOUNT, UNIT Inputs : UNIT = Tape unit number. Tape drives are selected via the UNIX environment variables "MT1", "MT2", etc. The desired tape drive is thus specified by numbers, as in VMS. Must be from 0 to 9. Opt. Inputs : None. Outputs : None. Opt. Outputs: None. Keywords : NOUNLOAD = If set, then the tape is simply rewound, not taken off line. Calls : CHECK_TAPE_DRV Common : CHCK_TAPE_DRVS contains array TAPE_LUN, containing logical unit numbers for each tape device, and TAPE_OPEN, which tells whether each device is open or not. Restrictions: The environment variable "MTn", where n corresponds to the variable UNIT, must be defined. E.g., setenv MT0 /dev/nrst0 Requires IDL v3.0 or later. Side effects: The device file is opened. Category : Utilities, I/O, Tape. Prev. Hist. : None. Written : William Thompson, GSFC, 21 December 1993. Modified : Version 1, William Thompson, GSFC, 21 December 1993. Version : Version 1, 21 December 1993. Converted to IDL V5.0 W. Landsman September 1997(See dismount.pro)
DIST_CIRCLE
[Previous Routine] [Next Routine] [List of Routines]NAME: DIST_CIRCLE PURPOSE: Form a square array where each value is its distance to a given center. EXPLANATION: Returns a square array in which the value of each element is its distance to a specified center. Useful for circular aperture photometry.  XCEN,YCEN = Scalars designating the X,Y pixel center. These need not be integers, and need not be located within the output image OUTPUTS: IM - N by N (or M x N) floating array in which the value of each pixel is equal to its distance to XCEN,YCEN EXAMPLE: Total the flux in a circular aperture within 3' of a specified RA and DEC on an 512 x 512 image IM, with a header H. IDL> adxy, H, RA, DEC, x, y ;Convert RA and DEC to X,Y IDL> getrot, H, rot, cdelt ;CDELT gives plate scale deg/pixel IDL> cdelt = cdelt*3600. ;Convert to arc sec/pixel IDL> dist_circle, circle, 512, x, y ;Create a distance circle image IDL> circle = circle*abs(cdelt(0)) ;Distances now given in arcseconds IDL> good = where(circle LT 180) ;Within 3 arc minutes IDL> print,total( IM(good) ) ;Total pixel values within 3' RESTRICTIONS: The speed of DIST_CIRCLE decreases and the the demands on virtual increase as the square of the output dimensions. Users should dimension the output array as small as possible, and re-use the array rather than re-calling DIST_CIRCLE MODIFICATION HISTORY: Adapted from DIST W. Landsman March 1991 Allow a rectangular output array W. Landsman June 1994 Converted to IDL V5.0 W. Landsman September 1997(See dist_circle.pro)
DIST_ELLIPSE
[Previous Routine] [Next Routine] [List of Routines]NAME: DIST_ELLIPSE PURPOSE: Create a mask array useful for elliptical aperture photemetry EXPLANATION: Form an array in which the value of each element is equal to the semi-major axis of the ellipse of specified center, axial ratio, and position angle, which passes through that element. Useful for elliptical aperture photometry.  XC,YC - Scalars giving the position of the ellipse center. This does not necessarily have to be within the image RATIO - Scalar giving the ratio of the major to minor axis. This should be greater than 1 for postion angle to have its standard meaning. OPTIONAL INPUTS: POS_ANG - Position angle of the major axis, measured counter-clockwise from the Y axis. For an image in standard orientation (North up, East left) this is the astronomical position angle. OUTPUT: IM - REAL*4 elliptical mask array, of size M x N. THe value of each pixel is equal to the semi-major axis of the ellipse of center XC,YC, axial ratio RATIO, and position angle POS_ANG, which passes through the pixel. EXAMPLE: Total the flux in a elliptical aperture with a major axis of 3', an axial ratio of 2.3, and a position angle of 25 degrees centered on a specified RA and DEC. The image array, IM is 200 x 200, and has an associated FITS header H. ADXY, H, ra, dec, x, y ;Get X and Y corresponding to RA and Dec GETROT, H, rot, cdelt ;CDELT gives plate scale degrees/pixel cdelt = abs( cdelt)*3600. ;CDELT now in arc seconds/pixel DIST_ELLIPSE, ell, 200, x, y, 2.3, 25 ;Create a elliptical image mask ell = ell*cdelt(0) ;Distances now given in arcseconds good = where( ell lt 180 ) ;Within 3 arc minutes print,total( im(good) ) ;Total pixel values within 3' RESTRICTIONS: The speed of DIST_ELLIPSE decreases and the the demands on virtual increase as the square of the output dimensions. Users should dimension the output array as small as possible, and re-use the array rather than re-calling DIST_ELLIPSE REVISION HISTORY: Written W. Landsman April, 1991 Somewhat faster algorithm August, 1992 Allow rectangular output array June, 1994 Converted to IDL V5.0 W. Landsman September 1997(See dist_ellipse.pro)
EQPOLE
[Previous Routine] [Next Routine] [List of Routines]NAME: EQPOLE PURPOSE: Convert RA and Dec to X,Y using an equal-area polar projection. EXPLANATION: The output X and Y coordinates are scaled to be between -90 and +90 to go from equator to pole to equator. Output map points can be centered on the north pole or south pole. CALLING SEQUENCE: EQPOLE, L, B, X, Y, [ /SOUTHPOLE ] INPUTS: L - longitude - scalar or vector, in degrees B - latitude - same number of elements as RA, in degrees OUTPUTS: X - X coordinate, same number of elements as RA. X is normalized to be between -90 and 90. Y - Y coordinate, same number of elements as DEC. Y is normalized to be between -90 and 90. KEYWORDS: /SOUTHPOLE - Keyword to indicate that the plot is to be centered on the south pole instead of the north pole. REVISION HISTORY: J. Bloch LANL, SST-9 1.1 5/16/91 Converted to IDL V5.0 W. Landsman September 1997(See eqpole.pro)
EQPOLE_GRID
[Previous Routine] [Next Routine] [List of Routines]NAME: EQPOLE_GRID PURPOSE: Produce an overlay of latitude and longitude lines over a plot or image EXPLANATION: Grid is written on the current graphics device using the equal area polar projection. EQPOLE_GRID assumes that the output plot coordinates span the x and y ranges of -90 to 90 for a region that covers the equator to the chosen pole. The grid is assumed to go from the equator to the chosen pole. CALLING SEQUENCE: EQPOLE_GRID[,DLONG,DLAT,[/SOUTHPOLE,LINESTYLE=N,/LABEL] INPUTS: DLONG = Optional input longitude line spacing in degrees. If left out, defaults to 30. DLAT = Optional input lattitude line spacing in degrees. If left out, defaults to 30. KEYWORDS: SOUTHPOLE = Optional flag indicating that the output plot is to be centered on the south rather than the north pole. LINESTYLE = Optional input integer specifying the linestyle to use for drawing the grid lines. LABELS = Optional flag for creating labels on the output grid on the prime meridian and the equator for lattitude and longitude lines. If set =2, then the longitude lines are labeled in hours and minutes. OUTPUTS: Draws grid lines on current graphics device. CATAGORY: SST-9 Graphics routine. COPYRIGHT NOTICE: Copyright 1992, The Regents of the University of California. This software was produced under U.S. Government contract (W-7405-ENG-36) by Los Alamos National Laboratory, which is operated by the University of California for the U.S. Department of Energy. The U.S. Government is licensed to use, reproduce, and distribute this software. Neither the Government nor the University makes any warranty, express or implied, or assumes any liability or responsibility for the use of this software. AUTHOR AND MODIFICATIONS: J. Bloch 1.4 10/28/92 Converted to IDL V5.0 W. Landsman September 1997(See eqpole_grid.pro)
EULER
[Previous Routine] [Next Routine] [List of Routines]NAME: EULER PURPOSE: Transform between Galactic, celestial, and ecliptic coordinates. EXPLANATION: Use the procedure ASTRO to use this routine interactively CALLING SEQUENCE: EULER, AI, BI, AO, BO, [ SELECT ] INPUTS: AI - Input Longitude in DEGREES, scalar or vector. If only two parameters are supplied, then AI and BI will be modified to contain the output longitude and latitude. BI - Input Latitude in DEGREES OPTIONAL INPUT: SELECT - Integer (1-6) specifying type of coordinate transformation. SELECT From To | SELECT From To 1 RA-DEC(1950) GAL.(ii) | 4 ECLIPTIC RA-DEC 2 GAL.(ii) RA-DEC | 5 ECLIPTIC GAL.(ii) 3 RA-DEC ECLIPTIC | 6 GAL.(ii) ECLIPTIC If omitted, program will prompt for the value of SELECT OUTPUTS: AO - Output Longitude in DEGREES BO - Output Latitude in DEGREES REVISION HISTORY: Written W. Landsman, February 1987 Adapted from Fortran by Daryl Yentis NRL Converted to IDL V5.0 W. Landsman September 1997(See euler.pro)
EXPAND_TILDE()
[Previous Routine] [Next Routine] [List of Routines]NAME: EXPAND_TILDE() PURPOSE: Expand tilde in UNIX directory names CALLING SEQUENCE: IDL> output=expand_tilde(input) INPUTS: INPUT = input file or directory name, scalar string OUTPUT: Returns expanded filename, scalar string EXAMPLES: output=expand_tilde('~zarro/test.doc') ---> output='/usr/users/zarro' PROCEDURE CALLS: DATATYPE() REVISION HISTORY: Version 1, 17-Feb-1997, D M Zarro. Written Transfered from Solar Library W. Landsman Sep. 1997(See expand_tilde.pro)
EXTAST
[Previous Routine] [Next Routine] [List of Routines]NAME: EXTAST PURPOSE: Extract astrometry parameters from a FITS image header. EXPLANATION: The astrometry in the header can be in either CD (Coordinate description) format, or CROTA and CDELT (AIPS-type) format. However, the output astrometry will always be in CD format. CALLING SEQUENCE: EXTAST, hdr, [ astr, noparams ] INPUT: HDR - variable containing the FITS header (string array) OUTPUTS: ASTR - Anonymous structure containing astrometry info from the FITS header ASTR always contains the following tags (even though some projections do not require all the parameters) .CD - 2 x 2 array containing the astrometry parameters CD1_1 CD1_2 in DEGREES/PIXEL CD2_1 CD2_2 .CDELT - 2 element vector giving physical increment at reference pixel .CRPIX - 2 element vector giving X and Y coordinates of reference pixel (def = NAXIS/2) .CRVAL - 2 element double precision vector giving R.A. and DEC of reference pixel in DEGREES .CTYPE - 2 element string vector giving projection types, default ['RA---TAN','DEC--TAN'] .LONGPOLE - scalar longitude of north pole (default = 180) .PROJP1 - Scalar parameter needed in some projections .PROJP2 - Scalar parameter needed in some projections NOPARAMS - Scalar indicating the results of EXTAST -1 = Failure - Header missing astrometry parameters 0 = Success - Header contains CD00n00m + CDELT* astrometry 1 = Success - Header contains CROTA + CDELT (AIPS-type) astrometry 2 = Success - Header contains CDn_m astrometry PROCEDURE EXTAST checks for astrometry parameters in the following order: (1) the CD matrix CD1_1,CD1_2... plus CRPIX and CRVAL. (2) the CD matrix CD001001,CD001002...plus CRPIX and CRVAL (3) CROTA2 (or CROTA1) and CDELT plus CRPIX and CRVAL. See the Memo: Representations of Celestial Coordinates in FITS by Griesen and Calabretta, available at fits.cv.nrao.edu NOTES: (1) An anonymous structure is created to avoid structure definition conflicts. This is needed because some projection systems require additional dimensions (i.e. spherical cube projections require a specification of the cube face). PROCEDURES CALLED: FITS_CD_FIX, GSSSEXTAST, SXPAR(), ZPARCHECK REVISION HISTORY Written by B. Boothman 4/15/86 Accept CD001001 keywords 1-3-88 Accept CD1_1, CD2_1... keywords W. Landsman Nov. 92 Recognize GSSS FITS header W. Landsman June 94 Converted to IDL V5.0 W. Landsman September 1997(See extast.pro)
EXTGRP
[Previous Routine] [Next Routine] [List of Routines]NAME: EXTGRP PURPOSE: Extract the group parameter information out of SXREAD output EXPLANATION: This procedure extracts the group parameter information out of a header and parameter variable obtained from SXREAD. This allows astrometry, photometry and other parameters to be easily SXPARed by conventional methods and allows the image and header to be saved in a SIMPLE format. CALLING SEQUENCE: ExtGrp, hdr, par INPUT: HDR - The header which is to be converted (input and output) PAR - The Parameter string returned from a call to SXREAD OUTPUT: HDR - The converted header, string array OTHER PROCEDURES CALLED: SXPAR(), SXADDPAR, SXGPAR(), STRN() HISTORY: 25-JUN-90 Version 1 written 13-JUL-92 Header finally added to this ancient procedure, code spiffed up a bit. Now 3 times faster. Added PTYPE comment inclusion. E. Deutsch Converted to IDL V5.0 W. Landsman September 1997(See extgrp.pro)
FACTOR
[Previous Routine] [Next Routine] [List of Routines]NAME: FACTOR PURPOSE: Find prime factors of a given number. CATEGORY: CALLING SEQUENCE: factor, x, p, n INPUTS: x = Number to factor. in KEYWORD PARAMETERS: OUTPUTS: p = Array of prime numbers. out n = Count of each element of p. out COMMON BLOCKS: NOTES: Note: see also prime, numfactors, print_fact. MODIFICATION HISTORY: R. Sterner. 4 Oct, 1988. RES 25 Oct, 1990 --- converted to IDL V2. Johns Hopkins University Applied Physics Laboratory. Copyright (C) 1988, Johns Hopkins University/Applied Physics Laboratory This software may be used, copied, or redistributed as long as it is not sold and this copyright notice is reproduced on each copy made. This routine is provided as is without any express or implied warranties whatsoever. Other limitations apply as described in the file disclaimer.txt. Converted to IDL V5.0 W. Landsman September 1997(See factor.pro)
FDECOMP
[Previous Routine] [Next Routine] [List of Routines]NAME: FDECOMP PURPOSE: Routine to decompose a file name for any operating system CALLING SEQUENCE: FDECOMP, filename, disk, dir, name, qual, version, [OSFamily = ] INPUT: filename - string file name, scalar OUTPUTS: All the output parameters are scalar strings disk - disk name, always '' on a Unix machine, scalar string dir - directory name, scalar string name - file name, scalar string qual - qualifier, set equal to the characters beyond the last "." version - version number, always '' on a non-VMS machine, scalar string OPTIONAL INPUT KEYWORD: OSFamily - one of the four scalar strings specifying the operating system: 'vms','windows','MacOS' or 'unix'. If not supplied, then !VERSION.OS_FAMILY is used to determine the OS. EXAMPLES: Consider the following file names Unix: file = '/rsi/idl40/avg.pro' VMS: file = '$1$dua5:[rsi.idl40]avg.pro;3 Mac: file = 'Macintosh HD:Programs:avg.pro' Windows: file = 'd:\rsi\idl40\avg.pro' then IDL> FDECOMP, file, disk, dir, name, qual, version will return the following Disk Dir Name Qual Version Unix: '' '/rsi/idl40/' 'avg' 'pro' '' VMS: '$1$dua5' '[RSI.IDL40]' 'avg' 'pro' '3' Mac: 'Macintosh HD' ':Programs:' 'avg' 'pro' '' Windows: 'd:' \rsi\idl40\ 'avg' 'pro' '' NOTES: (1) All tokens are removed between 1) name and qual (i.e period is removed) 2) qual and ver (i.e. VMS semicolon is removed) (2) On VMS the filenames "MOTD" and "MOTD." are distinguished by the fact that qual = '' for the former and qual = ' ' for the latter. ROUTINES CALLED: Function GETTOK() HISTORY version 1 D. Lindler Oct 1986 Include VMS DECNET machine name in disk W. Landsman HSTX Feb. 94 Converted to Mac IDL, I. Freedman HSTX March 1994 Converted to IDL V5.0 W. Landsman September 1997(See fdecomp.pro)
FILTER_IMAGE
[Previous Routine] [Next Routine] [List of Routines]NAME: FILTER_IMAGE PURPOSE: Identical to MEDIAN or SMOOTH but handle edges and allow iterations. EXPLANATION: Computes the average and/or median of pixels in moving box, replacing center pixel with the computed average and/or median, (using the IDL smooth or median functions). The main reason for using this function is the options to also process the pixels at edges and corners of image, and, to apply iterative smoothing simulating convolution with Gaussian, and/or to convolve image with a Gaussian kernel. CALLING SEQUENCE: Result = filter_image( image, SMOOTH=box_width, /MEDIAN, /ALL ) INPUT: image = 2-D array (matrix) OPTIONAL INPUT KEYWORDS: SMOOTH = scalar (odd) integer specifying the width of a square box for moving average, in # pixels. /SMOOTH means use box width = 3 pixels for smoothing. MEDIAN = scalar (odd) integer specifying the width of square moving box for median filter, in # pixels. /MEDIAN means use box width = 3 pixels for median filter. /ALL_PIXELS causes the edges of image to be filtered as well, accomplished by reflecting pixels adjacent to edges outward. /ITERATE means apply smooth(image,3) iteratively for a count of (box_width-1)/2 times (=radius), when box_width >= 5. This is equivalent to convolution with a Gaussian PSF of FWHM = 2 * sqrt( radius ) as radius gets large. Note that /ALL_PIXELS is automatically applied, giving better results in the iteration limit. (also, MEDIAN keyword is ignored when /ITER is specified). FWHM_GAUSSIAN = Full-width half-max of Gaussian to convolve with image. FWHM can be a single number (circular beam), or 2 numbers giving axes of elliptical beam. /NO_FT_CONVOL causes the convolution to be computed directly, with IDL function convol. The default is to use FFT when factors of size are all LE 13. (note that external function convolve handles both cases) RESULT: Function returns the smoothed, median filtered, or convolved image. If both SMOOTH and MEDIAN are specified, median filter is applied first. EXAMPLES: To apply 3x3 moving median filter and then 3x3 moving average, both applied to all pixels: Result = filter_image( image, /SMOOTH, /MEDIAN, /ALL ) To iteratively apply 3x3 moving average filter for 4 = (9-1)/2 times, thus approximating convolution with Gaussian of FWHM = 2*sqrt(4) = 4 : Result = filter_image( image, SMOOTH=9, /ITER ) To convolve all pixels with Gaussian of FWHM = 3.7 x 5.2 pixels: Result = filter_image( image, FWHM=[3.7,5.2], /ALL ) EXTERNAL CALLS: function psf_gaussian function convolve pro factor function prime ;all these called only if FWHM is specified. PROCEDURE: If /ALL_PIXELS or /ITERATE keywords are set then create a larger image by reflecting the edges outward, then call the IDL median and/or smooth function on the larger image, and just return the central part (the orginal size image). HISTORY: Written, 1991, Frank Varosi, NASA/GSFC. FV, 1992, added /ITERATE option. FV, 1993, added FWHM_GAUSSIAN= option. Converted to IDL V5.0 W. Landsman September 1997(See filter_image.pro)
FIND
[Previous Routine] [Next Routine] [List of Routines]NAME: FIND PURPOSE: Find positive brightness perturbations (i.e stars) in an image EXPLANATION: Also returns centroids and shape parameters (roundness & sharpness). Adapted from 1986 STSDAS version of DAOPHOT. CALLING SEQUENCE: FIND, image, [ x, y, flux, sharp, round, hmin, fwhm, roundlim, sharplim PRINT= , /SILENT ] INPUTS: image - 2 dimensional image array (integer or real) for which one wishes to identify the stars present OPTIONAL INPUTS: FIND will prompt for these parameters if not supplied hmin - Threshold intensity for a point source - should generally be 3 or 4 sigma above background fwhm - FWHM to be used in the convolve filter sharplim - 2 element vector giving low and high cutoff for the sharpness statistic (Default: [0.2,1.0] ). Change this default only if the stars have siginificantly larger or or smaller concentration than a Gaussian roundlim - 2 element vector giving low and high cutoff for the roundness statistic (Default: [-1.0,1.0] ). Change this default only if the stars are significantly elongated. OPTIONAL INPUT KEYWORDS: SILENT - Normally, FIND will write out each star that meets all selection criteria. If the SILENT keyword is set and non-zero, then this printout is suppressed. PRINT - if set and non-zero then T_FIND will also write its results to a file FIND.PRT. Also one can specify a different output file name by setting PRINT = 'filename'. OPTIONAL OUTPUTS: x - vector containing x position of all stars identified by FIND y- vector containing y position of all stars identified by FIND flux - vector containing flux of identified stars as determined by a gaussian fit. Fluxes are NOT converted to magnitudes. sharp - vector containing sharpness statistic for identified stars round - vector containing roundness statistic for identified stars NOTES: The sharpness statistic compares the central pixel to the mean of the surrounding pixels. If this difference is greater than the originally estimated height of the Gaussian or less than 0.2 the height of the Gaussian (for the default values of SHARPLIM) then the star will be rejected. PROCEDURE CALLS: DATATYPE(), GETOPT REVISION HISTORY: Written W. Landsman, STX February, 1987 ROUND now an internal function in V3.1 W. Landsman July 1993 Change variable name DERIV to DERIVAT W. Landsman Feb. 1996 Use /PRINT keyword instead of TEXTOUT W. Landsman May 1996 Changed loop indices to type LONG W. Landsman Aug. 1997 Converted to IDL V5.0 W. Landsman September 1997(See find.pro)
FINDPRO
[Previous Routine] [Next Routine] [List of Routines]NAME: FINDPRO PURPOSE: Find all locations of procedure in the IDL !PATH EXPLANATION: The procedure is searched in all IDL Libraries or directories given in the !PATH system variable. Finds and returns the paths of all examples of the procedure in the directories listed in the path. CALLING SEQUENCE: FINDPRO, [ Proc_Name, /NoPrint, DirList = , ProList = ] OPTIONAL INPUT: Proc_Name - Character string giving the name of the IDL procedure or function. Do not include the ".pro" extension. If Proc_Name is omitted, the program will prompt for PROC_NAME. "*" wildcards are permitted. OPTINAL KEYWORD INPUT: NoPrint - if set, then the file's path is not printed on the screen and absolutely no error messages are printed on the screen. If not set, then - since the MESSAGE routine is used - error messages will be printed but the printing of informational messages depends on the value of the !Quiet variable. OPTIONAL KEYWORD OUTPUTS: DirList - The directories in which the file is located are returned in the keyword as a string array. If the procedure was found in a VMS text library, then the full path and name of that library is returned and is prefixed by an "@" sign as a flag that it is a library, not a directory. If the procedure is an intrinsic IDL procedure, then the value of DirList = ['INTRINSIC']. If the procedure is not found, the value of DirList = ['']. ProList - The list (full pathnames) of procedures found. Useful if you are looking for the name of a procedure using wildcards. PROCEDURE: The system variable !PATH is parsed using EXPAND_PATH into individual libraries or directories. Each library or directory is then searched for the procedure name. If not found in !PATH, then the the name is compared with the list of intrinsic IDL procedures given by the ROUTINE_NAMES function. EXAMPLE: (1) Find the procedure CURVEFIT. Assume for this example that the user also has a copy of the CURVEFIT.PRO procedure in her home directory on a Unix machine. IDL> findpro, 'curvefit', DIRLIST=DirList Procedure curvefit.pro found in directory . Procedure curvefit.pro found in directory /home/idl/lib/userlib IDL> help, DirList DIRLIST STRING = Array(2) IDL> help, DirList(0), DirList(1)STRING = '.' STRING = '/home/idl/lib/userlib' (2) Find all procedures in one's !path containing the characters "zoom" IDL> findpro,'*zoom*' RESTRICTIONS: User will be unable to find a path for a native IDL function or procedure, or for a FORTRAN or C routine added with CALL_EXTERNAL. Remember that Unix is case sensitive, and most procedures will be in lower case. PROCEDURES USED: ZPARCHECK, FDECOMP REVISION HISTORY: Based on code extracted from the GETPRO procedure, J. Parker 1994 Use the intrinsic EXPAND_PATH function W. Landsman Nov. 1994 Use ROUTINE_NAMES() to check for intrinsic procs W. Landsman Jul 95 Added Macintosh, WINDOWS compatibility W. Landsman Sep. 95 Removed spurious first element in PROLIST W. Landsman March 1997 Don't include duplicate directories in !PATH WL May 1997 Converted to IDL V5.0 W. Landsman September 1997 (See findpro.pro)
FIND_ALL_DIR()
[Previous Routine] [Next Routine] [List of Routines]NAME: FIND_ALL_DIR() PURPOSE: Finds all directories under a specified directory. EXPLANATION: This routine finds all the directories in a directory tree when the root of the tree is specified. This provides the same functionality as having a directory with a plus in front of it in the environment variable IDL_PATH. CALLING SEQUENCE: Result = FIND_ALL_DIR( PATH ) PATHS = FIND_ALL_DIR('+mypath', /PATH_FORMAT) PATHS = FIND_ALL_DIR('+mypath1:+mypath2') INPUTS: PATH = The path specification for the top directory in the tree. Optionally this may begin with the '+' character but the action is the same unless the PLUS_REQUIRED keyword is set. One can also path a series of directories separated by the correct character ("," for VMS, ":" for Unix) OUTPUTS: The result of the function is a list of directories starting from the top directory passed and working downward from there. Normally, this will be a string array with one directory per array element, but if the PATH_FORMAT keyword is set, then a single string will be returned, in the correct format to be incorporated into !PATH. OPTIONAL INPUT KEYWORDS: PATH_FORMAT = If set, then a single string is returned, in the format of !PATH. PLUS_REQUIRED = If set, then a leading plus sign is required in order to expand out a directory tree. This is especially useful if the input is a series of directories, where some components should be expanded, but others shouldn't. RESET = Often FIND_ALL_DIR is used with logical names. It can be rather slow to search through these subdirectories. The /RESET keyword can be used to redefine an environment variable so that subsequent calls don't need to look for the subdirectories. To use /RESET, the PATH parameter must contain the name of a *single* environment variable. For example setenv,'FITS_DATA=+/datadisk/fits' dir = find_all_dir('FITS_DATA',/reset,/plus) The /RESET keyword is usually combined with /PLUS_REQUIRED. PROCEDURE CALLS: DEF_DIRLIST, FIND_WITH_DEF(), BREAK_PATH(), TRIM() RESTRICTIONS: PATH must point to a directory that actually exists. On VMS computers this routine calls a command file, FIND_ALL_DIR.COM (available only on VMS distribution) to find the directories. This command file must be in one of the directories in IDL's standard search path, !PATH. REVISION HISTORY: Written : William Thompson, GSFC, 3 May 1993. Version 6 William Thompson, GSFC, 20 August 1996 Version 7, William Thompson, GSFC, 13 February 1998 Include Windows and MacOS seperators. Converted to V5.0, March 1998(See find_all_dir.pro)
FIND_WITH_DEF()
[Previous Routine] [Next Routine] [List of Routines]NAME: FIND_WITH_DEF() PURPOSE: Searches for files with a default path and extension. EXPLANATION: Finds files using default paths and extensions, similar to using the DEFAULT keyword with the OPEN statement in VMS. Using this routine together with environment variables allows an OS-independent approach to finding files. CALLING SEQUENCE: Result = FIND_WITH_DEF( FILENAME, PATHS [, EXTENSIONS ] ) INPUTS: FILENAME = Name of file to be searched for. It may either be a complete filename, or the path or extension could be left off, in which case the routine will attempt to find the file using the default paths and extensions. PATHS = One or more default paths to use in the search in case FILENAME does not contain a path itself. The individual paths are separated by commas, although in UNIX, colons can also be used. In other words, PATHS has the same format as !PATH, except that commas can be used as a separator regardless of operating system. The current directory is always searched first, unless the keyword NOCURRENT is set. A leading $ can be used in any path to signal that what follows is an environmental variable, but the $ is not necessary. (In VMS the $ can either be part of the path, or can signal logical names for compatibility with Unix.) Environmental variables can themselves contain multiple paths. OPTIONAL INPUTS: EXTENSIONS = One or more extensions to append to end of filename if the filename does not contain one (e.g. ".dat"). The period is optional. Multiple extensions can be separated by commas or colons. OUTPUTS: The result of the function is the name of the file if successful, or the null string if unsuccessful. OPTIONAL INPUT KEYWORDS: NOCURRENT = If set, then the current directory is not searched. RESET = The FIND_WITH_DEF routine supports paths which are preceeded with the plus sign to signal that all subdirectories should also be searched. Often this is used with logical names. It can be rather slow to search through these subdirectories. The /RESET keyword can be used to redefine an environment variable so that subsequent calls don't need to look for the subdirectories. To use /RESET, the PATHS parameter must contain the name of a *single* environment variable. For example setenv,'FITS_DATA=+/datadisk/fits' file = find_with_def('test.fits','FITS_DATA',/reset) EXAMPLE: FILENAME = '' READ, 'File to open: ', FILENAME FILE = FIND_WITH_DEF( FILENAME, 'SERTS_DATA', '.fix' ) IF FILE NE '' THEN ... PROCEDURE CALLS: BREAK_PATH(), FIND_ALL_DIR(), STR_SEP(), TRIM() REVISION HISTORY: Version 1, William Thompson, GSFC, 3 May 1993. Removed trailing / and : characters. Fixed bugs Allow for commas within values of logical names. Added keyword NOCURRENT. Changed to call BREAK_PATH Version 2, William Thompson, GSFC, 3 November 1994 Made EXTENSIONS optional. Version 3, William Thompson, GSFC, 30 April 1996 Call FIND_ALL_DIR to resolve any plus signs. Version 4, S.V. Haugan, UiO, 5 June 1996 Using OPENR,..,ERROR=ERROR to avoid an IDL 3.6 internal nesting error. Version 5, R.A. Schwartz, GSFC, 11 July 1996 Use SPEC_DIR to interpret PATH under VMS Version 6, William Thompson, GSFC, 5 August 1996 Took out call to SPEC_DIR (i.e., reverted to version 4). The use of SPEC_DIR was required to support logical names defined via SETLOG,/CONFINE. However, it conflicted with the ability to use logical names with multiple values. Removing the /CONFINE made it unnecessary to call SPEC_DIR in this routine. Version 7, William Thompson, GSFC, 6 August 1996 Added keyword RESET Converted to IDL V5.0 W. Landsman October 1997(See find_with_def.pro)
FITEXY
[Previous Routine] [Next Routine] [List of Routines]NAME: FITEXY PURPOSE: Best straight-line fit to data with errors in both coordinates EXPLANATION: Linear Least-squares approximation in one-dimension (y = a + b*x), when both x and y data have errors CALLING EXAMPLE: FITEXY, x, y, A, B, X_SIG=sigx, Y_SIG=sigy, [sigma_A_B, chi_sq, q, TOL=] INPUTS: x = array of values for independent variable. y = array of data values assumed to be linearly dependent on x. REQUIRED INPUT KEYWORDS: X_SIGMA = scalar or array specifying the standard deviation of x data. Y_SIGMA = scalar or array specifying the standard deviation of y data. OPTIONAL INPUT KEYWORD: TOLERANCE = desired accuracy of minimum & zero location, default=1.e-3. OUTPUTS: A_intercept = constant parameter result of linear fit, B_slope = slope parameter, so that: ( A_intercept + B_slope * x ) approximates the y data. OPTIONAL OUTPUT: sigma_A_B = two element array giving standard deviation of A_intercept and B_slope parameters, respectively. The standard deviations are not meaningful if (i) the fit is poor (see parameter q), or (ii) b is so large that the data are consistent with a vertical (infinite b) line. If the data are consistent with *all* values of b, then sigma_A_B = [1e33,e33] chi_sq = resulting minimum Chi-Square of Linear fit, scalar q - chi-sq probability, scalar (0-1) giving the probability that a correct model would give a value equal or larger than the observed chi squared. A small value of q indicates a poor fit, perhaps because the errors are underestimated. COMMON: common fitexy, communicates the data for computation of chi-square. PROCEDURE CALLS: CHISQ_FITEXY() ;Included in this file MINF_BRACKET, MINF_PARABOLIC, ZBRENT ;In IDL Astronomy Library MOMENT(), CHISQR_PDF() ;In standard IDL distribution PROCEDURE: From "Numerical Recipes" column by Press and Teukolsky: in "Computer in Physics", May, 1992 Vol.6 No.3 Also see the 2nd edition of the book "Numerical Recipes" by Press et al. MODIFICATION HISTORY: Written, Frank Varosi NASA/GSFC September 1992. Now returns q rather than 1-q W. Landsman December 1992 Converted to IDL V5.0 W. Landsman September 1997 Use CHISQR_PDF, MOMENT instead of STDEV,CHI_SQR1 W. Landsman April 1998(See fitexy.pro)
FITSDIR
[Previous Routine] [Next Routine] [List of Routines]NAME: FITSDIR PURPOSE: Provide a brief description of the primary headers of FITS disk files. EXPLANATION: The values of the FITS keywords NAXISi, OBS-DATE, TELESCOPE, OBJECT, EXPTIME are displayed. All of these are commonly used FITS keywords and all except EXPTIME are officially reserved FITS keywords. CALLING SEQUENCE: FITSDIR , [ directory, TEXTOUT =, /NoTelescope ] OPTIONAL INPUT PARAMETERS: DIRECTORY - Scalar string giving file name, disk or directory to be searched. Wildcard file names are allowed. Examples of valid VMS or Unix names include '*.fit' or 'tape*'. An example of a valid VMS name is 'UIT$USER2:[JONES]*.FIT' while a valid Unix string is 'iraf/*.fits'. If not given, FITSDIR searches *.fits files in the default directory. OPTIONAL KEYWORD INPUT PARAMETER NOTELESCOPE - If this keyword is set and non-zero then the value of the (usually less important) TELESCOPE keyword is not displayed, and more space is available to display the other keyword values TEXTOUT - Controls output device as described in TEXTOPEN procedure 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=7 Append to existing .prt file textout = filename (default extension of .prt) OUTPUT PARAMETERS: None. RESTRICTIONS: (1) Field values may be truncated if their length exceeds the default format. File name NAXISi OBS-DATE TELESCOPE OBJECT EXPTIME A18 A11 A10 A10 A20 F7.1 A20 A12 A10 A29 F7.1 (2) Only reads the primary FITS headers. FITS files containing only extensions (binary or ASCII tables) may have little information in their primary header. (3) Users may wish to modify the program to display other FITS keywords of particular interest to them EXAMPLES: IDL> fitsdir ;Print info on all '*.fits' files in current directory. IDL> fitsdir ,'*.fit' ;Lists all '*.fit' files in current directory IDL> fitsdir ,'tape*' ;Print info on all tape* files in current ;directory. Files meeting the wildcard name ;that are not FITS files are ignored Write info on all *.fits files in the Unix directory /usr2/smith, to a file 'smith.txt' and don't display the value of the TELESCOPE keyword IDL> fitsdir ,'/usr2/smith/*.fits',t='smith.txt', /NoTel PROCEDURE: FINDFILE is used to find the specified FITS files. The header of each file is read, and rejected if the file is not FITS. Each header searched for the parameters NAXISi, TELESCOP, OBJECT, DATE-OBS and EXPTIME. SYSTEM VARIABLES: The non-standard system variables !TEXTOUT and !TEXTUNIT must be defined before calling FITS_INFO. DEFSYSV,'!TEXTOUT',1 DEFSYSV,'!TEXTUNIT',0 One way to define these is to call the procedure ASTROLIB. See TEXTOPEN.PRO for more info PROCEDURES USED: FDECOMP, REMCHAR, SPEC_DIR(), TEXTOPEN, TEXTCLOSE, ZPARCHECK MODIFICATION HISTORY: Written, W. Landsman, HSTX February, 1993 Converted to IDL V5.0 W. Landsman September 1997 (See fitsdir.pro)
FITSLIST
[Previous Routine] [Next Routine] [List of Routines]NAME: FITSLIST PURPOSE: Display and write FITS headers from a FITS tape EXPLANATION: Procedure will read FITS files from a tape on the specified tape unit. The headers are placed in file NAME, with the default extension of .LIS. Headers are also displayed at the terminal. Unix and VMS IDL only. CALLING SEQUENCE: FITSLIST FITSLIST,UPDATE_SWITCH OPTIONAL INPUT: UPDATE_SWITCH - If passed and nonzero, then an existing file is opened, and output is appended to the end of this file. Also, the FITS tape is not rewound prior to starting the read. This is useful if the tape contains spurious EOF marks. OUTPUT: None. SIDE EFFECTS: File NAME or NAME.LIS is created, or if UPDATE_SWITCH is nonzero then additional information is appended to the file. Headers are displayed at terminal as well as written to file. RESTRICTIONS: Tape must be mounted before calling FITSLIST. FITSLIST uses the VMS IDL tape positioning command, but will also run on Unix machines by using procedures which call IOCTL and which emulate the VMS IDL tape I/O functions (e.g TAPRD) PROMPTS: Program will prompt for (1) NAME of output listing file (2) tape unit number PROCEDURES CALLED: FITSTAPE HISTORY: William Thompson, 15-May-1986, based on FITSREAD. William Thompson, 09-Feb-1990, added file numbers. Converted to IDL V5.0 W. Landsman September 1997(See fitslist.pro)
FITSRGB_TO_TIFF
[Previous Routine] [Next Routine] [List of Routines]NAME: FITSRGB_to_TIFF PURPOSE: Combine separate red, green, and blue FITS images into TIFF format EXPLANATION: The output TIFF (class R) file can have colors interleaved either either by pixel or image. The colour mix is also adjustable. CALLING SEQUENCE: FITSRGB_to_TIFF, path, rgb_files, tiff_name [,/BY_PIXEL, /PREVIEW, R=red_mix, G=green_mix, B=blue_mix] INPUTS: path = file system directory path to the RGB files required. rgb_files = string array with three components - the red FITS file filename, the blue FITS file filename and the green FITS file filename OUTPUTS: tiff_name = string containing name of tiff file to be produced OPTIONAL OUTPUT: Header = String array containing the header from the FITS file. OPTIONAL INPUT KEYWORDS: BY_PIXEL = This causes TIFF file RGB to be interleaved by pixel rather than the default of by image. PREVIEW = Allows a 24 bit image to be displayed on the screen to check the colour mix. RED = Real number containing the fractional mix of red GREEN = Real number containing the fractional mix of green BLUE = Real number containing the fractional mix of blue EXAMPLE: Read three FITS files, 'red.fits', 'blue.fits' and 'green.fits' from the directory '/data/images/space' and output a TIFF file named 'colour.tiff' IDL> FITSRGB_to_TIFF, '/data/images/space', ['red.fits', $ 'blue.fits', 'green.fits'], 'colour.tiff' Read three FITS files, 'red.fits', 'blue.fits' and 'green.fits' from the current directory and output a TIFF file named '/images/out.tiff' In this case, the red image is twice as strong as the green and the blue is a third more intense. A preview on screen is also wanted. IDL> FITSRGB_to_TIFF, '.', ['red.fits', $ 'blue.fits', 'green.fits'], '/images/out.tiff', $ /PREVIEW, RED=0.5, GREEN=1.0, BLUE=0.666 RESTRICTIONS: (1) Limited to the ability of the routine READFITS NOTES: None PROCEDURES USED: Functions: SXPAR, WHERENAN, READFITS, STRNUMBER, CONCAT_DIR Procedures: IEEE_TO_HOST, SXADDPAR, TIFF_WRITE MODIFICATION HISTORY: 16th January 1995 - Written by Carl Shaw, Queen's University Belfast 27 Jan 1995 - W. Landsman, Add CONCAT_DIR for VMS, Windows compatibility Converted to IDL V5.0 W. Landsman September 1997(See fitsrgb_to_tiff.pro)
FITSTAPE
[Previous Routine] [Next Routine] [List of Routines]NAME: FITSTAPE PURPOSE: Subroutine to perform FITS tape I/O. EXPLANATION: For VMS or Unix IDL only CALLING SEQUENCE: status = fitstape( command, unit, bitpix, data ) INPUTS: command - string command from the following choices 'init' - initialization (must be first call to fitstape) 'read' - get next 2880 byte data buffer 'eof' - check for end of tape file 'write'- write 2880 byte data buffer 'woef' - empty buffer and write end-of-file unit - tape unit number bitpix - bits/per data element (used to control byte swapping) (required for 'read' and 'write') (for 'init' command this parameter gives the blocking factor, number of 2880 byte records per tape record. if not supplied 1 is assumed) data - 2880 byte data array if 'write' command OUTPUTS: data - 2880 byte data array if 'read' command status is returned as the function value with the following meanings. 'init' = 1 'read' = !err returned by taprd 'write' = 1 'eof' = 1 if at end of file 0 if not at end of file 'weof' = 1 COMMON BLOCKS QFITSTAPE HISTORY Version 1 D. Lindler Nov 1986 Converted to IDL Version 2. M. Greason, STX, June 1990. Recognize BITPIX = -32 and BITPIX = -64 W. Landsman April 1992 Converted to IDL V5.0 W. Landsman September 1997(See fitstape.pro)
FITS_CD_FIX
[Previous Routine] [Next Routine] [List of Routines]NAME: FITS_CD_FIX PURPOSE: Convert from the representation of the CD matrix in a FITS header with an underscore (e.g. CDn_m) to that with all integers (e.g. CD00n00m). According to the proposed World Coordinate System standard by Griesen and Calabretta, the CD00n00m form is to be preferred and does not include the plate scale, so that CDELT* keywords are also needed. The CD1_1 form (used in IRAF) includes the plate scale (CDELT) factor. Because of past confusion as to which form to use, it will sometimes be necessary to convert from one form to the other. CALLING SEQUENCE: FITS_CD_FIX, Hdr, [/REVERSE] INPUT-OUTPUT: HDR - FITS header, 80 x N string array. If the header does not contain the CDn_m keywords then it is left unmodified. Other- wise the CDn_m keywords are removed and the CD00n00m keywords inserted (with the same values). OPTIONAL KEYWORD INPUT REVERSE - If this keyword is set and non-zero, then the process is reversed, i.e. CD00n00m keywords are removed from the header and CDn_m keywords are inserted. REVISION HISTORY: Written W. Landsman Feb 1990 Major rewrite Feb 1994 Converted to IDL V5.0 W. Landsman September 1997(See fits_cd_fix.pro)
FITS_CLOSE
[Previous Routine] [Next Routine] [List of Routines]*NAME: FITS_CLOSE *PURPOSE: Close a FITS data file *CATEGORY: INPUT/OUTPUT *CALLING SEQUENCE: FITS_CLOSE,fcb *INPUTS: FCB: fits control block returned by FITS_OPEN. *KEYWORD PARAMETERS: /NO_ABORT: Set to return to calling program instead of a RETALL when an I/O error is encountered. If set, the routine will return with !err=-1 and a message in the keyword MESSAGE. If not set, FITS_CLOSE will print the message and issue a RETALL MESSAGE = value: Output error message *EXAMPLES: Open a FITS file, read some data, and close it with FITS_CLOSE FITS_OPEN,'infile',fcb FITS_READ,fcb,data FITS_READ,fcb,moredata FITS_CLOSE,fcb *HISTORY: Written by: D. Lindler August, 1995 Converted to IDL V5.0 W. Landsman September 1997(See fits_close.pro)
FITS_HELP
[Previous Routine] [Next Routine] [List of Routines]*NAME: FITS_HELP *PURPOSE: To print a summary of the primary data units and extensions in a FITS file. *CATEGORY: INPUT/OUTPUT *CALLING SEQUENCE: FITS_HELP,filename_or_fcb *INPUTS: FILENAME_OR_FCB - name of the fits file or the FITS Control Block (FCB) returned by FITS_OPEN. *OUTPUTS: a summary of the fits file is printed. *EXAMPLES: FITS_HELP,'myfile.fits' FITS_OPEN,'anotherfile.fits',fcb FITS_HELP,fcb *PROCEDURES USED: FITS_OPEN, FITS_CLOSE *HISTORY: Written by: D. Lindler August, 1995 Converted to IDL V5.0 W. Landsman September 1997(See fits_help.pro)
FITS_INFO
[Previous Routine] [Next Routine] [List of Routines]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 CALLING SEQUENCE: FITS_INFO, Filename, [ /SILENT , TEXTOUT = , N_ext = ] INPUT: Filename: Scalar or vector string giving the name of the FITS file(s) Can include wildcards such as '*.fits' OPTIONAL INPUT KEYWORDS: SILENT - This key word will suppress display of the file description on the terminal TEXTOUT - specifies output device. 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, see TEXTOPEN textout=7 append to existing file textout = filename (default extension of .prt) If TEXTOUT is not supplied, then !TEXTOUT is used OPTIONAL OUTPUT KEYWORD: N_ext - Returns an integer scalar giving the number of extensions in the FITS file 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) See the procedure RDFITS_STRUCT for an example of the use of this common block 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(), STRN(), SXPAR(), TEXTOPEN, TEXTCLOSE SYSTEM VARIABLES: The non-standard system variables !TEXTOUT and !TEXTUNIT must be defined before calling FITS_INFO. DEFSYSV,'!TEXTOUT',1 DEFSYSV,'!TEXTUNIT',0 One way to define these is to call the procedure ASTROLIB. 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 (See fits_info.pro)
FITS_OPEN
[Previous Routine] [Next Routine] [List of Routines]*NAME: FITS_OPEN *PURPOSE: Opens a FITS (Flexible Image Transport System) data file. *CATEGORY: INPUT/OUTPUT *CALLING SEQUENCE: FITS_OPEN, filename, fcb *INPUTS: filename : name of the FITS file to open *OUTPUTS: fcb : (FITS Control Block) a IDL structure containing information concerning the file. It is an input to FITS_READ, FITS_WRITE and FITS_CLOSE *KEYWORD PARAMETERS: /WRITE: Set this keyword to open a new file for writing. /APPEND: Set to append to an existing file. /NO_ABORT: Set to return to calling program instead of a RETALL when an I/O error is encountered. If set, the routine will return with !err=-1 and a message in the keyword MESSAGE. If not set, FITS_OPEN will print the message and issue a RETALL MESSAGE = value: Output error message /HPRINT - print headers with routine HPRINT as they are read. (useful for debugging a strange file) *NOTES: The output FCB should be passed to the other FITS routines (FITS_OPEN, FITS_READ, FITS_HELP, and FITS_WRITE). It has the following structure when FITS_OPEN is called without /WRITE or /APPEND keywords set. FCB.FILENAME - name of the input file .UNIT - unit number the file is opened to .NEXTEND - number of extensions in the file. .XTENSION - string array giving the extension type for each extension. .EXTNAME - string array giving the extension name for each extension. (null string if not defined the extension) .EXTVER - vector of extension version numbers (0 if not defined) .EXTLEVEL - vector of extension levels (0 if not defined) .GCOUNT - vector with the number of groups in each extension. .PCOUNT - vector with parameter count for each group .BITPIX - BITPIX for each extension with values 8 byte data 16 short word integers 32 long word integers -32 IEEE floating point -64 IEEE double precision floating point .NAXIS - number of axes for each extension. (0 for null data units) .AXIS - 2-D array where axis(*,N) gives the size of each axes for extension N .START_HEADER - vector giving the starting byte in the file where each extension header begins .START_DATA - vector giving the starting byte in the file where the data for each extension begins .HMAIN - keyword parameters (less standard required FITS keywords) for the primary data unit. .OPEN_FOR_WRITE - flag (0= open for read, 1=open for write, 2=open for update) .LAST_EXTENSION - last extension number read. .RANDOM_GROUPS - 1 if the PDU is random groups format, 0 otherwise When FITS open is called with the /WRITE or /APPEND option, FCB contains: FCB.FILENAME - name of the input file .UNIT - unit number the file is opened to .NEXTEND - number of extensions in the file. .OPEN_FOR_WRITE - flag (1=open for write, 2=open for update) *EXAMPLES: Open a FITS file for reading: FITS_OPEN,'myfile.fits',fcb Open a new FITS file for output: FITS_OPEN,'newfile.fits',fcb,/write PROCEDURES USED: HPRINT, SXDELPAR, SXPAR() *HISTORY: Written by: D. Lindler August, 1995 July, 1996 NICMOS Modified to allow open for overwrite to allow primary header to be modified DJL Oct. 15, 1996 corrected to properly extend AXIS when more than 100 extensions present Converted to IDL V5.0 W. Landsman September 1997(See fits_open.pro)
FITS_READ
[Previous Routine] [Next Routine] [List of Routines]*NAME: FITS_READ *PURPOSE: To read a FITS file. *CATEGORY: INPUT/OUTPUT *CALLING SEQUENCE: FITS_READ, filename_or_fcb, data [,header, group_par] *INPUTS: FILENAME_OR_FCB - this parameter can be the FITS Control Block (FCB) returned by FITS_OPEN or the file name of the FITS file. If a file name is supplied, FITS_READ will open the file with FITS_OPEN and close the file with FITS_CLOSE before exiting. When multiple extensions are to be read from the file, it is more efficient for the user to call FITS_OPEN and leave the file open until all extensions are read. *OUTPUTS: DATA - data array. If /NOSCALE is specified, BSCALE and BZERO (if present in the header) will not be used to scale the data. If Keywords FIRST and LAST are used to read a portion of the data or the heap portion of an extension, no scaling is done and data is returned as a 1-D vector. The user can use the IDL function REFORM to convert the data to the correct dimensions if desired. If /DATA_ONLY is specified, no scaling is done. HEADER - FITS Header. If an extension is read, and the /NO_PDU keyword parameter is not supplied, the primary data unit header and the extension header will be combined. The header will have the form:BEGIN MAIN HEADER -------------------------------- BEGIN EXTENSION HEADER --------------------------- 1. (Default=0, the first group) NaNvalue - On non-IEEE floating point machines, it gives the value to place into words with IEEE NaN. ENUM - Output extensiont number that was read. *NOTES: Determination or which extension to read. case 1: EXTEN_NO specified. EXTEN_NO will give the number of the extension to read. The primary data unit is refered to as extension 0. If EXTEN_NO is specified, XTENSION, EXTNAME, EXTVER, and EXTLEVEL parameters are ignored. case 2: if EXTEN_NO is not specified, the first extension with the specified XTENSION, EXTNAME, EXTVER, and EXTLEVEL will be read. If any of the 4 parameters are not specified, they will not be used in the search. Setting EXTLEVEL=0, EXTVER=0, EXTNAME='', or XTENSION='' is the same as not supplying them. case 3: if none of the keyword parameters, EXTEN_NO, XTENSION, EXTNAME, EXTVER, or EXTLEVEL are supplied. FITS_READ will read the next extension in the file. If the primary data unit (PDU), extension 0, is null, the first call to FITS_READ will read the first extension of the file. The only way to read a null PDU is to use EXTEN_NO = 0. If FIRST and LAST are specified, the data is returned without applying any scale factors (BSCALE and BZERO) and the data is returned in a 1-D vector. This will allow you to read any portion of a multiple dimension data set. Once returned, the IDL function REFORM can be used to place the correct dimensions on the data. IMPLICIT IMAGES: FITS_READ will construct an implicit image for cases where NAXIS=0 and the NPIX1, NPIX2, and PIXVALUE keywords are present. The output image will be: image = replicate(PIXVALUE,NPIX1,NPIX2) *EXAMPLES: Read the primary data unit of a FITS file, if it is null read the first extension: FITS_READ, 'myfile.fits', data, header Read the first two extensions of a FITS file and the extension with EXTNAME = 'FLUX' and EXTVER = 4 FITS_OPEN, 'myfile.fits', fcb FITS_READ, fcb,data1, header2, exten_no = 1 FITS_READ, fcb,data1, header2, exten_no = 2 FITS_READ, fcb,data3, header3, extname='flux', extver=4 FITS_CLOSE, fcb Read the sixth image in a data cube for the fourth extension. FITS_OPEN, 'myfile.fits', fcb image_number = 6 ns = fcb.axis(0,4) nl = fcb.axis(1,4) i1 = (ns*nl)*(image_number-1) i2 = i2 + ns*nl-1 FITS_READ,fcb,image,header,first=i1,last=i2 image = reform(image,ns,nl,/overwrite) FITS_CLOSE *PROCEDURES USED: IEEE_TO_HOST, SXADDPAR, SXDELPAR, SXPAR() *HISTORY: Written by: D. Lindler, August 1995 Converted to IDL V5.0 W. Landsman September 1997 (See fits_read.pro)
FITS_WRITE
[Previous Routine] [Next Routine] [List of Routines]*NAME: FITS_WRITE *PURPOSE: To write a FITS primary data unit or extension. *CATEGORY: INPUT/OUTPUT *CALLING SEQUENCE: FITS_WRITE, filename_or_fcb, data, [header_in] *INPUTS: FILENAME_OR_FCB: name of the output data file or the FITS control block returned by FITS_OPEN (called with the /WRITE or /APPEND) parameters. *OPTIONAL INPUTS: DATA: data array to write. If not supplied or set to a scalar, a null image is written. HEADER_IN: FITS header keyword. If not supplied, a minimal basic header will be created. Required FITS keywords, SIMPLE, BITPIX, XTENSION, NAXIS, ... are added by FITS_WRITE and do not need to be supplied with the header. If supplied, thier values will be updated as necessary to reflect DATA. *KEYWORD PARAMETERS: XTENSION: type of extension to write (Default="IMAGE"). If not supplied, it will be taken from HEADER_IN. If not in either place, the default is "IMAGE". This parameter is ignored when writing the primary data unit. EXTNAME: EXTNAME for the extension. If not supplied, it will be taken from HEADER_IN. If not supplied and not in HEADER_IN, no EXTNAME will be written into the output extension. EXTVER: EXTVER for the extension. If not supplied, it will be taken from HEADER_IN. If not supplied and not in HEADER_IN, no EXTVER will be written into the output extension. EXTLEVEL: EXTLEVEL for the extension. If not supplied, it will be taken from HEADER_IN. If not supplied and not in HEADER_IN, no EXTLEVEL will be written into the output extension. NaNvalue: data value in DATA to be replaced with IEEE NaN in the output file. /NO_ABORT: Set to return to calling program instead of a RETALL when an I/O error is encountered. If set, the routine will return with !err=-1 and a message in the keyword MESSAGE. If not set, FITS_READ will print the message and issue a RETALL MESSAGE: value of the error message for use with /NO_ABORT HEADER: actual output header written to the FITS file. /NO_DATA: Set if you only want FITS_WRITE to write a header. The header supplied will be written without modification and the user is expected to write the data using WRITEU to unit FCB.UNIT. When FITS_WRITE is called with /NO_DATA, the user is responsible for the validity of the header, and must write the correct amount and format of the data. When FITS_WRITE is used in this fashion, it will pad the data from a previously written extension to 2880 blocks before writting the header. *NOTES: If the first call to FITS_WRITE is an extension, FITS_WRITE will automatically write a null image as the primary data unit. Keywords and history in the input header will be properly separated into the primary data unit and extension portions when constructing the output header (See FITS_READ for information on the internal Header format which separates the extension and PDU header portions). *EXAMPLES: Write an IDL variable to a FITS file with the minimal required header. FITS_WRITE,'newfile.fits',ARRAY Write the same array as an image extension, with a null Primary data unit. FITS_WRITE,'newfile.fits',ARRAY,xtension='IMAGE' Write 4 image extensions to the same file. FITS_OPEN,'newfile.fits',fcb FITS_WRITE,fcb,data1,extname='FLUX',extver=1 FITS_WRITE,fcb,err1,extname'ERR',extver=1 FITS_WRITE,fcb,data2,extname='FLUX',extver=2 FITS_WRITE,fcb,err2,extname='ERR',extver=2 FITS_CLOSE,FCB *PROCEDURES USED: FITS_OPEN, SXADDPAR, SXDELPAR, SXPAR() *HISTORY: Written by: D. Lindler August, 1995 Work for variable length extensions W. Landsman August 1997 Converted to IDL V5.0 W. Landsman September 1997(See fits_write.pro)
FLEGENDRE
[Previous Routine] [Next Routine] [List of Routines]NAME: FLEGENDRE PURPOSE: Compute the first M terms in a Legendre polynomial expansion. EXPLANATION: Meant to be used as a supplied function to SVDFIT. This procedure became partially obsolete in IDL V5.0 with the introduction of the /LEGENDRE keyword to SVDFIT and the associated SVDLEG function. However, note that, unlike SVDLEG, FLEGENDRE works on vector values of X. CALLING SEQUENCE: result = FLEGENDRE( X, M) INPUTS: X - the value of the independent variable, scalar or vector M - number of term of the Legendre expansion to compute, integer scalar OUTPUTS: result - (N,M) array, where N is the number of elements in X and M is the order. Contains the value of each Legendre term for each value of X EXAMPLE: (1) If x = 2.88 and M = 3 then IDL> print, flegendre(x,3) ==> [1.00, 2.88, 11.9416] This result can be checked by explicity computing the first 3 Legendre terms, 1.0, x, 0.5*( 3*x^2 -1) (2) Find the coefficients to an M term Legendre polynomial that gives the best least-squares fit to a dataset (x,y) IDL> coeff = SVDFIT( x,y,M,func='flegendre') The coefficients can then be supplied to the function POLYLEG to compute the best YFIT values for any X. METHOD: The recurrence relation for the Legendre polynomials is used to compute each term. Compare with the function FLEG in "Numerical Recipes" by Press et al. (1992), p. 674 REVISION HISTORY: Written Wayne Landsman Hughes STX April 1995 Converted to IDL V5.0 W. Landsman September 1997(See flegendre.pro)
FLUX2MAG
[Previous Routine] [Next Routine] [List of Routines]NAME: FLUX2MAG PURPOSE: Convert from flux (ergs/s/cm^2/A) to magnitudes. EXPLANATION: Use MAG2FLUX() for the opposite direction. CALLING SEQUENCE: mag = flux2mag( flux, [ zero_pt ] ) INPUTS: flux - scalar or vector flux vector OPTIONAL INPUT: zero_pt - scalar giving the zero point level of the magnitude. If not supplied then zero_pt = 21.1 (Code et al 1976) OUTPUT: mag - magnitude vector (mag = -2.5*alog10(flux) - zero_pt) REVISION HISTORY: Written J. Hill STX Co. 1988 Converted to IDL V5.0 W. Landsman September 1997(See flux2mag.pro)
FORPRINT
[Previous Routine] [Next Routine] [List of Routines]NAME: FORPRINT PURPOSE Print a set of vectors by looping over each index value. EXPLANATION: If W and F are equal length vectors, then the statement IDL> forprint, w, f is equivalent to IDL> for i = 0L, N_elements(w)-1 do print,w[i],f[i] CALLING SEQUENCE: forprint, v1,[ v2, v3, v4,....v18, FORMAT = , TEXTOUT = ,STARTLINE =, NUMLINE =, /SILENT ] INPUTS: V1,V2,...V18 - Arbitary IDL vectors. If the vectors are not of equal length then the number of rows printed will be equal to the length of the smallest vector. Up to 18 vectors can be supplied. OPTIONAL KEYWORD INPUTS: TEXTOUT - Controls print output device, defaults to !TEXTOUT 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) textout=7 Append to .prt file if it exists FORMAT - Scalar format string as in the PRINT procedure. The use of outer parenthesis is optional. Ex. - format="(F10.3,I7)" This program will automatically remove a leading "$" from incoming format statments. Ex. - "$(I4)" would become "(I4)". STARTLINE - Integer scalar specifying the first line in the arrays to print. Default is STARTLINE = 1, i.e. start at the beginning of the arrays. SILENT - Normally, with a hardcopy output (TEXTOUT > 2), FORPRINT will add a time stamp to the output file. If the SILENT keyword is set and non-zero, then this time stamp is suppressed. OUTPUTS: None SYSTEM VARIABLES: If keyword TEXTOUT is not used, the default is the nonstandard keyword !TEXTOUT. If you want to use FORPRINT to write more than once to the same file, or use a different file name then set TEXTOUT=5, and open and close then file yourself (see documentation of TEXTOPEN for more info). One way to add the non-standard system variables !TEXTOUT and !TEXTUNIT is to use the procedure ASTROLIB EXAMPLE: Suppose W,F, and E are the wavelength, flux, and epsilon vectors for an IUE spectrum. Print these values to a file 'output.dat' in a nice format. IDL> fmt = '(F10.3,1PE12.2,I7)' IDL> forprint, F = fmt, w, f, e, TEXT = 'output.dat' PROCEDURES CALLED: DATATYPE(), TEXTOPEN, TEXTCLOSE REVISION HISTORY: Written W. Landsman April, 1989 Keywords textout and format added, J. Isensee, July, 1990 Made use of parenthesis in FORMAT optional W. Landsman May 1992 Added STARTLINE keyword W. Landsman November 1992 Set up so can handle 18 input vectors. J. Isensee, HSTX Corp. July 1993 Handle string value of TEXTOUT W. Landsman, HSTX September 1993 Added NUMLINE keyword W. Landsman, HSTX February 1996 Added SILENT keyword W. Landsman, RSTX, April 1998 Converted to IDL V5.0 W. Landsman, RSTX, April, 1998 (See forprint.pro)
FREBIN
[Previous Routine] [Next Routine] [List of Routines]NAME: FREBIN PURPOSE: Shrink or expand the size of an array an arbitary amount using interpolation EXPLANATION: FREBIN is an alternative to CONGRID or REBIN. Like CONGRID it allows expansion or contraction by an arbitary amount. (REBIN requires integral factors of the original image size.) Like REBIN it conserves flux by ensuring that each input pixel is equally represented in the output array. CALLING SEQUENCE: result = FREBIN( image, nsout, nlout, [ /TOTAL] ) INPUTS: image - input image, 1-d or 2-d numeric array nsout - number of samples in the output image, integer scalar OPTIONAL INPUT: nlout - number of lines in the output image, integer scalar If not supplied, then set equal to 1 OPTIONAL KEYWORD INPUTS: /total - if set, the output pixels will be the sum of pixels within the appropriate box of the input image. Otherwise they will be the average. Use of the /TOTAL keyword conserves surface flux. OUTPUTS: The resized image is returned as the function result. If the input image is of type DOUBLE or FLOAT then the resized image is of the same type. If the input image is BYTE, INTEGER or LONG then the output image is usually of type FLOAT. The one exception is expansion by integral amount (pixel duplication), when the output image is the same type as the input image. EXAMPLE: Suppose one has an 800 x 800 image array, im, that must be expanded to a size 850 x 900 while conserving surface flux: IDL> im1 = frebin(im,850,900,/total) im1 will be a 850 x 900 array, and total(im1) = total(im) NOTES: If the input image sizes are a multiple of the output image sizes then FREBIN is equivalent to the IDL REBIN function for compression, and simple pixel duplication on expansion. PROCEDURE CALLS: DATATYPE() HISTORY: Adapted from May 1998 STIS version, written D. Lindler, ACC Added /NOZERO, use REBIN,/SAMPLE instead of CONGRID, June 98 W. Landsman(See frebin.pro)
FTAB_DELROW
[Previous Routine] [Next Routine] [List of Routines]NAME: FTAB_DELROW PURPOSE: Delete rows of data from a FITS ASCII or binary table extension CALLING SEQUENCE: ftab_delrow, filename, rows, EXTEN_NO =, NEWFILE = ] INPUTS-OUPUTS filename - scalar string giving name of the FITS file containing an ASCII or binary table extension. rows - scalar or vector, specifying the row numbers to delete First row has index 0. If a vector, it will be sorted and duplicates will be removed OPTIONAL KEYWORD INPUTS: EXTEN_NO - scalar integer specifying which extension number to process Default is to process the first extension NEWFILE - scalar string specifying the name of the new output FITS file FTAB_DELROW will prompt for this parameter if not supplied EXAMPLE: Compress the first extension of a FITS file 'test.fits' to include only non-negative values in the 'FLUX' column ftab_ext,'test.fits','flux',flux ;Obtain original flux vector bad = where(flux lt 0) ;Find negative fluxes ftab_delrow,'test.fits',bad,new='test1.fits' ;Delete specified rows RESTRICTIONS: Does not work for variable length binary tables PROCEDURES USED: FITS_CLOSE, FITS_OPEN, FITS_READ, FITS_WRITE, FTDELROW, TBDELROW REVISION HISTORY: Written W. Landsman STX Co. August, 1997 Converted to IDL V5.0 W. Landsman September 1997(See ftab_delrow.pro)
FTAB_EXT
[Previous Routine] [Next Routine] [List of Routines]NAME: FTAB_EXT PURPOSE: Routine to extract columns from a FITS (binary or ASCII) table CALLING SEQUENCE: FTAB_EXT, name, columns, v1, [v2,..,v9, ROWS=, EXTEN_NO= ] INPUTS: name - name of a FITS file containing a (binary or ASCII) table extension, scalar string columns - table columns to extract. Can be either (1) String with names separated by commas (2) Scalar or vector of column numbers OUTPUTS: v1,...,v9 - values for the columns OPTIONAL INPUT KEYWORDS: ROWS - scalar or vector giving row number(s) to extract Row numbers start at 0. If not supplied or set to -1 then values for all rows are returned EXTEN_NO - Extension number to process. If not set, then data is extracted from the first extension in the file (EXTEN_NO=1) EXAMPLES: Read wavelength and flux vectors from the first extension of a FITS file, 'spec.fit'. Using FTAB_HELP,'spec.fit' we find that this information is in columns named 'WAVELENGTH' and 'FLUX' (in columns 1 and 2). To read the data IDL> ftab_ext,'spec.fit','wavelength,flux',w,f or IDL> ftab_ext,'spec.fit',[1,2],w,f PROCEDURES CALLED: FITS_READ, FITS_CLOSE, FTGET(), GETTOK(), TBINFO, TBGET() HISTORY: version 1 W. Landsman August 1997 Converted to IDL V5.0 W. Landsman September 1997(See ftab_ext.pro)
FTAB_HELP
[Previous Routine] [Next Routine] [List of Routines]NAME: FTAB_HELP PURPOSE: Describe the columns of a FITS binary or ASCII table extension. CALLING SEQUENCE: FTAB_HELP, filename, [ EXTEN_No = , TEXTOUT= ] or FTAB_HELP, fcb, [EXTEN_No=, TEXTOUT= ] INPUTS: filename - scalar string giving name of the FITS file. Under Unix, FTAB_HELP also works for gzip or Unix compressed FITS files or fcb - FITS control block returned by a previous call to FITS_OPEN OPTIONAL KEYWORD INPUTS: EXTEN_NO - integer scalar specifying which FITS extension to read. Default is to display the first FITS extension. TEXTOUT - scalar number (0-7) or string (file name) determining output device (see TEXTOPEN). Default is TEXTOUT=1, output to the user's terminal PROCEDURE CALLS: FITS_READ, FITS_CLOSE, FITS_OPEN, FTHELP, TBHELP, TEXTOPEN, TEXTCLOSE EXAMPLE: Describe the columns in the second extension of a FITS file spec.fits and write the results to a file 'spec2.lis' IDL> ftab_help,'spec.fits',exten=2,t='spec2.lis' SYSTEM VARIABLES: Uses the non-standard system variables !TEXTOUT and !TEXTUNIT which must be defined (e.g. with ASTROLIB) before compilation HISTORY: version 1 W. Landsman August 1997 Converted to IDL V5.0 W. Landsman September 1997 Corrected documentation W. Landsman September 1997(See ftab_help.pro)
FTAB_PRINT
[Previous Routine] [Next Routine] [List of Routines]NAME: FTAB_PRINT PURPOSE: Print the contents of a FITS (binary or ASCII) table extension. EXPLANATION: User can specify which rows or columns to print CALLING SEQUENCE: FTAB_PRINT, filename, columns, rows, [ TEXTOUT=, FMT=, EXTEN_NO=] INPUTS: filename - scalar string giving name of a FITS file containing a binary or ASCII table 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 (beginning with 0). If not supplied or set to scalar, -1, then all rows are printed. OPTIONAL KEYWORD INPUT: EXTEN_NO - Extension number to read. If not set, then the first extension is printed (EXTEN_NO=1) TEXTOUT - scalar number (0-7) or string (file name) determining output device (see TEXTOPEN). Default is TEXTOUT=1, output to the user's terminal FMT = Format string for print display (binary tables only). If not supplied, then any formats in the TDISP keyword fields will be used, otherwise IDL default formats. For ASCII tables, the format used is always as stored in the FITS table. EXAMPLE: Print all rows of the first 5 columns of the first extension of the file 'wfpc.fits' IDL> ftab_print,'wfpc.fits',indgen(5)+1 SYSTEM VARIABLES: Uses the non-standard system variables !TEXTOUT and !TEXTUNIT which must be defined (e.g. with ASTROLIB) prior to compilation. HISTORY: version 1 W. Landsman August 1997 Converted to IDL V5.0 W. Landsman September 1997(See ftab_print.pro)
FTADDCOL
[Previous Routine] [Next Routine] [List of Routines]NAME: FTADDCOL PURPOSE: Routine to add a field to a FITS ASCII table CALLING SEQUENCE: ftaddcol, h, tab, name, idltype, [ tform, tunit, tscal, tzero, tnull ] INPUTS: h - FITS table header. It will be updated as appropriate tab - FITS table array. Number of columns will be increased if neccessary. name - field name idltype - idl data type (as returned by SIZE function) for field, For string data (type=7) use minus the string length. OPTIONAL INPUTS: tform - format specification 'qww.dd' where q = A, I, E, or D tunit - string giving physical units for the column. tscal - scale factor tzero - zero point for field tnull - null value for field Use '' as the value of tform,tunit,tscal,tzero,tnull if you want the default or no specification of them in the table header. OUTPUTS: h,tab - updated to allow new column of data PROCEDURES USED: FTINFO, FTSIZE, GETTOK(), SXADDPAR HISTORY: version 1 D. Lindler July, 1987 Converted to IDL V5.0 W. Landsman September 1997(See ftaddcol.pro)
FTCREATE
[Previous Routine] [Next Routine] [List of Routines]NAME: FTCREATE PURPOSE: Create a new (blank) FITS ASCII table and header with specified size. CALLING SEQUENCE: ftcreate, maxcols, maxrows, h, tab INPUTS: maxcols - number of character columns allocated, integer scalar maxrows - maximum number of rows allocated, integer scalar OUTPUTS: h - FITS header, string array tab - empty table, byte array HISTORY: version 1 D. Lindler July. 87 21-Sep-88: Because the degenerative dimension is deleted in Sun IDL, this procedure has been modified to create table with at least two rows. If this isn't done, the other FT routines choke on a table of one row. 24-Oct-88: Changed length of header strings from 81 to 80. This conforms to the latest format for FITS header strings. The 81 character format was dropped due to problems it caused when data was transferred back to the VAX. Converted to IDL V5.0 W. Landsman September 1997(See ftcreate.pro)
FTDELCOL
[Previous Routine] [Next Routine] [List of Routines]NAME: FTDELCOL PURPOSE: Delete a column of data from a FITS table CALLING SEQUENCE: ftdelcol, 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: Suppose it has been determined that the F7.2 format used for a field FLUX in a FITS table is insufficient. The old column must first be deleted before a new column can be written with a new format. flux = FTGET(h,tab,'FLUX') ;Save the existing values FTDELCOL,h,tab,'FLUX' ;Delete the existing column FTADDCOL,h,tab,'FLUX',8,'F9.2' ;Create a new column with larger format FTPUT,h,tab,'FLUX',0,flux ;Put back the original values REVISION HISTORY: Written W. Landsman STX Co. August, 1988 Adapted for IDL Version 2, J. Isensee, July, 1990 Converted to IDL V5.0 W. Landsman September 1997(See ftdelcol.pro)
FTDELROW
[Previous Routine] [Next Routine] [List of Routines]NAME: FTDELROW PURPOSE: Delete a row of data from a FITS table CALLING SEQUENCE: ftdelrow, 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 This vector will be sorted and duplicates removed by FTDELROW EXAMPLE: Compress a table to include only non-negative flux values flux = FTGET(h,tab,'FLUX') ;Obtain original flux vector bad = where(flux lt 0) ;Find negative fluxes FTDELROW,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 Converted to IDL V5.0 W. Landsman September 1997(See ftdelrow.pro)
FTGET
[Previous Routine] [Next Routine] [List of Routines]NAME: FTGET PURPOSE: Function to return value(s) from specified column in a FITS ASCII table CALLING SEQUENCE values = FTGET( h, tab, field, [ rows, nulls ] ) INPUTS: h - FITS ASCII extension header (e.g. as returned by FITS_READ) tab - FITS ASCII table array (e.g. as returned by FITS_READ) 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. EXAMPLE: Read the columns labeled 'WAVELENGTH' and 'FLUX' from the second (ASCII table) extension of a FITS file 'spectra.fit' IDL> fits_read,'spectra.fit',tab,htab,exten=2 ;Read 2nd extension IDL> w = ftget(tab,htab,'wavelength') ;Wavelength vector IDL> f = ftget(tab,htab,'flux') ;Flux vector NOTES: (1) Use the higher-level procedure FTAB_EXT to extract vectors directly from the FITS file. (2) Use FTAB_HELP or FTHELP to determine the columns in a particular ASCII table. HISTORY: coded by D. Lindler July, 1987 Always check for null values W. Landsman August 1990 More informative error message W. Landsman Feb. 1996 Converted to IDL V5.0 W. Landsman September 1997(See ftget.pro)
FTHELP
[Previous Routine] [Next Routine] [List of Routines]NAME: FTHELP PURPOSE: Routine to print a description of a FITS ASCII table extension CALLING SEQUENCE: FTHELP, H, [ TEXTOUT = ] INPUTS: H - FITS header for ASCII table extension, string array OPTIONAL INPUT KEYWORD TEXTOUT - scalar number (0-7) or string (file name) determining output device (see TEXTOPEN). Default is TEXTOUT=1, output to the user's terminal NOTES: FTHELP checks that the keyword XTENSION equals 'TABLE' in the FITS header. SYSTEM VARIABLES: Uses the non-standard system variables !TEXTOUT and !TEXTUNIT which must be defined (e.g. with ASTROLIB) prior to compilation. PROCEDURES USED: REMCHAR, SXPAR(), TEXTOPEN, TEXTCLOSE, ZPARCHECK HISTORY: version 1 W. Landsman Jan. 1988 Add TEXTOUT option, cleaner format W. Landsman September 1991 TTYPE value can be longer than 8 chars, W. Landsman August 1995 Converted to IDL V5.0 W. Landsman September 1997(See fthelp.pro)
FTHMOD
[Previous Routine] [Next Routine] [List of Routines]NAME: FTHMOD PURPOSE: Procedure to modify header information for a specified field in a FITS table. CALLING SEQUENCE: fthmod, h, field, parameter, value INPUT: h - FITS header for the table field - field name of number parameter - string name of the parameter to modify. Choices include: TTYPE - field name TUNIT - physical units for field (eg. 'ANGSTROMS') TNULL - null value (string) for field, (eg. '***') TFORM - format specification for the field TSCAL - scale factor TZERO - zero offset User should be aware that the validity of the change is not checked. Unless you really know what you are doing, this routine should only be used to change field names, units, or another user specified parameter. value - new value for the parameter. Refer to the FITS table standards documentation for valid values. METHOD: The header keywordis modified with the new value. HISTORY: version 1, D. Lindler July 1987 Converted to IDL V5.0 W. Landsman September 1997 (See fthmod.pro)
FTINFO
[Previous Routine] [Next Routine] [List of Routines]NAME: FTINFO PURPOSE: Procedure to return information on the specified field in a FITS ASCII table. CALLING SEQUENCE: ftinfo,h,field,tbcol,width,idltype,tunit,tscal,tzero,tnull, tform,ttype INPUTS: h - FITS ASCII table header field - field name or field number (beginning at 1) OUTPUTS: tbcol - starting column position in bytes width - width of the field in bytes idltype - idltype of field. 7 - string, 4- real*4, 3-integer, 5-real*8 tunit - string unit numbers tscal - scale factor tzero - zero point for field tnull - null value for the field tform - format for the field ttype - field name SIDE EFFECTS: !err is set to the field number. If the specified field is not in the table then !err is set to -1. HISTORY: D. Lindler July, 1987 Converted to IDL V5.0 W. Landsman September 1997(See ftinfo.pro)
FTKEEPROW
[Previous Routine] [Next Routine] [List of Routines]NAME: FTKEEPROW PURPOSE: Subscripts (and reorders) a FITS table. A companion piece to FTDELROW. CALLING SEQUENCE: ftkeeprow, h, tab, subs INPUT PARAMETERS: h = FITS table header array tab = FITS table data array subs = subscript array of FITS table rows. Works like any other IDL subscript array (0 based, of course). OUTPUT PARAMETERS: h and tab are modified MODIFICATION HISTORY: Written by R. S. Hill, ST Sys. Corp., 2 May 1991. Converted to IDL V5.0 W. Landsman September 1997(See ftkeeprow.pro)
FTPRINT
[Previous Routine] [Next Routine] [List of Routines]NAME: FTPRINT PURPOSE: Procedure to print specified columns and rows of a FITS table CALLING SEQUENCE: FTPRINT, 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 OPTIONAL INPUT 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: ftprint,h,tab,'STAR ID,RA,DEC' ;print id,ra,dec for all stars ftprint,h,tab,[2,3,4],indgen(100) ;print columns 2-4 for ;first 100 stars ftprint,h,tab,text="STARS.DAT" ;Convert entire FITS table to ;an ASCII file named STARS.DAT PROCEDURES USED: FTSIZE, FTINFO, TEXTOPEN, TEXTCLOSE 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 Accept undefined values of rows, columns W. Landsman August 1997 Converted to IDL V5.0 W. Landsman September 1997(See ftprint.pro)
FTPUT
[Previous Routine] [Next Routine] [List of Routines]NAME: FTPUT PURPOSE: Procedure to add or update a field in an FITS ASCII table CALLING SEQUENCE: FTPUT, htab, tab, field, row, values, [ nulls ] INPUTS: htab - FITS ASCII table header string array tab - FITS ASCII table array (e.g. as read by READFITS) field - string field name or integer field number row - either a non-negative integer scalar giving starting row to update, or a non-negative integer vector specifying rows to update. FTPUT will append a new row to a table if the value of 'row' exceeds the number of rows in the tab array values - value(s) to add or update. If row is a vector then values must contain the same number of elements. OPTIONAL INPUT: nulls - null value flag of same length as values. It should be set to 1 at null value positions and 0 elsewhere. OUTPUTS: htab,tab will be updated as specified. NOTES: (1) If the specified field is not already in the table, then FTPUT will create a new column for that field using default formatting. However, FTADDCOL should be called prior to FTPUT for explicit formatting. PROCEDURES CALLED FTADDCOL, FTINFO, FTSIZE, SXADDPAR, SXPAR() HISTORY: version 1 D. Lindler July, 1987 Allow E format W. Landsman March 1992 Write in F format if E format will overflow April 1994 Update documentation W. Landsman January 1996 Allow 1 element vector W. Landsman March 1996 Adjust string length to maximum of input string array June 1997 Work for more than 32767 elements August 1997 Converted to IDL V5.0 W. Landsman September 1997(See ftput.pro)
FTSIZE
[Previous Routine] [Next Routine] [List of Routines]NAME: FTSIZE PURPOSE: Procedure to return the size of a FITS ASCII table. CALLING SEQUENCE: ftsize,h,tab,ncols,rows,tfields,ncols_all,nrows_all INPUTS: h - FITS ASCII table header, string array tab - FITS table array, 2-d byte 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 Fix for 1-row table, W. Landsman HSTX, June 1994 Converted to IDL V5.0 W. Landsman September 1997(See ftsize.pro)
FTSORT
[Previous Routine] [Next Routine] [List of Routines]NAME: FTSORT PURPOSE: Sort a FITS ASCII table according to a specified field CALLING SEQUENCE: FTSORT,H,TAB,[FIELD] ;Sort original table header and array or FTSORT,H,TAB,HNEW,TABNEW,[FIELD] ;Create new sorted header INPUTS: H - FITS header (string array) TAB - FITS table (byte array) associated with H. If less than 4 parameters are supplied, then H and TAB will be updated to contain the sorted table OPTIONAL INPUTS: FIELD - Field name used to sort the entire table. Character fields are sorted using the ASCII collating sequence. If omitted, the user will be prompted for the field name. OPTIONAL OUTPUTS: HNEW,TABNEW - Header and table containing the sorted tables RESTRICTIONS: FTSORT always sorts in order of increasing magnitude. To sort in decreasing magnitude, type TAB = REVERSE(TAB,2) after running FTSORT. SIDE EFFECTS: A HISTORY record is added to the table header. REVISION HISTORY: Written W. Landsman June, 1988 Converted to IDL V5.0 W. Landsman September 1997(See ftsort.pro)
FXADDPAR
[Previous Routine] [Next Routine] [List of Routines]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 2, William Thompson, GSFC, 5 September 1997 Fixed bug replacing strings that contain "/" character--it interpreted the following characters as a comment. Version : Version 2, 5 September 1997 Converted to IDL V5.0 W. Landsman September 1997(See fxaddpar.pro)
FXBADDCOL
[Previous Routine] [Next Routine] [List of Routines]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 [, COMMENT ]] 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"). This keyword is only needed prior to IDL Version 4.0, when the double double complex datatype was unavailable in IDL 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. TCUNI = Same. TROTA = Same. TRPIX = Same. TRVAL = Same. TDELT = Same. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBADDCOL, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... 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 2, William Thompson, GSFC, 31 May 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 4, William Thompson, GSFC, 30 December 1994 Added keyword TCUNI. Version 5, Wayne Landsman, GSFC, 12 Aug 1997 Recognize double complex IDL datatype Version : Version 5, 12 Aug 1997 Converted to IDL V5.0 W. Landsman September 1997(See fxbaddcol.pro)
FXBCLOSE
[Previous Routine] [Next Routine] [List of Routines]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 : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBCLOSE, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... 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 2, William Thompson, GSFC, 21 June 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version : Version 3, 23 June 1994 Converted to IDL V5.0 W. Landsman September 1997(See fxbclose.pro)
FXBCOLNUM
[Previous Routine] [Next Routine] [List of Routines]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 : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' Result = FXBCOLNUM( ERRMSG=ERRMSG, ... ) IF ERRMSG NE '' THEN ... 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 3, William Thompson, GSFC, 21 June 1994 Added ERRMSG keyword. Version 4, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version : Version 4, 23 June 1994 Converted to IDL V5.0 W. Landsman September 1997(See fxbcolnum.pro)
FXBCREATE
[Previous Routine] [Next Routine] [List of Routines]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 : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBCREATE, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... 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 3, William Thompson, GSFC, 21 June 1994 Added ERRMSG keyword. Version 4, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 5, Antony Bird, Southampton, 25 June 1997 Modified to allow very long tables Version : Version 5, 25 June 1997 Converted to IDL V5.0 W. Landsman September 1997(See fxbcreate.pro)
FXBDIMEN