Provided by: libtokyotyrant-dev_1.1.40-4.2build1_amd64 
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)