[转]Working with Parameters and Return Codes in the Execute SQL Task
2014-03-05 12:28
696 查看
本文转自:http://msdn.microsoft.com/zh-cn/magazine/cc280502(en-us,SQL.100).aspx
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.
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.
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.
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.
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
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.
An input parameter of the NVARCHAR data type.
An output parameter of with the appropriate data type, as listed in the following table.
If the data is not stored in the appropriate input or output parameter, the package fails.
An input parameter of the SQL_WVARCHAR data type
An output parameter with the appropriate data type, as listed in the following table.
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.
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.
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.
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
External Resources
Blog entry, Stored procedures with output parameters, on blogs.msdn.com
CodePlex sample, Execute SQL Parameters and Result Sets, on msftisprodsamples.codeplex.com
See Also
Working with Result Sets 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. |
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 |
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 |
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 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 |
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 |
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
External Resources
Blog entry, Stored procedures with output parameters, on blogs.msdn.com
CodePlex sample, Execute SQL Parameters and Result Sets, on msftisprodsamples.codeplex.com
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: Visit the Integration Services page on MSDN Visit the Integration Services page on TechNet For automatic notification of these updates, subscribe to the RSS feeds available on the page. |
See Also
Concepts
Execute SQL TaskWorking with Result Sets in the Execute SQL Task
相关文章推荐
- Retrieving the Gazoutas: Understanding SQL Server Return Codes and Output Parameters
- Problems in mapping parameters of type Int64 to the Execute SQL Task
- System variables, logging and the Execute SQL Task...(zz)
- call different method with the same name, parameters and return value, select which one is called using const symbol
- Use sp_executesql to deal with the Image type Parameter in SP
- [转]SSIS Execute SQL Task : Mapping Parameters And Result Sets
- Working with EXIT, STOP, CONTINUE and RETURN in SAP ABAP
- Lesson 05: Working with Disconnected Data - The DataSet and SqlDataAdapter(使用断开数据--DataSet和SqlDataAdapter)
- 126.View the Exhibit and examine the data in the PROJ_TASK_DETAILS table.
- Working with Linux Files and Folders in Bash
- SPRING IN ACTION 第4版笔记-第十章Hitting the database with spring and jdbc-001-Spring对原始JDBC的封装
- Android: setPreviewCallbackWithBuffer, buffer in the queue and no callbacks
- Nullsoft Winamp Plug-in With Bitmapped UI, Docking and Restrictive Resizing - The Code Project - Dialog and Windows
- What's the difference between Future and FutureTask in Java?
- SPRING IN ACTION 第4版笔记-第十章Hitting the database with spring and jdbc-004-使用NamedParameterJdbcTemplate
- Laravel 出现"RuntimeException inEncrypter.php line 43: The only supported ciphers are AES-128-CBC and AES-256-CBC with the correct key lengths."问题的解决办法
- How to execute an OS command in SQL*PLUS without leaving the session ?
- SQL The data types ntext and varchar are incompatible in the not equal to operator 错误
- The Microsoft Data Warehouse Toolkit: With SQL Server 2005 and the Microsoft Business Intelligence T
- Using MERGE in SQL Server to insert, update and delete at the same time