Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
TCRDB(3)			 Tokyo Tyrant			      TCRDB(3)

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  mem-
       ory  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 con-
       nect  the  remote  database  object to the server.  The function	`tcrd-
       bopen' is used to open a	database connection and	the  function  `tcrdb-
       close' 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 er-
       ror 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, `TTE-
		     KEEP'  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' spec-
		     ifies 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 lat-
		     ter field is omitted, the default port number  is	speci-
		     fied.
		     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  re-
       mote 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 cre-
		     ated.

       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 cre-
		     ated.

       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 cre-
		     ated.

       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 cre-
		     ated.

       The function `tcrdbputnr' is used in order to store a record into a re-
       mote 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 re-
       mote 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 re-
		     gion 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 re-
       mote 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  ex-
		     isting 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	itera-
       tor 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 re-
		     gion of the next key, else, it is `NULL'.	`NULL' is  re-
		     turned 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  as-
		     sured 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	corre-
		     sponds, 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 re-
		     gion 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 con-
       tents 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 mas-
       ter 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  lat-
		     ter  field	 is omitted, the default port number is	speci-
		     fied.
		     `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 ob-
		     ject does not connect to any database server.

       The function `tcrdbsize'	is used	in order to get	the size of the	 data-
       base 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  af-
		     ter 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 pri-
		     mary 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 pri-
		     mary 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 pri-
		     mary 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 cre-
		     ated.

       The function `tcrdbtblout' is used in order to remove a record of a re-
       mote 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  pri-
		     mary 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  pri-
		     mary 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 lexi-
		     cal string, `RDBITDECIMAL'	for decimal string,  `RDBITTO-
		     KEN'  for	token  inverted	index, `RDBITQGRAM' for	q-gram
		     inverted index.  If it is `RDBITOPT', the index is	 opti-
		     mized.   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 con-
       dition 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, `RDBQC-
		     STRRX' 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,  `RD-
		     BQCFTSAND'	 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 oper-
		     ations  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, `RDBQON-
		     UMASC' for	number ascending,  `RDBQONUMDESC'  for	number
		     descending.

       The  function `tcrdbqrysetlimit'	is used	in order to set	the limit num-
       ber 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  re-
		     sult.  If it is negative, no limit	is specified.
		     `skip' specifies the number of skipped records of the re-
		     sult.  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	corre-
		     sponds.
		     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	corre-
       sponding	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 col-
		     umns 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'.   Be-
		     cause  the	object of the return value is created with the
		     function `tclistnew', it should be	deleted	with the func-
		     tion `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	corre-
		     sponds.
		     If	the first query	object has the order setting, the  re-
		     sult array	is sorted by the order.	 Because the object of
		     the return	value is created with  the  function  `tclist-
		     new',  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 col-
		     umns 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'.   Be-
		     cause  the	object of the return value is created with the
		     function `tclistnew', it should be	deleted	with the func-
		     tion `tclistdel' when it is no longer in use.

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

Man Page			  2010-08-05			      TCRDB(3)

NAME | DESCRIPTION | DESCRIPTION | TABLE EXTENSION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=tcrdb&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help