MINI MINI MANI MO

%
% Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved.
%
\name{ore.pull}
\alias{ore.pull}
\alias{ore.pull,ANY-method}
\alias{ore.pull,list-method}
\alias{ore.pull,ore.date-method}
\alias{ore.pull,ore.factor-method}
\alias{ore.pull,ore.frame-method}
\alias{ore.pull,ore.integer-method}
\alias{ore.pull,ore.logical-method}
\alias{ore.pull,ore.raw-method}
\alias{ore.pull,ore.tblmatrix-method}
\alias{ore.pull,ore.vecmatrix-method}
\alias{ore.pull,ore.vector-method}
\alias{ore.push}
\alias{ore.push,ANY-method}
\alias{ore.push,data.frame-method}
\alias{ore.push,Date-method}
\alias{ore.push,difftime-method}
\alias{ore.push,matrix-method}
\alias{ore.push,POSIXt-method}
\alias{ore.push,vector-method}
\title{Oracle R Enterprise Data Exchange Functions}
\description{
  Pulls or pushes data between an \R session and an Oracle R Enterprise
  schema.
}
\usage{
ore.pull(x, ...)
ore.push(x, ...)
}
\arguments{
  \item{x}{
    For function \code{ore.pull}, \code{\linkS4class{ore}} objects. For
    function \code{ore.push}, \code{vector}, \code{data.frame},
    \code{matrix}, or \code{list} objects.
  }
  \item{\dots}{
    For future expansion. 
  }
}
\details{
  Functions \code{ore.push} and \code{ore.pull} place data in or
  retrieve data from an Oracle R Enterprise schema. The supported
  in-memory \R object to \code{\linkS4class{ore}} object mappings are as
  follows:
  \itemize{
    \item \code{logical} maps to \code{\linkS4class{ore.logical}}
    \item \code{integer} maps to \code{\linkS4class{ore.integer}}
    \item \code{numeric} maps to \code{\linkS4class{ore.numeric}}
    \item \code{character} maps to \code{\linkS4class{ore.character}}
    \item \code{factor} maps to \code{\linkS4class{ore.factor}}
    \item \code{raw} maps to \code{\linkS4class{ore.raw}}
    \item \code{Date} maps to \code{\linkS4class{ore.date}}
    \item \code{POSIXt} maps to \code{\linkS4class{ore.datetime}}
    \item \code{difftime} maps to \code{\linkS4class{ore.difftime}}
    \item \code{data.frame} with columns of type \code{logical},
          \code{integer}, \code{numeric}, \code{character},
          \code{factor}, list of \code{raw}, \code{Date}, \code{POSIXct}, 
          \code{difftime} maps to \code{\linkS4class{ore.frame}} 
          with the appropriately typed columns
  }

  In addition to the mappings above, for function \code{ore.push} if the
  input is a \code{list} object, \code{ore.push} is applied recursively
  to each element. Meanwhile, the list elements are serialized before
  saving to the database. The argument \code{envAsEmptyenv} in \code{\dots}
  is a logical value indicating whether referenced environments
  in the list element objects to be saved should be replaced with an empty
  environment during serialization. When \code{TRUE}, the referenced
  environment will be replaced with an empty environment whose parent is
  \code{.GlobalEnv}, and therefore, the contents in the referenced
  environment will not be serialized and saved to the database. In some
  situations, this could significantly reduce the size of the saved
  objects. When \code{FALSE}, the contents in the referenced environment
  will be serialized and saved, and could be unserialized and loaded
  into memory when calling \code{ore.pull}. The default value is
  regulated by the global option \code{ore.envAsEmptyenv}.

  For in-memory \R types listed in the table above, the \code{ore.push}
  function creates objects that maintain vector element or data set row
  ordering of the original data object. For all other data types the
  behavior of \code{ore.push} is unspecified.

  Attribute \code{ora.type} can be used to specify mapping \R types 
  \code{character} and \code{factor} to \code{CLOB} and 
  \R type \code{raw} to \code{BLOB}. The \code{ora.type} takes the string 
  value \code{"clob"} and \code{"blob"} respectively for these two cases.
}
\value{
  Function \code{ore.pull} returns an in-memory \R object containing the
  appropriate in-memory data.

  Function \code{ore.push} returns an \code{\linkS4class{ore}} object
  of the appropriate type.
}
\references{
  \href{http://www.oracle.com/technetwork/database/database-technologies/r/r-enterprise/documentation/index.html}{Oracle R Enterprise}
}
\author{
  Oracle \email{oracle-r-enterprise@oracle.com}
}
\seealso{
  \code{\link{ore.ls}},
  \code{\linkS4class{ore.frame}},
  \code{\linkS4class{ore.matrix}},
  \code{\linkS4class{ore.vector}}
  \code{\link{ore.options}}  
}
\examples{
vec <- 1:10
oreVec <- ore.push(vec)
class(oreVec)
vec2 <- ore.pull(oreVec)
class(vec2)
oreVec3 <- ore.push(oreVec)
class(oreVec3)
vec
oreVec
vec2
oreVec3

IRIS <- ore.push(iris)
class(IRIS)
new.iris <- ore.pull(IRIS)
class(new.iris)
head(IRIS)
head(new.iris)

vraw <- raw(2000L)
oreRaw <- ore.push(vraw)
class(oreRaw)
new.vraw <- ore.pull(oreRaw)
class(new.vraw)
length(new.vraw)

vbraw <- raw(3000L)
attr(vbraw, "ora.type") <- "blob"
oreBRaw <- ore.push(vbraw)
class(oreBRaw)
new.vbraw <- ore.pull(oreBRaw)
class(new.vbraw)
length(new.vbraw)

attr(iris$Species, "ora.type") <- "clob"
iris$Species.raw <- lapply(iris$Species, 
                           function(x) charToRaw(as.character(x)))
attr(iris$Species.raw, "ora.type") <- "blob"
IRIS2 <- ore.push(iris)
class(IRIS2)
new.iris2 <- ore.pull(IRIS2)
class(new.iris2)
}
\keyword{data}
\keyword{database}
\keyword{ORE}