SQL.REQUEST

Some of the content in this topic may not be applicable to some languages.

 Important   The SQL.REQUEST function is not supported in Microsoft Office Excel 2003 because the Excel 2002 Add-in: Open Database Connectivity (XLODBC.XLA) is only supported in Excel 2002.

SQL.REQUEST connects with an external data source, and runs a query from a worksheet. SQL.REQUEST then returns the result as an array without the need for macro programming. If this function is not available, you must install the Microsoft Excel ODBC add-in program (add-in: A supplemental program that adds custom commands or custom features to Microsoft Office.) (XLODBC.XLA). You can install the add-in from the Microsoft Office Web site.

Syntax

SQL.REQUEST(connection_string,output_ref,driver_prompt,query_text,col_names_logical)

Connection_string     supplies information, such as the data source name, user ID, and passwords, required by the driver being used to connect to a data source and must follow the driver's format. The following table provides three example connection strings for three drivers.

Driver Connection_string
dBASE DSN=NWind;PWD=test
SQL Server DSN=MyServer;UID=dbayer; PWD=123;Database=Pubs
ORACLE DNS=My Oracle Data Source;DBQ=MYSER VER;UID=JohnS;PWD=Sesame
  • You must define the data source name (DSN) used in connection_string before you try to connect to it.
  • You can enter connection_string as an array or a string. If connection_string exceeds 250 characters, you must enter it as an array.
  • If SQL.REQUEST is unable to gain access to the data source using connection_string, it returns the #N/A error value.

Output_ref     is a cell reference where you want the completed connection string placed. If you enter SQL.REQUEST on a worksheet, then output_ref is ignored.

  • Use output_ref when you want SQL.REQUEST to return the completed connection string (you must enter SQL.REQUEST on a macro sheet in this case).
  • If you omit output_ref, SQL.REQUEST does not return a completed connection string.

Driver_prompt     specifies when the driver dialog box is displayed and which options are available. Use one of the numbers described in the following table. If driver_prompt is omitted, SQL.REQUEST uses 2 as the default.

Driver_prompt Description
1 Driver dialog box is always displayed.
2 Driver dialog box is displayed only if information provided by the connection string and the data source specification is not sufficient to complete the connection. All dialog box options are available.
3 Driver dialog box is displayed only if information provided by the connection string and the data source specification is not sufficient to complete the connection. Dialog box options appear dimmed and unavailable if they are not required.
4 Driver dialog box is not displayed. If the connection is not successful, it returns an error.

Query_text     is the SQL statement that you want to execute on the data source.

  • If SQL.REQUEST is unable to execute query_text on the specified data source, it returns the #N/A error value.
  • You can update a query by concatenating references into query_text. In the following example, every time $A$3 changes, SQL.REQUEST uses the new value to update the query.
"SELECT Name FROM Customers WHERE Balance > "&$A$3&"".

Excel limits strings to a length of 255 characters. If query_text exceeds that length, enter the query in a vertical range of cells, and use the entire range as the query_text. The values of the cells are concatenated to form the complete SQL statement.

Column_names_logical     indicates whether column names are returned as the first row of the results. Set this argument to TRUE if you want the column names to be returned as the first row of the results. Use FALSE if you do not want the column names returned. If column_names_logical is omitted, SQL.REQUEST does not return column names.

Return Value

  • If this function completes all of its actions, it returns an array of query results or the number of rows affected by the query.
  • If SQL.REQUEST is unable to access the data source using connection_string, it returns the #N/A error value.

Remarks

  • SQL.REQUEST can be entered as an array. When you enter SQL.REQUEST as an array, it returns an array to fit that range.
  • If the range of cells is larger than the result set, SQL.REQUEST adds empty cells to the returned array to increase it to the necessary size.
  • If the result set is larger than the range entered as an array, SQL.REQUEST returns the whole array.
  • The arguments to SQL.REQUEST are in a different order than the arguments to the SQLRequest function in Visual Basic for Applications.

Example

Suppose you want to make a query of a dBASE database named DBASE4. When you enter the following formula in a cell, an array of query results is returned, with the first row being the column names:

SQL.REQUEST("DSN=NWind;DBQ=c:\msquery;FIL=dBASE4", c15, 2, "Select Custmr_ID, Due_Date from Orders WHERE order_Amt>100", TRUE)
 
 
Applies to:
Excel 2003