dbSendQuery               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:

     Submits and executes an arbitrary SQL statement on a specific
     connection.  Also, clears (closes) a result set.

_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/Splus,
     others may transfer all the data to the client - but not
     necessarily to the  memory that R/Splus 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:

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

