NAME: DBBUILD PURPOSE: Build a database by appending new values for every item. The database must be opened for update (with DBOPEN) before calling DBBUILD. CALLING SEQUENCE: dbbuild, [ v1, v2, v3, v4......v25, NOINDEX = ] INPUTS: v1,v2....v25 - vectors containing values for all items in the database. V1 contains values for the first item, V2 for the second, etc. The number of vectors supplied must equal the number of items (excluding entry number) in the database. The number of elements in each vector should be the same. A multiple valued item should be dimensioned NVALUE by NENTRY, where NVALUE is the number of values, and NENTRY is the number of entries. OPTIONAL KEYWORD: NOINDEX - If this keyword is supplied and non-zero then DBBUILD will *not* create an indexed file. Useful to save time if DBBUILD is to be called several times and the indexed file need only be created on the last call STATUS - Returns a status code denoting whether the operation was successful (1) or unsuccessful (0). Useful when DBBUILD is called from within other applications. EXAMPLE: Suppose a database named STARS contains the four items NAME,RA,DEC, and FLUX. Assume that one already has the four vectors containing the values, and that the database definition (.DBD) file already exists. IDL> !PRIV=2 ;Writing to database requires !PRIV=2 IDL> dbcreate,'stars',1,1 ;Create database (.DBF) & index (.DBX) file IDL> dbopen,'stars',1 ;Open database for update IDL> dbbuild,name,ra,dec,flux ;Write 4 vectors into the database NOTES: Do not call DBCREATE before DBBUILD if you want to append entries to an existing database DBBUILD checks that each value vector matches the idl type given in the database definition (.DBD) file, and that character strings are the proper length. REVISION HISTORY: Written W. Landsman March, 1989 Added /NOINDEX keyword W. Landsman November, 1992 User no longer need supply all items W. Landsman December, 1992 Added STATUS keyword, William Thompson, GSFC, 1 April 1994
NAME: DBCIRCLE PURPOSE: Find sources in a database within a specified radius of a specified center. Database should include RA and DEC items and should previously be opened with DBOPEN CALLING SEQUENCE: list = DBCIRCLE( ra_cen, dec_cen, [radius, dis, sublist, /SILENT] ) INPUTS: RA_CEN - Right ascension of the search center in decimal HOURS, scalar DEC_CEN - Declination of the search center in decimal DEGREES, scalar RA_CEN and DEC_CEN should be in the same equinox as the currently opened catalog. OPTIONAL INPUT: RADIUS - Radius of the search field in arc minutes, scalar. DBCIRCLE prompts for RADIUS if not supplied. SUBLIST - Vector giving entry numbers in currently opened database to be searched. Default is to search all entries OUTPUTS: LIST - Vector giving entry numbers in the currently opened catalog which have positions within the specified search circle LIST is set to -1 if no sources fall within the search circle !ERR is set to the number sources found. OPTIONAL OUTPUT DIS - The distance in arcminutes of each entry specified by LIST to the search center (given by RA_CEN and DEC_CEN) OPTIONAL KEYWORD INPUT: SILENT - If this keyword is set, then DBCIRCLE will not print the number of entries found at the terminal TO_J2000 - If this keyword is set, then the entered coordinates are assumed to be in equinox B1950, and will be converted to J2000 before searching the database TO_B1950 - If this keyword is set, then the entered coordinates are assumed to be in equinox J2000, and will be converted to B1950 before searching the database NOTE: The user must determine on his own whether the database is in B1950 or J2000 coordinates. METHOD: A DBFIND search is first performed on a square area of given radius. The list is the restricted to a circular area by using GCIRC to compute the distance of each object to the field center. EXAMPLE: Find all SAO stars within 40' of the nucleus of M33 (at 1h 31m 1.67s 30d 24' 15'') IDL> dbopen,'sao' IDL> list = dbcircle( ten(1,31,1.67), ten(30,24,15), 40) REVISION HISTORY: Written W. Landsman STX January 1990 Fixed search when crossing 0h July 1990 Spiffed up code a bit October, 1991
NAME: DBCLOSE PURPOSE: procedure to close a data base file CALLING SEQUENCE: dbclose INPUTS: None OUTPUTS None SIDE EFFECTS: the data base files currently opened are closed HISTORY: version 2 D. Lindler Oct. 1987 For IDL version 2 August 1990 William Thompson, GSFC/CDS (ARC), 30 May 1994 Added support for external (IEEE) data format
NAME: DBCREATE PURPOSE: Create new data base file or modify description. A database definition file (.dbd) file must already exist. The default directory must be a ZDBASE: directory. CALLING SEQUENCE: dbcreate, name,[ newindex, newdb, maxitems] [,/external] INPUT: name- name of the data base (with no qualifier), scalar string. The description will be read from the file "NAME".dbd OPTIONAL INPUTS: newindex - if non-zero then a new index file is created, otherwise it is assumed that changes do not affect the index file. (default=0) newdb - if non-zero then a new data base file (.dbf) will be created. Otherwise changes are assumed not to affect the file's present format. maxitems - maximum number of items in data base. If not supplied then the number of items is limited to 200. OUTPUTS: none OPTIONAL KEYWORDS: external - If set, then the database is written with an external data representation. This allows the database files to be used on any computer platform, e.g. through NFS mounts, but some overhead is added to reading the files. The default is to write the data in the native format of the computer being used. SIDE EFFECTS: data base description file ZDBASE:name.dbc is created and optionally ZDBASE:name.dbf (data file) and ZDBASE.dbx (index file) if it is a new data base. RESTRICTIONS: If newdb=0 is not specified, the changes to the .dbd file can not alter the length of the records in the data base file. and may not alter positions of current fields in the file. permissible changes are: 1) utilization of spares to create a item or field 2) change in field name(s) 3) respecification of index items 4) changes in default print formats 5) change in data base title 6) changes in pointer specification to other data data bases !priv must be 2 or greater to execute this routine. HISTORY: version 2 D. Lindler OCT, 1987 Modified to work under IDL version 2. M. Greason, STX, June 1990. Modified to work under Unix D. Neill, ACC, Feb 1991. William Thompson, GSFC/CDS (ARC), 28 May 1994 Added EXTERNAL keyword.
NAME: DBDELETE PURPOSE Deletes specified entries from data base CALLING SEQUENCE: DBDELETE, list, [ name ] INPUTS: list - list of entries to be deleted, scalar or vector name - optional name of data base, scalar string. If not specified then the data base file must be previously opened for update by DBOPEN. OPERATIONAL NOTES: !PRIV must be at least 3 to execute. SIDE EFFECTS: The data base file (ZDBASE:name.DBF) is modified by removing the specified entries and reordering the remaining entry numbers accordingly (ie. if you delete entry 100, it will be replaced by entry 101 and the database will contain 1 less entry. EXAMPLE: Delete entries in a database STARS where RA=DEC = 0.0 IDL> !PRIV= 3 ;Set privileges IDL> dbopen,'STARS',1 ;Open for update IDL> list = dbfind('ra=0.0,dec=0.0') ;Obtain LIST vector IDL> dbdelete, list ;Delete specified entries from db NOTES: The procedure is rather slow because the entire database is re- created with the specified entries deleted. SYSTEM VARIABLES: Set the non-standard system variable !DEBUG = 2 to obtain additional diagnostics COMMON BLOCKS: DBCOM HISTORY Version 2 D. Lindler July, 1989 Updated documentation W. Landsman December 1992
NAME: DBEDIT PURPOSE: Interactively edit specified fields in a database. The value of each field is displayed, and the user has the option of changing or keeping the value. Widgets will be used if they are available. CALLING SEQUENCE: dbedit, list, [ items ] INPUTS: list - scalar or vector of database entry numberss. Set list = 0 to interactively add a new entry to a database. Set list = -1 to edit all entries. OPTIONAL INPUTS: items - list of items to be edited. If omitted, all fields can be edited. COMMON BLOCKS: DB_COM -- contains information about the opened database. DBW_C -- contains information intrinsic to this program. SIDE EFFECTS: Will update the database files. RESTRICTIIONS: Database must be opened for update prior to running this program. User must be running DBEDIT from an account that has write privileges to the databases. If one is editing an indexed item, then after all edits are complete, DBINDEX will be called to reindex the entire item. This may be time consuming. EXAMPLE: Suppose one wanted to edit all of the previously unknown moon angles (assigned a value of -999) the database FRAMES IDL> !priv=2 IDL> dbopen, 'frames', 1 IDL> list = dbfind( 'moonang = -999.0') IDL> dbedit, list, 'moonang' PROCEDURE: (1) Use the cursor and point to the value you want to edit. (2) Type the new field value over the old field value. (3) When you are done changing all of the field values for each entry save the entry to the databases by pressing 'SAVE ENTRY TO DATABASES'. Here all of the values will be checked to see if they are the correct data type. If a field value is not of the correct data type, it will not be saved. Use the buttons "PREV ENTRY" and "NEXT ENTRY" to move between entry numbers. You must save each entry before going on to another entry in order for your changes to be saved. Pressing "RESET THIS ENTRY" will remove any unsaved changes to the current entry. REVISION HISTORY: Adapted from Landsman's DBEDIT added widgets, Melissa Marsh, HSTX, August 1993 do not need to press return after entering each entry, fixed layout problem on SUN, Melissa Marsh, HSTX, January 1994 Only updates the fields which are changed. Joel Offenberg, HSTX, Mar 94
NAME DBEDIT_BASIC PURPOSE: Interactively edit specified fields in a database. The value of each field is displayed, and the user has the option of changing or keeping the value. CALLING SEQUENCE: dbedit_basic, list, [ items ] INPUTS: list - scalar or vector of database entry numbers. Set LIST=0 to interactively add a new entry to a database. OPTIONAL INPUTS items - list of items to be edited. If not supplied, then the value of every field will be displayed. NOTES: (1) Database must be opened for update (dbopen,
,1) before calling DBEDIT_BASIC. User must have write privileges on the database files. (2) User gets a second chance to look at edited values, before they are actually written to the database PROMPTS: The item values for each entry to be edited are first displayed User is the asked "EDIT VALUES IN THIS ENTRY (Y(es), N(o), or Q(uit))? If user answers 'Y' or hits RETURN, then each item is displayed with its current value, which the user can update. If user answered 'N' then DBEDIT_BASIC skips to the next entry. If user answers 'Q' then DBEDIT will exit, saving all previous changes. EXAMPLE: Suppose V magnitudes (V_MAG) in a database STARS with unknown values were assigned a value of 99.9. Once the true values become known, the database can be edited IDL> !PRIV=2 & dbopen,'STARS',1 ;Open database for update IDL> list = dbfind('V_MAG=99.9') ;Get list of bad V_MAG values IDL> dbedit,list,'V_MAG' ;Interactively insert good V_MAG values REVISION HISTORY: Written W. Landsman STX April, 1989 Rename DBEDIT_BASIC from DBEDIT July, 1993
NAME: DBEXT PURPOSE: Procedure to extract values of up to 12 items from data base file, and place into IDL variables CALLING SEQUECE: dbext,list,items,v1,[v2,v3,v4,v5,v6,v7,v8,v9,v10,v11,v12] INPUTS: list - list of entry numbers to be printed, vector or scalar If list = -1, then all entries will be extracted. list may be converted to a vector by DBEXT items - standard item list specification. See DBPRINT for the 6 different ways that items may be specified. OUTPUTS: v1...v12 - the vectors of values for up to 12 items. EXAMPLE: Extract all RA and DEC values from the currently opened database, and place into the IDL vectors, IDLRA and IDLDEC. IDL> DBEXT,-1,'RA,DEC',idlra,idldec HISTORY version 2 D. Lindler NOV. 1987 check for INDEXED items W. Landsman Feb. 1989
NAME: DBEXT_DBF PURPOSE: Procedure to extract values of up to 12 items from a data base file. This is a subroutine of DBEXT, which is the routine a user should normally use. CALLING SEQUECE: dbext_dbf,list,dbno,sbyte,nbytes,idltype,nval,v1,v2,v3,v4,v5,v6,v7, v8,v9,v10,v11,v12 INPUTS: list - list of entry numbers to extract desired items. It is the entry numbers in the primary data base unless dbno is greater than or equal to -1. In that case it is the entry number in the specified data base. dbno - number of the opened db file if set to -1 then all data bases are included sbyte - starting byte in the entry. If single data base then it must be the starting byte for that data base only and not the concatenation of db records nbytes - number of bytes in the entry idltype - idl data type of each item to be extracted nval - number of values per entry of each item to be extracted OUTPUTS: v1...v12 - the vectors of values for up to 12 items HISTORY version 1 D. Lindler Nov. 1987 Extract multiple valued entries W. Landsman May 1989 William Thompson, GSFC/CDS (ARC), 1 June 1994 Added support for external (IEEE) representation.
NAME: DBEXT_IND PURPOSE: routine to read a indexed item values from index file CALLING SEQUENCE: dbext_ind,list,item,dbno,values INPUTS: list - list of entry numbers to extract values for (if it is a scalar, values for all entries are extracted) item - item to extract dbno - number of the opened data base OUTPUT: values - vector of values returned as function value HISTORY: version 1 D. Lindler Feb 88 Faster processing of string values W. Landsman April, 1992 William Thompson, GSFC/CDS (ARC), 30 May 1994 Added support for external (IEEE) data format
NAME: DBFIND PURPOSE: Function to search data base for entries with specified search characteristics. CALLING SEQUENCE: result = dbfind(spar,[ listin, /SILENT, /FULLSTRING]) INPUTS: spar - search_parameters (string)...each search parameter is of the form: option 1) min_val < item_name < max_val option 2) item_name = value option 3) item_name = [value_1, value_10] Note: option 3 is also the slowest. option 4) item_name > value option 5) item_name < value option 6) item_name = value(tolerance) ;eg. temp=25.0(5.2) option 7) item_name ;must be non-zero Multiple search parameters are separated by a comma. eg. 'cam_no=2,14
is interpreted as greater than or equal. RA and DEC keyfields are stored as floating point numbers in the data base may be entered as HH:MM:SEC and DEG:MIN:SEC. Where: HH:MM:SEC equals HH + MM/60.0 + SEC/3600. DEG:MIN:SEC equals DEG + MIN/60.0 + SEC/3600. For example: 40:34:10.5 < dec < 43:25:19 , 8:22:1.0 < ra < 8:23:23.0 Specially encoded date/time in the data base may be entered by YY/DAY:hr:min:sec which is interpreted as YY*1000+DAY+hr/24.0+min/24.0/60.+sec/24.0/3600. For example 85/201:10:35:30
DBFIND_ENTRY[Previous Routine] [Next Routine] [List of Routines]NAME: DBFIND_ENTRY PURPOSE: This is a subroutine of dbfind and is not a standalone procedure It performs a entry number search. CALLING SEQUENCE: dbfind_entry, type, svals, nentries, values INPUTS: 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 REVISION HISTORY: D. Lindler July,1987
DBFIND_SORT[Previous Routine] [Next Routine] [List of Routines]NAME: DBFIND_SORT PURPOSE: This is a subroutine of dbfind and is not a standalone procedure It is used to limit the search using sorted values CALLING SEQUENCE: dbfind_sort, it, type, svals, list INPUT: it - item number, scalar type - type of search (output from dbfparse) svals - search values (output from dbfparse) INPUT/OUTPUT: list - found entries !err is set to number of good values !ERR = -2 for an invalid search REVISION HISTORY: D. Lindler July,1987 William Thompson, GSFC/CDS (ARC), 30 May 1994 Added support for external (IEEE) data format
DBFPARSE[Previous Routine] [Next Routine] [List of Routines]NAME: DBFPARSE PURPOSE Parse the search string supplied to DBFIND. Not a standalone routine CALLING SEQUENCE: DBFPARSE, [ spar, items, stype, values ] INPUTS: spar - search parameter specification, scalar string OUTPUTS: items - list of items to search on stype - search type, numeric scalar 0 item=values(j,0) -1 item>values(j,0) -2 item
DBGET[Previous Routine] [Next Routine] [List of Routines]NAME: DBGET PURPOSE: Find entry number of fields which contain specified values in a specified item. DBGET is an altnerative to DBFIND when the desired search values are not easily expressed as a string. CALLING SEQUENCE: list = dbget( item, values, [ listin ], SILENT = ) INPUTS: item - Item name or number 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 giving the entry number of entries containing desired item values. The number of elements in LIST may be different from that of VALUE, since a value might be located zero, once, or many times in the database. Use the function DBMATCH if a one to one correspondence is desired between VALUES and LIST. KEYWORDS: SILENT - If this keyword is supplied, then DBGET will not display the number of entries found EXAMPLE: Get info on selected HD stars in Bright Star catalogue IDL> dbopen, 'YALE_BS' IDL> hdno = [1141,2363,3574,4128,6192,6314,6668] ;Desired HD numbers IDL> list = dbget( 'HD', hdno ) ;Get corresponding entry numbers SYSTEM VARIABLES: !ERR is set to the number of entries found REVISION HISTORY: Written, W. Landsman STX February, 1989
DBHELP[Previous Routine] [Next Routine] [List of Routines]NAME: DBHELP PURPOSE: Procedure to either list available databases (if no database is currently open) or the items in the currently open database. CALLING SEQUENCE: dbhelp, [ flag , TEXTOUT = ] INPUT: flag - (optional) if set to nonzero then item or database descriptions are also printed default=0 If flag is a string, then it is interpreted as the name of a data base (if no data base is opened) or a name of an item in the opened data base. In this case, help is displayed only for the particular item or database OUTPUTS: None OPTIONAL INPUT KEYWORDS: textout Used to determine output device. If not present, the value of !TEXTOUT system variable is used (see TEXTOPEN ) textout=1 Terminal with /MORE textout=2 Terminal without /MORE textout=3
.PRT textout=4 LASER PRINTER textout=5 USER MUST OPEN FILE; METHOD: If no data base is opened then a list of data bases are printed, otherwise the items in the open data base are printed. If a string is supplied for flag and a data base is opened flag is assumed to be an item name. The information for that item is printed along with contents in a optional file zdbase:dbname_itemname.hlp if a string is supplied for flag and no data base is opened, then string is assumed to be the name of a data base file. only information for that file is printed along with an optional file zdbase:dbname.hlp. HISTORY Version 2 D. Lindler Nov 1987 (new db format) Faster printing of title desc. W. Landsman May 1989 Keyword textout added, J. Isensee, July, 1990 Modified to work on Unix, D. Neill, ACC, Feb 1991. William Thompson, GSFC/CDS (ARC), 1 June 1994 Added support for external (IEEE) representation.
DBINDEX[Previous Routine] [Next Routine] [List of Routines]NAME: DBINDEX PURPOSE: Procedure to create index file for data base CALLING SEQUENCE: dbindex, [ items ] OPTIONAL INPUT: items - names or numbers of items to be index -- if not supplied, then all indexed fields will be processed. OUTPUT: Index file
.dbx is created on disk location ZDBASE: OPERATIONAL NOTES: Data base must have been previously opened for update by DBOPEN HISTORY: version 2 D. Lindler Nov 1987 (new db format) W. Landsman added optional items parameter Feb 1989 M. Greason converted to IDL version 2. June 1990. William Thompson, GSFC/CDS (ARC), 30 May 1994 Added support for external (IEEE) data format
DBINDEX_BLK[Previous Routine] [Next Routine] [List of Routines]NAME: DBINDEX_BLK PURPOSE: To set up an associated variable of the correct data-type and offset into the file by some amount in preparation for writing to the file. CALLING SEQUENCE: res = dbindex_blk(unit, nb, bsz, ofb, dtype) INPUTS: unit The unit number assigned to the file. nb The number of blocks to offset into the file. bsz The size of each block, in bytes, to offset into the file. ofb The offset into the block, in bytes. dtype The IDL datatype as defined in the SIZE function OUTPUTS: res The returned variable. This is an associated variable. RESTRICTIONS: The file must have been previously opened. MODIFICATION HISTORY: Written by Michael R. Greason, STX, 14 June 1990.
DBMATCH[Previous Routine] [Next Routine] [List of Routines]NAME: DBMATCH PURPOSE: Find one entry number in a database for each element in a vector of item values. 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 ] ) 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. 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. 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 Nov 1992
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-existant 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.
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 Used to determine output device. If not present, the value of !TEXTOUT system variable is used. textout=1 Terminal with /MORE textout=2 Terminal without /MORE textout=3
.prt textout=4 laser.tmp textout=5 user must open file 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) Extra space added at end of printout W. Landsman Nov. 1990 Test if user pressed 'Q' in response to /MORE W. Landsman Sep 1991 Apply STRTRIM to free form output W. Landsman Dec 1992 Test for string value of TEXTOUT W. Landsman Feb 1994
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
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] 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) 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.
DBSEARCH[Previous Routine] [Next Routine] [List of Routines]NAME: DBSEARCH PURPOSE: Search a vector for specified values This is a subroutine of dbfind and is not a standalone procedure 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
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
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
DBUPDATE[Previous Routine] [Next Routine] [List of Routines]NAME: DBUPDATE PURPOSE: Update columns of data in a database -- inverse of DBEXT 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
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)
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 ] 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. 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.
DBXPUT[Previous Routine] [Next Routine] [List of Routines]NAME: DBXPUT PURPOSE: routine to replace value of an item in a data base entry CALLING SEQENCE: 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 to be updated idltype - idl data type for item 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. No validity checks are made HISTORY: version 1, D. Lindler Aug, 1986 converted to IDL Version 2. M. Greason, STX, June 1990.
DBXVAL[Previous Routine] [Next Routine] [List of Routines]NAME: DBXVAL PURPOSE: 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 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) OUTPUT: function value is value of the specified item in entry OPERATIONAL NOTES: To increase speed the routine assumes that entry and item are valid and that the data base is already opened using dbopen. HISTORY: version 2 D. Lindler Nov. 1987 (for new db format)
DB_ENT2EXT[Previous Routine] [Next Routine] [List of Routines]NAME: DB_ENT2EXT PURPOSE: 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
DB_ENT2HOST[Previous Routine] [Next Routine] [List of Routines]NAME: DB_ENT2HOST PURPOSE: Converts a database entry from external (IEEE) data format to host format after reading it from the file. 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
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.
DB_ITEM[Previous Routine] [Next Routine] [List of Routines]NAME: DB_ITEM PURPOSE: 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 HISTORY: version 2 D. Lindler Oct. 1987 Return selected items in form 5 W. Landsman Jan. 1987
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
DB_OR[Previous Routine] [Next Routine] [List of Routines]NAME: DB_OR PURPOSE: Combine two vectors of entry numbers, removing duplicate values. 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
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 .DBC 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.
IMDBASE[Previous Routine] [Next Routine] [List of Routines]NAME IMDBASE PURPOSE: Locate sources within a specified IDL database that are within a given image. The image must contain a FITS header with world coordinates CALLING SEQUENCE: imdbase, hdr, catalogue, [list, XPOS= ,YPOS=, XRANGE= ,YRANGE= , SUBLIST = ] INPUTS: hdr - FITS image header containing astrometry, and the NAXIS1, NAXIS2 keywords giving the image size catalogue - string giving name of catalogue in database Database must contain the (preferably indexed) fields RA (in hours) and DEC. Type DBHELP for a list of the names of available catalogues. OPTIONAL OUTPUT PARAMETER: LIST - A long vector containing the entry numbers of sources found within the image. This vector can then be used with other database procedures, e.g. to print specified fields (DBPRINT) or subselect with further criteria (DBFIND) OPTIONAL OUTPUT KEYWORD PARAMETERS: XPOS - REAL*4 vector giving X positions of catalogue sources found within the image YPOS - REAL*4 vector giving Y positions of catalogue sources found within the image OPTIONAL INPUT KEYWORD PARAMETERS: XRANGE - 2 element vector giving the X range of the image to consider. The default is to search for catalogue sources within the entire image YRANGE - 2 element vector giving the Y range of the image to consider. SUBLIST - vector giving entries in the database to consider in the search. If not supplied, or set equal to -1, then all entries are considered. NOTES: (1) If a list vector is not supplied, then the found objects are displayed at the terminal. (2) There is currently no way of determining the equinox of the database coordinates. The SAO, NGC2000, GUIDESTAR, PRIN_GAL, SKYMAP, HST_CATALOG, OMEGACEN, and YALE_BS catalogues are assumed to be in equinox 2000. All other catalogues are assumed to be in 1950 equinox EXAMPLE: Find all existing IUE SWP observations within the field of the disk file FUV0435. Subselect those taken with the SWP camera SXHREAD,'FUV0435',H ; Read header from disk IMDBASE,H,'IUE',list ;Find IUE obs. within image LIST2 = DBFIND('CAM_NO=3',LIST) ;Subselect on SWP images SIDE EFFECTS: The IDL database is left open upon exiting IMDBASE: SYSTEM VARIABLES: The non-standard system variable !TEXTOUT to control the output device for the listing. See TEXTOPEN for more info PROCEDURES USED: SXPAR, EXTAST, GET_EQUINOX, PRECESS, TEXTOPEN, TEXTCLOSE, XY2AD, DBOPEN, DBFIND, AD2XY, DBEXT REVISION HISTORY: Written W. Landsman September, 1988 Added SUBLIST keyword September, 1991
TAB_TO_DB[Previous Routine] [List of Routines]NAME: TAB_TO_DB PURPOSE: Add STSDAS table contents to an existing or new database file. CALLING SEQUENCE: tab_to_db, table, database, new INPUTS: table - table name database - database name OPTIONAL INPUTS: new - integer flag, 0 - add to existing data base 1 - create new data base (default = 0) OPERATIONAL NOTES: !PRIV must be 2 or greater to execute tab_to_db. If a new data base is to be created, It will be created in your current default directory and your current default directory must be included in the logical definition of ZDBASE: WARNING: If a table column ENTRY is present. It will cause the present data base entries (as specified by ENTRY values) to be updated. HISTORY: version 1 D. Lindler Nov 1989 converted to IDL v 2, D. Neill Mar 1991