MINI MINI MANI MO

%
% Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved.
%
\name{ore.save}
\alias{ore.save}
\title{Oracle R Enterprise Datastore Saving Function}
\description{
  Saves \R objects into a datastore in the user's Oracle Database schema.
}
\usage{
ore.save(..., list = character(0), 
         name = stop("parameter 'name' must be specified"), 
         grantable = FALSE,
         envir = parent.frame(), overwrite = FALSE, append = FALSE, 
         description = character(0),
         envAsEmptyenv = getOption("ore.envAsEmptyenv", FALSE))
}
\arguments{
  \item{...}{
    The names of the \R objects to be saved (as symbols or character
    strings).
  }
  \item{list}{
    A character vector containing the names of \R objects to be saved.
  }
  \item{name}{
    A character string specifying the name of datastore in which to save
    the \R objects.
  }
  \item{grantable}{
    A scalar logical value specifying whether to create a new datastore
    the read privilege for which can be granted to other users.
    Argument \code{grantable} is ignored when used with argument 
    \code{overwrite} or \code{append}.
  }
  \item{envir}{
    An environment to search for the \R objects to be saved.
  }
  \item{overwrite}{
    A logical value specifying whether to overwrite the datastore, if it
    already exists.
  }
  \item{append}{
    A logical value specifying whether to append the \R objects to the
    datastore, if it already exists.
  }
  \item{description}{
    A character string containing no more than 2000 characters to be
    used as comments for the datastore.
  }
  \item{envAsEmptyenv}{
     A logical value indicating whether referenced environments
     in the \R objects to be saved should be replaced with an empty
     environment during serialization. When \code{TRUE}, the referenced
     environment in the objects will be replaced with an empty
     environment whose parent is \code{.GlobalEnv}, and therefore, the
     contents in the original 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.load}.  The default value is
     regulated by the global option \code{ore.envAsEmptyenv}.
   }
}
\details{
  Function \code{ore.save} saves the \R objects from argument \code{...}
  or itemized in argument \code{list} for retrieval from environment
  \code{envir} to the datastore specified in argument \code{name} of the
  user's Oracle Database schema. Nonexistent \R objects referenced in
  argument \code{list} are ignored. If no \R objects given in argument
  \code{list} exist in environment \code{envir}, the function will throw
  an error.

  By default, \R objects are saved to a new datastore with the specified
  \code{name}. Arguments \code{overwrite} and \code{append} can be used
  to save \R objects to an existing datastore, but only one of them can
  be \code{TRUE}.

  Comments can be added to datastore through argument \code{description}.
}
\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.load}},
  \code{\link{ore.delete}},
  \code{\link{ore.datastore}},
  \code{\link{ore.datastoreSummary}}
  \code{\link[OREbase]{ore.options}}
}

\examples{
if (any(sapply(c("x", "y", "z"), exists))) 
  stop("object x, y, or z exists")

x <- stats::runif(20)
y <- list(a = 1, b = TRUE, c = "oops")
z <- ore.push(x)

# save all objects in the current workspace environment to 
# a datastore with name 'rq$ds_1' in the user's schema
ore.save(list=ls(), name="rq$ds_1")

# overwrite existing datastore rq$ds_1 with object x, y in 
# the current workspace environment 
ore.save(x, y, name="rq$ds_1", overwrite=TRUE)

# add object z in the current workspace environment to 
# the existing datastore rq$ds_1 
ore.save(z, name="rq$ds_1", append=TRUE)

ore.delete(name="rq$ds_1")
rm(x, y, z)
}
\keyword{datastore}
\keyword{database}
\keyword{ORE}