dbSendQuery-methods           package:DBI           R Documentation

_E_x_e_c_u_t_e _a _s_t_a_t_e_m_e_n_t _o_n _a _g_i_v_e_n _d_a_t_a_b_a_s_e _c_o_n_n_e_c_t_i_o_n

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

     Methods for submiting and executing arbitrary SQL statements on a
     specific connection, clearing result sets, and extracting
     exception information from the DBMS.

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

       dbSendQuery(conn, statement, ...)
       dbGetQuery(conn, statement, ...)
       dbClearResult(res, ...)
       dbGetException(conn, ...) 

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

    conn: a connection object. 

statement: a character vector of length 1 with the SQL statement. 

     res: a result set object (i.e., the value of 'dbSendQuery'). 

    ... : database-specific parameters may be specified. 

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

     The function 'dbSendQuery' only submits and synchronously executes
      the SQL statement to the database engine.  It does _not_ extracts
     any records -  for that you need to use the function  'fetch'
     (make sure you invoke 'dbClearResult' when you  finish fetching
     the records you need).

     The function 'dbGetQuery' does all these in one operation (submits
     the statement, fetches all output records, and clears the result
     set).

     'dbClearResult' frees all resources (local and remote) associated
     with a result set.  It some cases (e.g., very large result sets)
     this can  be a critical step to avoid exhausting resources
     (memory, file descriptors,  etc.)

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

     'dbSendQuery' returns a result set object, i.e., an object that
     inherits from 'DBIResult';  if the statement generates output
     (e.g., a 'SELECT' statement) the result set can be used with
     'fetch' to extract records.

     'dbGetQuery' returns a data.frame with the output (if any) of the
     query.  

     'dbClearResult' returns a logical indicating whether clearing the
     result set was successful or not.

     'dbGetException' returns a list with elements 'errNum'  (an
     integer error number) and 'errMsg' (a character string) describing
     the last error in the connection 'conn'.

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

     The statement is submitted for synchronous execution to the server
      connected through the 'conn' object.  The DBMS executes the
     statement, possibly generating vast amounts of data.  Where these
     data reside is driver-specific:  some drivers may choose to leave
     the output on the server and transfer them piecemeal to R/S-Plus,
     others may transfer all the data to the client - but not
     necessarily to the  memory that R/S-Plus manages.  See the
     individual drivers'  'dbSendQuery' method for implementation
     details.

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

     See the Database Interface definition document 'DBI.pdf' in the
     base directory of this package or <URL:
     http://developer.r-project.org/db>.

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

     'dbDriver' 'dbConnect' 'fetch' 'dbCommit' 'dbGetInfo'
     'dbReadTable'

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

     ## Not run: 
     drv <- dbDriver("MySQL")
     con <- dbConnect(drv)
     res <- dbSendQuery(con, "SELECT * from liv25")
     data <- fetch(res, n = -1)
     ## End(Not run)

