Execute SQL Queries

DESCRIPTION:

Execute any valid SQL query string in the server database you are connected to. The executeSql function is functional only in S-PLUS for Windows; it is deprecated in favor of executeSQL with type="ODBC"

USAGE:

executeSQL(type="", server="", user="", password="", database="", 
           odbcConnection=character(0), sqlQuery=character(0), returnData=F)
executeSql(odbcConnection=character(0), 
           odbcSqlQuery=character(0), returnData=F)

OPTIONAL ARGUMENTS:

type
a character string. This can be any database type accepted by , such as "ORACLE", "ODBC", etc. The case of the string is ignored.
server
a character string specifying the database server when importing from a relational database. If type="DIRECT-SQL", and you are accessing a non-default instance of SQL Server, specify server="SERVERNAME\\INSTANCE". To access the default instance, use server= "SERVERNAME".

This should be left as the empty string "" if type="DB2".

user
a character string specifying the user name.
password
a character string specifying the user's password for accessing the database.
database
a character string specifying the database. This should be left as the empty string "" if type="ORACLE".
sqlQuery
a character string specifying the SQL query to execute.
odbcConnection
a character string containing an ODBC connection string. In executeSQL, this argument is functional only when type="ODBC". See the importData help file for information on the form this string should take.
odbcSqlQuery
a character string containing an optional SQL query to use with executeSql when type="ODBC". If no query is specified, the first table in the data source is retrieved.
returnData
a logical flag. Set returnData=TRUE only if your query returns data. Otherwise, keep returnData=FALSE (the default). Do not set returnData=TRUE for SQL statements that have side effects (e.g., INSERT statements). Note that when returnData=TRUE, the SQL may be executed twice: a small "trial" run may be done to determine the column types before the full result is extracted.

VALUE:

The executeSQL function returns a data frame containing the result of the SQL query if returnData=TRUE, or NULL otherwise.

DETAILS:

If type=ODBC, you must specify a valid ODBC connection string to a valid data source for your SQL query to be successful. The SQL query string is passed directly through to the server for evaluation, and any errors encountered by the server are reported back and will stop execution of the S-PLUS code.

NOTE:

The executeSQL function is designed to execute arbitrary SQL queries, either stored procedures or simple statements that return data. It is not designed to execute arbitrary SQL "programs." If you need to work with a long succession of SQL statments, it is best to convert the statements to a SQL stored procedure and then call the procedure using executeSql or executeSQL .

SEE ALSO:

, .

EXAMPLES:

# Examples for an Oracle database with S-PLUS for Solaris. Note that 
# your system database administrator will likely have to supply the server
# name(s), table names, and other settings specific to your system.
# 

# Create two tables TEST1 and TEST2 in the Oracle database ORACLEDB,
# each containing the data in fuel.frame
exportData(fuel.frame, table="TEST1", appendToTable=F,
      type="oracle", user="scott", password="tiger", server="ORACLEDB")
exportData(fuel.frame, table="TEST2", appendToTable=F,
      type="oracle", user="scott", password="tiger", server="ORACLEDB")

# Use an INSERT statement to append selected rows from TEST2 to
# the table TEST1.
executeSQL(sqlQuery = "INSERT INTO TEST1 SELECT * FROM TEST2 where FUEL>5",
      type="oracle", user="scott", password="tiger", server="ORACLEDB")

# Examples for ODBC with S-PLUS for Windows. Note that 
# your system database administrator will likely have to supply the server
# name(s), table names, and other settings specific to your system.
#
# Specify a valid ODBC connection string to the server database.
myConnection <- "DSN=SQL Server;UID=myuser;PWD=mypass;DATABASE=master"

# The following statements return NULL because no results are 
# returned from these SQL commands.
executeSQL(type="ODBC", odbcConnection=myConnection, 
   sqlQuery="create table mytable (a1 varchar(10))")
executeSQL(type="ODBC", odbcConnection=myConnection, 
   sqlQuery="insert into mytable values ('Hello')")

# The following query returns a data frame into the "mydata" 
# object that represents all the data from "mytable".
# Notice that returnData=TRUE here.
mydata <- executeSQL(type="ODBC", odbcConnection=myConnection, 
   sqlQuery="select * from mytable", returnData=T)