Working with Parameters and Return Codes in the Execute SQL Task

Working with Parameters and Return ...

Switch on low bandwidth view

Community Content

In this section

Statistics Annotations (0)

Click here to expand

Collapse All

SQL Server 2008 Books Online (June 2009)

Working with Parameters and Return Codes in the Execute SQL Task

SQL statements and stored procedures frequently use input parameters, output parameters, and return codes. In Integration Services, the Execute SQL task supports the Input, Output, and ReturnValue parameter types. You use the Input type for input parameters, Output for output parameters, and ReturnValue for return codes.

Note:
You can use parameters in an Execute SQL task only if the data provider supports them.

Parameters in SQL commands, including queries and stored procedures, are mapped to user-defined variables that are created within the scope of the Execute SQL task, a parent container, or within the scope of the package. The values of variables can be set at design time or populated dynamically at run time. You can also map parameters to system variables. For more information, see Integration Services Variables and System Variables.

However, working with parameters and return codes in an Execute SQL task is more than just knowing what parameter types the task supports and how these parameters will be mapped. There are additional usage requirements and guidelines to successfully use parameters and return codes in the Execute SQL task. The remainder of this topic covers these usage requirements and guidelines:

Using parameters names and markers
Using parameters with date and time data types
Using parameters in WHERE clauses
Using parameters with stored procedures
Getting values of return codes
Configuring parameters and return codes in the Execute SQL Task Editor

Using Parameter Names and Markers

Depending on the connection type that the Execute SQL task uses, the syntax of the SQL command uses different parameter markers. For example, the ADO.NET connection manager type requires that the SQL command uses a parameter marker in the format @varParameter, whereas OLE DB connection type requires the question mark (?) parameter marker.

The names that you can use as parameter names in the mappings between variables and parameters also vary by connection manager type. For example, the ADO.NET connection manager type uses a user-defined name with a @ prefix, whereas the OLE DB connection manager type requires that you use the numeric value of a 0-based ordinal as the parameter name.

The following table summarizes the requirements for SQL commands for the connection manager types that the Execute SQL task can use.

Connection type	Parameter marker	Parameter name	Example SQL command
ADO	?	Param1, Param2, …	SELECT FirstName, LastName, Title FROM Person.Contact WHERE ContactID = ?
ADO.NET	@<parameter name>	@<parameter name>	SELECT FirstName, LastName, Title FROM Person.Contact WHERE ContactID = @parmContactID
ODBC	?	1, 2, 3, …	SELECT FirstName, LastName, Title FROM Person.Contact WHERE ContactID = ?
EXCEL and OLE DB	?	0, 1, 2, 3, …	SELECT FirstName, LastName, Title FROM Person.Contact WHERE ContactID = ?

Using Parameters with ADO.NET and ADO Connection Managers

ADO.NET and ADO connection managers have specific requirements for SQL commands that use parameters:

ADO.NET connection managers require that the SQL command use parameter names as parameter markers. This means that variables can be mapped directly to parameters. For example, the variable @varName is mapped to the parameter named @parName and provides a value to the parameter @parName.
ADO connection managers require that the SQL command use question marks (?) as parameter markers. However, you can use any user-defined name, except for integer values, as parameter names.

To provide values to parameters, variables are mapped to parameter names. Then, the Execute SQL task uses the ordinal value of the parameter name in the parameter list to load values from variables to parameters.

Using Parameters with EXCEL, ODBC, and OLE DB Connection Managers

EXCEL, ODBC, and OLE DB connection managers require that the SQL command use question marks (?) as parameter markers and 0-based or 1-based numeric values as parameter names. If the Execute SQL task uses the ODBC connection manager, the parameter name that maps to the first parameter in the query is named 1; otherwise, the parameter is named 0. For subsequent parameters, the numeric value of the parameter name indicates the parameter in the SQL command that the parameter name maps to. For example, the parameter named 3 maps to the third parameter, which is represented by the third question mark (?) in the SQL command.

To provide values to parameters, variables are mapped to parameter names and the Execute SQL task uses the ordinal value of the parameter name to load values from variables to parameters.

