oraSupport: Support Functions

Description

These functions are the workhorse behind the ROracle package, but users need not invoke these directly.

Usage

## OraDriver-related
   oraInitDriver(max.con=10, fetch.default.rec = 500, force.reload=FALSE)
   oraDriverInfo(obj, what)
   oraDescribeDriver(obj, verbose = FALSE, ...)
   oraCloseDriver(drv, ...)
   ## OraConnection-related
   oraNewConnection(drv, username="", password="", 
      dbname = if(is.R()) Sys.getenv("ORACLE_SID") else getenv("ORACLE_SID"),
      max.results = 1)
   oraCloneConnection(drv, ...)
   oraConnectionInfo(obj, what)
   oraDescribeConnection(obj, verbose = FALSE, ...)
   oraCloseConnection(con, ..., force = FALSE)
   ## OraResult-related
   oraExecStatement(ps, data = NULL, ora.buf.size = -1)
   oraFetch(res, n=0, ..., ora.buf.size)
   oraQuickSQL(con, statement, ...)
   oraExecDirect(con, statement, ora.buf.size = 500)
   oraResultInfo(obj, what)
   oraDescribeResult(obj, verbose = FALSE, ...)
   oraCloseResult(res, ...)
   ## OraPreparedStatement-related
   oraPrepareStatement(con, statement, bind)
   oraExecStatement(ps, data, ora.buf.size)
   oraDescribePreparedStatement(obj, verbose, ...)
   oraPreparedStatementInfo(obj, what, ...)
   oraBoundParamsInfo(obj)
   ## transactions
   oraCommit(conn, ...)
   oraRollback(conn, ...)
   ## data mappings and convenience functions
   oraDataType(obj, ...)
   oraReadTable(con, name, row.names = "row_names", check.names = TRUE, ...)
   oraWriteTable(con, name, value, field.oraTypes, row.names = TRUE, 
      overwrite=FALSE, append=FALSE, ...)
   oraTableFields(con, name, ...)

Arguments

max.con

positive integer specifying maximum number of open connections. The current default of 10 is hardcoded in the C code.

fetch.default.rec

default number of rows to fetch (move to R/S-Plus). This default is used in oraFetch. The default is 500.

force.reload

logical indicating whether to re-initialize the driver. This may be useful if you want to change the defaults (e.g., fetch.default.rec). Note that the driver is a singleton (subsequent inits just returned the previously initialized

obj

any of the Oracle DBI objects (e.g., OraConnection, OraResult).

what

character vector of metadata to extract, e.g., "version", "statement", "isSelect".

verbose

logical controlling how much information to display. Defaults to FALSE.

drv

an OraDriver object as produced by oraInit.

con

an OraConnection object as produced by oraNewConnection and oraCloneConnection.

conn

an OraConnection object as produced by oraNewConnection and oraCloneConnection.

res

an OraResult, for instance as produced by oraExecDirect.

an OraPreparedStatement object as produce by oraPrepareStatement.

data

a data.frame whose columns are to be bound to a prepared statement.

bind

a characte vector with the classes of the bound data.frame columns.

ora.buf.size

an integer less than or equal to RS_ORA_MAX_BUFFER_SIZE (initially set to 4096) specifying how many rows per fetch should Oracle move at a time. The ProC/C++ Oracle implementation limits the size of these buffers to 65767/si

username

a character string with the Oracle's user name. It can also be any of the Oracle-recognize login strings, e.g., "user/password" or "user/password@dbname".

password

character string with the Oracle's password.

dbname

character string with the Oracle System Identification (SID).

max.results

positive integer indicating the maximum number of results that Oracle connections will hold open. The current default of 1 is hardcoded in the C code.

force

logical indicating whether to close a connection that has open result sets. The default is FALSE.

statement

character string holding one (and only one) SQL statement.

number of rows to fetch from the given result set. A value of -1 indicates to retrieve all the rows. The default of 0 specifies to extract whatever the fetch.default.rec was specified during driver initialization oraInit

name

character vector of names (table names, fields, keywords).

value

a data.frame.

field.oraTypes

a list specifying the mapping from R/S-Plus fields in the data.frame value to SQL data types. The default is sapply(value,SQLDataType), see OraSQLType.

row.names

a logical specifying whether to prepend the value data.frame row names or not. The default is TRUE.

check.names

a logical specifying whether to convert DBMS field names into legal S names. Default is TRUE.

overwrite

logical indicating whether to replace the table name with the contents of the data.frame value. The defauls is FALSE.

append

logical indicating whether to append value to the existing table name.

...

placeholder for future use.

Value

oraInitDriver returns an OraDriver object.
oraDriverInfo returns a list of name-value metadata pairs.
oraDescribeDriver returns NULL (displays the object's metadata).
oraCloseDriver returns a logical indicating whether the operation succeeded or not.
oraNewConnection returns an OraConnection object.
oraCloneConnection returns an OraConnection object.
oraConnectionInforeturns a list of name-value metadata pairs.
oraDescribeConnection returns NULL (displays the object's metadata).
oraCloseConnection returns a logical indicating whether the operation succeeded or not.
oraExecStatement returns an OraResult object.
oraFetch returns a data.frame.
oraQuickSQL returns either a data.frame if the statement is a select-like or NULL otherwise.
oraDescribeResult returns NULL (displays the object's metadata). oraCloseResult returns a logical indicating whether the operation succeeded or not.
oraPrepareStatement returns a prepared statement.
oraExecStatement executes (and optionally binds new data) a prepared statement.
oraExecDirect executes a simple (no binding) SQL statement.
oraPreparedStatementInfo list of prepared statement metadata.
oraDescribePreparedStatement a simple print out of the prepared statement status
oraBoundParamsInfo data frame with as many rows as bound parameters with the columns number and class for the data.frame bindings.
oraReadTable returns a data.frame with the contents of the DBMS table. oraWriteTable returns a logical indicating whether the operation succeeded or not. oraTableFields returns a character vector with the table name field names. oraDataType retuns a character string with the closest oraResultInfo returns a list of name-value metadata pairs.
oraCommit commits the current transaction in the connection.
oraRollback roll backs the current transaction in the connection.

Constants

.OraPkgName (currently "ROracle"), .OraPkgVersion (the R package version), .OraPkgRCS (the RCS revision), .Oracle.NA.string (character that Oracle uses to denote NULL on input), .OraSQLKeywords (a lot!) .conflicts.OK.