Oracle                package:ROracle                R Documentation

_I_n_s_t_a_n_t_i_a_t_e _a_n _O_r_a_c_l_e _c_l_i_e_n_t _f_r_o_m _t_h_e _c_u_r_r_e_n_t _R _s_e_s_s_i_o_n

_D_e_s_c_r_i_p_t_i_o_n:

     This function creates and initializes an Oracle client from the
     current R session. It returns an object that allows you to connect
      to one or several Oracle servers.

_U_s_a_g_e:

     Oracle(max.con = 10, fetch.default.rec = 500, force.reload = F)

_A_r_g_u_m_e_n_t_s:

max.con : maximum number of connections that we intend to have open.
          This can be up to 10, a limit hard-coded in the current
          implementation. 

fetch.default.rec: number of records to fetch at one time from the
          database. (The 'fetch' method uses this number as a default.) 

force.reload: should we reload (reinitialize) the client code? Setting
          this to 'TRUE' allows you to change default settings.  Notice
          that all connections should be closed before re-loading. 

_D_e_t_a_i_l_s:

     This object is a singleton, that is, on subsequent invocations it
     returns the same initialized object. 

     This implementation allows you to connect to multiple host servers
     and run multiple connections on each server simultaneously.

_V_a_l_u_e:

     An object 'OraDriver' whose class extends  'DBIDriver' and the
     mixin (helper) class 'dbObjectId'. This object is used to create
     connections, using the function 'dbConnect', to one or several
     Oracle database engines.

_S_i_d_e _E_f_f_e_c_t_s:

     The R client part of the database communication is initialized,
     but note that connecting to the database engine needs to be done
     through calls to 'dbConnect'.

_O_r_a_c_l_e _u_s_e_r _a_u_t_h_e_n_t_i_c_a_t_i_o_n:

     In order to establish a connection to an Oracle server users need
     to provide a user name, a password, and possibly an ``Oracle SID''
     (i.e., a database name); by default the Oracle SID is taken from
     the environment variable  '\$ORACLE_SID'. The function 'dbConnect'
     allows authentication strings  similar to the Oracle monitor
     'SQL*Plus', namely, a  string of any of the following forms:

        1.  '"user/passsword"' 

        2.  '"user/password@dbname"'

        3.  '"/"' (provided the Oracle server is set up to use the
           underlying operating system users and passwords);

_P_r_e_p_a_r_e_d _s_t_a_t_e_m_e_n_t_s _a_n_d _d_a_t_a._f_r_a_m_e _b_i_n_d_i_n_g_s:

     As of version 0.5-0, 'ROracle' implements R data binding to
     prepared SQL statements.  This is done in two stages with the
     functions 'dbPrepareStatement' and 'dbExecStatement'.

     In the first stage of preparing a statement column numbers are
     embedded  inside the SQL statement, e.g.,  '"insert into my_table
     (id, name, val) VALUES (:1, :3, :2)"'  and the S class of those
     columns are specified in the 'bind=' argument to
     'dbPrepareStatement' 

     In the second stage 'dbExecStatement' binds the pre-specified
     columns from a supplied  'data=' data frame  to the SQL statement
     and the SQL statement is executed once for each row in the input
     data frame.  This step can be repeated with new data as many times
     as needed.

     _It is very important_ to note that typically a prepared statement
     implicitly will define a new transaction which needs to be
     explicitly committed with 'dbCommit' or rolled back with
     'dbRollback'.

     The current implementation allows only primitive types
     'c("numeric", "integer", "logical", "character")' for binding.

_T_r_a_n_s_a_c_t_i_o_n_s:

     The current implementation directly supports transaction commits
     and rollbacks on a connection-wide basis through calls to
     'dbCommit' and 'dbRollback'. Save points are not yet directly
     implemented, but you may be able to define them and rollback to
     them through calls to dynamic SQL with 'dbGetQuery'.

     Notice that Oracle (and ANSI/ISO compliant DBMS) transactions are 
     implicitly started when data definition SQL are executed (create
     table, etc.), which helper functions like 'dbWriteTable' may
     execute behind the scenes.   You may want or need to commit or
     roll back your work before issuing any of these helper functions.