Depending on the provider that the connection manager uses, some OLE DB data types may not be supported. For example, the Excel driver recognizes only a limited set of data types. For more information about the behavior of the Jet provider with the Excel driver, see Excel Source.

Using Parameters with OLE DB Connection Managers

When the Execute SQL task uses the OLE DB connection manager, the BypassPrepare property of the task is available. You should set this property to true if the Execute SQL task uses SQL statements with parameters.

When you use an OLE DB connection manager, you cannot use parameterized subqueries because the Execute SQL Task cannot derive parameter information through the OLE DB provider. However, you can use an expression to concatenate the parameter values into the query string and to set the SqlStatementSource property of the task.

Using Parameters with Date and Time Data Types

Using Date and Time Parameters with ADO.NET and ADO Connection Managers

When reading data of the SQL Server types, time and datetimeoffset, an Execute SQL task that uses either an ADO.NET or ADO connection manager has the following additional requirements:

For time data, an ADO.NET connection manager requires this data to be stored in a parameter whose parameter type is Input or Output, and whose data type is string.
For datetimeoffset data, an ADO.NET connection manager requires this data to be stored in one of the following parameters:
- A parameter whose parameter type is Input and whose data type is string.
- A parameter whose parameter type is Output or ReturnValue, and whose data type is datetimeoffset, string, or datetime2. If you select a parameter whose data type is either string or datetime2, Integration Services converts the data to either string or datetime2.
An ADO connection manager requires that either time or datetimeoffset data be stored in a parameter whose parameter type is Input or Output, and whose data type is adVarWchar.

For more information about SQL Server data types and how they map to Integration Services data types, see Data Types (Transact-SQL) and Integration Services Data Types.

Using Date and Time Parameters with OLE DB Connection Managers

When using an OLE DB connection manager, an Execute SQL task has specific storage requirements for data of the SQL Server data types, date, time, datetime, datetime2, and datetimeoffset. You must store this data in one of the following parameter types:

An input parameter of the NVARCHAR data type.

An output parameter of with the appropriate data type, as listed in the following table.

Output parameter type	Date data type
DBDATE	date
DBTIME2	time
DBTIMESTAMP	datetime, datetime2
DBTIMESTAMPOFFSET	datetimeoffset

If the data is not stored in the appropriate input or output parameter, the package fails.

Using Date and Time Parameters with ODBC Connection Managers

When using an ODBC connection manager, an Execute SQL task has specific storage requirements for data with one of the SQL Server data types, date, time, datetime, datetime2, or datetimeoffset. You must store this data in one of the following parameter types:

An input parameter of the SQL_WVARCHAR data type

An output parameter with the appropriate data type, as listed in the following table.

Output parameter type	Date data type
SQL_DATE	date
SQL_SS_TIME2	time
SQL_TYPE_TIMESTAMP -or- SQL_TIMESTAMP	datetime, datetime2
SQL_SS_TIMESTAMPOFFSET	datetimeoffset

If the data is not stored in the appropriate input or output parameter, the package fails.

Using Parameters in WHERE Clauses

SELECT, INSERT, UPDATE, and DELETE commands frequently include WHERE clauses to specify filters that define the conditions each row in the source tables must meet to qualify for an SQL command. Parameters provide the filter values in the WHERE clauses.

You can use parameter markers to dynamically provide parameter values. The rules for which parameter markers and parameter names can be used in the SQL statement depend on the type of connection manager that the Execute SQL uses.

The following table lists examples of the SELECT command by connection manager type. The INSERT, UPDATE, and DELETE statements are similar. The examples use SELECT to return products from the Product table in AdventureWorks that have a ProductID greater than and less than the values specified by two parameters.

Connection type	SELECT syntax
EXCEL, ODBC, and OLEDB	`SELECT* FROM Production.Product WHERE ProductId > ? AND ProductID < ?`
ADO	`SELECT* FROM Production.Product WHERE ProductId > ? AND ProductID < ?`
ADO.NET	`SELECT* FROM Production.Product WHERE ProductId > @parmMinProductID AND ProductID < @parmMaxProductID`

The examples would require parameters that have the following names:

