DBFIND()

     Search data base for entries with specified characteristics

     Function to search data base for entries with specified
     search characteristics.

     result = dbfind(spar,[ listin, /SILENT, /FULLSTRING, ERRMSG=, Count = ])

     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
Example
                       input_array = strarr(2)
                       input_array(0) = '14
Optional Input Parameters
       listin - gives list of entries to be searched.  If not supplied or
               set to -1 then all entries are searched.

Output Parameters
       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 Keyword Output
       COUNT - Integer scalar giving the number of valid matches

Procedures Used
       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



Last modified by pro2html on 2001 August 07 at 09:36 UTC


[Home Page]
[Software, Documentation]
[IDL Documentation]
[Quick Reference]
[Feedback]




Jörn Wilms (wilms@astro.uni-tuebingen.de)


Updated automatically