idlastro / Database Procedures: DBMATCH

[Source code]

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 Hipparcos 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, 'hipparcos'          ;Open the Hipparcos catalog
IDL> list = dbmatch( 'HD', HD)    ;Get entries in Hipparcos catalog 
                                  ;corresponding to each HD number.
PROCEDURE CALLS
DB_ITEM, DB_ITEM_INFO(), DBEXT, DBFIND_SORT()
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
Change some loop variables to type LONG,  W. Landsman  July 1999
Remove loop for substring searches (faster)  W. landsman August 1999
Replace DATATYPE() with size(/TNAME)  W. Landsman  November 2001
Fixed typo when search on sorted items W. Landsman February 2002
Fixed bug from Nov 2001 where /FULLSTRING was always set.  W.L Feb 2007