idlastro / Database Procedures: DBFIND

[Source code]

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 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
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
Delay warning now for 10000 instead of 2000 entries W.L. Aug 2014