_R_e_f_e_r_e_n_c_e_s:

     For more details on the R database interface see the PDF file
     'DBI.pdf' under the 'doc' directory of this package,  <URL:
     http://stat.bell-labs/RS-DBI>, and the Omega Project for
     Statistical Computing at <URL: http://www.omegahat.org>.

     See the documentation at the Oracle Web site <URL:
     http://www.oracle.com> for details.

_A_u_t_h_o_r(_s):

     David A. James

_S_e_e _A_l_s_o:

     On database managers:

     'dbDriver' 'Oracle' 'dbUnloadDriver'

     On connections:

     'dbConnect' 'dbDisconnect'

     On queries, prepared statements, and result objects:

     'dbSendQuery' 'fetch' 'dbGetQuery' 'dbClearResult'
     'dbPrepareStatement'    'dbExecStatement'       

     On transaction management:

     'dbCommit' 'dbRollback'

     On meta-data:

     'dbGetInfo' 'summary' 'dbListTables' 'dbListFields'
     'dbListConnections' 'dbListResults' 'dbGetException'
     'dbGetStatement' 'dbHasCompleted' 'dbGetRowCount'
     'dbGetAffectedRows'

_E_x_a_m_p_l_e_s:

     ## Not run: 
     ## create a Oracle instance and create one connection.
     ora <- Oracle()     ## or dbDriver("Oracle")
     con <- dbConnect(ora, user = "opto", password="pure-light", db="oras")

     ## you can also use Oracle's user/password@dbname convention
     con2 <- dbConnect(ora, user = "opto/pure-light@oras")

     ## or if you have defined the ORACLE_SID shell variable
     con3 <- dbConnect(ora, user = "opto", password = "pure-light")

     ## clone an existing connection
     w <- dbConnect(con)

     ## execute a statement and fetch its output in chunks of no more
     ## than 5000 rows at a time

     rs <- dbSendQuery(con, "select * from HTTP_ACCESS where IP_ADDRESS='127.0.0.1'")

     while(!dbHasCompleted(rs)){
        df <- fetch(rs, n = 5000)
        process(df)
     }
     dbHasCompleted(rs)
     [1] TRUE
     dbClearResult(rs)      ## done with this query
     [1] TRUE

     ## prepare and bind columns 2, 3, and 7 to the Oracle table 
     ## fields "cell", "erlangs", "blocking"
     ps <- dbPrepareStatement(con, 
              "INSERT into my_table (cell, erlangs, blocking) VALUE (:2,:3,:7)",
              bind = my.data.frame)

     ## execute one sql INSERT per row using columns 2, 3 and 7 
     ps <- dbExecStatement(ps, my.data.frame)
     ps <- dbExecStatement(ps, more.data)

     dbCommit(con)  ## ok, everything looks fine

     ## a concise description of the driver 
     summary(ora)

     <OraDriver:(24694)> 
       Driver name:  Oracle (ProC/C++) 
       Max  connections: 10 
       Conn. processed: 9 
       Default records per fetch: 500 
       Open connections: 2 

     ## a full description of the ora connection
     summary(con, verbose = T)

     <OraConnection:(25272,0)> 
       User: opto 
       Dbname: oras 
       Oracle Server version: 
         Oracle8 Enterprise Edition Release 8.0.4.0.0 - Production 
         PL/SQL Release 8.0.4.0.0 - Production 
         CORE Version 4.0.4.0.0 - Production 
         TNS for Solaris: Version 8.0.4.0.0 - Production 
         NLSRTL Version 3.3.1.0.0 - Production 

     dbDisconnect(con)     ## done with this connection
     [1] TRUE
     ## End(Not run)

