db_put: Methods to Store And Retrieve Database Records
In hrbrmstr/RBerkeley: Oracle 'Berkeley DB' Interface for R

Description Usage Arguments Details Value Note Author(s) References See Also Examples

Store and retrieve R objects as key/value pairs from a Berkeley DB.

1	db_put(dbh, txnid = NULL, key, data, flags = 0L)

`dbh`	A DB handle to an open Berkeley database.
`txnid`	A DB_TXN transaction handle. (currently ignored)
`key`	An object, raw or will be coerced to raw. See details.
`data`	An object, raw or will be coerced to raw. See details.
`flags`	A valid flag created with `mkFlags`.
`dbc`	A DBC handle to an open cursor.
`n`	Elements to return.

BerkeleyDB uses key/data pairs for records, with no underlying data schema.

This allows for arbitrary byte-strings to be stored as keys or values in a DB. Internally these are a C struct of type DBT. To the RBerkeley user, these objects can range from standard (serialized) R objects to anything representable as a RAW vector in R, which is everything.

The design of db_put, db_get, dbcursor_put and dbcursor_get differ from package philosophy in that by default all objects are preprocessed via R to make usable byte strings (RAW vectors) for internal Berkeley use.

When passed an R object of any type, a check is made to see if it needs to be converted into a raw vector, if so the serialize function is called. This conversion is applied to both key and value automatically.

To avoid the use of serialize one must provide a vector of class raw.

The db_get and dbcursor_get methods will return a vector or list of vectors of type raw. Further application specific processing may be required.

*put functions return non-zero on failure, 0 on success. The *get calls will return a raw vector that must be processed on success, or non-zero on failure.

These functions are called for their database side effects.

Serialized objects in R have certain limitations with respect to underlying design considerations.

Jeffrey A. Ryan

BerkeleyDB DB->put
http://docs.oracle.com/cd/E17076_04/html/gsg/C/PutEntryWCursor.html

BerkeleyDB DB->get
http://docs.oracle.com/cd/E17076_04/html/gsg/C/Positioning.html

serialize, unserialize

## Not run: 
dbh <- db_create()
db_open(dbh, flags=mkFlags(DB_CREATE))

db_put(dbh, key="key", data="value")

db_get(dbh, key="key") # serialized "value"
unserialize(db_get(dbh, key="key")) # "value"

db_put(dbh, key=charToRaw("key2"), data=charToRaw("value"))
db_get(dbh, key=charToRaw("key2"))
rawToChar(db_get(dbh, key=charToRaw("key2"))) # what you expect, "value"

db_get(dbh, key="key2")  # not there, must use symmetric marshalling/conversion

db_close(dbh) # close DB
dbh <- db_create()
db_remove(dbh, "access.db", NULL)

## End(Not run)