1TCRDB(3) Tokyo Tyrant TCRDB(3)
2
6 tcrdb - the remote database API
7
10 Remote database is a set of interfaces to use an abstract database of
11 Tokyo Cabinet, mediated by a server of Tokyo Tyrant.
12 To use the remote database API, include `tcrdb.h' and related standard
14 header files. Usually, write the following description near the front
15 of a source file.
16 #include <tcrdb.h>
18 #include <stdlib.h>
19 #include <stdbool.h>
20 #include <stdint.h>
21 Objects whose type is pointer to `TCRDB' are used to handle remote
23 databases. a remote database object is created with the function
24 `tcrdbnew' and is deleted with the function `tcrdbdel'. To avoid mem‐
25 ory leak, it is important to delete every object when it is no longer
26 in use.
27 Before operations to store or retrieve records, it is necessary to con‐
29 nect the remote database object to the server. The function `tcrd‐
30 bopen' is used to open a database connection and the function `tcrdb‐
31 close' is used to close the connection.
32
35 The function `tcrdberrmsg' is used in order to get the message string
36 corresponding to an error code.
37 const char *tcrdberrmsg(int ecode);
39 `ecode' specifies the error code.
40 The return value is the message string of the error code.
41 The function `tcrdbnew' is used in order to create a remote database
43 object.
44 TCRDB *tcrdbnew(void);
46 The return value is the new remote database object.
47 The function `tcrdbdel' is used in order to delete a remote database
49 object.
50 void tcrdbdel(TCRDB *rdb);
52 `rdb' specifies the remote database object.
53 The function `tcrdbecode' is used in order to get the last happened
55 error code of a remote database object.
56 int tcrdbecode(TCRDB *rdb);
58 `rdb' specifies the remote database object.
59 The return value is the last happened error code.
60 The following error code is defined: `TTESUCCESS' for
61 success, `TTEINVALID' for invalid operation, `TTENOHOST'
62 for host not found, `TTEREFUSED' for connection refused,
63 `TTESEND' for send error, `TTERECV' for recv error, `TTE‐
64 KEEP' for existing record, `TTENOREC' for no record
65 found, `TTEMISC' for miscellaneous error.
66 The function `tcrdbtune' is used in order to set the tuning parameters
68 of a hash database object.
69 bool tcrdbtune(TCRDB *rdb, double timeout, int opts);
71 `rdb' specifies the remote database object.
72 `timeout' specifies the timeout of each query in seconds.
73 If it is not more than 0, the timeout is not specified.
74 `opts' specifies options by bitwise-or: `RDBTRECON' spec‐
75 ifies that the connection is recovered automatically when
76 it is disconnected.
77 If successful, the return value is true, else, it is
78 false.
79 Note that the tuning parameters should be set before the
80 database is opened.
81 The function `tcrdbopen' is used in order to open a remote database.
83 bool tcrdbopen(TCRDB *rdb, const char *host, int port);
85 `rdb' specifies the remote database object.
86 `host' specifies the name or the address of the server.
87 `port' specifies the port number. If it is not more than
88 0, UNIX domain socket is used and the path of the socket
89 file is specified by the host parameter.
90 If successful, the return value is true, else, it is
91 false.
92 The function `tcrdbopen2' is used in order to open a remote database
94 with a simple server expression.
95 bool tcrdbopen2(TCRDB *rdb, const char *expr);
97 `rdb' specifies the remote database object.
98 `expr' specifies the simple server expression. It is
99 composed of two substrings separated by ":". The former
100 field specifies the name or the address of the server.
101 The latter field specifies the port number. If the lat‐
102 ter field is omitted, the default port number is speci‐
103 fied.
104 If successful, the return value is true, else, it is
105 false.
106 The function `tcrdbclose' is used in order to close a remote database
108 object.
109 bool tcrdbclose(TCRDB *rdb);
111 `rdb' specifies the remote database object.
112 If successful, the return value is true, else, it is
113 false.
114 The function `tcrdbput' is used in order to store a record into a
116 remote database object.
117 bool tcrdbput(TCRDB *rdb, const void *kbuf, int ksiz, const void
119 *vbuf, int vsiz);
120 `rdb' specifies the remote database object.
121 `kbuf' specifies the pointer to the region of the key.
122 `ksiz' specifies the size of the region of the key.
123 `vbuf' specifies the pointer to the region of the value.
124 `vsiz' specifies the size of the region of the value.
125 If successful, the return value is true, else, it is
126 false.
127 If a record with the same key exists in the database, it
128 is overwritten.
129 The function `tcrdbput2' is used in order to store a string record into
131 a remote object.
132 bool tcrdbput2(TCRDB *rdb, const char *kstr, const char *vstr);
134 `rdb' specifies the remote database object.
135 `kstr' specifies the string of the key.
136 `vstr' specifies the string of the value.
137 If successful, the return value is true, else, it is
138 false.
139 If a record with the same key exists in the database, it
140 is overwritten.
141 The function `tcrdbputkeep' is used in order to store a new record into
143 a remote database object.
144 bool tcrdbputkeep(TCRDB *rdb, const void *kbuf, int ksiz, const
146 void *vbuf, int vsiz);
147 `rdb' specifies the remote database object.
148 `kbuf' specifies the pointer to the region of the key.
149 `ksiz' specifies the size of the region of the key.
150 `vbuf' specifies the pointer to the region of the value.
151 `vsiz' specifies the size of the region of the value.
152 If successful, the return value is true, else, it is
153 false.
154 If a record with the same key exists in the database,
155 this function has no effect.
156 The function `tcrdbputkeep2' is used in order to store a new string
158 record into a remote database object.
159 bool tcrdbputkeep2(TCRDB *rdb, const char *kstr, const char
161 *vstr);
162 `rdb' specifies the remote database object.
163 `kstr' specifies the string of the key.
164 `vstr' specifies the string of the value.
165 If successful, the return value is true, else, it is
166 false.
167 If a record with the same key exists in the database,
168 this function has no effect.
169 The function `tcrdbputcat' is used in order to concatenate a value at
171 the end of the existing record in a remote database object.
172 bool tcrdbputcat(TCRDB *rdb, const void *kbuf, int ksiz, const
174 void *vbuf, int vsiz);
175 `rdb' specifies the remote database object.
176 `kbuf' specifies the pointer to the region of the key.
177 `ksiz' specifies the size of the region of the key.
178 `vbuf' specifies the pointer to the region of the value.
179 `vsiz' specifies the size of the region of the value.
180 If successful, the return value is true, else, it is
181 false.
182 If there is no corresponding record, a new record is cre‐
183 ated.
184 The function `tcrdbputcat2' is used in order to concatenate a string
186 value at the end of the existing record in a remote database object.
187 bool tcrdbputcat2(TCRDB *rdb, const char *kstr, const char
189 *vstr);
190 `rdb' specifies the remote database object.
191 `kstr' specifies the string of the key.
192 `vstr' specifies the string of the value.
193 If successful, the return value is true, else, it is
194 false.
195 If there is no corresponding record, a new record is cre‐
196 ated.
197 The function `tcrdbputshl' is used in order to concatenate a value at
199 the end of the existing record and shift it to the left.
200 bool tcrdbputshl(TCRDB *rdb, const void *kbuf, int ksiz, const
202 void *vbuf, int vsiz, int width);
203 `rdb' specifies the remote database object.
204 `kbuf' specifies the pointer to the region of the key.
205 `ksiz' specifies the size of the region of the key.
206 `vbuf' specifies the pointer to the region of the value.
207 `vsiz' specifies the size of the region of the value.
208 `width' specifies the width of the record.
209 If successful, the return value is true, else, it is
210 false.
211 If there is no corresponding record, a new record is cre‐
212 ated.
213 The function `tcrdbputshl2' is used in order to concatenate a string
215 value at the end of the existing record and shift it to the left.
216 bool tcrdbputshl2(TCRDB *rdb, const char *kstr, const char
218 *vstr, int width);
219 `rdb' specifies the remote database object.
220 `kstr' specifies the string of the key.
221 `vstr' specifies the string of the value.
222 `width' specifies the width of the record.
223 If successful, the return value is true, else, it is
224 false.
225 If there is no corresponding record, a new record is cre‐
226 ated.
227 The function `tcrdbputnr' is used in order to store a record into a
229 remote database object without response from the server.
230 bool tcrdbputnr(TCRDB *rdb, const void *kbuf, int ksiz, const
232 void *vbuf, int vsiz);
233 `rdb' specifies the remote database object.
234 `kbuf' specifies the pointer to the region of the key.
235 `ksiz' specifies the size of the region of the key.
236 `vbuf' specifies the pointer to the region of the value.
237 `vsiz' specifies the size of the region of the value.
238 If successful, the return value is true, else, it is
239 false.
240 If a record with the same key exists in the database, it
241 is overwritten.
242 The function `tcrdbputnr2' is used in order to store a string record
244 into a remote object without response from the server.
245 bool tcrdbputnr2(TCRDB *rdb, const char *kstr, const char
247 *vstr);
248 `rdb' specifies the remote database object.
249 `kstr' specifies the string of the key.
250 `vstr' specifies the string of the value.
251 If successful, the return value is true, else, it is
252 false.
253 If a record with the same key exists in the database, it
254 is overwritten.
255 The function `tcrdbout' is used in order to remove a record of a remote
257 database object.
258 bool tcrdbout(TCRDB *rdb, const void *kbuf, int ksiz);
260 `rdb' specifies the remote database object.
261 `kbuf' specifies the pointer to the region of the key.
262 `ksiz' specifies the size of the region of the key.
263 If successful, the return value is true, else, it is
264 false.
265 The function `tcrdbout2' is used in order to remove a string record of
267 a remote database object.
268 bool tcrdbout2(TCRDB *rdb, const char *kstr);
270 `rdb' specifies the remote database object.
271 `kstr' specifies the string of the key.
272 If successful, the return value is true, else, it is
273 false.
274 The function `tcrdbget' is used in order to retrieve a record in a
276 remote database object.
277 void *tcrdbget(TCRDB *rdb, const void *kbuf, int ksiz, int *sp);
279 `rdb' specifies the remote database object.
280 `kbuf' specifies the pointer to the region of the key.
281 `ksiz' specifies the size of the region of the key.
282 `sp' specifies the pointer to the variable into which the
283 size of the region of the return value is assigned.
284 If successful, the return value is the pointer to the
285 region of the value of the corresponding record. `NULL'
286 is returned if no record corresponds.
287 Because an additional zero code is appended at the end of
288 the region of the return value, the return value can be
289 treated as a character string. Because the region of the
290 return value is allocated with the `malloc' call, it
291 should be released with the `free' call when it is no
292 longer in use.
293 The function `tcrdbget2' is used in order to retrieve a string record
295 in a remote database object.
296 char *tcrdbget2(TCRDB *rdb, const char *kstr);
298 `rdb' specifies the remote database object.
299 `kstr' specifies the string of the key.
300 If successful, the return value is the string of the
301 value of the corresponding record. `NULL' is returned if
302 no record corresponds.
303 Because the region of the return value is allocated with
304 the `malloc' call, it should be released with the `free'
305 call when it is no longer in use.
306 The function `tcrdbget3' is used in order to retrieve records in a
308 remote database object.
309 bool tcrdbget3(TCRDB *rdb, TCMAP *recs);
311 `rdb' specifies the remote database object.
312 `recs' specifies a map object containing the retrieval
313 keys. As a result of this function, keys existing in the
314 database have the corresponding values and keys not
315 existing in the database are removed.
316 If successful, the return value is true, else, it is
317 false.
318 The function `tcrdbvsiz' is used in order to get the size of the value
320 of a record in a remote database object.
321 int tcrdbvsiz(TCRDB *rdb, const void *kbuf, int ksiz);
323 `rdb' specifies the remote database object.
324 `kbuf' specifies the pointer to the region of the key.
325 `ksiz' specifies the size of the region of the key.
326 If successful, the return value is the size of the value
327 of the corresponding record, else, it is -1.
328 The function `tcrdbvsiz2' is used in order to get the size of the value
330 of a string record in a remote database object.
331 int tcrdbvsiz2(TCRDB *rdb, const char *kstr);
333 `rdb' specifies the remote database object.
334 `kstr' specifies the string of the key.
335 If successful, the return value is the size of the value
336 of the corresponding record, else, it is -1.
337 The function `tcrdbiterinit' is used in order to initialize the itera‐
339 tor of a remote database object.
340 bool tcrdbiterinit(TCRDB *rdb);
342 `rdb' specifies the remote database object.
343 If successful, the return value is true, else, it is
344 false.
345 The iterator is used in order to access the key of every
346 record stored in a database.
347 The function `tcrdbiternext' is used in order to get the next key of
349 the iterator of a remote database object.
350 void *tcrdbiternext(TCRDB *rdb, int *sp);
352 `rdb' specifies the remote database object.
353 `sp' specifies the pointer to the variable into which the
354 size of the region of the return value is assigned.
355 If successful, the return value is the pointer to the
356 region of the next key, else, it is `NULL'. `NULL' is
357 returned when no record is to be get out of the iterator.
358 Because an additional zero code is appended at the end of
359 the region of the return value, the return value can be
360 treated as a character string. Because the region of the
361 return value is allocated with the `malloc' call, it
362 should be released with the `free' call when it is no
363 longer in use. The iterator can be updated by multiple
364 connections and then it is not assured that every record
365 is traversed.
366 The function `tcrdbiternext2' is used in order to get the next key
368 string of the iterator of a remote database object.
369 char *tcrdbiternext2(TCRDB *rdb);
371 `rdb' specifies the remote database object.
372 If successful, the return value is the string of the next
373 key, else, it is `NULL'. `NULL' is returned when no
374 record is to be get out of the iterator.
375 Because the region of the return value is allocated with
376 the `malloc' call, it should be released with the `free'
377 call when it is no longer in use. The iterator can be
378 updated by multiple connections and then it is not
379 assured that every record is traversed.
380 The function `tcrdbfwmkeys' is used in order to get forward matching
382 keys in a remote database object.
383 TCLIST *tcrdbfwmkeys(TCRDB *rdb, const void *pbuf, int psiz, int
385 max);
386 `rdb' specifies the remote database object.
387 `pbuf' specifies the pointer to the region of the prefix.
388 `psiz' specifies the size of the region of the prefix.
389 `max' specifies the maximum number of keys to be fetched.
390 If it is negative, no limit is specified.
391 The return value is a list object of the corresponding
392 keys. This function does never fail. It returns an
393 empty list even if no key corresponds.
394 Because the object of the return value is created with
395 the function `tclistnew', it should be deleted with the
396 function `tclistdel' when it is no longer in use.
397 The function `tcrdbfwmkeys2' is used in order to get forward matching
399 string keys in a remote database object.
400 TCLIST *tcrdbfwmkeys2(TCRDB *rdb, const char *pstr, int max);
402 `rdb' specifies the remote database object.
403 `pstr' specifies the string of the prefix.
404 `max' specifies the maximum number of keys to be fetched.
405 If it is negative, no limit is specified.
406 The return value is a list object of the corresponding
407 keys. This function does never fail. It returns an
408 empty list even if no key corresponds.
409 Because the object of the return value is created with
410 the function `tclistnew', it should be deleted with the
411 function `tclistdel' when it is no longer in use.
412 The function `tcrdbaddint' is used in order to add an integer to a
414 record in a remote database object.
415 int tcrdbaddint(TCRDB *rdb, const void *kbuf, int ksiz, int
417 num);
418 `rdb' specifies the remote database object.
419 `kbuf' specifies the pointer to the region of the key.
420 `ksiz' specifies the size of the region of the key.
421 `num' specifies the additional value.
422 If successful, the return value is the summation value,
423 else, it is `INT_MIN'.
424 If the corresponding record exists, the value is treated
425 as an integer and is added to. If no record corresponds,
426 a new record of the additional value is stored.
427 The function `tcrdbadddouble' is used in order to add a real number to
429 a record in a remote database object.
430 double tcrdbadddouble(TCRDB *rdb, const void *kbuf, int ksiz,
432 double num);
433 `rdb' specifies the remote database object.
434 `kbuf' specifies the pointer to the region of the key.
435 `ksiz' specifies the size of the region of the key.
436 `num' specifies the additional value.
437 If successful, the return value is the summation value,
438 else, it is Not-a-Number.
439 If the corresponding record exists, the value is treated
440 as a real number and is added to. If no record corre‐
441 sponds, a new record of the additional value is stored.
442 The function `tcrdbext' is used in order to call a function of the
444 script language extension.
445 void *tcrdbext(TCRDB *rdb, const char *name, int opts, const
447 void *kbuf, int ksiz, const void *vbuf, int vsiz, int *sp);
448 `rdb' specifies the remote database object.
449 `name' specifies the function name.
450 `opts' specifies options by bitwise-or: `RDBXOLCKREC' for
451 record locking, `RDBXOLCKGLB' for global locking.
452 `kbuf' specifies the pointer to the region of the key.
453 `ksiz' specifies the size of the region of the key.
454 `vbuf' specifies the pointer to the region of the value.
455 `vsiz' specifies the size of the region of the value.
456 `sp' specifies the pointer to the variable into which the
457 size of the region of the return value is assigned.
458 If successful, the return value is the pointer to the
459 region of the value of the response. `NULL' is returned
460 on failure.
461 Because an additional zero code is appended at the end of
462 the region of the return value, the return value can be
463 treated as a character string. Because the region of the
464 return value is allocated with the `malloc' call, it
465 should be released with the `free' call when it is no
466 longer in use.
467 The function `tcrdbext2' is used in order to call a function of the
469 script language extension with string parameters.
470 char *tcrdbext2(TCRDB *rdb, const char *name, int opts, const
472 char *kstr, const char *vstr);
473 `rdb' specifies the remote database object.
474 `name' specifies the function name.
475 `opts' specifies options by bitwise-or: `RDBXOLCKREC' for
476 record locking, `RDBXOLCKGLB' for global locking.
477 `kstr' specifies the string of the key.
478 `vstr' specifies the string of the value.
479 If successful, the return value is the string of the
480 value of the response. `NULL' is returned on failure.
481 Because the region of the return value is allocated with
482 the `malloc' call, it should be released with the `free'
483 call when it is no longer in use.
484 The function `tcrdbsync' is used in order to synchronize updated con‐
486 tents of a remote database object with the file and the device.
487 bool tcrdbsync(TCRDB *rdb);
489 `rdb' specifies the remote database object.
490 If successful, the return value is true, else, it is
491 false.
492 The function `tcrdboptimize' is used in order to optimize the storage
494 of a remove database object.
495 bool tcrdboptimize(TCRDB *rdb, const char *params);
497 `rdb' specifies the remote database object.
498 `params' specifies the string of the tuning parameters.
499 If it is `NULL', it is not used.
500 If successful, the return value is true, else, it is
501 false.
502 The function `tcrdbvanish' is used in order to remove all records of a
504 remote database object.
505 bool tcrdbvanish(TCRDB *rdb);
507 `rdb' specifies the remote database object.
508 If successful, the return value is true, else, it is
509 false.
510 The function `tcrdbcopy' is used in order to copy the database file of
512 a remote database object.
513 bool tcrdbcopy(TCRDB *rdb, const char *path);
515 `rdb' specifies the remote database object.
516 `path' specifies the path of the destination file. If it
517 begins with `@', the trailing substring is executed as a
518 command line.
519 If successful, the return value is true, else, it is
520 false. False is returned if the executed command returns
521 non-zero code.
522 The database file is assured to be kept synchronized and
523 not modified while the copying or executing operation is
524 in progress. So, this function is useful to create a
525 backup file of the database file.
526 The function `tcrdbrestore' is used in order to restore the database
528 file of a remote database object from the update log.
529 bool tcrdbrestore(TCRDB *rdb, const char *path, uint64_t ts, int
531 opts);
532 `rdb' specifies the remote database object.
533 `path' specifies the path of the update log directory.
534 `opts' specifies options by bitwise-or: `RDBROCHKCON' for
535 consistency checking.
536 `ts' specifies the beginning time stamp in microseconds.
537 If successful, the return value is true, else, it is
538 false.
539 The function `tcrdbsetmst' is used in order to set the replication mas‐
541 ter of a remote database object.
542 bool tcrdbsetmst(TCRDB *rdb, const char *host, int port,
544 uint64_t ts, int opts);
545 `rdb' specifies the remote database object.
546 `host' specifies the name or the address of the server.
547 If it is `NULL', replication of the database is disabled.
548 `port' specifies the port number.
549 `ts' specifies the beginning timestamp in microseconds.
550 `opts' specifies options by bitwise-or: `RDBROCHKCON' for
551 consistency checking.
552 If successful, the return value is true, else, it is
553 false.
554 The function `tcrdbsetmst2' is used in order to set the replication
556 master of a remote database object with a simple server expression.
557 bool tcrdbsetmst2(TCRDB *rdb, const char *expr, uint64_t ts, int
559 opts);
560 `rdb' specifies the remote database object.
561 `expr' specifies the simple server expression. It is
562 composed of two substrings separated by ":". The former
563 field specifies the name or the address of the server.
564 The latter field specifies the port number. If the lat‐
565 ter field is omitted, the default port number is speci‐
566 fied.
567 `ts' specifies the beginning timestamp in microseconds.
568 `opts' specifies options by bitwise-or: `RDBROCHKCON' for
569 consistency checking.
570 If successful, the return value is true, else, it is
571 false.
572 The function `tcrdbrnum' is used in order to get the number of records
574 of a remote database object.
575 uint64_t tcrdbrnum(TCRDB *rdb);
577 `rdb' specifies the remote database object.
578 The return value is the number of records or 0 if the
579 object does not connect to any database server.
580 The function `tcrdbsize' is used in order to get the size of the data‐
582 base of a remote database object.
583 uint64_t tcrdbsize(TCRDB *rdb);
585 `rdb' specifies the remote database object.
586 The return value is the size of the database or 0 if the
587 object does not connect to any database server.
588 The function `tcrdbstat' is used in order to get the status string of
590 the database of a remote database object.
591 char *tcrdbstat(TCRDB *rdb);
593 `rdb' specifies the remote database object.
594 The return value is the status message of the database or
595 `NULL' if the object does not connect to any database
596 server. The message format is TSV. The first field of
597 each line means the parameter name and the second field
598 means the value.
599 Because the region of the return value is allocated with
600 the `malloc' call, it should be released with the `free'
601 call when it is no longer in use.
602 The function `tcrdbmisc' is used in order to call a versatile function
604 for miscellaneous operations of a remote database object.
605 TCLIST *tcrdbmisc(TCRDB *rdb, const char *name, int opts, const
607 TCLIST *args);
608 `rdb' specifies the remote database object.
609 `name' specifies the name of the function. All databases
610 support "put", "out", "get", "putlist", "outlist", and
611 "getlist". "put" is to store a record. It receives a
612 key and a value, and returns an empty list. "out" is to
613 remove a record. It receives a key, and returns an empty
614 list. "get" is to retrieve a record. It receives a key,
615 and returns a list of the values. "putlist" is to store
616 records. It receives keys and values one after the
617 other, and returns an empty list. "outlist" is to remove
618 records. It receives keys, and returns an empty list.
619 "getlist" is to retrieve records. It receives keys, and
620 returns keys and values of corresponding records one
621 after the other.
622 `opts' specifies options by bitwise-or: `RDBMONOULOG' for
623 omission of the update log.
624 `args' specifies a list object containing arguments.
625 If successful, the return value is a list object of the
626 result. `NULL' is returned on failure.
627 Because the object of the return value is created with
628 the function `tclistnew', it should be deleted with the
629 function `tclistdel' when it is no longer in use.
630
633 The function `tcrdbtblput' is used in order to store a record into a
634 remote database object.
635 bool tcrdbtblput(TCRDB *rdb, const void *pkbuf, int pksiz, TCMAP
637 *cols);
638 `rdb' specifies the remote database object.
639 `pkbuf' specifies the pointer to the region of the pri‐
640 mary key.
641 `pksiz' specifies the size of the region of the primary
642 key.
643 `cols' specifies a map object containing columns.
644 If successful, the return value is true, else, it is
645 false.
646 If a record with the same key exists in the database, it
647 is overwritten.
648 The function `tcrdbtblputkeep' is used in order to store a new record
650 into a remote database object.
651 bool tcrdbtblputkeep(TCRDB *rdb, const void *pkbuf, int pksiz,
653 TCMAP *cols);
654 `rdb' specifies the remote database object.
655 `pkbuf' specifies the pointer to the region of the pri‐
656 mary key.
657 `pksiz' specifies the size of the region of the primary
658 key.
659 `cols' specifies a map object containing columns.
660 If successful, the return value is true, else, it is
661 false.
662 If a record with the same key exists in the database,
663 this function has no effect.
664 The function `tcrdbtblputcat' is used in order to concatenate columns
666 of the existing record in a remote database object.
667 bool tcrdbtblputcat(TCRDB *rdb, const void *pkbuf, int pksiz,
669 TCMAP *cols);
670 `rdb' specifies the remote database object.
671 `pkbuf' specifies the pointer to the region of the pri‐
672 mary key.
673 `pksiz' specifies the size of the region of the primary
674 key.
675 `cols' specifies a map object containing columns.
676 If successful, the return value is true, else, it is
677 false.
678 If there is no corresponding record, a new record is cre‐
679 ated.
680 The function `tcrdbtblout' is used in order to remove a record of a
682 remote database object.
683 bool tcrdbtblout(TCRDB *rdb, const void *pkbuf, int pksiz);
685 `rdb' specifies the remote database object.
686 `pkbuf' specifies the pointer to the region of the pri‐
687 mary key.
688 `pksiz' specifies the size of the region of the primary
689 key.
690 If successful, the return value is true, else, it is
691 false.
692 The function `tcrdbtblget' is used in order to retrieve a record in a
694 remote database object.
695 TCMAP *tcrdbtblget(TCRDB *rdb, const void *pkbuf, int pksiz);
697 `rdb' specifies the remote database object.
698 `pkbuf' specifies the pointer to the region of the pri‐
699 mary key.
700 `pksiz' specifies the size of the region of the primary
701 key.
702 If successful, the return value is a map object of the
703 columns of the corresponding record. `NULL' is returned
704 if no record corresponds.
705 Because the object of the return value is created with
706 the function `tcmapnew', it should be deleted with the
707 function `tcmapdel' when it is no longer in use.
708 The function `tcrdbtblsetindex' is used in order to set a column index
710 to a remote database object.
711 bool tcrdbtblsetindex(TCRDB *rdb, const char *name, int type);
713 `rdb' specifies the remote database object.
714 `name' specifies the name of a column. If the name of an
715 existing index is specified, the index is rebuilt. An
716 empty string means the primary key.
717 `type' specifies the index type: `RDBITLEXICAL' for lexi‐
718 cal string, `RDBITDECIMAL' for decimal string, `RDBITTO‐
719 KEN' for token inverted index, `RDBITQGRAM' for q-gram
720 inverted index. If it is `RDBITOPT', the index is opti‐
721 mized. If it is `RDBITVOID', the index is removed. If
722 `RDBITKEEP' is added by bitwise-or and the index exists,
723 this function merely returns failure.
724 If successful, the return value is true, else, it is
725 false.
726 The function `tcrdbtblgenuid' is used in order to generate a unique ID
728 number of a remote database object.
729 int64_t tcrdbtblgenuid(TCRDB *rdb);
731 `rdb' specifies the remote database object.
732 The return value is the new unique ID number or -1 on
733 failure.
734 The function `tcrdbqrynew' is used in order to create a query object.
736 RDBQRY *tcrdbqrynew(TCRDB *rdb);
738 `rdb' specifies the remote database object.
739 The return value is the new query object.
740 The function `tcrdbqrydel' is used in order to delete a query object.
742 void tcrdbqrydel(RDBQRY *qry);
744 `qry' specifies the query object.
745 The function `tcrdbqryaddcond' is used in order to add a narrowing con‐
747 dition to a query object.
748 void tcrdbqryaddcond(RDBQRY *qry, const char *name, int op,
750 const char *expr);
751 `qry' specifies the query object.
752 `name' specifies the name of a column. An empty string
753 means the primary key.
754 `op' specifies an operation type: `RDBQCSTREQ' for string
755 which is equal to the expression, `RDBQCSTRINC' for
756 string which is included in the expression, `RDBQCSTRBW'
757 for string which begins with the expression, `RDBQCSTREW'
758 for string which ends with the expression, `RDBQCSTRAND'
759 for string which includes all tokens in the expression,
760 `RDBQCSTROR' for string which includes at least one token
761 in the expression, `RDBQCSTROREQ' for string which is
762 equal to at least one token in the expression, `RDBQC‐
763 STRRX' for string which matches regular expressions of
764 the expression, `RDBQCNUMEQ' for number which is equal to
765 the expression, `RDBQCNUMGT' for number which is greater
766 than the expression, `RDBQCNUMGE' for number which is
767 greater than or equal to the expression, `RDBQCNUMLT' for
768 number which is less than the expression, `RDBQCNUMLE'
769 for number which is less than or equal to the expression,
770 `RDBQCNUMBT' for number which is between two tokens of
771 the expression, `RDBQCNUMOREQ' for number which is equal
772 to at least one token in the expression, `RDBQCFTSPH' for
773 full-text search with the phrase of the expression,
774 `RDBQCFTSAND' for full-text search with all tokens in the
775 expression, `RDBQCFTSOR' for full-text search with at
776 least one token in the expression, `RDBQCFTSEX' for
777 full-text search with the compound expression. All oper‐
778 ations can be flagged by bitwise-or: `RDBQCNEGATE' for
779 negation, `RDBQCNOIDX' for using no index.
780 `expr' specifies an operand exression.
781 The function `tcrdbqrysetorder' is used in order to set the order of a
783 query object.
784 void tcrdbqrysetorder(RDBQRY *qry, const char *name, int type);
786 `qry' specifies the query object.
787 `name' specifies the name of a column. An empty string
788 means the primary key.
789 `type' specifies the order type: `RDBQOSTRASC' for string
790 ascending, `RDBQOSTRDESC' for string descending, `RDBQON‐
791 UMASC' for number ascending, `RDBQONUMDESC' for number
792 descending.
793 The function `tcrdbqrysetlimit' is used in order to set the limit num‐
795 ber of records of the result of a query object.
796 void tcrdbqrysetlimit(RDBQRY *qry, int max, int skip);
798 `qry' specifies the query object.
799 `max' specifies the maximum number of records of the
800 result. If it is negative, no limit is specified.
801 `skip' specifies the number of skipped records of the
802 result. If it is not more than 0, no record is skipped.
803 The function `tcrdbqrysearch' is used in order to execute the search of
805 a query object.
806 TCLIST *tcrdbqrysearch(RDBQRY *qry);
808 `qry' specifies the query object.
809 The return value is a list object of the primary keys of
810 the corresponding records. This function does never
811 fail. It returns an empty list even if no record corre‐
812 sponds.
813 Because the object of the return value is created with
814 the function `tclistnew', it should be deleted with the
815 function `tclistdel' when it is no longer in use.
816 The function `tcrdbqrysearchout' is used in order to remove each record
818 corresponding to a query object.
819 bool tcrdbqrysearchout(RDBQRY *qry);
821 `qry' specifies the query object of the database.
822 If successful, the return value is true, else, it is
823 false.
824 The function `tcrdbqrysearchget' is used in order to get records corre‐
826 sponding to the search of a query object.
827 TCLIST *tcrdbqrysearchget(RDBQRY *qry);
829 `qry' specifies the query object.
830 The return value is a list object of zero separated col‐
831 umns of the corresponding records.
832 This function does never fail. It returns an empty list
833 even if no record corresponds. Each element of the list
834 can be treated with the function `tcrdbqryrescols'.
835 Because the object of the return value is created with
836 the function `tclistnew', it should be deleted with the
837 function `tclistdel' when it is no longer in use.
838 The function `tcrdbqryrescols' is used in order to get columns of a
840 record in a search result.
841 TCMAP *tcrdbqryrescols(TCLIST *res, int index);
843 `res' specifies a list of zero separated columns of the
844 search result.
845 `index' the index of a element of the search result.
846 The return value is a map object containing columns.
847 Because the object of the return value is created with
848 the function `tcmapnew', it should be deleted with the
849 function `tcmapdel' when it is no longer in use.
850 The function `tcrdbqrysearchcount' is used in order to get the count of
852 corresponding records of a query object.
853 int tcrdbqrysearchcount(RDBQRY *qry);
855 `qry' specifies the query object.
856 The return value is the count of corresponding records or
857 0 on failure.
858 The function `tcrdbqryhint' is used in order to get the hint string of
860 a query object.
861 const char *tcrdbqryhint(RDBQRY *qry);
863 `qry' specifies the query object.
864 The return value is the hint string.
865 This function should be called after the query execution
866 by `tcrdbqrysearch' and so on. The region of the return
867 value is overwritten when this function is called again.
868 The function `tcrdbmetasearch' is used in order to retrieve records
870 with multiple query objects and get the set of the result.
871 TCLIST *tcrdbmetasearch(RDBQRY **qrys, int num, int type);
873 `qrys' specifies an array of the query objects.
874 `num' specifies the number of elements of the array.
875 `type' specifies a set operation type: `RDBMSUNION' for
876 the union set, `RDBMSISECT' for the intersection set,
877 `RDBMSDIFF' for the difference set.
878 The return value is a list object of the primary keys of
879 the corresponding records. This function does never
880 fail. It returns an empty list even if no record corre‐
881 sponds.
882 If the first query object has the order setting, the
883 result array is sorted by the order. Because the object
884 of the return value is created with the function `tclist‐
885 new', it should be deleted with the function `tclistdel'
886 when it is no longer in use.
887 The function `tcrdbparasearch' is used in order to search records for
889 multiple servers in parallel.
890 TCLIST *tcrdbparasearch(RDBQRY **qrys, int num);
892 `qrys' specifies an array of the query objects.
893 `num' specifies the number of elements of the array.
894 The return value is a list object of zero separated col‐
895 umns of the corresponding records.
896 This function does never fail. It returns an empty list
897 even if no record corresponds. Each element of the list
898 can be treated with the function `tcrdbqryrescols'.
899 Because the object of the return value is created with
900 the function `tclistnew', it should be deleted with the
901 function `tclistdel' when it is no longer in use.
902
905 ttserver(1), tcrtest(1), tcrmttest(1), tcrmgr(1), ttutil(3)
906Man Page 2010-01-20 TCRDB(3)