Share via

  • Article

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.Person WHERE BusinessEntityID = ?

ADO.NET

@<parameter name>

@<parameter name>

SELECT FirstName, LastName, Title FROM Person.Person WHERE BusinessEntityID = @parmBusinessEntityID

ODBC

?

1, 2, 3, …

SELECT FirstName, LastName, Title FROM Person.Person WHERE BusinessEntityID = ?

EXCEL and OLE DB

?

0, 1, 2, 3, …

SELECT FirstName, LastName, Title FROM Person.Person WHERE BusinessEntityID = ?

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 AdventureWorks2008R2 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 AdventureWorks2008R2. 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).

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:

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

External Resources

Integration Services icon (small) 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.