Provided by: libtokyotyrant-dev_1.1.40-4.3_amd64 bug

NAME

       tcrdb - the remote database API

DESCRIPTION

       Remote  database  is  a  set  of  interfaces to use an abstract database of Tokyo Cabinet,
       mediated by a server of Tokyo Tyrant.

       To use the remote database API, include  `tcrdb.h'  and  related  standard  header  files.
       Usually, write the following description near the front of a source file.

              #include <tcrdb.h>
              #include <stdlib.h>
              #include <stdbool.h>
              #include <stdint.h>

       Objects  whose  type  is pointer to `TCRDB' are used to handle remote databases.  a remote
       database object is created with the function `tcrdbnew' and is deleted with  the  function
       `tcrdbdel'.   To  avoid  memory leak, it is important to delete every object when it is no
       longer in use.

       Before operations to store or retrieve records, it is  necessary  to  connect  the  remote
       database  object  to  the  server.   The  function  `tcrdbopen' is used to open a database
       connection and the function `tcrdbclose' is used to close the connection.

DESCRIPTION

       The function `tcrdberrmsg' is used in order to get the message string corresponding to  an
       error code.

              const char *tcrdberrmsg(int ecode);
                     `ecode' specifies the error code.
                     The return value is the message string of the error code.

       The function `tcrdbnew' is used in order to create a remote database object.

              TCRDB *tcrdbnew(void);
                     The return value is the new remote database object.

       The function `tcrdbdel' is used in order to delete a remote database object.

              void tcrdbdel(TCRDB *rdb);
                     `rdb' specifies the remote database object.

       The function `tcrdbecode' is used in order to get the last happened error code of a remote
       database object.

              int tcrdbecode(TCRDB *rdb);
                     `rdb' specifies the remote database object.
                     The return value is the last happened error code.
                     The following error code is defined: `TTESUCCESS' for success,  `TTEINVALID'
                     for  invalid  operation,  `TTENOHOST'  for  host not found, `TTEREFUSED' for
                     connection refused, `TTESEND' for send  error,  `TTERECV'  for  recv  error,
                     `TTEKEEP' for existing record, `TTENOREC' for no record found, `TTEMISC' for
                     miscellaneous error.

       The function `tcrdbtune' is used in order to set the tuning parameters of a hash  database
       object.

              bool tcrdbtune(TCRDB *rdb, double timeout, int opts);
                     `rdb' specifies the remote database object.
                     `timeout' specifies the timeout of each query in seconds.  If it is not more
                     than 0, the timeout is not specified.
                     `opts' specifies options  by  bitwise-or:  `RDBTRECON'  specifies  that  the
                     connection is recovered automatically when it is disconnected.
                     If successful, the return value is true, else, it is false.
                     Note that the tuning parameters should be set before the database is opened.

       The function `tcrdbopen' is used in order to open a remote database.

              bool tcrdbopen(TCRDB *rdb, const char *host, int port);
                     `rdb' specifies the remote database object.
                     `host' specifies the name or the address of the server.
                     `port'  specifies  the  port  number.  If it is not more than 0, UNIX domain
                     socket is used and the path of the socket file  is  specified  by  the  host
                     parameter.
                     If successful, the return value is true, else, it is false.

       The  function `tcrdbopen2' is used in order to open a remote database with a simple server
       expression.

              bool tcrdbopen2(TCRDB *rdb, const char *expr);
                     `rdb' specifies the remote database object.
                     `expr' specifies the simple  server  expression.   It  is  composed  of  two
                     substrings  separated  by  ":".   The former field specifies the name or the
                     address of the server.  The latter field specifies the port number.  If  the
                     latter field is omitted, the default port number is specified.
                     If successful, the return value is true, else, it is false.

       The function `tcrdbclose' is used in order to close a remote database object.

              bool tcrdbclose(TCRDB *rdb);
                     `rdb' specifies the remote database object.
                     If successful, the return value is true, else, it is false.

       The function `tcrdbput' is used in order to store a record into a remote database object.

              bool tcrdbput(TCRDB *rdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
                     `rdb' specifies the remote database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `vbuf' specifies the pointer to the region of the value.
                     `vsiz' specifies the size of the region of the value.
                     If successful, the return value is true, else, it is false.
                     If a record with the same key exists in the database, it is overwritten.

       The function `tcrdbput2' is used in order to store a string record into a remote object.

              bool tcrdbput2(TCRDB *rdb, const char *kstr, const char *vstr);
                     `rdb' specifies the remote database object.
                     `kstr' specifies the string of the key.
                     `vstr' specifies the string of the value.
                     If successful, the return value is true, else, it is false.
                     If a record with the same key exists in the database, it is overwritten.

       The  function `tcrdbputkeep' is used in order to store a new record into a remote database
       object.

              bool tcrdbputkeep(TCRDB *rdb, const void *kbuf, int ksiz,  const  void  *vbuf,  int
              vsiz);
                     `rdb' specifies the remote database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `vbuf' specifies the pointer to the region of the value.
                     `vsiz' specifies the size of the region of the value.
                     If successful, the return value is true, else, it is false.
                     If  a  record with the same key exists in the database, this function has no
                     effect.

       The function `tcrdbputkeep2' is used in order to store a new string record into  a  remote
       database object.

              bool tcrdbputkeep2(TCRDB *rdb, const char *kstr, const char *vstr);
                     `rdb' specifies the remote database object.
                     `kstr' specifies the string of the key.
                     `vstr' specifies the string of the value.
                     If successful, the return value is true, else, it is false.
                     If  a  record with the same key exists in the database, this function has no
                     effect.

       The function `tcrdbputcat' is used in order to concatenate a  value  at  the  end  of  the
       existing record in a remote database object.

              bool  tcrdbputcat(TCRDB  *rdb,  const  void  *kbuf, int ksiz, const void *vbuf, int
              vsiz);
                     `rdb' specifies the remote database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `vbuf' specifies the pointer to the region of the value.
                     `vsiz' specifies the size of the region of the value.
                     If successful, the return value is true, else, it is false.
                     If there is no corresponding record, a new record is created.

       The function `tcrdbputcat2' is used in order to concatenate a string value at the  end  of
       the existing record in a remote database object.

              bool tcrdbputcat2(TCRDB *rdb, const char *kstr, const char *vstr);
                     `rdb' specifies the remote database object.
                     `kstr' specifies the string of the key.
                     `vstr' specifies the string of the value.
                     If successful, the return value is true, else, it is false.
                     If there is no corresponding record, a new record is created.

       The  function  `tcrdbputshl'  is  used  in  order to concatenate a value at the end of the
       existing record and shift it to the left.

              bool tcrdbputshl(TCRDB *rdb, const void *kbuf, int  ksiz,  const  void  *vbuf,  int
              vsiz, int width);
                     `rdb' specifies the remote database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `vbuf' specifies the pointer to the region of the value.
                     `vsiz' specifies the size of the region of the value.
                     `width' specifies the width of the record.
                     If successful, the return value is true, else, it is false.
                     If there is no corresponding record, a new record is created.

       The  function  `tcrdbputshl2' is used in order to concatenate a string value at the end of
       the existing record and shift it to the left.

              bool tcrdbputshl2(TCRDB *rdb, const char *kstr, const char *vstr, int width);
                     `rdb' specifies the remote database object.
                     `kstr' specifies the string of the key.
                     `vstr' specifies the string of the value.
                     `width' specifies the width of the record.
                     If successful, the return value is true, else, it is false.
                     If there is no corresponding record, a new record is created.

       The function `tcrdbputnr' is used in order to store a record into a remote database object
       without response from the server.

              bool  tcrdbputnr(TCRDB  *rdb,  const  void  *kbuf,  int ksiz, const void *vbuf, int
              vsiz);
                     `rdb' specifies the remote database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `vbuf' specifies the pointer to the region of the value.
                     `vsiz' specifies the size of the region of the value.
                     If successful, the return value is true, else, it is false.
                     If a record with the same key exists in the database, it is overwritten.

       The function `tcrdbputnr2' is used in order to store a string record into a remote  object
       without response from the server.

              bool tcrdbputnr2(TCRDB *rdb, const char *kstr, const char *vstr);
                     `rdb' specifies the remote database object.
                     `kstr' specifies the string of the key.
                     `vstr' specifies the string of the value.
                     If successful, the return value is true, else, it is false.
                     If a record with the same key exists in the database, it is overwritten.

       The function `tcrdbout' is used in order to remove a record of a remote database object.

              bool tcrdbout(TCRDB *rdb, const void *kbuf, int ksiz);
                     `rdb' specifies the remote database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     If successful, the return value is true, else, it is false.

       The  function  `tcrdbout2' is used in order to remove a string record of a remote database
       object.

              bool tcrdbout2(TCRDB *rdb, const char *kstr);
                     `rdb' specifies the remote database object.
                     `kstr' specifies the string of the key.
                     If successful, the return value is true, else, it is false.

       The function `tcrdbget' is used in order to retrieve a record in a remote database object.

              void *tcrdbget(TCRDB *rdb, const void *kbuf, int ksiz, int *sp);
                     `rdb' specifies the remote database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     If successful, the return value is the pointer to the region of the value of
                     the corresponding record.  `NULL' is returned if no record corresponds.
                     Because an additional zero code is appended at the end of the region of  the
                     return  value,  the  return  value  can  be  treated  as a character string.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcrdbget2' is used in order to retrieve a string record in a remote database
       object.

              char *tcrdbget2(TCRDB *rdb, const char *kstr);
                     `rdb' specifies the remote database object.
                     `kstr' specifies the string of the key.
                     If successful,  the  return  value  is  the  string  of  the  value  of  the
                     corresponding record.  `NULL' is returned if no record corresponds.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcrdbget3' is used in order to retrieve records in a remote database object.

              bool tcrdbget3(TCRDB *rdb, TCMAP *recs);
                     `rdb' specifies the remote database object.
                     `recs' specifies a map object containing the retrieval keys.  As a result of
                     this  function,  keys existing in the database have the corresponding values
                     and keys not existing in the database are removed.
                     If successful, the return value is true, else, it is false.

       The function `tcrdbvsiz' is used in order to get the size of the value of a  record  in  a
       remote database object.

              int tcrdbvsiz(TCRDB *rdb, const void *kbuf, int ksiz);
                     `rdb' specifies the remote database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     If   successful,  the  return  value  is  the  size  of  the  value  of  the
                     corresponding record, else, it is -1.

       The function `tcrdbvsiz2' is used in order to get the size of the value of a string record
       in a remote database object.

              int tcrdbvsiz2(TCRDB *rdb, const char *kstr);
                     `rdb' specifies the remote database object.
                     `kstr' specifies the string of the key.
                     If   successful,  the  return  value  is  the  size  of  the  value  of  the
                     corresponding record, else, it is -1.

       The function `tcrdbiterinit' is used in order to  initialize  the  iterator  of  a  remote
       database object.

              bool tcrdbiterinit(TCRDB *rdb);
                     `rdb' specifies the remote database object.
                     If successful, the return value is true, else, it is false.
                     The  iterator is used in order to access the key of every record stored in a
                     database.

       The function `tcrdbiternext' is used in order to get the next key of  the  iterator  of  a
       remote database object.

              void *tcrdbiternext(TCRDB *rdb, int *sp);
                     `rdb' specifies the remote database object.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     If successful, the return value is the pointer to the  region  of  the  next
                     key, else, it is `NULL'.  `NULL' is returned when no record is to be get out
                     of the iterator.
                     Because an additional zero code is appended at the end of the region of  the
                     return  value,  the  return  value  can  be  treated  as a character string.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it should be released with the `free' call when it is no longer in use.  The
                     iterator can be updated by multiple connections and then it is  not  assured
                     that every record is traversed.

       The  function `tcrdbiternext2' is used in order to get the next key string of the iterator
       of a remote database object.

              char *tcrdbiternext2(TCRDB *rdb);
                     `rdb' specifies the remote database object.
                     If successful, the return value is the string of the next key, else,  it  is
                     `NULL'.  `NULL' is returned when no record is to be get out of the iterator.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.  The
                     iterator  can  be updated by multiple connections and then it is not assured
                     that every record is traversed.

       The function `tcrdbfwmkeys' is used in order to get forward  matching  keys  in  a  remote
       database object.

              TCLIST *tcrdbfwmkeys(TCRDB *rdb, const void *pbuf, int psiz, int max);
                     `rdb' specifies the remote database object.
                     `pbuf' specifies the pointer to the region of the prefix.
                     `psiz' specifies the size of the region of the prefix.
                     `max'  specifies  the  maximum  number  of  keys  to  be  fetched.  If it is
                     negative, no limit is specified.
                     The return value is a list object of the corresponding keys.  This  function
                     does never fail.  It returns an empty list even if no key corresponds.
                     Because  the  object  of  the  return  value  is  created  with the function
                     `tclistnew', it should be deleted with the function `tclistdel' when  it  is
                     no longer in use.

       The  function  `tcrdbfwmkeys2'  is  used in order to get forward matching string keys in a
       remote database object.

              TCLIST *tcrdbfwmkeys2(TCRDB *rdb, const char *pstr, int max);
                     `rdb' specifies the remote database object.
                     `pstr' specifies the string of the prefix.
                     `max' specifies the maximum  number  of  keys  to  be  fetched.   If  it  is
                     negative, no limit is specified.
                     The  return value is a list object of the corresponding keys.  This function
                     does never fail.  It returns an empty list even if no key corresponds.
                     Because the object  of  the  return  value  is  created  with  the  function
                     `tclistnew',  it  should be deleted with the function `tclistdel' when it is
                     no longer in use.

       The function `tcrdbaddint' is used in order to add an integer to  a  record  in  a  remote
       database object.

              int tcrdbaddint(TCRDB *rdb, const void *kbuf, int ksiz, int num);
                     `rdb' specifies the remote database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `num' specifies the additional value.
                     If  successful,  the  return  value  is  the  summation  value,  else, it is
                     `INT_MIN'.
                     If the corresponding record exists, the value is treated as an  integer  and
                     is added to.  If no record corresponds, a new record of the additional value
                     is stored.

       The function `tcrdbadddouble' is used in order to add a real  number  to  a  record  in  a
       remote database object.

              double tcrdbadddouble(TCRDB *rdb, const void *kbuf, int ksiz, double num);
                     `rdb' specifies the remote database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `num' specifies the additional value.
                     If  successful,  the  return  value  is  the  summation  value,  else, it is
                     Not-a-Number.
                     If the corresponding record exists, the value is treated as  a  real  number
                     and  is  added to.  If no record corresponds, a new record of the additional
                     value is stored.

       The function `tcrdbext' is used in order  to  call  a  function  of  the  script  language
       extension.

              void  *tcrdbext(TCRDB *rdb, const char *name, int opts, const void *kbuf, int ksiz,
              const void *vbuf, int vsiz, int *sp);
                     `rdb' specifies the remote database object.
                     `name' specifies the function name.
                     `opts' specifies options by bitwise-or: `RDBXOLCKREC'  for  record  locking,
                     `RDBXOLCKGLB' for global locking.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `vbuf' specifies the pointer to the region of the value.
                     `vsiz' specifies the size of the region of the value.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     If successful, the return value is the pointer to the region of the value of
                     the response.  `NULL' is returned on failure.
                     Because  an additional zero code is appended at the end of the region of the
                     return value, the return  value  can  be  treated  as  a  character  string.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcrdbext2' is used in order to  call  a  function  of  the  script  language
       extension with string parameters.

              char  *tcrdbext2(TCRDB  *rdb,  const  char *name, int opts, const char *kstr, const
              char *vstr);
                     `rdb' specifies the remote database object.
                     `name' specifies the function name.
                     `opts' specifies options by bitwise-or: `RDBXOLCKREC'  for  record  locking,
                     `RDBXOLCKGLB' for global locking.
                     `kstr' specifies the string of the key.
                     `vstr' specifies the string of the value.
                     If  successful, the return value is the string of the value of the response.
                     `NULL' is returned on failure.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it should be released with the `free' call when it is no longer in use.

       The  function  `tcrdbsync'  is  used  in order to synchronize updated contents of a remote
       database object with the file and the device.

              bool tcrdbsync(TCRDB *rdb);
                     `rdb' specifies the remote database object.
                     If successful, the return value is true, else, it is false.

       The function `tcrdboptimize' is used in order to optimize the storage of a remove database
       object.

              bool tcrdboptimize(TCRDB *rdb, const char *params);
                     `rdb' specifies the remote database object.
                     `params' specifies the string of the tuning parameters.  If it is `NULL', it
                     is not used.
                     If successful, the return value is true, else, it is false.

       The function `tcrdbvanish' is used in order to remove all records  of  a  remote  database
       object.

              bool tcrdbvanish(TCRDB *rdb);
                     `rdb' specifies the remote database object.
                     If successful, the return value is true, else, it is false.

       The  function  `tcrdbcopy' is used in order to copy the database file of a remote database
       object.

              bool tcrdbcopy(TCRDB *rdb, const char *path);
                     `rdb' specifies the remote database object.
                     `path' specifies the path of the destination file.  If it begins  with  `@',
                     the trailing substring is executed as a command line.
                     If  successful,  the  return  value  is  true,  else, it is false.  False is
                     returned if the executed command returns non-zero code.
                     The database file is assured to be kept synchronized and not modified  while
                     the  copying  or  executing  operation is in progress.  So, this function is
                     useful to create a backup file of the database file.

       The function `tcrdbrestore' is used in order to restore the  database  file  of  a  remote
       database object from the update log.

              bool tcrdbrestore(TCRDB *rdb, const char *path, uint64_t ts, int opts);
                     `rdb' specifies the remote database object.
                     `path' specifies the path of the update log directory.
                     `opts'  specifies  options  by  bitwise-or:  `RDBROCHKCON'  for  consistency
                     checking.
                     `ts' specifies the beginning time stamp in microseconds.
                     If successful, the return value is true, else, it is false.

       The function `tcrdbsetmst' is used in order to set the  replication  master  of  a  remote
       database object.

              bool tcrdbsetmst(TCRDB *rdb, const char *host, int port, uint64_t ts, int opts);
                     `rdb' specifies the remote database object.
                     `host'  specifies  the  name or the address of the server.  If it is `NULL',
                     replication of the database is disabled.
                     `port' specifies the port number.
                     `ts' specifies the beginning timestamp in microseconds.
                     `opts'  specifies  options  by  bitwise-or:  `RDBROCHKCON'  for  consistency
                     checking.
                     If successful, the return value is true, else, it is false.

       The  function  `tcrdbsetmst2'  is  used in order to set the replication master of a remote
       database object with a simple server expression.

              bool tcrdbsetmst2(TCRDB *rdb, const char *expr, uint64_t ts, int opts);
                     `rdb' specifies the remote database object.
                     `expr' specifies the simple  server  expression.   It  is  composed  of  two
                     substrings  separated  by  ":".   The former field specifies the name or the
                     address of the server.  The latter field specifies the port number.  If  the
                     latter field is omitted, the default port number is specified.
                     `ts' specifies the beginning timestamp in microseconds.
                     `opts'  specifies  options  by  bitwise-or:  `RDBROCHKCON'  for  consistency
                     checking.
                     If successful, the return value is true, else, it is false.

       The function `tcrdbrnum' is used in order to  get  the  number  of  records  of  a  remote
       database object.

              uint64_t tcrdbrnum(TCRDB *rdb);
                     `rdb' specifies the remote database object.
                     The  return  value  is  the  number  of  records or 0 if the object does not
                     connect to any database server.

       The function `tcrdbsize' is used in order to get the size of  the  database  of  a  remote
       database object.

              uint64_t tcrdbsize(TCRDB *rdb);
                     `rdb' specifies the remote database object.
                     The  return  value  is  the size of the database or 0 if the object does not
                     connect to any database server.

       The function `tcrdbstat' is used in order to get the status string of the  database  of  a
       remote database object.

              char *tcrdbstat(TCRDB *rdb);
                     `rdb' specifies the remote database object.
                     The  return  value  is  the  status message of the database or `NULL' if the
                     object does not connect to any database server.  The message format is  TSV.
                     The  first  field of each line means the parameter name and the second field
                     means the value.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it should be released with the `free' call when it is no longer in use.

       The  function  `tcrdbmisc' is used in order to call a versatile function for miscellaneous
       operations of a remote database object.

              TCLIST *tcrdbmisc(TCRDB *rdb, const char *name, int opts, const TCLIST *args);
                     `rdb' specifies the remote database object.
                     `name' specifies the name of the function.   All  databases  support  "put",
                     "out",  "get",  "putlist",  "outlist",  and  "getlist".  "put" is to store a
                     record.  It receives a key and a value, and returns an empty list.  "out" is
                     to remove a record.  It receives a key, and returns an empty list.  "get" is
                     to retrieve a record.  It receives a key, and returns a list of the  values.
                     "putlist"  is  to  store records.  It receives keys and values one after the
                     other, and returns an empty list.   "outlist"  is  to  remove  records.   It
                     receives keys, and returns an empty list.  "getlist" is to retrieve records.
                     It receives keys, and returns keys and values of corresponding  records  one
                     after the other.
                     `opts'  specifies  options  by bitwise-or: `RDBMONOULOG' for omission of the
                     update log.
                     `args' specifies a list object containing arguments.
                     If successful, the return value is a list object of the result.   `NULL'  is
                     returned on failure.
                     Because  the  object  of  the  return  value  is  created  with the function
                     `tclistnew', it should be deleted with the function `tclistdel' when  it  is
                     no longer in use.

TABLE EXTENSION

       The  function  `tcrdbtblput'  is  used  in  order to store a record into a remote database
       object.

              bool tcrdbtblput(TCRDB *rdb, const void *pkbuf, int pksiz, TCMAP *cols);
                     `rdb' specifies the remote database object.
                     `pkbuf' specifies the pointer to the region of the primary key.
                     `pksiz' specifies the size of the region of the primary key.
                     `cols' specifies a map object containing columns.
                     If successful, the return value is true, else, it is false.
                     If a record with the same key exists in the database, it is overwritten.

       The function `tcrdbtblputkeep' is used in order to  store  a  new  record  into  a  remote
       database object.

              bool tcrdbtblputkeep(TCRDB *rdb, const void *pkbuf, int pksiz, TCMAP *cols);
                     `rdb' specifies the remote database object.
                     `pkbuf' specifies the pointer to the region of the primary key.
                     `pksiz' specifies the size of the region of the primary key.
                     `cols' specifies a map object containing columns.
                     If successful, the return value is true, else, it is false.
                     If  a  record with the same key exists in the database, this function has no
                     effect.

       The function `tcrdbtblputcat' is used in order to  concatenate  columns  of  the  existing
       record in a remote database object.

              bool tcrdbtblputcat(TCRDB *rdb, const void *pkbuf, int pksiz, TCMAP *cols);
                     `rdb' specifies the remote database object.
                     `pkbuf' specifies the pointer to the region of the primary key.
                     `pksiz' specifies the size of the region of the primary key.
                     `cols' specifies a map object containing columns.
                     If successful, the return value is true, else, it is false.
                     If there is no corresponding record, a new record is created.

       The  function  `tcrdbtblout'  is  used  in  order  to remove a record of a remote database
       object.

              bool tcrdbtblout(TCRDB *rdb, const void *pkbuf, int pksiz);
                     `rdb' specifies the remote database object.
                     `pkbuf' specifies the pointer to the region of the primary key.
                     `pksiz' specifies the size of the region of the primary key.
                     If successful, the return value is true, else, it is false.

       The function `tcrdbtblget' is used in order to retrieve a  record  in  a  remote  database
       object.

              TCMAP *tcrdbtblget(TCRDB *rdb, const void *pkbuf, int pksiz);
                     `rdb' specifies the remote database object.
                     `pkbuf' specifies the pointer to the region of the primary key.
                     `pksiz' specifies the size of the region of the primary key.
                     If  successful,  the  return  value  is  a  map object of the columns of the
                     corresponding record.  `NULL' is returned if no record corresponds.
                     Because the object  of  the  return  value  is  created  with  the  function
                     `tcmapnew',  it should be deleted with the function `tcmapdel' when it is no
                     longer in use.

       The function `tcrdbtblsetindex' is used in order  to  set  a  column  index  to  a  remote
       database object.

              bool tcrdbtblsetindex(TCRDB *rdb, const char *name, int type);
                     `rdb' specifies the remote database object.
                     `name'  specifies the name of a column.  If the name of an existing index is
                     specified, the index is rebuilt.  An empty string means the primary key.
                     `type'  specifies  the  index  type:  `RDBITLEXICAL'  for  lexical   string,
                     `RDBITDECIMAL'  for  decimal  string, `RDBITTOKEN' for token inverted index,
                     `RDBITQGRAM' for q-gram inverted index.  If it is `RDBITOPT', the  index  is
                     optimized.   If  it is `RDBITVOID', the index is removed.  If `RDBITKEEP' is
                     added by bitwise-or and the  index  exists,  this  function  merely  returns
                     failure.
                     If successful, the return value is true, else, it is false.

       The  function `tcrdbtblgenuid' is used in order to generate a unique ID number of a remote
       database object.

              int64_t tcrdbtblgenuid(TCRDB *rdb);
                     `rdb' specifies the remote database object.
                     The return value is the new unique ID number or -1 on failure.

       The function `tcrdbqrynew' is used in order to create a query object.

              RDBQRY *tcrdbqrynew(TCRDB *rdb);
                     `rdb' specifies the remote database object.
                     The return value is the new query object.

       The function `tcrdbqrydel' is used in order to delete a query object.

              void tcrdbqrydel(RDBQRY *qry);
                     `qry' specifies the query object.

       The function `tcrdbqryaddcond' is used in order to add a narrowing condition  to  a  query
       object.

              void tcrdbqryaddcond(RDBQRY *qry, const char *name, int op, const char *expr);
                     `qry' specifies the query object.
                     `name'  specifies  the  name of a column.  An empty string means the primary
                     key.
                     `op' specifies an operation type: `RDBQCSTREQ' for string which is equal  to
                     the   expression,   `RDBQCSTRINC'  for  string  which  is  included  in  the
                     expression, `RDBQCSTRBW'  for  string  which  begins  with  the  expression,
                     `RDBQCSTREW'  for  string  which ends with the expression, `RDBQCSTRAND' for
                     string which includes all tokens in the expression, `RDBQCSTROR' for  string
                     which  includes  at  least  one  token in the expression, `RDBQCSTROREQ' for
                     string which is equal to at least one token in the expression,  `RDBQCSTRRX'
                     for string which matches regular expressions of the expression, `RDBQCNUMEQ'
                     for number which is equal to the expression, `RDBQCNUMGT' for  number  which
                     is  greater  than  the  expression, `RDBQCNUMGE' for number which is greater
                     than or equal to the expression, `RDBQCNUMLT' for number which is less  than
                     the  expression,  `RDBQCNUMLE' for number which is less than or equal to the
                     expression, `RDBQCNUMBT' for number which  is  between  two  tokens  of  the
                     expression,  `RDBQCNUMOREQ'  for number which is equal to at least one token
                     in the expression, `RDBQCFTSPH' for full-text search with the phrase of  the
                     expression,  `RDBQCFTSAND'  for  full-text  search  with  all  tokens in the
                     expression, `RDBQCFTSOR' for full-text search with at least one token in the
                     expression,  `RDBQCFTSEX' for full-text search with the compound expression.
                     All operations can be flagged by  bitwise-or:  `RDBQCNEGATE'  for  negation,
                     `RDBQCNOIDX' for using no index.
                     `expr' specifies an operand exression.

       The function `tcrdbqrysetorder' is used in order to set the order of a query object.

              void tcrdbqrysetorder(RDBQRY *qry, const char *name, int type);
                     `qry' specifies the query object.
                     `name'  specifies  the  name of a column.  An empty string means the primary
                     key.
                     `type'  specifies  the  order  type:  `RDBQOSTRASC'  for  string  ascending,
                     `RDBQOSTRDESC'  for  string  descending, `RDBQONUMASC' for number ascending,
                     `RDBQONUMDESC' for number descending.

       The function `tcrdbqrysetlimit' is used in order to set the limit number of records of the
       result of a query object.

              void tcrdbqrysetlimit(RDBQRY *qry, int max, int skip);
                     `qry' specifies the query object.
                     `max'  specifies  the  maximum  number  of  records of the result.  If it is
                     negative, no limit is specified.
                     `skip' specifies the number of skipped records of the result.  If it is  not
                     more than 0, no record is skipped.

       The function `tcrdbqrysearch' is used in order to execute the search of a query object.

              TCLIST *tcrdbqrysearch(RDBQRY *qry);
                     `qry' specifies the query object.
                     The  return  value is a list object of the primary keys of the corresponding
                     records.  This function does never fail.  It returns an empty list  even  if
                     no record corresponds.
                     Because  the  object  of  the  return  value  is  created  with the function
                     `tclistnew', it should be deleted with the function `tclistdel' when  it  is
                     no longer in use.

       The function `tcrdbqrysearchout' is used in order to remove each record corresponding to a
       query object.

              bool tcrdbqrysearchout(RDBQRY *qry);
                     `qry' specifies the query object of the database.
                     If successful, the return value is true, else, it is false.

       The function `tcrdbqrysearchget' is used in order to  get  records  corresponding  to  the
       search of a query object.

              TCLIST *tcrdbqrysearchget(RDBQRY *qry);
                     `qry' specifies the query object.
                     The  return  value  is  a  list  object  of  zero  separated  columns of the
                     corresponding records.
                     This function does never fail.  It returns an empty list even if  no  record
                     corresponds.   Each  element  of  the  list can be treated with the function
                     `tcrdbqryrescols'.  Because the object of the return value is  created  with
                     the function `tclistnew', it should be deleted with the function `tclistdel'
                     when it is no longer in use.

       The function `tcrdbqryrescols' is used in order to get columns of a  record  in  a  search
       result.

              TCMAP *tcrdbqryrescols(TCLIST *res, int index);
                     `res' specifies a list of zero separated columns of the search result.
                     `index' the index of a element of the search result.
                     The return value is a map object containing columns.
                     Because  the  object  of  the  return  value  is  created  with the function
                     `tcmapnew', it should be deleted with the function `tcmapdel' when it is  no
                     longer in use.

       The  function  `tcrdbqrysearchcount'  is  used  in order to get the count of corresponding
       records of a query object.

              int tcrdbqrysearchcount(RDBQRY *qry);
                     `qry' specifies the query object.
                     The return value is the count of corresponding records or 0 on failure.

       The function `tcrdbqryhint' is used in order to get the hint string of a query object.

              const char *tcrdbqryhint(RDBQRY *qry);
                     `qry' specifies the query object.
                     The return value is the hint string.
                     This function should be called after the query execution by `tcrdbqrysearch'
                     and so on.  The region of the return value is overwritten when this function
                     is called again.

       The function `tcrdbmetasearch' is used in order to retrieve records  with  multiple  query
       objects and get the set of the result.

              TCLIST *tcrdbmetasearch(RDBQRY **qrys, int num, int type);
                     `qrys' specifies an array of the query objects.
                     `num' specifies the number of elements of the array.
                     `type'  specifies  a  set  operation  type:  `RDBMSUNION' for the union set,
                     `RDBMSISECT' for the intersection set, `RDBMSDIFF' for the difference set.
                     The return value is a list object of the primary keys of  the  corresponding
                     records.   This  function does never fail.  It returns an empty list even if
                     no record corresponds.
                     If the first query object has the order setting, the result array is  sorted
                     by  the  order.   Because the object of the return value is created with the
                     function `tclistnew', it should be deleted  with  the  function  `tclistdel'
                     when it is no longer in use.

       The  function `tcrdbparasearch' is used in order to search records for multiple servers in
       parallel.

              TCLIST *tcrdbparasearch(RDBQRY **qrys, int num);
                     `qrys' specifies an array of the query objects.
                     `num' specifies the number of elements of the array.
                     The return value  is  a  list  object  of  zero  separated  columns  of  the
                     corresponding records.
                     This  function  does never fail.  It returns an empty list even if no record
                     corresponds.  Each element of the list can  be  treated  with  the  function
                     `tcrdbqryrescols'.   Because  the object of the return value is created with
                     the function `tclistnew', it should be deleted with the function `tclistdel'
                     when it is no longer in use.

SEE ALSO

       ttserver(1), tcrtest(1), tcrmttest(1), tcrmgr(1), ttutil(3)