The EXCEL and OLED DB connection managers use the parameter names 0 and 1. The ODBC connection type uses 1 and 2.
The ADO connection type could use any two parameter names, such as Param1 and Param2, but the parameters must be mapped by their ordinal position in the parameter list.
The ADO.NET connection type uses the parameter names @parmMinProductID and @parmMaxProductID.

Using Parameters with Stored Procedures

SQL commands that run stored procedures can also use parameter mapping. The rules for how to use parameter markers and parameter names depends on the type of connection manager that the Execute SQL uses, just like the rules for parameterized queries.

The following table lists examples of the EXEC command by connection manager type. The examples run the uspGetBillOfMaterials stored procedure in AdventureWorks. The stored procedure uses the @StartProductID and @CheckDate input parameters.

Connection type	EXEC syntax
EXCEL and OLEDB	`EXEC uspGetBillOfMaterials ?, ?`
ODBC	`{call uspGetBillOfMaterials(?, ?)}` For more information about ODBC call syntax, see the topic, Procedure Parameters, in the ODBC Programmer's Reference in the MSDN Library.
ADO	If IsQueryStoredProcedure is set to False, `EXEC uspGetBillOfMaterials ?, ?` If IsQueryStoredProcedure is set to True, `uspGetBillOfMaterials`
ADO.NET	If IsQueryStoredProcedure is set to False, `EXEC uspGetBillOfMaterials @StartProductID, @CheckDate` If IsQueryStoredProcedure is set to True, `uspGetBillOfMaterials`

To use output parameters, the syntax requires that the OUTPUT keyword follow each parameter marker. For example, the following output parameter syntax is correct: EXEC myStoredProcedure ? OUTPUT.

For more information about using input and output parameters with Transact-SQL stored procedures, see Parameters (Database Engine), Returning Data by Using OUTPUT Parameters, and EXECUTE (Transact-SQL).

For a sample that demonstrates how to configure the Execute SQL task to use parameters with a stored procedure, see Readme_Execute SQL Parameters and Result Sets Sample.

Getting Values of Return Codes

A stored procedure can return an integer value, called a return code, to indicate the execution status of a procedure. To implement return codes in the Execute SQL task, you use parameters of the ReturnValue type.

The following table lists by connection type some examples of EXEC commands that implement return codes. All examples use an input parameter. The rules for how to use parameter markers and parameter names are the same for all parameter types—Input, Output, and ReturnValue.

Some syntax does not support parameter literals. In that case, you must provide the parameter value by using a variable.

Connection type	EXEC syntax
EXCEL and OLEDB	`EXEC ? = myStoredProcedure 1`
ODBC	`{? = call myStoredProcedure(1)}` For more information about ODBC call syntax, see the topic, Procedure Parameters, in the ODBC Programmer's Reference in the MSDN Library.
ADO	If IsQueryStoreProcedure is set to False, `EXEC ? = myStoredProcedure 1` If IsQueryStoreProcedure is set to True, `myStoredProcedure`
ADO.NET	Set IsQueryStoreProcedure is set to True. `myStoredProcedure`

In the syntax shown in the previous table, the Execute SQL task uses the Direct Input source type to run the stored procedure. The Execute SQL task can also use the File Connection source type to run a stored procedure. Regardlesss of whether the Excecute SQL task uses the Direct Input or File Connection source type, use a parameter of the ReturnValue type to implement the return code. For more information about how to configure the source type of the SQL statement that the Execute SQL task runs, see Execute SQL Task Editor (General Page).

For more information about using return codes with Transact-SQL stored procedures, see Returning Data by Using a Return Code and RETURN (Transact-SQL).

Configuring Parameters and Return Codes in the Execute SQL Task

For more information about the properties of parameters and return codes that you can set in SSIS Designer, click the following topic:

Execute SQL Task Editor (Parameter Mapping Page)

For more information about how to set these properties in SSIS Designer, click the following topic:

How to: Set the Properties of a Task or Container

Stay Up to Date with Integration Services

For the latest downloads, articles, samples, and videos from Microsoft, as well as selected solutions from the community, visit the Integration Services page on MSDN or TechNet:

For automatic notification of these updates, subscribe to the RSS feeds available on the page.

Concepts

Execute SQL Task
Working with Result Sets in the Execute SQL Task

Help and Information

Getting SQL Server 2008 Assistance