1 /* $Id: ncbisam.h,v 6.5 2006/05/10 20:47:14 camacho Exp $ 2 * =========================================================================== 3 * 4 * PUBLIC DOMAIN NOTICE 5 * National Center for Biotechnology Information 6 * 7 * This software/database is a "United States Government Work" under the 8 * terms of the United States Copyright Act. It was written as part of 9 * the author's official duties as a United States Government employee and 10 * thus cannot be copyrighted. This software/database is freely available 11 * to the public for use. The National Library of Medicine and the U.S. 12 * Government have not placed any restriction on its use or reproduction. 13 * 14 * Although all reasonable efforts have been taken to ensure the accuracy 15 * and reliability of the software and data, the NLM and the U.S. 16 * Government do not and cannot warrant the performance or results that 17 * may be obtained by using this software or data. The NLM and the U.S. 18 * Government disclaim all warranties, express or implied, including 19 * warranties of performance, merchantability or fitness for any particular 20 * purpose. 21 * 22 * Please cite the author in any work or product based on this material. 23 * 24 * =========================================================================== 25 * 26 * File Name: $RCSfile: ncbisam.h,v $ 27 * 28 * Author: Sergei Shavirin 29 * 30 * Initial Version Creation Date: 02/24/1997 31 * 32 * $Revision: 6.5 $ 33 * 34 * File Description: 35 * External include file for ISAM library 36 * 37 * $Log: ncbisam.h,v $ 38 * Revision 6.5 2006/05/10 20:47:14 camacho 39 * From Ilya Dondoshansky: Added ISAMSetDataSorted function to set flag that data is already sorted. 40 * 41 * Revision 6.4 2003/04/14 19:52:31 camacho 42 * Added ISAMUninitSearch 43 * 44 * Revision 6.3 2000/07/18 19:29:27 shavirin 45 * Added new parameter test_non_unique to suppress check for non-unique 46 * strings ids in the database - default - TRUE. 47 * 48 * Revision 6.2 1999/08/25 20:18:50 shavirin 49 * Added possibility to store user-specified Int4 options in the index 50 * header. 51 * 52 * Revision 6.1 1997/11/07 16:18:06 shavirin 53 * Added definition for the function SISAMFindAllData() 54 * 55 * Revision 6.0 1997/08/25 18:53:30 madden 56 * Revision changed to 6.0 57 * 58 * Revision 1.8 1997/05/12 19:55:20 shavirin 59 * Some fixes type-changes to support ISAMCreateDatabase() API 60 * 61 * Revision 1.6 1997/05/08 21:18:40 shavirin 62 * Added definition for function ISAMSearchTerm() 63 * 64 * Revision 1.3 1997/05/01 17:25:05 shavirin 65 * Added String ISAM functionality 66 * 67 * Revision 1.2 1997/02/25 22:17:17 shavirin 68 * Changed general API of ISAM library . 69 * 70 * Revision 1.1 1997/02/24 21:07:07 shavirin 71 * Initial revision 72 * 73 * 74 * ========================================================================== 75 */ 76 77 #ifndef _NCBISAM_H_ 78 #define _NCBISAM_H_ ncbisam 79 80 /****************************************************************************/ 81 /* INCLUDES */ 82 /****************************************************************************/ 83 84 #include <ncbi.h> 85 86 /****************************************************************************/ 87 /* DEFINES */ 88 /****************************************************************************/ 89 90 #define DEFAULT_NISAM_SIZE 256 91 #define DEFAULT_SISAM_SIZE 64 92 #define ISAM_FOLLOW_KEY 1 93 #define ISAM_SHORT_KEY 2 94 #define ISAM_DATA_CHAR '\2' 95 #define MEMORY_ONLY_PAGE_SIZE 1 96 /****************************************************************************/ 97 /* TYPEDEFS */ 98 /****************************************************************************/ 99 100 typedef enum { 101 ISAMNumeric = 0, 102 ISAMNumericNoData = 1, 103 ISAMString = 2, 104 ISAMStringDatabase = 3, 105 ISAMStringBin = 4 106 } ISAMType; 107 108 typedef enum { 109 ISAMNotFound = 1, 110 ISAMNoError = 0, 111 ISAMNoSpace = -2, 112 ISAMBadFileName = -3, 113 ISAMNotImplemented = -4, 114 ISAMMemMap = -5, 115 ISAMNoOrder = -6, 116 ISAMNoCorrelation = -7, 117 ISAMBadParameter = -8, 118 ISAMNoMemory = -9, 119 ISAMBadVersion = -10, 120 ISAMBadType = -11, 121 ISAMWrongFile = -12, 122 ISAMFseekFailed = -13, 123 ISAMInvalidFormat = -14, 124 ISAMMiscError = -99 125 } ISAMErrorCode; 126 127 typedef VoidPtr ISAMObjectPtr; 128 129 /****************************************************************************/ 130 /* FINCTION DEFINITIONS */ 131 /****************************************************************************/ 132 133 #ifdef __cplusplus 134 extern "C" { 135 #endif 136 /* ---------------------- ISAMObjectNew -------------------------- 137 Purpose: Creates ISAM object structure with default parameters 138 139 Parameters: type - Type of ISAM (Numeric, String etc. ) 140 Returns: Poiner to created object structure 141 NOTE: None 142 143 ------------------------------------------------------------------*/ 144 ISAMObjectPtr ISAMObjectNew(ISAMType type, /* Type of ISAM */ 145 CharPtr DBFile, /* ISAM Database file */ 146 CharPtr IndexFile /* ISAM Index file */ 147 ); 148 149 /* ---------------------- ISAMObjectFree -------------------------- 150 Purpose: To terminate all allocated and used buffers 151 unmap and close all mapped/opened files 152 Parameters: ISAM object 153 Returns: None 154 NOTE: None 155 ------------------------------------------------------------------*/ 156 void ISAMObjectFree(ISAMObjectPtr object); 157 158 /* ---------------------- ISAMUninitSearch -------------------------- 159 Purpose: Uninitialize an ISAM search (free all allocated and used 160 buffers and unmap and close all mapped/opened files). 161 Undoes what the ISAMInitSearch function does. 162 Parameters: ISAM object 163 Returns: ISAM Error Code 164 NOTE: None 165 ------------------------------------------------------------------*/ 166 ISAMErrorCode ISAMUninitSearch(ISAMObjectPtr object); 167 168 /* ------------------------ ISAMSearchTerm ------------------------- 169 Purpose: Main search function of complete String ISAM 170 171 Parameters: object - ISAM Object 172 term_in - input string 173 field_mask - fields to search in 0 and -1 mean search 174 all fields 175 uid - array of returned uids 176 count number of returned uids 177 Returns: ISAM Error Code 178 NOTE: Initialization done with first call to this function 179 ------------------------------------------------------------------*/ 180 ISAMErrorCode ISAMSearchTerm(ISAMObjectPtr object, CharPtr term_in, 181 Uint4 field_mask, Uint4Ptr PNTR uid, 182 Int4Ptr count); 183 184 /* ---------------------- ISAMCreateDatabase ------------------------ 185 Purpose: To create coded array/offsets and ISAM database files 186 from input files in special form: 187 All files are in sorted order and sorted through 188 format: <term><\2><uid><field-bit mask><CR> 189 190 Parameters: ISAM Object 191 files - list of sorted files to process 192 Returns: ISAM itemized error code 193 ------------------------------------------------------------------*/ 194 ISAMErrorCode ISAMCreateDatabase(CharPtr PNTR files, 195 Int4 num_files, 196 Int4 MaxOffset, 197 CharPtr BaseName, 198 CharPtr DBExt, 199 CharPtr IndexExt, 200 CharPtr OffExt, 201 CharPtr CodeExt); 202 203 /* ---------------------- ISAMUpdateDatabase ------------------------ 204 205 Purpose: 206 207 Parameters: NOT IMPLEMENTED YET!!! 208 209 Returns: 210 ------------------------------------------------------------------*/ 211 ISAMErrorCode ISAMUpdateDatabase(CharPtr InFile, 212 CharPtr NewDBDir, 213 Int4 MaxOffset, 214 CharPtr BaseName, 215 CharPtr DBExt, 216 CharPtr IndexExt, 217 CharPtr OffExt, 218 CharPtr CodeExt); 219 220 /* ---------------------- ISAMSetUpCAInfo -------------------------- 221 Purpose: Added toISAM object Coded Array filenames information 222 223 Parameters: CAName - Common name for all CA/FA DB and offset files 224 CADBExt - exetntio for CA/FA DB files 225 CAOffExt - extention for CA/FA offset files 226 MaxOffset - threshhold offset for starting write new 227 file 228 229 Returns: ISAM Error Code 230 NOTE: MaxOffset is set to default value if 10.000.000 231 ------------------------------------------------------------------*/ 232 ISAMErrorCode ISAMSetUpCAInfo(ISAMObjectPtr object, Int4 MaxOffset, 233 CharPtr CAName, CharPtr CADBExt, 234 CharPtr CAOffExt); 235 236 /* ---------------------- ISAMMakeIndex -------------------------- 237 Purpose: To create ISAM Intex file for Database file 238 239 Parameters: ISAM Object 240 Returns: ISAM itemized error code 241 NOTE: Special default rules for UNIX platform 242 Page size is set to default value if 0 243 ------------------------------------------------------------------*/ 244 ISAMErrorCode ISAMMakeIndex(ISAMObjectPtr object, 245 Int4 page_size, /* ISAM page size */ 246 Int4 idx_option /* Option for upper layer */ 247 ); 248 249 /* ------------------------ NISAMSearch ---------------------------- 250 Purpose: Main search function of Numeric ISAM 251 252 Parameters: Key - interer to search 253 Data - returned value (for NIASM with data) 254 Index - internal index in database 255 Returns: ISAM Error Code 256 NOTE: Initialization done with first call to this function 257 ------------------------------------------------------------------*/ 258 ISAMErrorCode NISAMSearch(ISAMObjectPtr object, 259 Uint4 Key, 260 Uint4Ptr Data, 261 Uint4Ptr Index 262 ); 263 264 /* ---------------------- NISAMSearchList -------------------------- 265 Purpose: Perform search of multiple Keys 266 267 Parameters: NumKeys - number of input keys 268 Keys - array of keys 269 Returns: Data - array of returned values 270 Index - array of internal indexes 271 NOTE: None 272 ------------------------------------------------------------------*/ 273 ISAMErrorCode NISAMSearchList(ISAMObjectPtr object, 274 Int4 NumKeys, 275 Uint4Ptr Keys, 276 Uint4Ptr Data, 277 Uint4Ptr index 278 ); 279 280 281 ISAMErrorCode SISAMSearch(ISAMObjectPtr object, 282 CharPtr key_in, 283 Int4 type, 284 CharPtr PNTR key_out, 285 CharPtr PNTR data, 286 Uint4Ptr index); 287 288 ISAMErrorCode SISAMFindAllData(ISAMObjectPtr object, 289 CharPtr term_in, 290 Int4Ptr PNTR ids_out, 291 Int4Ptr count_out); 292 293 /* ------------------------ NISAMFindKey --------------------------- 294 Purpose: Return Key value by absolute internal index 295 296 Parameters: Index - absolute internal index 297 Returns: Key - corresponding key value 298 Data - corresponding data value 299 NOTE: 300 ------------------------------------------------------------------*/ 301 ISAMErrorCode NISAMFindKey(ISAMObjectPtr object, 302 Int4 Index, 303 Uint4Ptr Key, 304 Uint4Ptr Data 305 ); 306 307 /* ---------------------- NISANFindKeys ------------------------- 308 Purpose: Retuns set of Key/Data pairs from 309 First to Last internal index 310 311 Parameters: First - beginning of interval 312 Last - the end of interval 313 Returns: Keys - array of Keys 314 Data - array of Data 315 NOTE: None 316 ------------------------------------------------------------------*/ 317 ISAMErrorCode NISAMFindKeys(ISAMObjectPtr object, 318 Int4 First, 319 Int4 Last, 320 Uint4Ptr Keys, 321 Uint4Ptr Data 322 ); 323 324 /* ------------------------ ISAMNumTerms --------------------------- 325 Purpose: Returns total number of terms in ISAM database 326 327 Parameters: ISAM object 328 Returns: Number of terms 329 NOTE: None 330 ------------------------------------------------------------------*/ 331 ISAMErrorCode ISAMNumTerms(ISAMObjectPtr object, Int4Ptr terms); 332 333 /* ------------------------ ISAMGetIdxOption ------------------------ 334 Purpose: Returns user specified option from ISAM database 335 336 Parameters: ISAM object 337 Returns: User specified option (set while formating) 338 NOTE: None 339 ------------------------------------------------------------------*/ 340 ISAMErrorCode ISAMGetIdxOption(ISAMObjectPtr object, Int4Ptr idx_option); 341 342 /* ------------------------ ISAMGetIdxOption ------------------------ 343 Purpose: To set option to check or not check for non-unique 344 elements 345 Parameters: ISAM object 346 Returns: None 347 NOTE: None 348 ------------------------------------------------------------------*/ 349 void ISAMSetCheckForNonUnique(ISAMObjectPtr object, Boolean test_non_unique); 350 351 /** Sets the sorting_done boolean, avoiding an expensive check in the 352 * ISAMCheckIfSorted function. 353 * @param object ISAM object to modify. [in] [out] 354 * @param num_terms Number of terms in the data, which otherwise would have to 355 * be calculated in ISAMCheckIfSorted. [in] 356 */ 357 void ISAMSetDataSorted(ISAMObjectPtr object, Int4 num_terms); 358 359 #ifdef __cplusplus 360 } 361 #endif 362 363 #endif 364