Class TokyoTyrant::RDB
In: tokyotyrant.rb
Parent: Object

Remote database is a set of interfaces to use an abstract database of Tokyo Cabinet, mediated by a server of Tokyo Tyrant. Before operations to store or retrieve records, it is necessary to connect the remote database object to the server. The method `open' is used to open a database connection and the method `close' is used to close the connection.

Methods

[]   []=   adddouble   addint   clear   close   copy   delete   each   each_keys   each_pair   each_values   ecode   empty?   errmsg   ext   fetch   fwmkeys   get   has_key?   has_value?   iterinit   iternext   keys   length   mget   misc   new   open   optimize   out   put   putcat   putkeep   putnr   putshl   rnum   size   stat   store   sync   values   vanish   vsiz  

Constants

ESUCCESS = 0   error code: success
EINVALID = 1   error code: invalid operation
ENOHOST = 2   error code: host not found
EREFUSED = 3   error code: connection refused
ESEND = 4   error code: send error
ERECV = 5   error code: recv error
EKEEP = 6   error code: existing record
ENOREC = 7   error code: no record found
EMISC = 9999   error code: miscellaneous error
XOLCKREC = 1 << 0   scripting extension option: record locking
XOLCKGLB = 1 << 1   scripting extension option: global locking
MONOULOG = 1 << 0   versatile function option: omission of the update log

Public Class methods

new()

Create a remote database object.
The return value is the new remote database object.

Public Instance methods

[](key)

Hash-compatible method.
Alias of `get'.

[]=(key, value)

Hash-compatible method.
Alias of `put'.

adddouble(key, num)

Add a real number to a record.
`key' specifies the key.
`num' specifies the additional value. If it is not defined, 0 is specified.
If successful, the return value is the summation value, else, it is `nil'.
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. Because records are stored in binary format, they should be processed with the `unpack' function with the `d' operator after retrieval.

addint(key, num = 0)

Add an integer to a record.
`key' specifies the key.
`num' specifies the additional value. If it is not defined, 0 is specified.
If successful, the return value is the summation value, else, it is `nil'.
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. Because records are stored in binary format, they should be processed with the `unpack' function with the `i' operator after retrieval.

clear()

Hash-compatible method.
Alias of `vanish'.

close()

Close the database connection.
If successful, the return value is true, else, it is false.

copy(path)

Copy the database file.
`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 method is useful to create a backup file of the database file.

delete(key)

Hash-compatible method.
Alias of `out'.

each() {|key, value| ...}

Hash-compatible method.
Iterator of pairs of the key and the value.

each_keys() {|key| ...}

Hash-compatible method.
Iterator of the keys.

each_pair()

Alias for each

each_values() {|value| ...}

Hash-compatible method.
Iterator of the values.

ecode()

Get the last happened error code.
The return value is the last happened error code.
The following error code is defined: `TokyoTyrant::RDB::ESUCCESS' for success, `TokyoTyrant::RDB::EINVALID' for invalid operation, `TokyoTyrant::RDB::ENOHOST' for host not found, `TokyoTyrant::RDB::EREFUSED' for connection refused, `TokyoTyrant::RDB::ESEND' for send error, `TokyoTyrant::RDB::ERECV' for recv error, `TokyoTyrant::RDB::EKEEP' for existing record, `TokyoTyrant::RDB::ENOREC' for no record found, `TokyoTyrant::RDB::EMISC' for miscellaneous error.

empty?()

Hash-compatible method.
Alias of `rnum < 1'.

errmsg(ecode = nil)

Get the message string corresponding to an error code.
`ecode' specifies the error code. If it is not defined or negative, the last happened error code is specified.
The return value is the message string of the error code.

ext(name, key = "", value = "", opts = 0)

Call a function of the script language extension.
`name' specifies the function name.
`key' specifies the key. If it is not defined, an empty string is specified.
`value' specifies the value. If it is not defined, an empty string is specified.
`opts' specifies options by bitwise-or: `TokyoTyrant::RDB::XOLCKREC' for record locking, `TokyoTyrant::RDB::XOLCKGLB' for global locking. If it is not defined, no option is specified.
If successful, the return value is the value of the response or `nil' on failure.

fetch(key)

Hash-compatible method.
Alias of `get'.

