MINI MINI MANI MO

%
% Copyright (c) 2012, 2016, Oracle and/or its affiliates. All rights reserved.
%
\name{ore.connect}
\alias{ore.is.connected}
\alias{ore.connect}
\alias{ore.disconnect}
\title{Oracle R Enterprise Connection Functions}
\description{
  Establishes or terminates a connection to an Oracle R Enterprise
  server.
}
\usage{
  ore.is.connected(type = c("ORACLE", "HIVE"))
  ore.connect(user = "", sid = "", host = "localhost", password = "",
              port = NULL, service_name = NULL, conn_string = NULL,
              all = FALSE, type = c("ORACLE", "HIVE"),
              tzone = Sys.getenv("TZ"), schema = NULL, ...)
  ore.disconnect()
}
\arguments{
  \item{user}{
    When argument \code{type = "ORACLE"} (the default), a character
    string specifying the Oracle Database user name.
  }
  \item{sid}{
    When argument \code{type = "ORACLE"} (the default), a character
    string specifying the Oracle Database SID or Oracle Wallet
    connection string.
  }
  \item{host}{
    When argument \code{type = "ORACLE"} (the default), a character
    string for the host name of the Oracle Database.
  }
  \item{password}{
    When argument \code{type = "ORACLE"} (the default), a character
    string specifying the Oracle Database user password.
  }
  \item{port}{
    When argument \code{type = "ORACLE"} (the default), a number
    specifying the Oracle Database port (usually 1521).
  }
  \item{service_name}{
    When argument \code{type = "ORACLE"} (the default), a character
    string specifying the service name to be used in the connection
    identifier for the Oracle Database.
  }
  \item{conn_string}{
    When argument \code{type = "ORACLE"} (the default), a character
    string specifying the connection string used to connect to the
    Oracle Database. Usually used for database connection with Oracle
    Wallet.
  }
  \item{all}{
    A logical value indicating whether to call functions
    \code{\link{ore.sync}} and \code{\link{ore.attach}} using their
    default arguments. This will result in synchronizing and attaching
    all tables and views in the schema for the Oracle R Enterprise
    connection. The execution time for \code{\link{ore.sync}} grows
    linearly with the number of visible tables and views.
  }
  \item{type}{
    A character string specifying the database type; either
    \code{"ORACLE"} (default) or \code{"HIVE"}. 
  }
  \item{tzone}{
    A character string specifying the session time zone for both the \R
    and database sessions. The default value of \code{tzone} is the value
    of the system environment variable \code{TZ}. If the value of
    \code{tzone} is either \code{NA} or an empty string, \code{UTC} is
    used for both the \R and database sessions.
  }
  \item{schema}{
    A character string specifying the schema.
  }
  \item{...}{
    Additional parameters for a Hive connection when using Hiveserver2 in
    different modes such as:
    \itemize{
      \item{HiveServer2 with Kerberos authentication:}{
        Use the parameter \code{principal} to specify the Kerberos server
        principal for the host where HiveServer2 is running.
      }
      \item{Hiveserver2 with SSL:}{
        In this mode, use parameters such as \code{ssl="true"},
        \code{sslTrustStore} to specify the path to the client's truststore file
        and \code{trustStorePassword} to specify the password for the truststore.
      }
      \item{Any other configuration of HiveServer2:}{
        There are many such configuration combinations in which HiveServer2
        could be running. Check the Hive Documentation for the various modes and
        parameters needed to connect in those modes.
      }
    }
  }
}
\details{
  Functions \code{ore.connect} and \code{ore.disconnect} are called for
  their side effects, namely establishing or terminating a connection to
  an Oracle R Enterprise server. The call to function \code{ore.connect}
  must precede all other calls to Oracle R Enterprise functionality
  (except \code{ore.is.connected}). There can only be one active Oracle
  R Enterprise connection. An Oracle R Enterprise session can optionally
  end with a call to function \code{ore.disconnect}. An Oracle R
  Enterprise session is implicitly terminated when the \R session ends.

  Both the \R and the database session time zones are set during the
  execution of function \code{ore.connect}. The session time zones are
  set to the value of the argument \code{tzone}, whose default value is
  equal to the system environment variable \code{TZ}. If both \code{TZ}
  and \code{tzone} are not specified, the session time zones are set to
  \code{UTC}.

  If you are using Oracle Wallet to store username and password, then
  use the \code{conn_string} argument to pass the connection string for
  the wallet mapping (for more information refer to chapter 3
  "Configuring Clients to Use the External Password Store" of Oracle
  Database Security Guide). In addition, the \code{service_name} argument
  can be used to pass service name information. (Refer to the chapter 2
  of Oracle Database Net Services Administrator's Guide for more
  information on service names).

  Calling \code{ore.connect} when an active Oracle R Enterprise
  connection already exists results in disconnecting the active session
  prior to starting a new session.
}
\value{
  A logical value in the case of function \code{ore.is.connected}
  indicating whether there exists an active Oracle R Enterprise
  connection; otherwise an invisible \code{NULL} value.
}
\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.attach}},
  \code{\link{ore.exists}},
  \code{\link{ore.get}},
  \code{\link{ore.ls}},
  \code{\link{ore.rm}},
  \code{\link{ore.sync}}
}
\examples{
\dontrun{
  # pass the username password during connect
  if (!is.ore.connected())
    ore.connect("rquser", "orcl", "localhost", "rquser")
  ore.ls()
  ore.disconnect()

  # pass the connect string for wallet mode
  if (!is.ore.connected())
    ore.connect(conn_string = "<wallet_connect_string>")
  ore.ls()
  ore.disconnect()
}}
\keyword{database}
\keyword{ORE}