table of contents
TCRDB(3) | Tokyo Tyrant | TCRDB(3) |
NAME¶
tcrdb - the remote database APIDESCRIPTION¶
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.DESCRIPTION¶
The function `tcrdberrmsg' is used in order to get the message string corresponding to an error code.`ecode' specifies the error code.
The return value is the message string of the
error code.
The return value is the new remote database
object.
`rdb' specifies the remote database
object.
`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.
`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.
`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.
`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.
`rdb' specifies the remote database
object.
If successful, the return value is true, else,
it is false.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`rdb' specifies the remote database
object.
`kstr' specifies the string of the
key.
If successful, the return value is true, else,
it is false.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`rdb' specifies the remote database
object.
If successful, the return value is true, else,
it is false.
`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.
`rdb' specifies the remote database
object.
If successful, the return value is true, else,
it is false.
`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.
`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.
`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.
`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.
`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.
`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.
`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.
`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.`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.
`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.
`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.
`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.
`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.
`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.
`rdb' specifies the remote database
object.
The return value is the new unique ID number
or -1 on failure.
`rdb' specifies the remote database
object.
The return value is the new query
object.
`qry' specifies the query object.
`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.
`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.
`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.
`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.
`qry' specifies the query object of the
database.
If successful, the return value is true, else,
it is false.
`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.
`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.
`qry' specifies the query object.
The return value is the count of corresponding
records or 0 on failure.
`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.
`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.
`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)2010-01-20 | Man Page |