DBFIND
Name
DBFIND()
Purpose
Search data base for entries with specified characteristics
Explanation
Function to search data base for entries with specified
search characteristics.
Calling Sequence
result = dbfind(spar,[ listin, /SILENT, /FULLSTRING, ERRMSG=, Count = ])
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<ra<20'
Note: < is interpreted as less than or equal.
> 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 CCYY/DAY:hr:min:sec which is
interpreted as
CCYY*1000+DAY+hr/24.0+min/24.0/60.+sec/24.0/3600.
If a two digit year is supplied and YY GE 40 then it is
understood to refer to year 1900 +YY; if YY LT 40 then it is
understood to refer to year 2000 +YY
For example
1985/201:10:35:30<date_time<1985/302:10:33:33.4
would specify all entries between:
year 1985 day 201 at 10:35:30 to
day 302 at 10:33:33.4
The date/time may also be encoded as:
DD-MMM-YEAR HH::MM:SS.SS
eg. 12-JUL-86 10:23:33.45
(this is the format of system variable !stime)
Multiple search parameters may be stored in a string
array (one parameter per array element) instead of
concatenating them with commas in a single string.
Example
input_array = strarr(2)
input_array[0] = '14<ra<16' ; 14-16 hrs of ra.
input_array[1] = '8<dec<20' ; + 8-20 deg. decl.
Optional Input
listin - gives list of entries to be searched. If not supplied or
set to -1 then all entries are searched.
Output
List of ENTRY numbers satisfying search characteristics
is returned as the function value.
Optional Input Keywords
/SILENT - If the keyword SILENT is set and non-zero, then DBFIND
will not print the number of entries found.
/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.
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 ...;
Optional Output Keyword
COUNT - Integer scalar giving the number of valid matches
Procedure Calls
DB_INFO, DB_ITEM, DB_ITEM_INFO, DBEXT, DBEXT_IND, DBFIND_ENTRY,
DBFIND_SORT, DBFPARSE, DBRD, DBSEARCH, ZPARCHECK,IS_IEEE_BIG
Restrictions
The data base must be previously opened with DBOPEN.
Side Effects
The obsolete system variable !ERR is set to number of entries found
Revision History
Written : D. Lindler, GSFC/HRS, November 1987
Version 2, Wayne Landsman, GSFC/UIT (STX), 1 April 1994
Added FULLSTRING keyword.
Version 3, William Thompson, GSFC, 1 April 1994
Added check for empty database
Version 4, William Thompson, GSFC, 5 April 1994
Changed so that !ERR is zero when database is empty,
and LISTIN is returned, based on discussion with Wayne
Landsman.
Version 5, Wayne Landsman, GSFC/UIT (STX), 26 May 1994
Added error message when database is empty.
Version 6, William Thompson, GSFC, 14 March 1995
Added FULLSTRING keyword to DBFIND_SORT call
Version 7, Richard Schwartz, GSFC/SDAC 23 August 1996
Move external to host conversion from DBRD to
operation on extracted values only.
Version 8, William Thompson, GSFC, 3 December 1996
Renamed BYTESWAP variable to BSWAP--appeared to be
conflicting with function of same name.
Version 9, William Thompson, GSFC, 17-Mar-1997
Added keyword ERRMSG
Version 10, July, 1997 W. Landsman, added CATCH errors
Converted to IDL V5.0 W. Landsman October 1997
Update documentation for new Y2K compliant DBFPARSE W. Landsman Nov 1998
Suppress empty database message with /SILENT, W. Landsman Jan 1999
Added COUNT keyword, deprecate !ERR W. Landsman March 2000
Added new unsigned & 64bit datatypes W. Landsman July 2001
Fix possible floating illegand operand error W. Landsman July 2009
Change arrays to LONG to support entries >32767 bytes W.L. Oct. 2010