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.%%
error code: invalid operation
error code: existing record
error code: miscellaneous error
error code: host not found
error code: no record found
error code: recv error
error code: connection refused
error code: send error
error code: success
versatile function option: omission of the update log
scripting extension option: global locking
scripting extension option: record locking
Hash-compatible method.%% Alias of `get’.%%
# File tokyotyrant.rb, line 936 def [](key) return get(key) end
Hash-compatible method.%% Alias of `put’.%%
# File tokyotyrant.rb, line 931 def []=(key, value) return put(key, value) end
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.%%
# File tokyotyrant.rb, line 572 def adddouble(key, num) key = _argstr(key) num = _argnum(num) if !@sock @ecode = EINVALID return nil end integ = num.truncate fract = ((num - integ) * 1000000000000).truncate sbuf = [0xC8, 0x61, key.length].pack("CCN") sbuf += _packquad(integ) + _packquad(fract) + key if !_send(sbuf) @ecode = ESEND return nil end code = _recvcode if code == -1 @ecode = ERECV return nil end if code != 0 @ecode = EKEEP return nil end integ = _recvint64() fract = _recvint64() return integ + fract / 1000000000000.0 end
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.%%
# File tokyotyrant.rb, line 543 def addint(key, num = 0) key = _argstr(key) num = _argnum(num) if !@sock @ecode = EINVALID return nil end sbuf = [0xC8, 0x60, key.length, num].pack("CCNN") sbuf += key if !_send(sbuf) @ecode = ESEND return nil end code = _recvcode if code == -1 @ecode = ERECV return nil end if code != 0 @ecode = EKEEP return nil end return _recvint32 end
Hash-compatible method.%% Alias of `vanish’.%%
# File tokyotyrant.rb, line 916 def clear return vanish end
Close the database connection.%% If successful, the return value is true, else, it is false.%%
# File tokyotyrant.rb, line 142 def close() if !@sock @ecode = EINVALID return false end begin @sock.close rescue Exception @ecode = EMISC @sock = nil return false end @sock = nil return true end
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.%%
# File tokyotyrant.rb, line 718 def copy(path) path = _argstr(path) if !@sock @ecode = EINVALID return false end sbuf = [0xC8, 0x73, path.length].pack("CCN") sbuf += path if !_send(sbuf) @ecode = ESEND return false end code = _recvcode if code == -1 @ecode = ERECV return false end if code != 0 @ecode = EMISC return false end return true end
Hash-compatible method.%% Alias of `out’.%%
# File tokyotyrant.rb, line 890 def delete(key) return out(key) end
Hash-compatible method.%% Iterator of pairs of the key and the value.%%
# File tokyotyrant.rb, line 941 def each return nil if !iterinit while key = iternext value = get(key) break if !value yield(key, value) end return nil end
Hash-compatible method.%% Iterator of the keys.%%
# File tokyotyrant.rb, line 953 def each_keys return nil if !iterinit while key = iternext yield(key) end return nil end
Hash-compatible method.%% Iterator of the values.%%
# File tokyotyrant.rb, line 962 def each_values return nil if !iterinit while key = iternext value = get(key) break if !value yield(value) end return nil end
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.%%
# File tokyotyrant.rb, line 92 def ecode() return @ecode end
Hash-compatible method.%% Alias of `rnum < 1’.%%
# File tokyotyrant.rb, line 926 def empty? return rnum < 1 end
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.%%
# File tokyotyrant.rb, line 66 def errmsg(ecode = nil) ecode = @ecode if !ecode if ecode == ESUCCESS return "success" elsif ecode == EINVALID return "invalid operation" elsif ecode == ENOHOST return "host not found" elsif ecode == EREFUSED return "connection refused" elsif ecode == ESEND return "send error" elsif ecode == ERECV return "recv error" elsif ecode == EKEEP return "existing record" elsif ecode == ENOREC return "no record found" elsif ecode == EMISC return "miscellaneous error" end return "unknown" end
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.%%
# File tokyotyrant.rb, line 606 def ext(name, key = "", value = "", opts = 0) name = _argstr(name) key = _argstr(key) value = _argstr(value) opts = _argnum(opts) if !@sock @ecode = EINVALID return nil end sbuf = [0xC8, 0x68, name.length, opts, key.length, value.length].pack("CCNNNN") sbuf += name + key + value if !_send(sbuf) @ecode = ESEND return nil end code = _recvcode if code == -1 @ecode = ERECV return nil end if code != 0 @ecode = EMISC return nil end vsiz = _recvint32 if vsiz < 0 @ecode = ERECV return nil end vbuf = _recv(vsiz) if !vbuf @ecode = ERECV return nil end return _retstr(vbuf) end
Hash-compatible method.%% Alias of `get’.%%
# File tokyotyrant.rb, line 895 def fetch(key) return get(key) end
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.%%
# File tokyotyrant.rb, line 495 def fwmkeys(prefix, max = -1) prefix = _argstr(prefix) max = _argnum(max) if !@sock @ecode = EINVALID return Array::new end sbuf = [0xC8, 0x58, prefix.length, max].pack("CCNN") sbuf += prefix if !_send(sbuf) @ecode = ESEND return Array::new end code = _recvcode if code == -1 @ecode = ERECV return Array::new end if code != 0 @ecode = ENOREC return Array::new end knum = _recvint32 if knum < 0 @ecode = ERECV return Array::new end keys = Array::new for i in 1..knum ksiz = _recvint32() if ksiz < 0 @ecode = ERECV return Array::new end kbuf = _recv(ksiz) if !kbuf @ecode = ERECV return Array::new end keys.push(_retstr(kbuf)) end return keys end
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.%%
# File tokyotyrant.rb, line 324 def get(key) key = _argstr(key) sbuf = [0xC8, 0x30, key.length].pack("CCN") sbuf += key if !_send(sbuf) @ecode = ESEND return nil end code = _recvcode if code == -1 @ecode = ERECV return nil end if code != 0 @ecode = ENOREC return nil end vsiz = _recvint32 if vsiz < 0 @ecode = ERECV return nil end vbuf = _recv(vsiz) if !vbuf @ecode = ERECV return nil end return _retstr(vbuf) end
Hash-compatible method.%% Check existence of a key.%%
# File tokyotyrant.rb, line 900 def has_key?(key) return vsiz(key) >= 0 end
Hash-compatible method.%% Check existence of a value.%%
# File tokyotyrant.rb, line 905 def has_value?(value) return nil if !iterinit while tkey = iternext tvalue = get(tkey) break if !tvalue return true if value == tvalue end return false end
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.%%
# File tokyotyrant.rb, line 435 def iterinit() if !@sock @ecode = EINVALID return false end sbuf = [0xC8, 0x50].pack("CC") if !_send(sbuf) @ecode = ESEND return false end code = _recvcode if code == -1 @ecode = ERECV return false end if code != 0 @ecode = EMISC return false end return true end
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.%%
# File tokyotyrant.rb, line 459 def iternext() if !@sock @ecode = EINVALID return nil end sbuf = [0xC8, 0x51].pack("CC") if !_send(sbuf) @ecode = ESEND return nil end code = _recvcode if code == -1 @ecode = ERECV return nil end if code != 0 @ecode = ENOREC return nil end vsiz = _recvint32 if vsiz < 0 @ecode = ERECV return nil end vbuf = _recv(vsiz) if !vbuf @ecode = ERECV return nil end return _retstr(vbuf) end
Hash-compatible method.%% Get an array of all keys.%%
# File tokyotyrant.rb, line 973 def keys tkeys = Array::new return tkeys if !iterinit while key = iternext tkeys.push(key) end return tkeys end
Hash-compatible method.%% Alias of `rnum’.%%
# File tokyotyrant.rb, line 921 def length return rnum end
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.%%
# File tokyotyrant.rb, line 356 def mget(recs) raise ArgumentError if !recs.is_a?(Hash) if !@sock @ecode = EINVALID return -1 end rnum = 0 sbuf = "" recs.each_pair do |key, value| key = _argstr(key) sbuf += [key.length].pack("N") + key rnum += 1 end sbuf = [0xC8, 0x31, rnum].pack("CCN") + sbuf if !_send(sbuf) @ecode = ESEND return -1 end code = _recvcode rnum = _recvint32 if code == -1 @ecode = ERECV return -1 end if code != 0 @ecode = ENOREC return -1 end if rnum < 0 @ecode = ERECV return -1 end recs.clear for i in 1..rnum ksiz = _recvint32() vsiz = _recvint32() if ksiz < 0 || vsiz < 0 @ecode = ERECV return -1 end kbuf = _recv(ksiz) vbuf = _recv(vsiz) if !kbuf || !vbuf @ecode = ERECV return -1 end recs[kbuf] = _retstr(vbuf) end return rnum end
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.%%
# File tokyotyrant.rb, line 835 def misc(name, args = [], opts = 0) name = _argstr(name) args = Array::new if !args.is_a?(Array) opts = _argnum(opts) if !@sock @ecode = EINVALID return nil end sbuf = [0xC8, 0x90, name.length, opts, args.size].pack("CCNNN") sbuf += name args.each do |arg| arg = _argstr(arg) sbuf += [arg.length].pack("N") + arg end if !_send(sbuf) @ecode = ESEND return nil end code = _recvcode rnum = _recvint32 if code == -1 @ecode = ERECV return nil end if code != 0 @ecode = EMISC return nil end res = Array::new for i in 1..rnum esiz = _recvint32 if esiz < 0 @ecode = ERECV return nil end ebuf = _recv(esiz) if !ebuf @ecode = ERECV return nil end res.push(_retstr(ebuf)) end return res end
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.%%
# File tokyotyrant.rb, line 100 def open(host, port = 0, timeout = 0) host = _argstr(host) port = _argnum(port) timeout = _argnum(timeout) if @sock @ecode = EINVALID return false end if port > 0 begin info = TCPSocket::gethostbyname(host) rescue Exception @ecode = ENOHOST return false end begin sock = TCPSocket::open(info[3], port) rescue Exception @ecode = EREFUSED return false end begin sock.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, true) rescue Exception end else begin sock = UNIXSocket::open(host) rescue Exception @ecode = EREFUSED return false end end if sock.respond_to?(:set_encoding) sock.set_encoding("ASCII-8BIT") end @sock = sock @tout = timeout return true end
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.%%
# File tokyotyrant.rb, line 668 def optimize(params = nil) params = params ? _argstr(params) : "" if !@sock @ecode = EINVALID return false end sbuf = [0xC8, 0x71, params.length].pack("CCN") sbuf += params if !_send(sbuf) @ecode = ESEND return false end code = _recvcode if code == -1 @ecode = ERECV return false end if code != 0 @ecode = EMISC return false end return true end
Remove a record.%% `key’ specifies the key.%% If successful, the return value is true, else, it is false.%%
# File tokyotyrant.rb, line 298 def out(key) key = _argstr(key) if !@sock @ecode = EINVALID return false end sbuf = [0xC8, 0x20, key.length].pack("CCN") sbuf += key if !_send(sbuf) @ecode = ESEND return false end code = _recvcode if code == -1 @ecode = ERECV return false end if code != 0 @ecode = ENOREC return false end return true end
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.%%
# File tokyotyrant.rb, line 162 def put(key, value) key = _argstr(key) value = _argstr(value) if !@sock @ecode = EINVALID return false end sbuf = [0xC8, 0x10, key.length, value.length].pack("CCNN") sbuf += key + value if !_send(sbuf) @ecode = ESEND return false end code = _recvcode if code == -1 @ecode = ERECV return false end if code != 0 @ecode = EMISC return false end return true end
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.%%
# File tokyotyrant.rb, line 220 def putcat(key, value) key = _argstr(key) value = _argstr(value) if !@sock @ecode = EINVALID return false end sbuf = [0xC8, 0x12, key.length, value.length].pack("CCNN") sbuf += key + value if !_send(sbuf) @ecode = ESEND return false end code = _recvcode if code == -1 @ecode = ERECV return false end if code != 0 @ecode = EMISC return false end return true end
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.%%
# File tokyotyrant.rb, line 191 def putkeep(key, value) key = _argstr(key) value = _argstr(value) if !@sock @ecode = EINVALID return false end sbuf = [0xC8, 0x11, key.length, value.length].pack("CCNN") sbuf += key + value if !_send(sbuf) @ecode = ESEND return false end code = _recvcode if code == -1 @ecode = ERECV return false end if code != 0 @ecode = EKEEP return false end return true end
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.%%
# File tokyotyrant.rb, line 280 def putnr(key, value) key = _argstr(key) value = _argstr(value) if !@sock @ecode = EINVALID return false end sbuf = [0xC8, 0x18, key.length, value.length].pack("CCNN") sbuf += key + value if !_send(sbuf) @ecode = ESEND return false end return true end
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.%%
# File tokyotyrant.rb, line 250 def putshl(key, value, width = 0) key = _argstr(key) value = _argstr(value) width = _argnum(width) if !@sock @ecode = EINVALID return false end sbuf = [0xC8, 0x13, key.length, value.length, width].pack("CCNNN") sbuf += key + value if !_send(sbuf) @ecode = ESEND return false end code = _recvcode if code == -1 @ecode = ERECV return false end if code != 0 @ecode = EMISC return false end return true end
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.%%
# File tokyotyrant.rb, line 743 def rnum() if !@sock @ecode = EINVALID return 0 end sbuf = [0xC8, 0x80].pack("CC") if !_send(sbuf) @ecode = ESEND return 0 end code = _recvcode if code == -1 @ecode = ERECV return 0 end if code != 0 @ecode = EMISC return 0 end rv = _recvint64 if rv < 0 @ecode = ERECV return 0 end return rv end
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.%%
# File tokyotyrant.rb, line 771 def size() if !@sock @ecode = EINVALID return 0 end sbuf = [0xC8, 0x81].pack("CC") if !_send(sbuf) @ecode = ESEND return 0 end code = _recvcode if code == -1 @ecode = ERECV return 0 end if code != 0 @ecode = EMISC return 0 end rv = _recvint64 if rv < 0 @ecode = ERECV return 0 end return rv end
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.%%
# File tokyotyrant.rb, line 799 def stat() if !@sock @ecode = EINVALID return nil end sbuf = [0xC8, 0x88].pack("CC") if !_send(sbuf) @ecode = ESEND return nil end code = _recvcode if code == -1 @ecode = ERECV return nil end if code != 0 @ecode = ENOREC return nil end ssiz = _recvint32 if ssiz < 0 @ecode = ERECV return nil end sbuf = _recv(ssiz) if !sbuf @ecode = ERECV return nil end return _retstr(sbuf) end
Hash-compatible method.%% Alias of `put’.%%
# File tokyotyrant.rb, line 885 def store(key, value) return put(key, value) end
Synchronize updated contents with the file and the device.%% If successful, the return value is true, else, it is false.%%
# File tokyotyrant.rb, line 644 def sync() if !@sock @ecode = EINVALID return false end sbuf = [0xC8, 0x70].pack("CC") if !_send(sbuf) @ecode = ESEND return false end code = _recvcode if code == -1 @ecode = ERECV return false end if code != 0 @ecode = EMISC return false end return true end
Hash-compatible method.%% Get an array of all keys.%%
# File tokyotyrant.rb, line 983 def values tvals = Array::new return tvals if !iterinit while key = iternext value = get(key) break if !value tvals.push(value) end return tvals end
Remove all records.%% If successful, the return value is true, else, it is false.%%
# File tokyotyrant.rb, line 693 def vanish() if !@sock @ecode = EINVALID return false end sbuf = [0xC8, 0x72].pack("CC") if !_send(sbuf) @ecode = ESEND return false end code = _recvcode if code == -1 @ecode = ERECV return false end if code != 0 @ecode = EMISC return false end return true end
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.%%
# File tokyotyrant.rb, line 409 def vsiz(key) key = _argstr(key) if !@sock @ecode = EINVALID return -1 end sbuf = [0xC8, 0x38, key.length].pack("CCN") sbuf += key if !_send(sbuf) @ecode = ESEND return -1 end code = _recvcode if code == -1 @ecode = ERECV return -1 end if code != 0 @ecode = ENOREC return -1 end return _recvint32 end
Generated with the Darkfish Rdoc Generator 2.