fwmkeys(prefix, max = -1)

Get forward matching keys.
`prefix' specifies the prefix of the corresponding keys.
`max' specifies the maximum number of keys to be fetched. If it is not defined or negative, no limit is specified.
The return value is an array of the keys of the corresponding records. This method does never fail. It returns an empty array even if no record corresponds.
Note that this method may be very slow because every key in the database is scanned.

get(key)

Retrieve a record.
`key' specifies the key.
If successful, the return value is the value of the corresponding record. `nil' is returned if no record corresponds.

has_key?(key)

Hash-compatible method.
Check existence of a key.

has_value?(value)

Hash-compatible method.
Check existence of a value.

iterinit()

Initialize the iterator.
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.

iternext()

Get the next key of the iterator.
If successful, the return value is the next key, else, it is `nil'. `nil' is returned when no record is to be get out of the iterator.
It is possible to access every record by iteration of calling this method. It is allowed to update or remove records whose keys are fetched while the iteration. However, it is not assured if updating the database is occurred while the iteration. Besides, the order of this traversal access method is arbitrary, so it is not assured that the order of storing matches the one of the traversal access.

keys()

Hash-compatible method.
Get an array of all keys.

length()

Hash-compatible method.
Alias of `rnum'.

mget(recs)

Retrieve records.
`recs' specifies a hash containing the retrieval keys. As a result of this method, keys existing in the database have the corresponding values and keys not existing in the database are removed.
If successful, the return value is the number of retrieved records or -1 on failure.

misc(name, args = [], opts = 0)

Call a versatile function for miscellaneous operations.
`name' specifies the name of the function. All databases support “putlist”, “outlist”, and “getlist”. “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 array. “getlist” is to retrieve records. It receives keys, and returns keys and values of corresponding records one after the other. Table database supports “setindex”, “search”, and “genuid”.
`args' specifies an array containing arguments. If it is not defined, no argument is specified.
`opts' specifies options by bitwise-or: `TokyoTyrant::RDB::MONOULOG' for omission of the update log. If it is not defined, no option is specified.
If successful, the return value is an array of the result. `nil' is returned on failure.

open(host, port = 0, timeout = 0)

Open a remote database connection.
`host' specifies the name or the address of the server.
`port' specifies the port number. If it is not defined or not more than 0, UNIX domain socket is used and the path of the socket file is specified by the host parameter.
`timeout' specifies the timeout of each query in seconds. If it is not defined or not more than 0, the timeout is not specified. If successful, the return value is true, else, it is false.

optimize(params = nil)

Optimize the storage.
`params' specifies the string of the tuning parameters. If it is not defined, it is not used.
If successful, the return value is true, else, it is false.

out(key)

Remove a record.
`key' specifies the key.
If successful, the return value is true, else, it is false.

put(key, value)

Store a record.
`key' specifies the key.
`value' specifies 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.

putcat(key, value)

Concatenate a value at the end of the existing record.
`key' specifies the key.
`value' specifies the value.
If successful, the return value is true, else, it is false.
If there is no corresponding record, a new record is created.

putkeep(key, value)

Store a new record.
`key' specifies the key.
`value' specifies 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 method has no effect.

putnr(key, value)

Store a record without response from the server.
`key' specifies the key.
`value' specifies 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.

putshl(key, value, width = 0)

Concatenate a value at the end of the existing record and shift it to the left.
`key' specifies the key.
`value' specifies 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.

rnum()

Get the number of records.
The return value is the number of records or 0 if the object does not connect to any database server.

size()

Get the size of the database.
The return value is the size of the database or 0 if the object does not connect to any database server.

stat()

Get the status string of the database server.
The return value is the status message of the database or `nil' 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.

store(key, value)

Hash-compatible method.
Alias of `put'.

sync()

Synchronize updated contents with the file and the device.
If successful, the return value is true, else, it is false.

values()

Hash-compatible method.
Get an array of all keys.

vanish()

Remove all records.
If successful, the return value is true, else, it is false.

vsiz(key)

Get the size of the value of a record.
`key' specifies the key.
If successful, the return value is the size of the value of the corresponding record, else, it is -1.