man/db2env.Rd

   1 \name{dbLoad}
   2 \alias{dbLoad}
   3 \alias{dbLoad,filehash-method}
   4 \alias{dbLazyLoad}
   5 \alias{dbLazyLoad,filehash-method}
   6 \alias{db2env}
   7
   8 \title{Load database into environment}
   9 \description{
  10   Load entire database into an environment
  11 }
  12 \usage{
  13 db2env(db)
  14 dbLoad(db, ...)
  15 dbLazyLoad(db, ...)
  16
  17 \S4method{dbLoad}{filehash}(db, env = parent.frame(2), keys = NULL, ...)
  18 \S4method{dbLazyLoad}{filehash}(db, env = parent.frame(2), keys = NULL, ...)
  19 }
  20 \arguments{
  21   \item{db}{database object}
  22   \item{env}{an environment}
  23   \item{keys}{character vector of database keys to load}
  24   \item{...}{other arguments passed to methods}
  25 }
  26 \details{
  27   \code{db2env} loads the entire database \code{db} into an environment
  28   via calls to \code{makeActiveBinding}.  Therefore, the data themselves
  29   are not stored in the environment, but a function pointing to the data
  30   in the database is stored.  When an element of the environment is
  31   accessed, the function is called to retrieve the data from the
  32   database.  If the data in the database is changed, the changes will be
  33   reflected in the environment.
  34
  35   \code{dbLoad} loads objects in the database directly into the
  36   environment specified, like \code{load} does except with active bindings.
  37   \code{dbLoad} takes a second argument \code{env}, which is an
  38   environment, and the default for \code{env} is \code{parent.frame()}.
  39
  40   The use of \code{makeActiveBinding} in \code{db2env} and \code{dbLoad}
  41   allows for potentially large databases to, at least conceptually, be
  42   used in R, as long as you don't need simultaneous access to all of the
  43   elements in the database.
  44
  45   With \code{dbLazyLoad} database objects are
  46   "lazy-loaded" into the environment.  Promises to load the
  47   objects are created in the environment specified by \code{env}.  Upon
  48   first access, those objects are copied into the environment and will
  49   from then on reside in memory.  Changes to the database will not be
  50   reflected in the object residing in the environment after first
  51   access.  Conversely, changes to the object in the environment will not
  52   be reflected in the database.  This type of loading is useful for
  53   read-only databases.
  54 }
  55
  56 \value{
  57   For \code{db2env}, an environment is returned, the elements of which
  58   are the keys of the database.  For \code{dbLoad} and \code{dbLazyLoad}, a character vector
  59   is returned (invisibly) containing the keys associated with the values
  60   loaded into the environment.
  61 }
  62
  63 \author{Roger D. Peng}
  64
  65 \seealso{
  66   \code{\link{dbInit}} and \code{\link{filehash-class}}
  67 }
  68
  69 \examples{
  70 dbCreate("myDB")
  71 db <- dbInit("myDB")
  72 dbInsert(db, "a", rnorm(100))
  73 dbInsert(db, "b", 1:10)
  74
  75 env <- db2env(db)
  76 ls(env)  ## "a", "b"
  77 print(env$b)
  78 mean(env$a)
  79 env$a <- rnorm(100)
  80 mean(env$a)
  81
  82 env$b[1:5] <- 5:1
  83 print(env$b)
  84
  85 env <- new.env()
  86 dbLoad(db, env)
  87 ls(env)
  88
  89 env <- new.env()
  90 dbLazyLoad(db, env)
  91 ls(env)
  92 }
  93
  94 \keyword{database}