1 /************************************************************************************************* 2 * The table database API of Tokyo Cabinet 3 * Copyright (C) 2006-2012 FAL Labs 4 * This file is part of Tokyo Cabinet. 5 * Tokyo Cabinet is free software; you can redistribute it and/or modify it under the terms of 6 * the GNU Lesser General Public License as published by the Free Software Foundation; either 7 * version 2.1 of the License or any later version. Tokyo Cabinet is distributed in the hope 8 * that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of 9 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 10 * License for more details. 11 * You should have received a copy of the GNU Lesser General Public License along with Tokyo 12 * Cabinet; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, 13 * Boston, MA 02111-1307 USA. 14 *************************************************************************************************/ 15 16 17 #ifndef _TCTDB_H /* duplication check */ 18 #define _TCTDB_H 19 20 #if defined(__cplusplus) 21 #define __TCTDB_CLINKAGEBEGIN extern "C" { 22 #define __TCTDB_CLINKAGEEND } 23 #else 24 #define __TCTDB_CLINKAGEBEGIN 25 #define __TCTDB_CLINKAGEEND 26 #endif 27 __TCTDB_CLINKAGEBEGIN 28 29 30 #include <tcutil.h> 31 #include <tchdb.h> 32 #include <tcbdb.h> 33 34 35 36 /************************************************************************************************* 37 * API 38 *************************************************************************************************/ 39 40 41 typedef struct { /* type of structure for a column index */ 42 char *name; /* column name */ 43 int type; /* data type */ 44 void *db; /* internal database object */ 45 void *cc; /* internal cache object */ 46 } TDBIDX; 47 48 typedef struct { /* type of structure for a table database */ 49 void *mmtx; /* mutex for method */ 50 TCHDB *hdb; /* internal database object */ 51 bool open; /* whether the internal database is opened */ 52 bool wmode; /* whether to be writable */ 53 uint8_t opts; /* options */ 54 int32_t lcnum; /* max number of cached leaves */ 55 int32_t ncnum; /* max number of cached nodes */ 56 int64_t iccmax; /* maximum size of the inverted cache */ 57 double iccsync; /* synchronization ratio of the inverted cache */ 58 TDBIDX *idxs; /* column indices */ 59 int inum; /* number of column indices */ 60 bool tran; /* whether in the transaction */ 61 } TCTDB; 62 63 enum { /* enumeration for additional flags */ 64 TDBFOPEN = HDBFOPEN, /* whether opened */ 65 TDBFFATAL = HDBFFATAL /* whether with fatal error */ 66 }; 67 68 enum { /* enumeration for tuning options */ 69 TDBTLARGE = 1 << 0, /* use 64-bit bucket array */ 70 TDBTDEFLATE = 1 << 1, /* compress each page with Deflate */ 71 TDBTBZIP = 1 << 2, /* compress each record with BZIP2 */ 72 TDBTTCBS = 1 << 3, /* compress each page with TCBS */ 73 TDBTEXCODEC = 1 << 4 /* compress each record with outer functions */ 74 }; 75 76 enum { /* enumeration for open modes */ 77 TDBOREADER = 1 << 0, /* open as a reader */ 78 TDBOWRITER = 1 << 1, /* open as a writer */ 79 TDBOCREAT = 1 << 2, /* writer creating */ 80 TDBOTRUNC = 1 << 3, /* writer truncating */ 81 TDBONOLCK = 1 << 4, /* open without locking */ 82 TDBOLCKNB = 1 << 5, /* lock without blocking */ 83 TDBOTSYNC = 1 << 6 /* synchronize every transaction */ 84 }; 85 86 enum { /* enumeration for index types */ 87 TDBITLEXICAL, /* lexical string */ 88 TDBITDECIMAL, /* decimal string */ 89 TDBITTOKEN, /* token inverted index */ 90 TDBITQGRAM, /* q-gram inverted index */ 91 TDBITOPT = 9998, /* optimize */ 92 TDBITVOID = 9999, /* void */ 93 TDBITKEEP = 1 << 24 /* keep existing index */ 94 }; 95 96 typedef struct { /* type of structure for a condition */ 97 char *name; /* column name */ 98 int nsiz; /* size of the column name */ 99 int op; /* operation type */ 100 bool sign; /* positive sign */ 101 bool noidx; /* no index flag */ 102 char *expr; /* operand expression */ 103 int esiz; /* size of the operand expression */ 104 void *regex; /* regular expression object */ 105 void *ftsunits; /* full-text search units */ 106 int ftsnum; /* number of full-text search units */ 107 bool alive; /* alive flag */ 108 } TDBCOND; 109 110 typedef struct { /* type of structure for a query */ 111 TCTDB *tdb; /* database object */ 112 TDBCOND *conds; /* condition objects */ 113 int cnum; /* number of conditions */ 114 char *oname; /* column name for ordering */ 115 int otype; /* type of order */ 116 int max; /* max number of retrieval */ 117 int skip; /* skipping number of retrieval */ 118 TCXSTR *hint; /* hint string */ 119 int count; /* count of corresponding records */ 120 } TDBQRY; 121 122 enum { /* enumeration for query conditions */ 123 TDBQCSTREQ, /* string is equal to */ 124 TDBQCSTRINC, /* string is included in */ 125 TDBQCSTRBW, /* string begins with */ 126 TDBQCSTREW, /* string ends with */ 127 TDBQCSTRAND, /* string includes all tokens in */ 128 TDBQCSTROR, /* string includes at least one token in */ 129 TDBQCSTROREQ, /* string is equal to at least one token in */ 130 TDBQCSTRRX, /* string matches regular expressions of */ 131 TDBQCNUMEQ, /* number is equal to */ 132 TDBQCNUMGT, /* number is greater than */ 133 TDBQCNUMGE, /* number is greater than or equal to */ 134 TDBQCNUMLT, /* number is less than */ 135 TDBQCNUMLE, /* number is less than or equal to */ 136 TDBQCNUMBT, /* number is between two tokens of */ 137 TDBQCNUMOREQ, /* number is equal to at least one token in */ 138 TDBQCFTSPH, /* full-text search with the phrase of */ 139 TDBQCFTSAND, /* full-text search with all tokens in */ 140 TDBQCFTSOR, /* full-text search with at least one token in */ 141 TDBQCFTSEX, /* full-text search with the compound expression of */ 142 TDBQCNEGATE = 1 << 24, /* negation flag */ 143 TDBQCNOIDX = 1 << 25 /* no index flag */ 144 }; 145 146 enum { /* enumeration for order types */ 147 TDBQOSTRASC, /* string ascending */ 148 TDBQOSTRDESC, /* string descending */ 149 TDBQONUMASC, /* number ascending */ 150 TDBQONUMDESC /* number descending */ 151 }; 152 153 enum { /* enumeration for set operation types */ 154 TDBMSUNION, /* union */ 155 TDBMSISECT, /* intersection */ 156 TDBMSDIFF /* difference */ 157 }; 158 159 enum { /* enumeration for post treatments */ 160 TDBQPPUT = 1 << 0, /* modify the record */ 161 TDBQPOUT = 1 << 1, /* remove the record */ 162 TDBQPSTOP = 1 << 24 /* stop the iteration */ 163 }; 164 165 /* type of the pointer to a iterator function for each table record. 166 `pkbuf' specifies the pointer to the region of the primary key. 167 `pksiz' specifies the size of the region of the primary key. 168 `cols' specifies a map object containing columns. 169 `op' specifies the pointer to the optional opaque object. 170 The return value is flags of the post treatment by bitwise-or: `TDBQPPUT' to modify the 171 record, `TDBQPOUT' to remove the record, `TDBQPSTOP' to stop the iteration. */ 172 typedef int (*TDBQRYPROC)(const void *pkbuf, int pksiz, TCMAP *cols, void *op); 173 174 175 /* Get the message string corresponding to an error code. 176 `ecode' specifies the error code. 177 The return value is the message string of the error code. */ 178 const char *tctdberrmsg(int ecode); 179 180 181 /* Create a table database object. 182 The return value is the new table database object. */ 183 TCTDB *tctdbnew(void); 184 185 186 /* Delete a table database object. 187 `tdb' specifies the table database object. 188 If the database is not closed, it is closed implicitly. Note that the deleted object and its 189 derivatives can not be used anymore. */ 190 void tctdbdel(TCTDB *tdb); 191 192 193 /* Get the last happened error code of a table database object. 194 `tdb' specifies the table database object. 195 The return value is the last happened error code. 196 The following error code is defined: `TCESUCCESS' for success, `TCETHREAD' for threading 197 error, `TCEINVALID' for invalid operation, `TCENOFILE' for file not found, `TCENOPERM' for no 198 permission, `TCEMETA' for invalid meta data, `TCERHEAD' for invalid record header, `TCEOPEN' 199 for open error, `TCECLOSE' for close error, `TCETRUNC' for trunc error, `TCESYNC' for sync 200 error, `TCESTAT' for stat error, `TCESEEK' for seek error, `TCEREAD' for read error, 201 `TCEWRITE' for write error, `TCEMMAP' for mmap error, `TCELOCK' for lock error, `TCEUNLINK' 202 for unlink error, `TCERENAME' for rename error, `TCEMKDIR' for mkdir error, `TCERMDIR' for 203 rmdir error, `TCEKEEP' for existing record, `TCENOREC' for no record found, and `TCEMISC' for 204 miscellaneous error. */ 205 int tctdbecode(TCTDB *tdb); 206 207 208 /* Set mutual exclusion control of a table database object for threading. 209 `tdb' specifies the table database object which is not opened. 210 If successful, the return value is true, else, it is false. 211 Note that the mutual exclusion control is needed if the object is shared by plural threads and 212 this function should be called before the database is opened. */ 213 bool tctdbsetmutex(TCTDB *tdb); 214 215 216 /* Set the tuning parameters of a table database object. 217 `tdb' specifies the table database object which is not opened. 218 `bnum' specifies the number of elements of the bucket array. If it is not more than 0, the 219 default value is specified. The default value is 131071. Suggested size of the bucket array 220 is about from 0.5 to 4 times of the number of all records to be stored. 221 `apow' specifies the size of record alignment by power of 2. If it is negative, the default 222 value is specified. The default value is 4 standing for 2^4=16. 223 `fpow' specifies the maximum number of elements of the free block pool by power of 2. If it 224 is negative, the default value is specified. The default value is 10 standing for 2^10=1024. 225 `opts' specifies options by bitwise-or: `TDBTLARGE' specifies that the size of the database 226 can be larger than 2GB by using 64-bit bucket array, `TDBTDEFLATE' specifies that each record 227 is compressed with Deflate encoding, `TDBTBZIP' specifies that each record is compressed with 228 BZIP2 encoding, `TDBTTCBS' specifies that each record is compressed with TCBS encoding. 229 If successful, the return value is true, else, it is false. 230 Note that the tuning parameters should be set before the database is opened. */ 231 bool tctdbtune(TCTDB *tdb, int64_t bnum, int8_t apow, int8_t fpow, uint8_t opts); 232 233 234 /* Set the caching parameters of a table database object. 235 `tdb' specifies the table database object which is not opened. 236 `rcnum' specifies the maximum number of records to be cached. If it is not more than 0, the 237 record cache is disabled. It is disabled by default. 238 `lcnum' specifies the maximum number of leaf nodes to be cached. If it is not more than 0, 239 the default value is specified. The default value is 4096. 240 `ncnum' specifies the maximum number of non-leaf nodes to be cached. If it is not more than 0, 241 the default value is specified. The default value is 512. 242 If successful, the return value is true, else, it is false. 243 Note that the caching parameters should be set before the database is opened. Leaf nodes and 244 non-leaf nodes are used in column indices. */ 245 bool tctdbsetcache(TCTDB *tdb, int32_t rcnum, int32_t lcnum, int32_t ncnum); 246 247 248 /* Set the size of the extra mapped memory of a table database object. 249 `tdb' specifies the table database object which is not opened. 250 `xmsiz' specifies the size of the extra mapped memory. If it is not more than 0, the extra 251 mapped memory is disabled. The default size is 67108864. 252 If successful, the return value is true, else, it is false. 253 Note that the mapping parameters should be set before the database is opened. */ 254 bool tctdbsetxmsiz(TCTDB *tdb, int64_t xmsiz); 255 256 257 /* Set the unit step number of auto defragmentation of a table database object. 258 `tdb' specifies the table database object which is not opened. 259 `dfunit' specifie the unit step number. If it is not more than 0, the auto defragmentation 260 is disabled. It is disabled by default. 261 If successful, the return value is true, else, it is false. 262 Note that the defragmentation parameters should be set before the database is opened. */ 263 bool tctdbsetdfunit(TCTDB *tdb, int32_t dfunit); 264 265 266 /* Open a database file and connect a table database object. 267 `tdb' specifies the table database object which is not opened. 268 `path' specifies the path of the database file. 269 `omode' specifies the connection mode: `TDBOWRITER' as a writer, `TDBOREADER' as a reader. 270 If the mode is `TDBOWRITER', the following may be added by bitwise-or: `TDBOCREAT', which 271 means it creates a new database if not exist, `TDBOTRUNC', which means it creates a new 272 database regardless if one exists, `TDBOTSYNC', which means every transaction synchronizes 273 updated contents with the device. Both of `TDBOREADER' and `TDBOWRITER' can be added to by 274 bitwise-or: `TDBONOLCK', which means it opens the database file without file locking, or 275 `TDBOLCKNB', which means locking is performed without blocking. 276 If successful, the return value is true, else, it is false. */ 277 bool tctdbopen(TCTDB *tdb, const char *path, int omode); 278 279 280 /* Close a table database object. 281 `tdb' specifies the table database object. 282 If successful, the return value is true, else, it is false. 283 Update of a database is assured to be written when the database is closed. If a writer opens 284 a database but does not close it appropriately, the database will be broken. */ 285 bool tctdbclose(TCTDB *tdb); 286 287 288 /* Store a record into a table database object. 289 `tdb' specifies the table database object connected as a writer. 290 `pkbuf' specifies the pointer to the region of the primary key. 291 `pksiz' specifies the size of the region of the primary key. 292 `cols' specifies a map object containing columns. 293 If successful, the return value is true, else, it is false. 294 If a record with the same key exists in the database, it is overwritten. */ 295 bool tctdbput(TCTDB *tdb, const void *pkbuf, int pksiz, TCMAP *cols); 296 297 298 /* Store a string record into a table database object with a zero separated column string. 299 `tdb' specifies the table database object connected as a writer. 300 `pkbuf' specifies the pointer to the region of the primary key. 301 `pksiz' specifies the size of the region of the primary key. 302 `cbuf' specifies the pointer to the region of the zero separated column string where the name 303 and the value of each column are situated one after the other. 304 `csiz' specifies the size of the region of the column string. 305 If successful, the return value is true, else, it is false. 306 If a record with the same key exists in the database, it is overwritten. */ 307 bool tctdbput2(TCTDB *tdb, const void *pkbuf, int pksiz, const void *cbuf, int csiz); 308 309 310 /* Store a string record into a table database object with a tab separated column string. 311 `tdb' specifies the table database object connected as a writer. 312 `pkstr' specifies the string of the primary key. 313 `cstr' specifies the string of the the tab separated column string where the name and the 314 value of each column are situated one after the other. 315 If successful, the return value is true, else, it is false. 316 If a record with the same key exists in the database, it is overwritten. */ 317 bool tctdbput3(TCTDB *tdb, const char *pkstr, const char *cstr); 318 319 320 /* Store a new record into a table database object. 321 `tdb' specifies the table database object connected as a writer. 322 `pkbuf' specifies the pointer to the region of the primary key. 323 `pksiz' specifies the size of the region of the primary key. 324 `cols' specifies a map object containing columns. 325 If successful, the return value is true, else, it is false. 326 If a record with the same key exists in the database, this function has no effect. */ 327 bool tctdbputkeep(TCTDB *tdb, const void *pkbuf, int pksiz, TCMAP *cols); 328 329 330 /* Store a new string record into a table database object with a zero separated column string. 331 `tdb' specifies the table database object connected as a writer. 332 `pkbuf' specifies the pointer to the region of the primary key. 333 `pksiz' specifies the size of the region of the primary key. 334 `cbuf' specifies the pointer to the region of the zero separated column string where the name 335 and the value of each column are situated one after the other. 336 `csiz' specifies the size of the region of the column string. 337 If successful, the return value is true, else, it is false. 338 If a record with the same key exists in the database, this function has no effect. */ 339 bool tctdbputkeep2(TCTDB *tdb, const void *pkbuf, int pksiz, const void *cbuf, int csiz); 340 341 342 /* Store a new string record into a table database object with a tab separated column string. 343 `tdb' specifies the table database object connected as a writer. 344 `pkstr' specifies the string of the primary key. 345 `cstr' specifies the string of the the tab separated column string where the name and the 346 value of each column are situated one after the other. 347 If successful, the return value is true, else, it is false. 348 If a record with the same key exists in the database, this function has no effect. */ 349 bool tctdbputkeep3(TCTDB *tdb, const char *pkstr, const char *cstr); 350 351 352 /* Concatenate columns of the existing record in a table database object. 353 `tdb' specifies the table database object connected as a writer. 354 `pkbuf' specifies the pointer to the region of the primary key. 355 `pksiz' specifies the size of the region of the primary key. 356 `cols' specifies a map object containing columns. 357 If successful, the return value is true, else, it is false. 358 If there is no corresponding record, a new record is created. */ 359 bool tctdbputcat(TCTDB *tdb, const void *pkbuf, int pksiz, TCMAP *cols); 360 361 362 /* Concatenate columns in a table database object with a zero separated column string. 363 `tdb' specifies the table database object connected as a writer. 364 `pkbuf' specifies the pointer to the region of the primary key. 365 `pksiz' specifies the size of the region of the primary key. 366 `cbuf' specifies the pointer to the region of the zero separated column string where the name 367 and the value of each column are situated one after the other. 368 `csiz' specifies the size of the region of the column string. 369 If successful, the return value is true, else, it is false. 370 If there is no corresponding record, a new record is created. */ 371 bool tctdbputcat2(TCTDB *tdb, const void *pkbuf, int pksiz, const void *cbuf, int csiz); 372 373 374 /* Concatenate columns in a table database object with with a tab separated column string. 375 `tdb' specifies the table database object connected as a writer. 376 `pkstr' specifies the string of the primary key. 377 `cstr' specifies the string of the the tab separated column string where the name and the 378 value of each column are situated one after the other. 379 If successful, the return value is true, else, it is false. 380 If there is no corresponding record, a new record is created. */ 381 bool tctdbputcat3(TCTDB *tdb, const char *pkstr, const char *cstr); 382 383 384 /* Remove a record of a table database object. 385 `tdb' specifies the table database object connected as a writer. 386 `pkbuf' specifies the pointer to the region of the primary key. 387 `pksiz' specifies the size of the region of the primary key. 388 If successful, the return value is true, else, it is false. */ 389 bool tctdbout(TCTDB *tdb, const void *pkbuf, int pksiz); 390 391 392 /* Remove a string record of a table database object. 393 `tdb' specifies the table database object connected as a writer. 394 `pkstr' specifies the string of the primary key. 395 If successful, the return value is true, else, it is false. */ 396 bool tctdbout2(TCTDB *tdb, const char *pkstr); 397 398 399 /* Retrieve a record in a table database object. 400 `tdb' specifies the table database object. 401 `pkbuf' specifies the pointer to the region of the primary key. 402 `pksiz' specifies the size of the region of the primary key. 403 If successful, the return value is a map object of the columns of the corresponding record. 404 `NULL' is returned if no record corresponds. 405 Because the object of the return value is created with the function `tcmapnew', it should be 406 deleted with the function `tcmapdel' when it is no longer in use. */ 407 TCMAP *tctdbget(TCTDB *tdb, const void *pkbuf, int pksiz); 408 409 410 /* Retrieve a record in a table database object as a zero separated column string. 411 `tdb' specifies the table database object. 412 `pkbuf' specifies the pointer to the region of the primary key. 413 `pksiz' specifies the size of the region of the primary key. 414 `sp' specifies the pointer to the variable into which the size of the region of the return 415 value is assigned. 416 If successful, the return value is the pointer to the region of the column string of the 417 corresponding record. `NULL' is returned if no record corresponds. 418 Because an additional zero code is appended at the end of the region of the return value, 419 the return value can be treated as a character string. Because the region of the return 420 value is allocated with the `malloc' call, it should be released with the `free' call when 421 it is no longer in use. */ 422 char *tctdbget2(TCTDB *tdb, const void *pkbuf, int pksiz, int *sp); 423 424 425 /* Retrieve a string record in a table database object as a tab separated column string. 426 `tdb' specifies the table database object. 427 `pkstr' specifies the string of the primary key. 428 If successful, the return value is the tab separated column string of the corresponding 429 record. `NULL' is returned if no record corresponds. 430 Because the region of the return value is allocated with the `malloc' call, it should be 431 released with the `free' call when it is no longer in use. */ 432 char *tctdbget3(TCTDB *tdb, const char *pkstr); 433 434 435 /* Get the size of the value of a record in a table database object. 436 `tdb' specifies the table database object. 437 `kbuf' specifies the pointer to the region of the primary key. 438 `ksiz' specifies the size of the region of the primary key. 439 If successful, the return value is the size of the value of the corresponding record, else, 440 it is -1. */ 441 int tctdbvsiz(TCTDB *tdb, const void *pkbuf, int pksiz); 442 443 444 /* Get the size of the value of a string record in a table database object. 445 `tdb' specifies the table database object. 446 `kstr' specifies the string of the primary key. 447 If successful, the return value is the size of the value of the corresponding record, else, 448 it is -1. */ 449 int tctdbvsiz2(TCTDB *tdb, const char *pkstr); 450 451 452 /* Initialize the iterator of a table database object. 453 `tdb' specifies the table database object. 454 If successful, the return value is true, else, it is false. 455 The iterator is used in order to access the primary key of every record stored in a 456 database. */ 457 bool tctdbiterinit(TCTDB *tdb); 458 459 460 /* Get the next primary key of the iterator of a table database object. 461 `tdb' specifies the table database object. 462 `sp' specifies the pointer to the variable into which the size of the region of the return 463 value is assigned. 464 If successful, the return value is the pointer to the region of the next primary key, else, it 465 is `NULL'. `NULL' is returned when no record is to be get out of the iterator. 466 Because an additional zero code is appended at the end of the region of the return value, the 467 return value can be treated as a character string. Because the region of the return value is 468 allocated with the `malloc' call, it should be released with the `free' call when it is no 469 longer in use. It is possible to access every record by iteration of calling this function. 470 It is allowed to update or remove records whose keys are fetched while the iteration. 471 However, it is not assured if updating the database is occurred while the iteration. Besides, 472 the order of this traversal access method is arbitrary, so it is not assured that the order of 473 storing matches the one of the traversal access. */ 474 void *tctdbiternext(TCTDB *tdb, int *sp); 475 476 477 /* Get the next primary key string of the iterator of a table database object. 478 `tdb' specifies the table database object. 479 If successful, the return value is the string of the next primary key, else, it is `NULL'. 480 `NULL' is returned when no record is to be get out of the iterator. 481 Because the region of the return value is allocated with the `malloc' call, it should be 482 released with the `free' call when it is no longer in use. It is possible to access every 483 record by iteration of calling this function. However, it is not assured if updating the 484 database is occurred while the iteration. Besides, the order of this traversal access method 485 is arbitrary, so it is not assured that the order of storing matches the one of the traversal 486 access. */ 487 char *tctdbiternext2(TCTDB *tdb); 488 489 490 /* Get the columns of the next record of the iterator of a table database object. 491 `tdb' specifies the table database object. 492 If successful, the return value is a map object of the columns of the next record, else, it is 493 `NULL'. `NULL' is returned when no record is to be get out of the iterator. The primary key 494 is added into the map as a column of an empty string key. 495 Because the object of the return value is created with the function `tcmapnew', it should be 496 deleted with the function `tcmapdel' when it is no longer in use. It is possible to access 497 every record by iteration of calling this function. However, it is not assured if updating 498 the database is occurred while the iteration. Besides, the order of this traversal access 499 method is arbitrary, so it is not assured that the order of storing matches the one of the 500 traversal access. */ 501 TCMAP *tctdbiternext3(TCTDB *tdb); 502 503 504 /* Get forward matching primary keys in a table database object. 505 `tdb' specifies the table database object. 506 `pbuf' specifies the pointer to the region of the prefix. 507 `psiz' specifies the size of the region of the prefix. 508 `max' specifies the maximum number of keys to be fetched. If it is negative, no limit is 509 specified. 510 The return value is a list object of the corresponding keys. This function does never fail. 511 It returns an empty list even if no key corresponds. 512 Because the object of the return value is created with the function `tclistnew', it should be 513 deleted with the function `tclistdel' when it is no longer in use. Note that this function 514 may be very slow because every key in the database is scanned. */ 515 TCLIST *tctdbfwmkeys(TCTDB *tdb, const void *pbuf, int psiz, int max); 516 517 518 /* Get forward matching string primary keys in a table database object. 519 `tdb' specifies the table database object. 520 `pstr' specifies the string of the prefix. 521 `max' specifies the maximum number of keys to be fetched. If it is negative, no limit is 522 specified. 523 The return value is a list object of the corresponding keys. This function does never fail. 524 It returns an empty list even if no key corresponds. 525 Because the object of the return value is created with the function `tclistnew', it should be 526 deleted with the function `tclistdel' when it is no longer in use. Note that this function 527 may be very slow because every key in the database is scanned. */ 528 TCLIST *tctdbfwmkeys2(TCTDB *tdb, const char *pstr, int max); 529 530 531 /* Add an integer to a column of a record in a table database object. 532 `tdb' specifies the table database object connected as a writer. 533 `kbuf' specifies the pointer to the region of the primary key. 534 `ksiz' specifies the size of the region of the primary key. 535 `num' specifies the additional value. 536 If successful, the return value is the summation value, else, it is `INT_MIN'. 537 The additional value is stored as a decimal string value of a column whose name is "_num". 538 If no record corresponds, a new record with the additional value is stored. */ 539 int tctdbaddint(TCTDB *tdb, const void *pkbuf, int pksiz, int num); 540 541 542 /* Add a real number to a column of a record in a table database object. 543 `tdb' specifies the table database object connected as a writer. 544 `kbuf' specifies the pointer to the region of the primary key. 545 `ksiz' specifies the size of the region of the primary key. 546 `num' specifies the additional value. 547 If successful, the return value is the summation value, else, it is Not-a-Number. 548 The additional value is stored as a decimal string value of a column whose name is "_num". 549 If no record corresponds, a new record with the additional value is stored. */ 550 double tctdbadddouble(TCTDB *tdb, const void *pkbuf, int pksiz, double num); 551 552 553 /* Synchronize updated contents of a table database object with the file and the device. 554 `tdb' specifies the table database object connected as a writer. 555 If successful, the return value is true, else, it is false. 556 This function is useful when another process connects to the same database file. */ 557 bool tctdbsync(TCTDB *tdb); 558 559 560 /* Optimize the file of a table database object. 561 `tdb' specifies the table database object connected as a writer. 562 `bnum' specifies the number of elements of the bucket array. If it is not more than 0, the 563 default value is specified. The default value is two times of the number of records. 564 `apow' specifies the size of record alignment by power of 2. If it is negative, the current 565 setting is not changed. 566 `fpow' specifies the maximum number of elements of the free block pool by power of 2. If it 567 is negative, the current setting is not changed. 568 `opts' specifies options by bitwise-or: `BDBTLARGE' specifies that the size of the database 569 can be larger than 2GB by using 64-bit bucket array, `BDBTDEFLATE' specifies that each record 570 is compressed with Deflate encoding, `BDBTBZIP' specifies that each record is compressed with 571 BZIP2 encoding, `BDBTTCBS' specifies that each record is compressed with TCBS encoding. If it 572 is `UINT8_MAX', the current setting is not changed. 573 If successful, the return value is true, else, it is false. 574 This function is useful to reduce the size of the database file with data fragmentation by 575 successive updating. */ 576 bool tctdboptimize(TCTDB *tdb, int64_t bnum, int8_t apow, int8_t fpow, uint8_t opts); 577 578 579 /* Remove all records of a table database object. 580 `tdb' specifies the table database object connected as a writer. 581 If successful, the return value is true, else, it is false. */ 582 bool tctdbvanish(TCTDB *tdb); 583 584 585 /* Copy the database file of a table database object. 586 `tdb' specifies the table database object. 587 `path' specifies the path of the destination file. If it begins with `@', the trailing 588 substring is executed as a command line. 589 If successful, the return value is true, else, it is false. False is returned if the executed 590 command returns non-zero code. 591 The database file is assured to be kept synchronized and not modified while the copying or 592 executing operation is in progress. So, this function is useful to create a backup file of 593 the database file. */ 594 bool tctdbcopy(TCTDB *tdb, const char *path); 595 596 597 /* Begin the transaction of a table database object. 598 `tdb' specifies the table database object connected as a writer. 599 If successful, the return value is true, else, it is false. 600 The database is locked by the thread while the transaction so that only one transaction can be 601 activated with a database object at the same time. Thus, the serializable isolation level is 602 assumed if every database operation is performed in the transaction. Because all pages are 603 cached on memory while the transaction, the amount of referred records is limited by the 604 memory capacity. If the database is closed during transaction, the transaction is aborted 605 implicitly. */ 606 bool tctdbtranbegin(TCTDB *tdb); 607 608 609 /* Commit the transaction of a table database object. 610 `tdb' specifies the table database object connected as a writer. 611 If successful, the return value is true, else, it is false. 612 Update in the transaction is fixed when it is committed successfully. */ 613 bool tctdbtrancommit(TCTDB *tdb); 614 615 616 /* Abort the transaction of a table database object. 617 `tdb' specifies the table database object connected as a writer. 618 If successful, the return value is true, else, it is false. 619 Update in the transaction is discarded when it is aborted. The state of the database is 620 rollbacked to before transaction. */ 621 bool tctdbtranabort(TCTDB *tdb); 622 623 624 /* Get the file path of a table database object. 625 `tdb' specifies the table database object. 626 The return value is the path of the database file or `NULL' if the object does not connect to 627 any database file. */ 628 const char *tctdbpath(TCTDB *tdb); 629 630 631 /* Get the number of records ccccof a table database object. 632 `tdb' specifies the table database object. 633 The return value is the number of records or 0 if the object does not connect to any database 634 file. */ 635 uint64_t tctdbrnum(TCTDB *tdb); 636 637 638 /* Get the size of the database file of a table database object. 639 `tdb' specifies the table database object. 640 The return value is the size of the database file or 0 if the object does not connect to any 641 database file. */ 642 uint64_t tctdbfsiz(TCTDB *tdb); 643 644 645 /* Set a column index to a table database object. 646 `tdb' specifies the table database object connected as a writer. 647 `name' specifies the name of a column. If the name of an existing index is specified, the 648 index is rebuilt. An empty string means the primary key. 649 `type' specifies the index type: `TDBITLEXICAL' for lexical string, `TDBITDECIMAL' for decimal 650 string, `TDBITTOKEN' for token inverted index, `TDBITQGRAM' for q-gram inverted index. If it 651 is `TDBITOPT', the index is optimized. If it is `TDBITVOID', the index is removed. If 652 `TDBITKEEP' is added by bitwise-or and the index exists, this function merely returns failure. 653 If successful, the return value is true, else, it is false. 654 Note that the setting indices should be set after the database is opened. */ 655 bool tctdbsetindex(TCTDB *tdb, const char *name, int type); 656 657 658 /* Generate a unique ID number of a table database object. 659 `tdb' specifies the table database object connected as a writer. 660 The return value is the new unique ID number or -1 on failure. */ 661 int64_t tctdbgenuid(TCTDB *tdb); 662 663 664 /* Create a query object. 665 `tdb' specifies the table database object. 666 The return value is the new query object. */ 667 TDBQRY *tctdbqrynew(TCTDB *tdb); 668 669 670 /* Delete a query object. 671 `qry' specifies the query object. */ 672 void tctdbqrydel(TDBQRY *qry); 673 674 675 /* Add a narrowing condition to a query object. 676 `qry' specifies the query object. 677 `name' specifies the name of a column. An empty string means the primary key. 678 `op' specifies an operation type: `TDBQCSTREQ' for string which is equal to the expression, 679 `TDBQCSTRINC' for string which is included in the expression, `TDBQCSTRBW' for string which 680 begins with the expression, `TDBQCSTREW' for string which ends with the expression, 681 `TDBQCSTRAND' for string which includes all tokens in the expression, `TDBQCSTROR' for string 682 which includes at least one token in the expression, `TDBQCSTROREQ' for string which is equal 683 to at least one token in the expression, `TDBQCSTRRX' for string which matches regular 684 expressions of the expression, `TDBQCNUMEQ' for number which is equal to the expression, 685 `TDBQCNUMGT' for number which is greater than the expression, `TDBQCNUMGE' for number which is 686 greater than or equal to the expression, `TDBQCNUMLT' for number which is less than the 687 expression, `TDBQCNUMLE' for number which is less than or equal to the expression, `TDBQCNUMBT' 688 for number which is between two tokens of the expression, `TDBQCNUMOREQ' for number which is 689 equal to at least one token in the expression, `TDBQCFTSPH' for full-text search with the 690 phrase of the expression, `TDBQCFTSAND' for full-text search with all tokens in the expression, 691 `TDBQCFTSOR' for full-text search with at least one token in the expression, `TDBQCFTSEX' for 692 full-text search with the compound expression. All operations can be flagged by bitwise-or: 693 `TDBQCNEGATE' for negation, `TDBQCNOIDX' for using no index. 694 `expr' specifies an operand exression. */ 695 void tctdbqryaddcond(TDBQRY *qry, const char *name, int op, const char *expr); 696 697 698 /* Set the order of a query object. 699 `qry' specifies the query object. 700 `name' specifies the name of a column. An empty string means the primary key. 701 `type' specifies the order type: `TDBQOSTRASC' for string ascending, `TDBQOSTRDESC' for 702 string descending, `TDBQONUMASC' for number ascending, `TDBQONUMDESC' for number descending. */ 703 void tctdbqrysetorder(TDBQRY *qry, const char *name, int type); 704 705 706 /* Set the limit number of records of the result of a query object. 707 `qry' specifies the query object. 708 `max' specifies the maximum number of records of the result. If it is negative, no limit is 709 specified. 710 `skip' specifies the number of skipped records of the result. If it is not more than 0, no 711 record is skipped. */ 712 void tctdbqrysetlimit(TDBQRY *qry, int max, int skip); 713 714 715 /* Execute the search of a query object. 716 `qry' specifies the query object. 717 The return value is a list object of the primary keys of the corresponding records. This 718 function does never fail. It returns an empty list even if no record corresponds. 719 Because the object of the return value is created with the function `tclistnew', it should 720 be deleted with the function `tclistdel' when it is no longer in use. */ 721 TCLIST *tctdbqrysearch(TDBQRY *qry); 722 723 724 /* Remove each record corresponding to a query object. 725 `qry' specifies the query object of the database connected as a writer. 726 If successful, the return value is true, else, it is false. */ 727 bool tctdbqrysearchout(TDBQRY *qry); 728 729 730 /* Process each record corresponding to a query object. 731 `qry' specifies the query object of the database connected as a writer. 732 `proc' specifies the pointer to the iterator function called for each record. It receives 733 four parameters. The first parameter is the pointer to the region of the primary key. The 734 second parameter is the size of the region of the primary key. The third parameter is a map 735 object containing columns. The fourth parameter is the pointer to the optional opaque object. 736 It returns flags of the post treatment by bitwise-or: `TDBQPPUT' to modify the record, 737 `TDBQPOUT' to remove the record, `TDBQPSTOP' to stop the iteration. 738 `op' specifies an arbitrary pointer to be given as a parameter of the iterator function. If 739 it is not needed, `NULL' can be specified. 740 If successful, the return value is true, else, it is false. */ 741 bool tctdbqryproc(TDBQRY *qry, TDBQRYPROC proc, void *op); 742 743 744 /* Get the hint string of a query object. 745 `qry' specifies the query object. 746 The return value is the hint string. 747 This function should be called after the query execution by `tctdbqrysearch' and so on. The 748 region of the return value is overwritten when this function is called again. */ 749 const char *tctdbqryhint(TDBQRY *qry); 750 751 752 /* Retrieve records with multiple query objects and get the set of the result. 753 `qrys' specifies an array of the query objects. 754 `num' specifies the number of elements of the array. 755 `type' specifies a set operation type: `TDBMSUNION' for the union set, `TDBMSISECT' for the 756 intersection set, `TDBMSDIFF' for the difference set. 757 The return value is a list object of the primary keys of the corresponding records. This 758 function does never fail. It returns an empty list even if no record corresponds. 759 If the first query object has the order setting, the result array is sorted by the order. 760 Because the object of the return value is created with the function `tclistnew', it should be 761 deleted with the function `tclistdel' when it is no longer in use. */ 762 TCLIST *tctdbmetasearch(TDBQRY **qrys, int num, int type); 763 764 765 766 /************************************************************************************************* 767 * features for experts 768 *************************************************************************************************/ 769 770 771 /* Set the error code of a table database object. 772 `tdb' specifies the table database object. 773 `ecode' specifies the error code. 774 `file' specifies the file name of the code. 775 `line' specifies the line number of the code. 776 `func' specifies the function name of the code. */ 777 void tctdbsetecode(TCTDB *tdb, int ecode, const char *filename, int line, const char *func); 778 779 780 /* Set the file descriptor for debugging output. 781 `tdb' specifies the table database object. 782 `fd' specifies the file descriptor for debugging output. */ 783 void tctdbsetdbgfd(TCTDB *tdb, int fd); 784 785 786 /* Get the file descriptor for debugging output. 787 `tdb' specifies the table database object. 788 The return value is the file descriptor for debugging output. */ 789 int tctdbdbgfd(TCTDB *tdb); 790 791 792 /* Check whether mutual exclusion control is set to a table database object. 793 `tdb' specifies the table database object. 794 If mutual exclusion control is set, it is true, else it is false. */ 795 bool tctdbhasmutex(TCTDB *tdb); 796 797 798 /* Synchronize updating contents on memory of a table database object. 799 `tdb' specifies the table database object connected as a writer. 800 `phys' specifies whether to synchronize physically. 801 If successful, the return value is true, else, it is false. */ 802 bool tctdbmemsync(TCTDB *tdb, bool phys); 803 804 805 /* Get the number of elements of the bucket array of a table database object. 806 `tdb' specifies the table database object. 807 The return value is the number of elements of the bucket array or 0 if the object does not 808 connect to any database file. */ 809 uint64_t tctdbbnum(TCTDB *tdb); 810 811 812 /* Get the record alignment of a table database object. 813 `tdb' specifies the table database object. 814 The return value is the record alignment or 0 if the object does not connect to any database 815 file. */ 816 uint32_t tctdbalign(TCTDB *tdb); 817 818 819 /* Get the maximum number of the free block pool of a table database object. 820 `tdb' specifies the table database object. 821 The return value is the maximum number of the free block pool or 0 if the object does not 822 connect to any database file. */ 823 uint32_t tctdbfbpmax(TCTDB *tdb); 824 825 826 /* Get the inode number of the database file of a table database object. 827 `tdb' specifies the table database object. 828 The return value is the inode number of the database file or 0 if the object does not connect 829 to any database file. */ 830 uint64_t tctdbinode(TCTDB *tdb); 831 832 833 /* Get the modification time of the database file of a table database object. 834 `tdb' specifies the table database object. 835 The return value is the inode number of the database file or 0 if the object does not connect 836 to any database file. */ 837 time_t tctdbmtime(TCTDB *tdb); 838 839 840 /* Get the additional flags of a table database object. 841 `tdb' specifies the table database object. 842 The return value is the additional flags. */ 843 uint8_t tctdbflags(TCTDB *tdb); 844 845 846 /* Get the options of a table database object. 847 `tdb' specifies the table database object. 848 The return value is the options. */ 849 uint8_t tctdbopts(TCTDB *tdb); 850 851 852 /* Get the pointer to the opaque field of a table database object. 853 `tdb' specifies the table database object. 854 The return value is the pointer to the opaque field whose size is 128 bytes. */ 855 char *tctdbopaque(TCTDB *tdb); 856 857 858 /* Get the number of used elements of the bucket array of a table database object. 859 `tdb' specifies the table database object. 860 The return value is the number of used elements of the bucket array or 0 if the object does not 861 connect to any database file. */ 862 uint64_t tctdbbnumused(TCTDB *tdb); 863 864 865 /* Get the number of column indices of a table database object. 866 `tdb' specifies the table database object. 867 The return value is the number of column indices or 0 if the object does not connect to any 868 database file. */ 869 int tctdbinum(TCTDB *tdb); 870 871 872 /* Get the seed of unique ID unumbers of a table database object. 873 `tdb' specifies the table database object. 874 The return value is the seed of unique ID numbers or -1 on failure. */ 875 int64_t tctdbuidseed(TCTDB *tdb); 876 877 878 /* Set the seed of unique ID unumbers of a table database object. 879 `tdb' specifies the table database object connected as a writer. 880 If successful, the return value is true, else, it is false. */ 881 bool tctdbsetuidseed(TCTDB *tdb, int64_t seed); 882 883 884 /* Set the parameters of the inverted cache of a table database object. 885 `tdb' specifies the table database object. 886 `iccmax' specifies the maximum size. If it is not more than 0, the default value is 887 specified. The default value is 67108864. 888 `iccsync' specifies synchronization ratio. If it is not more than 0, the default value is 889 specified. The default value is 0.01. 890 If successful, the return value is true, else, it is false. 891 Note that the caching parameters should be set before the database is opened. */ 892 bool tctdbsetinvcache(TCTDB *tdb, int64_t iccmax, double iccsync); 893 894 895 /* Set the custom codec functions of a table database object. 896 `tdb' specifies the table database object. 897 `enc' specifies the pointer to the custom encoding function. It receives four parameters. 898 The first parameter is the pointer to the region. The second parameter is the size of the 899 region. The third parameter is the pointer to the variable into which the size of the region 900 of the return value is assigned. The fourth parameter is the pointer to the optional opaque 901 object. It returns the pointer to the result object allocated with `malloc' call if 902 successful, else, it returns `NULL'. 903 `encop' specifies an arbitrary pointer to be given as a parameter of the encoding function. 904 If it is not needed, `NULL' can be specified. 905 `dec' specifies the pointer to the custom decoding function. 906 `decop' specifies an arbitrary pointer to be given as a parameter of the decoding function. 907 If it is not needed, `NULL' can be specified. 908 If successful, the return value is true, else, it is false. 909 Note that the custom codec functions should be set before the database is opened and should be 910 set every time the database is being opened. */ 911 bool tctdbsetcodecfunc(TCTDB *tdb, TCCODEC enc, void *encop, TCCODEC dec, void *decop); 912 913 914 /* Get the unit step number of auto defragmentation of a table database object. 915 `tdb' specifies the table database object. 916 The return value is the unit step number of auto defragmentation. */ 917 uint32_t tctdbdfunit(TCTDB *tdb); 918 919 920 /* Perform dynamic defragmentation of a table database object. 921 `tdb' specifies the table database object connected as a writer. 922 `step' specifie the number of steps. If it is not more than 0, the whole file is defragmented 923 gradually without keeping a continuous lock. 924 If successful, the return value is true, else, it is false. */ 925 bool tctdbdefrag(TCTDB *tdb, int64_t step); 926 927 928 /* Clear the cache of a table tree database object. 929 `tdb' specifies the table tree database object. 930 If successful, the return value is true, else, it is false. */ 931 bool tctdbcacheclear(TCTDB *tdb); 932 933 934 /* Store a record into a table database object with a duplication handler. 935 `tdb' specifies the table database object connected as a writer. 936 `pkbuf' specifies the pointer to the region of the primary key. 937 `pksiz' specifies the size of the region of the primary key. 938 `cbuf' specifies the pointer to the region of the zero separated column string where the name 939 and the value of each column are situated one after the other. `NULL' means that record 940 addition is ommited if there is no corresponding record. 941 `csiz' specifies the size of the region of the column string. 942 `proc' specifies the pointer to the callback function to process duplication. It receives 943 four parameters. The first parameter is the pointer to the region of the value. The second 944 parameter is the size of the region of the value. The third parameter is the pointer to the 945 variable into which the size of the region of the return value is assigned. The fourth 946 parameter is the pointer to the optional opaque object. It returns the pointer to the result 947 object allocated with `malloc'. It is released by the caller. If it is `NULL', the record is 948 not modified. If it is `(void *)-1', the record is removed. 949 `op' specifies an arbitrary pointer to be given as a parameter of the callback function. If 950 it is not needed, `NULL' can be specified. 951 If successful, the return value is true, else, it is false. 952 Note that the callback function can not perform any database operation because the function 953 is called in the critical section guarded by the same locks of database operations. */ 954 bool tctdbputproc(TCTDB *tdb, const void *pkbuf, int pksiz, const void *cbuf, int csiz, 955 TCPDPROC proc, void *op); 956 957 958 /* Retrieve the value of a column of a record in a table database object. 959 `tdb' specifies the table database object. 960 `pkbuf' specifies the pointer to the region of the primary key. 961 `pksiz' specifies the size of the region of the primary key. 962 `nbuf' specifies the pointer to the region of the column name. 963 `nsiz' specifies the size of the region of the column name. 964 `sp' specifies the pointer to the variable into which the size of the region of the return 965 value is assigned. 966 If successful, the return value is the pointer to the region of the value of the column of the 967 corresponding record. `NULL' is returned if no record corresponds or there is no column. 968 Because an additional zero code is appended at the end of the region of the return value, 969 the return value can be treated as a character string. Because the region of the return 970 value is allocated with the `malloc' call, it should be released with the `free' call when 971 it is no longer in use. */ 972 char *tctdbget4(TCTDB *tdb, const void *pkbuf, int pksiz, const void *nbuf, int nsiz, int *sp); 973 974 975 /* Move the iterator to the record corresponding a key of a table database object. 976 `tdb' specifies the table database object. 977 `pkbuf' specifies the pointer to the region of the primary key. 978 `pksiz' specifies the size of the region of the primary key. 979 If successful, the return value is true, else, it is false. False is returned if there is 980 no record corresponding the condition. */ 981 bool tctdbiterinit2(TCTDB *tdb, const void *pkbuf, int pksiz); 982 983 984 /* Move the iterator to the record corresponding a key string of a table database object. 985 `tdb' specifies the table database object. 986 `kstr' specifies the string of the primary key. 987 If successful, the return value is true, else, it is false. False is returned if there is 988 no record corresponding the condition. */ 989 bool tctdbiterinit3(TCTDB *tdb, const char *kstr); 990 991 992 /* Process each record atomically of a table database object. 993 `tdb' specifies the table database object. 994 `iter' specifies the pointer to the iterator function called for each record. It receives 995 five parameters. The first parameter is the pointer to the region of the key. The second 996 parameter is the size of the region of the key. The third parameter is the pointer to the 997 region of the value. The fourth parameter is the size of the region of the value. The fifth 998 parameter is the pointer to the optional opaque object. It returns true to continue iteration 999 or false to stop iteration. 1000 `op' specifies an arbitrary pointer to be given as a parameter of the iterator function. If 1001 it is not needed, `NULL' can be specified. 1002 If successful, the return value is true, else, it is false. 1003 Note that the callback function can not perform any database operation because the function 1004 is called in the critical section guarded by the same locks of database operations. */ 1005 bool tctdbforeach(TCTDB *tdb, TCITER iter, void *op); 1006 1007 1008 /* Process each record corresponding to a query object with non-atomic fashion. 1009 `qry' specifies the query object of the database connected as a writer. 1010 `proc' specifies the pointer to the iterator function called for each record. It receives 1011 four parameters. The first parameter is the pointer to the region of the primary key. The 1012 second parameter is the size of the region of the primary key. The third parameter is a map 1013 object containing columns. The fourth parameter is the pointer to the optional opaque object. 1014 It returns flags of the post treatment by bitwise-or: `TDBQPPUT' to modify the record, 1015 `TDBQPOUT' to remove the record, `TDBQPSTOP' to stop the iteration. 1016 `op' specifies an arbitrary pointer to be given as a parameter of the iterator function. If 1017 it is not needed, `NULL' can be specified. 1018 If successful, the return value is true, else, it is false. */ 1019 bool tctdbqryproc2(TDBQRY *qry, TDBQRYPROC proc, void *op); 1020 1021 1022 /* Remove each record corresponding to a query object with non-atomic fashion. 1023 `qry' specifies the query object of the database connected as a writer. 1024 If successful, the return value is true, else, it is false. */ 1025 bool tctdbqrysearchout2(TDBQRY *qry); 1026 1027 1028 /* Convert a string into the index type number. 1029 `str' specifies a string. 1030 The return value is the index type number or -1 on failure. */ 1031 int tctdbstrtoindextype(const char *str); 1032 1033 1034 /* Convert a string into the meta search type number. 1035 `str' specifies a string. 1036 The return value is the meta search type number or -1 on failure. */ 1037 int tctdbstrtometasearcytype(const char *str); 1038 1039 1040 /* Get the count of corresponding records of a query object. 1041 `qry' specifies the query object. 1042 The return value is the count of corresponding records. */ 1043 int tctdbqrycount(TDBQRY *qry); 1044 1045 1046 /* Generate keyword-in-context strings from a query object. 1047 `qry' specifies the query object. 1048 `cols' specifies a map object containing columns. 1049 `name' specifies the name of a column. If it is `NULL', the first column of the query is 1050 specified. 1051 `width' specifies the width of strings picked up around each keyword. 1052 `opts' specifies options by bitwise-or: `TCKWMUTAB' specifies that each keyword is marked up 1053 between two tab characters, `TCKWMUCTRL' specifies that each keyword is marked up by the STX 1054 (0x02) code and the ETX (0x03) code, `TCKWMUBRCT' specifies that each keyword is marked up by 1055 the two square brackets, `TCKWNOOVER' specifies that each context does not overlap, 1056 `TCKWPULEAD' specifies that the lead string is picked up forcibly. 1057 The return value is the list object whose elements are strings around keywords. 1058 Because the object of the return value is created with the function `tclistnew', it should 1059 be deleted with the function `tclistdel' when it is no longer in use. */ 1060 TCLIST *tctdbqrykwic(TDBQRY *qry, TCMAP *cols, const char *name, int width, int opts); 1061 1062 1063 /* Convert a string into the query operation number. 1064 `str' specifies a string. 1065 The return value is the query operation number or -1 on failure. */ 1066 int tctdbqrystrtocondop(const char *str); 1067 1068 1069 /* Convert a string into the query order type number. 1070 `str' specifies a string. 1071 The return value is the query order type or -1 on failure. */ 1072 int tctdbqrystrtoordertype(const char *str); 1073 1074 1075 /* Convert a string into the set operation type number. 1076 `str' specifies a string. 1077 The return value is the set operation type or -1 on failure. */ 1078 int tctdbmetastrtosettype(const char *str); 1079 1080 1081 1082 __TCTDB_CLINKAGEEND 1083 #endif /* duplication check */ 1084 1085 1086 /* END OF FILE */ 1087